EnvLauncher

EnvLauncher 是一个 macOS 工具，用来给指定 GUI 应用或 CLI 工具注入独立代理环境，而不修改系统网络代理设置。

适合这些场景：

• 只让 Codex、Claude Code、某个 Electron 应用走代理。
• 系统本身有 PAC 或其他代理规则，但希望某个应用使用单独代理。
• CLI 工具不方便手动 export HTTP_PROXY / HTTPS_PROXY。
• 需要快速确认代理服务器 DNS、TCP、Ping 和出口 IP 是否正常。

功能

• GUI 应用代理注入

  • 添加 .app 后，可从 EnvLauncher 重启启动目标应用。
  • 启动时注入 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY 等环境变量。
  • 对 Chromium / Electron 应用额外注入 --proxy-server 参数。

• CLI 工具代理注入

  • 自动扫描用户安装的 CLI：Homebrew、nvm、bun、cargo、pyenv、asdf、~/.local/bin、~/bin 等。
  • 不展示 /bin、/usr/bin、/usr/sbin 里的系统命令。
  • 支持一键启动 CLI：生成临时 .command 并打开 Terminal，让交互式工具在带代理环境的终端中运行。
  • 支持生成长期 wrapper，例如 ~/.local/bin/claude-env。

• SOCKS5 本地中转

  • 如果只配置 SOCKS5，EnvLauncher 会启动本地 HTTP CONNECT bridge。
  • 这样只支持 HTTP_PROXY / HTTPS_PROXY 的 CLI 也能使用 SOCKS5 上游。

• 代理诊断

  • 解析代理服务器 Host 对应 IP。
  • 本机 TCP connect 测试代理端口。
  • 本机 Ping 测试代理 IP。
  • 通过注入后的代理链路请求 IP echo 服务，显示出口 IP。

• 本地打包

  • Swift Package 项目。
  • scripts/package_app.sh 会构建 release app、写入 Info.plist、复制图标并做本地 ad-hoc codesign。

使用

1. 打开 dist/EnvLauncher.app。
2. 填写代理 Host 和端口。
   • Host 只填主机名或 IP，不要带 http://。
   • HTTP/HTTPS 端口和 SOCKS5 端口可二选一。
   • 如代理需要账号密码，打开“需要认证”。
3. 点击“检查代理”验证端口连通。
4. 添加目标：
   • GUI 应用：点击“添加应用”，选择 .app。
   • CLI 工具：点击“添加 CLI”，搜索并添加用户安装的命令。
5. 启动：
   • GUI 应用点击“重启启动”。
   • CLI 工具点击“启动”，会打开 Terminal 并运行该 CLI。
6. 点击“测试出口”确认注入代理后的出口 IP。
7. 点击“诊断”查看 DNS、TCP、Ping、出口 IP 等细节。

CLI wrapper

CLI 工具有两种使用方式：

• “启动”：临时生成 .command，打开 Terminal 直接运行原始 CLI。
• “生成”：生成长期 wrapper 到 ~/.local/bin。

例如添加 claude 后，点击“生成”会得到：

~/.local/bin/claude-env

之后可以直接运行：

claude-env

wrapper 只负责导出代理环境变量，然后 exec 原始 CLI；参数、stdin/stdout 和终端行为保持原生。

配置保存位置

EnvLauncher 的配置不保存在 .app 包里。

当前用户填写的 Host、端口、账号密码、已添加应用和 CLI 列表保存在 macOS UserDefaults：

~/Library/Preferences/dev.envlauncher.mac.plist

复制 EnvLauncher.app 给别人不会带走你的代理配置。

另外：

• 生成的 CLI wrapper 位于 ~/.local/bin/*-env。
• 一键启动 CLI 的临时 .command 位于 ~/Library/Application Support/EnvLauncher/CLI Launchers/。

这些文件也不在 .app 包内。

构建与测试

开发环境：

• macOS 14+
• Swift 6 / Xcode Command Line Tools

构建 debug：

swift build -c debug --product EnvLauncher

运行测试：

./scripts/test.sh

打包 app：

./scripts/package_app.sh

打包产物：

dist/EnvLauncher.app

跳过 codesign：

ENVLAUNCHER_SKIP_CODESIGN=1 ./scripts/package_app.sh

项目结构

Sources/EnvLauncherCore/     核心逻辑：环境变量、代理检查、CLI 扫描、wrapper、诊断
Sources/EnvLauncher/         macOS SwiftUI 应用界面
Tests/EnvLauncherCoreTests/  核心逻辑测试
Resources/                   应用图标资源
scripts/                     测试与打包脚本
dist/                        本地打包产物

代理行为说明

EnvLauncher 是“应用级环境注入”，不是系统级代理管理器。

• 它不会修改 macOS 系统代理、PAC、Wi-Fi 网络设置。
• 对 GUI 应用，代理是否生效取决于目标应用是否读取环境变量或 Chromium proxy 参数。
• 对 CLI 工具，通常依赖 HTTP_PROXY / HTTPS_PROXY / ALL_PROXY 是否被该工具支持。
• 对 SOCKS5-only 配置，EnvLauncher 会尽量通过本地 HTTP bridge 提高 CLI 兼容性。

如果目标应用完全忽略环境变量和启动参数，EnvLauncher 无法强制接管其网络栈。

版本

当前打包版本：0.1.1 (2)。