codex doctor 是 Codex CLI 自带的环境自检命令，依次检查配置文件语法与字段合法性、运行时目录读写权限、依赖组件版本匹配性及最小会话连接可达性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你在终端里执行 codex 命令却卡住、报错或根本没反应，又找不到日志入口时，codex doctor 就是你手边最直接的“体检报告生成器”——它不依赖 UI，不等待网络，只检查本地运行环境是否完整合规。
确认 CLI 已正确安装并可调用
在终端中输入 codex --version，回车。如果返回类似 codex 0.131.0 的版本号，说明 CLI 可执行；若提示 command not found，请先完成安装（npm / Homebrew / 二进制方式任选其一），再继续下一步。
这一步必须通过，否则 codex doctor 根本不会启动。很多用户跳过验证直接跑 doctor，结果连命令都不存在，白等几秒后误以为是 doctor 失败。
运行 codex doctor 获取环境快照
直接在任意路径下执行：codex doctor
命令会依次检查：配置文件是否存在且语法合法 → config.toml 中关键字段值是否有效（如 openai_base_url 是否为空或格式错误）→ 运行时目录（如 ~/.codex/runtime）是否可读写 → 依赖组件（如 sandbox runner、model adapter）版本是否匹配当前 CLI → 最后尝试建立一次最小会话连接。
输出按模块分段，每段开头有状态标记：[✓] Config OK、[!] Runtime dir permission denied、[⚠] openai_base_url unreachable。你要做的，就是盯住所有带 [!] 或 [⚠] 的行——它们就是故障锚点。
解读 doctor 输出中的关键失败项
方法一：关注「Config」段落下的报错
如果出现 [!] Config: syntax error at line 5, column 12，说明 ~/.codex/config.toml 第 5 行存在 TOML 语法错误（比如漏了引号、多了一个逗号）。此时不要改其他行，直接定位到那一行修正即可。
通过本地 Codex 或 OpenClaw OAuth 凭证直接调用 ChatGPT/Codex Responses 的 image_generation 工具来生成或编辑光栅图像，然后保存
方法二：关注「Runtime」段落中的权限提示
若显示 [!] Runtime: cannot write to ~/.codex/runtime，常见于 Windows 上该目录被杀毒软件锁定，或 macOS/Linux 下目录属主不是当前用户。【务必用当前登录用户身份运行 terminal，不要用 sudo 启动 codex doctor】 否则 doctor 检查的是 root 权限下的环境，和桌面版实际运行环境完全脱节。
方法三：看「Connection」段是否超时
出现 [⚠] Connection: timeout after 3s to https://api.qnaigc.com/v1/models，说明你配置的 openai_base_url 虽然格式正确，但服务端不可达。这时应暂停修改 config.toml，先用 curl -v https://api.qnaigc.com/v1/models 手动测试连通性，排除代理或 DNS 问题。
根据 doctor 结果快速修复（排序操作）
第一步：如果 doctor 明确指出 config.toml 解析失败，立即用编辑器打开该文件：code ~/.codex/config.toml（VS Code）或 notepad ~/.codex/config.toml（Windows）。
第二步：对照报错行号，检查引号闭合、布尔值是否写成 true（不能是 True 或 "true"）、URL 是否含中文字符或全角符号。
第三步：保存后，**不要重启终端**，直接再次运行 codex doctor。CLI 会热加载配置，无需重新安装或清理缓存。
第四步：若 doctor 全部显示 [✓]，但 codex 仍无法启动，请执行 codex --sandbox read-only 测试最小沙盒是否可用——这是 doctor 不覆盖但最常出问题的环节。
