AI 工具连不上?先把安装、配置、代理和网络分开检查。
English · 下载源码 ZIP · Windows 构建 · 反馈问题
一个面向 Codex CLI 的开源连接诊断工具。无需 API Key,无第三方运行依赖,在本机生成 HTML 和 JSON 报告。当前为 v0.1.0 初始版本,优先面向 Windows,Linux 可运行。
下载并解压源码,需要 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/demoCI 在 Windows/Linux、Python 3.11/3.12 上运行测试,并打包、冒烟测试 Windows EXE。测试包含秘密不外泄、错误归因、配置不变、超时、回环 TCP、离线模式和报告转义;不依赖真实账号或外网。CI 通过不等于已经在用户的实际代理/证书环境验证。
阅读 架构与诊断边界、贡献指南 和 安全反馈。配置路径和分层参考 OpenAI 配置文档;实际行为可能随 Codex 版本变化。
- 收集至少 5 个真实故障场景,记录能否缩短排查时间。
- 根据误诊/漏诊反馈补充测试及检查规则。
- 验证 Windows 系统代理与终端环境的差异,再决定是否支持。
- 验证后再增加其他 AI 编程工具适配。
如果它帮你定位了问题,欢迎 Star;更有价值的是提交一个不含敏感信息的反馈。尚无真实用户效果或准确率声明。
MIT License · 独立社区项目,与 OpenAI 无隶属关系。