Skip to content

About

Codex CLI 连接诊断:检查配置、代理和网络,生成本地脱敏报告。 | Codex CLI connection diagnostics: check config, proxy and network; generate local redacted reports.

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Agent Connection Doctor

AI 工具连不上?先把安装、配置、代理和网络分开检查。

English · 下载源码 ZIP · Windows 构建 · 反馈问题

Tests Python 3.11+ License MIT

模拟诊断报告预览,非实测结果

一个面向 Codex CLI 的开源连接诊断工具。无需 API Key,无第三方运行依赖,在本机生成 HTML 和 JSON 报告。当前为 v0.1.0 初始版本,优先面向 Windows,Linux 可运行。

30 秒体验

下载并解压源码,需要 Python 3.11 或更新版本。在解压目录打开 PowerShell:

# 先看模拟报告:不读取本机配置,不联网
py -3 run_doctor.py --demo --open

# 正式检查:安装、用户配置、代理和网络
py -3 run_doctor.py --open

也可双击 Start-Windows.cmd。它会检查 Python 版本,执行正式检测,再打开本地报告。若要排查某个终端的环境,请直接在那个终端运行命令;双击启动的进程环境可能不同。

没有 Python?在 Actions 最近一次成功运行的 Artifacts 中下载 AgentConnectionDoctor-Windows-x64(需登录 GitHub),解压后在 PowerShell 中执行:

.\AgentConnectionDoctor.exe --open

构建产物只有在 CI 的测试与打包任务成功后才会出现,有效期 30 天。EXE 尚未签名,系统可能显示发布者验证提示;不要为运行它关闭安全软件。不希望运行 EXE 时,可以审阅并运行源码。

Linux 使用 python3 run_doctor.py --open,同样需要 Python 3.11+。

它能告诉你什么

检查 结果 明确边界
Codex 启动入口 PATH 中没有入口,或存在多个安装目录 不扫描磁盘,不推断桌面版是否安装
用户配置 TOML 语法错误、提供商/配置档案设置存在 不验证全部配置语义,不合并项目配置
代理环境变量 格式错误、大小写冲突、选定代理端口是否可连接 不读取 Windows 系统代理/PAC,不判断 TUN
HTTPS 探测 分别记录直连/HTTP 代理的响应、超时、DNS 和 TLS 错误 不测试账户登录、模型调用、SSE 或 WebSocket
可选日志 连接/证书/401/403/429/超时的文本命中数量 只扫描末尾 256 KiB,不输出原文,可能包含旧错误

收到 HTTP 401 也能证明探测请求收到了响应,但不能证明账号正常。403 也不能单独证明封号或地区限制。 本工具会保留这些区别,不把所有问题都判成“代理坏了”。

常用命令

# 只检查本地信息,完全跳过网络探测
py -3 run_doctor.py --offline --open

# 检查你明确指定的配置和日志,输出到新目录
py -3 run_doctor.py --config "C:\path\config.toml" --log "C:\path\codex-tui.log" --output reports\first-run

# 用自定义 HTTPS 地址替换默认探测目标(最多 3 个)
py -3 run_doctor.py --endpoint https://example.com/v1/models --timeout 4 --open

# 可选执行 PATH 中的原生 Codex 程序读取版本
py -3 run_doctor.py --check-version

--endpoint 不接受用户名、密码、查询参数或 fragment;请勿在 URL 路径中放密钥。默认目标为 chatgpt.com、auth.openai.com、api.openai.com/v1/models。它们只是公共连接测试点,不代表本机 Codex 实际使用的提供商或请求地址。

默认不运行任何 Codex 程序。--check-version 是显式选择;脚本启动器 .cmd/.bat/.ps1 会跳过,由用户手动运行 codex --version。

默认报告保存到系统临时目录的新文件夹,命令行显示具体位置。长期保留请使用 --output。已有 report.html 或 report.json 时拒绝覆盖。默认退出码:完成报告为 0,参数/写入错误为 2;加 --strict 后,存在 fail 结果时为 1。

隐私和网络行为

  • 只读取 PATH、相关环境变量和用户配置;支持 CODEX_HOME。不会自动读取登录令牌、auth.json、系统凭据或聊天记录。
  • 配置、日志通过固定类别提取信息;报告不包含原文、密钥、用户名、本机安装路径或自定义目标地址。
  • 只在显式 --log 时读取指定文件的末尾;不会自动搜索日志。分享前仍请检查报告。
  • 正式网络检测会向目标发出 HEAD 请求;不发送 API Key、登录 Cookie 或请求正文,不读取响应正文,不跟随重定向,没有遥测或上传功能。
  • 含用户名/密码的代理会跳过。HTTP 代理支持 CONNECT;HTTPS/SOCKS 代理只测 TCP 端口。
  • 本工具的代理选择顺序是 https_proxy → HTTPS_PROXY → all_proxy → ALL_PROXY → http_proxy → HTTP_PROXY,不声称这是 Codex 的规则。为比较线路,显式代理测试忽略 NO_PROXY;直连测试不采用代理环境变量,但仍可能经过 TUN/透明代理。
  • Python 的证书库与目标工具可能不同。每次网络探测运行于可终止子进程,包含 DNS 在内的总时间有上限(超时值 + 2 秒启动余量)。
  • 不修改环境变量的持久设置,不修改系统代理,不安装软件,不自动执行修复建议,不关闭 TLS 验证。

开发与验证

python -m unittest discover -s tests -v
python run_doctor.py --demo --output reports/demo

CI 在 Windows/Linux、Python 3.11/3.12 上运行测试,并打包、冒烟测试 Windows EXE。测试包含秘密不外泄、错误归因、配置不变、超时、回环 TCP、离线模式和报告转义;不依赖真实账号或外网。CI 通过不等于已经在用户的实际代理/证书环境验证。

阅读 架构与诊断边界、贡献指南 和 安全反馈。配置路径和分层参考 OpenAI 配置文档;实际行为可能随 Codex 版本变化。

接下来优先做什么

  • 收集至少 5 个真实故障场景,记录能否缩短排查时间。
  • 根据误诊/漏诊反馈补充测试及检查规则。
  • 验证 Windows 系统代理与终端环境的差异,再决定是否支持。
  • 验证后再增加其他 AI 编程工具适配。

如果它帮你定位了问题,欢迎 Star;更有价值的是提交一个不含敏感信息的反馈。尚无真实用户效果或准确率声明。

MIT License · 独立社区项目,与 OpenAI 无隶属关系。

About

Codex CLI 连接诊断:检查配置、代理和网络,生成本地脱敏报告。 | Codex CLI connection diagnostics: check config, proxy and network; generate local redacted reports.

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages