Getting Started

安装与日常使用

先确认适用环境

平台	支持范围
Windows 11	x64 / ARM64，Store / MSIX Codex 桌面端，PowerShell 5.1 或 7
macOS	Intel / Apple Silicon，ChatGPT / Codex 桌面应用
Linux	x64 / ARM64，官方 Codex CLI；GNOME 系统代理可自动读取，其他桌面可指定代理

本机还需要已有可用的 HTTP/HTTPS、SOCKS5 代理端口，或已由系统配置的 PAC/WPAD，例如 Clash、Mihomo、v2rayN、sing-box 提供的监听。仅 TUN 且不暴露代理端口、SOCKS4 和带账号密码的代理 URL 暂不支持。

PAC/WPAD 默认自动发现。如果系统配置无法读取，可在安装目录的 config.json 中指定：

{
  "ExplicitPAC": "https://example.com/proxy.pac"
}

Guardian 会按实际 Codex 目标解析 PAC，再用解析出的端点发起真实 HTTPS 验证；如果不能安全得到一个可共用的有效端点，就保持原状而不猜测。

Windows 安装

推荐：一键安装

从最新正式版下载 CodexProxyGuardian-Setup-版本号.exe，双击后确认界面中的仓库地址为 CH-ZHOU-0512/codex-proxy-guardian，再点击“立即安装”。它只安装到当前用户，无需管理员权限。v1.4.0 起，窗口会按实际解压字节和已完成安装阶段显示 0–100% 进度，并说明当前正在检查或等待什么。v1.4.1 起，完成前还会核对 Guardian PID 与安装路径，意外退出时安全重试一次。

项目目前没有商业代码签名证书，Windows SmartScreen 可能显示无法识别提示。只应从本仓库正式 Release 下载并核对 .sha256；不确定来源或企业策略阻止未签名 EXE 时，使用下面的 ZIP 方式，不要关闭 Windows 安全功能。

备用：ZIP 手动安装

下载 CodexProxyGuardian-版本号.zip 与对应 .sha256，解压后在普通权限 PowerShell 中执行：

Unblock-File .\Install.ps1
.\Install.ps1

默认安装到 %LOCALAPPDATA%\CodexProxyGuardian，创建登录自启、每日安全更新任务、设置入口和 Codex (Managed Proxy) 确定性快捷方式。

Windows 日常推荐从开始菜单打开 Codex (Managed Proxy)。它会为新 Codex 进程树同时注入 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、WS_PROXY、WSS_PROXY（含小写形式）和 Chromium 代理参数。继续点原来的 Codex 图标也可以；如果只观察到系统代理 HTTP 流量、还不能证明流式连接已继承显式代理，Guardian 会在防抖后询问是否切换。只有明确点击“重启Codex”才会执行；选择“60分钟后再提醒我”、关闭或最小化确认窗口，都不会立即中断当前任务。

macOS 安装

在 Release 中按 CPU 下载：

• Apple Silicon：CodexProxyGuardian-版本号-darwin-arm64.tar.gz
• Intel：CodexProxyGuardian-版本号-darwin-amd64.tar.gz

解压并安装：

tar -xzf CodexProxyGuardian-版本号-darwin-架构.tar.gz
cd CodexProxyGuardian
./install.sh
codex-proxy-guardian status

安装器复制到 ~/.local/lib/codex-proxy-guardian，创建当前用户 LaunchAgent 并立即静默启动。以后照常打开 ChatGPT/Codex。

Linux 安装

在 Release 中按 CPU 下载 linux-amd64 或 linux-arm64 包，然后：

tar -xzf CodexProxyGuardian-版本号-linux-架构.tar.gz
cd CodexProxyGuardian
./install.sh
codex-proxy-guardian status
codex-guard

安装器优先创建 systemd 用户服务，不可用时回退到 XDG Autostart，不使用 sudo。日常请用 codex-guard 代替 codex；例如：

codex-guard resume --last

它会把当前已验证代理注入新启动的官方 Codex CLI，保留 TTY 和全部参数。直接运行普通 codex 仍取决于当前 shell 自己的代理环境；后台程序无法在事后改写另一个已启动终端的环境。

如果命令找不到，请把 ~/.local/bin 加入当前 shell 的 PATH，或直接运行 ~/.local/lib/codex-proxy-guardian/codex-proxy-guardian。

安装后还要做什么

• **Windows：**不需要先开终端或守护程序；推荐打开 Codex (Managed Proxy)。原图标仍可使用，必要时 Guardian 会先询问是否受管修复。
• **macOS：**不需要先开终端或守护程序，照常打开桌面应用。
• **Linux：**守护服务会自动运行，但启动 Codex CLI 时要用 codex-guard。
• **所有平台：**Guardian 不会修改系统代理、DNS、路由、防火墙或永久环境变量。

查看状态与诊断

Windows：

cd $env:LOCALAPPDATA\CodexProxyGuardian
.\Status.ps1
.\Doctor.ps1 -Online

Windows v1.5.2 的状态会显示 CodexCompatibilityState、兼容证据、更新检查结果、更新网络路线、失败重试时间、更新后观察样本和 StreamStability。重点看：

• StreamingProxyGuaranteed=true：已同时观察到受管启动和实际代理流量；
• EffectivenessEvidence=SystemProxyHttpTrafficOnly：只能证明普通 HTTP 走了系统代理，不能证明 WebSocket/流式子进程已继承显式代理；
• GuardianState=ObservingAfterCodexUpdate：Codex 刚更新，正在重新累计新鲜证据；
• GuardianState=CodexCompatibilityReviewRequired：当前机制无法安全确认，Guardian 已保持现有 Codex 并等待适配更新。

macOS/Linux：

codex-proxy-guardian status
codex-proxy-guardian status --json
codex-proxy-guardian doctor

卸载

Windows 在安装目录运行：

.\Uninstall.ps1

macOS/Linux 在解压目录运行（目录已删除时可重新下载同平台包）：

./uninstall.sh          # 保留配置和日志
./uninstall.sh --purge  # 同时删除本项目的本地数据

卸载脚本只删除本项目拥有且经过核对的当前用户资源。

---

返回首页 · 本文档已与正式版 v1.5.4 同步。