Skip to content

Troubleshooting

Jump to bottom
quangchibui79-blip edited this page Sep 8, 2026 · 18 revisions

故障排查

先看状态与脱敏诊断

Windows：

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

macOS/Linux：

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

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

Windows/macOS 仍然需要多次重连

  1. 确认代理软件已经运行，并开放 HTTP/HTTPS、SOCKS5 或混合端口；
  2. Windows 先运行 Status.ps1，查看 StreamingProxyGuaranteed、EffectivenessEvidence 和 GuardianState；
  3. 若为 SystemProxyHttpTrafficOnly，完成当前任务后同意一次修复提示，或关闭 Codex 后从 Codex (Managed Proxy) 打开；
  4. 若已是 ManagedTrafficObserved 且 Guardian 同期没有 codex_restart / proxy_changed，请检查代理节点的 TLS/WebSocket 重置和上游超时；
  5. 默认自动模式仍不稳定时，再尝试严格模式；提交 Issue 时附上 Doctor 的脱敏输出。

Guardian 没有重启，但 Codex 仍显示“正在重新连接”

先对照发生时间查看 Guardian 日志。存在 codex_restart 或 proxy_changed，才有 Guardian 生命周期动作的证据。如果同一时间没有这两个事件，而代理或 Codex 日志出现 TLS EOF、WebSocket reset、Windows 10054 或请求超时，那么被中断的通常是代理上游的流式连接，不是 Guardian 关闭了应用。

v1.6.1 起，Guardian 会监听 Codex 日志并在发现 WebSocket/流式失败后立即重新验证；状态里的 reconnectSignalsDetected、lastReconnectCategory、lastReconnectErrorClass 和 reconnectListenerAction 可用于判断监听是否捕获到真实信号。监听只会复核代理，不会因为“正在重新连接”就关闭 Codex。

Windows 设置页会直接显示归因说明；状态与 Doctor 会列出重连含义、应核对的事件、常见上游信号以及“Guardian 不管理服务商节点”的边界。ProxyCriticalTargetsPassed 与 ProxyCriticalFailures 仍用于判断 chatgpt.com 等关键入口能否通过。Guardian 可以尝试其他已发现的地址或协议，但不会擅自切换代理软件中的服务商节点。若代理软件日志出现上游 i/o timeout，请在代理软件里选择更稳定的节点。

Windows/macOS 桌面应用反复重启

Windows 请先升级到 v1.5.1 或更高版本。v1.4.2 对混合端口的修复不完整，已标记为被取代的预发布版；v1.5.0 及更早版本又可能把普通启动的系统代理 HTTP 流量误当成流式代理已完整继承。

立即切回自动模式。v1.5.3 的确认窗口只有明确点击“重启Codex”才会关闭并重启；选择“60分钟后再提醒我”、关闭窗口、超时或提示失败都会保留当前任务。窗口可以最小化，达到次数限制后熔断器仍会阻止继续重启；不要关闭熔断后反复尝试。

macOS 请先切回自动模式。达到次数限制后熔断器会阻止继续重启。检查最近日志中的代理候选变化和修复原因，不要关闭熔断后反复尝试。

如果 GuardianState=CodexCompatibilityReviewRequired，表示新 Codex 的受管启动或新鲜流量证据无法确认。Guardian 已停止自动生命周期操作、保持现有 Codex，并继续即时和每日检查适配更新；不要删除 state.json 或提高重启上限绕过保护。

Linux 普通 codex 没有使用新代理

这是预期的平台边界。后台程序不能安全改写已经启动的终端环境。请运行：

codex-guard
codex-guard resume --last

codex-guard 会注入 Guardian 当前已验证的代理并透传全部参数。Guardian 不会结束或重启交互式 CLI 会话。

Guardian 找不到代理

Guardian 支持带明确端口的 HTTP/HTTPS、SOCKS5/SOCKS5H 代理，也支持系统 PAC/WPAD。先检查代理软件是否真的暴露了代理端口；仅 TUN、SOCKS4 或带账号密码的代理 URL 不会被采用。

Windows 在安装目录的 config.json 设置：

{
  "ExplicitProxy": "http://127.0.0.1:7890"
}

纯 SOCKS5 可写为 "ExplicitProxy": "socks5h://127.0.0.1:1080"。需要指定 PAC 时使用：

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

macOS 配置位于 ~/Library/Application Support/CodexProxyGuardian/config.json；Linux 位于 ${XDG_CONFIG_HOME:-~/.config}/codex-proxy-guardian/config.json，使用同一字段。请把地址和端口换成代理程序实际提供的值。PAC 下载、执行和缓存都有时间/大小上限；无法安全验证时会保持原状。

macOS 找不到桌面应用

确认 ChatGPT/Codex 位于 /Applications 或 ~/Applications。状态显示 CodexApplicationUnavailable 时，可在配置中的 MacApplicationPaths 增加准确路径。Guardian 不会用模糊进程名去终止未知应用。

后台服务没有运行

  • **Windows：**在设置窗口查看安装状态，或重新运行安装器修复当前用户计划任务。
  • **macOS：**运行 launchctl print gui/$(id -u)/io.github.ch-zhou-0512.codex-proxy-guardian；重新执行 ./install.sh 可修复 LaunchAgent。
  • **Linux systemd：**运行 systemctl --user status codex-proxy-guardian.service；没有用户 systemd 时检查 ~/.config/autostart/codex-proxy-guardian.desktop。

自动更新失败

先手动检查：

.\Control.ps1 -Action CheckUpdate

或：

codex-proxy-guardian update

Windows 更新日志位于安装目录 logs\update-*.jsonl。macOS 日志位于 ~/Library/Application Support/CodexProxyGuardian/logs；Linux 日志位于 ${XDG_STATE_HOME:-~/.local/state}/codex-proxy-guardian/logs。更新校验或安装失败时会保留当前版本或回滚，不会修改系统代理。

Settings 从 v1.4.4 起会区分“更新器正忙，本次没有执行检查”和“检查完成，没有更高版本”，并显示本机版本、远端版本、通道、时间和 GitHub Releases 来源。看到“检查尚未完成”时稍后重试，不要把它解释为已经是最新版。

v1.6.1 起再查看 NetworkRoute、最终更新事件与 UpdateRetryAfterUtc：Windows 更新器优先使用系统自带 curl.exe，代理限流时会明确记录 WindowsDirectRoute 直连回退；Codex 版本触发的失败检查会在同一版本上自动重试。若更新计划任务丢失，Guardian 会从安装目录内的已校验更新器兜底执行。

v1.5.4 起，自动更新成功会记录 automatic_update_notification_shown 并发送一次桌面通知；若系统通知不可用则记录 automatic_update_notification_failed，但不影响已经完成的更新。通知会明确 Codex 无需重启，同一版本不会在每次登录重复出现。

Codex 更新后又开始重连

先查看 Status.ps1 与 Doctor.ps1 -Online：

  • ObservingAfterCodexUpdate：Guardian 正在等待至少 60 秒、3 次新鲜关键入口验证；不要把一条旧连接当作新版本已稳定。
  • UpstreamSuspected：本地代理端口可达，但关键外部验证失败。Guardian 会保留 Codex，不会切换服务商节点；请检查代理软件的上游日志或手动换稳定节点。
  • CodexCompatibilityReviewRequired：新版本的启动入口或代理证据无法确认。Guardian 已暂停自动修复并保持 Codex 打开，同时会继续按正式通道检查适配更新。
  • Compatible 且没有 codex_restart / proxy_changed：界面重连更可能来自流式链路或上游节点，不应归因于 Guardian 重启。

若 StreamingProxyGuaranteed=false 或 EffectivenessEvidence=SystemProxyHttpTrafficOnly，打开 Settings，点击 优化流式连接（会先征求你的同意）。按钮只发起受管修复请求；Guardian 必须再次取得前台的“重启Codex”确认后才会关闭 Codex。若已经是 ManagedTrafficObserved，且同期没有 codex_restart / proxy_changed，请排查代理节点的 TLS/WebSocket 重置或上游超时。

短 HTTPS 探测与本地 TCP 元数据只能给出间接证据，无法从外部证明登录态长时间 SSE/HTTP 流绝对稳定；因此状态会如实显示 StreamStability=IndirectEvidenceOnly。

提交 Issue 时请附上脱敏 Doctor JSON，不要直接上传可能含私人路径的完整日志。

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

Codex Proxy Guardian

Clone this wiki locally