AI Agent / 系统课时
排查常见运行问题
排查常见运行问题
运行异常最怕凭感觉反复重装。本课把安装、认证、上下文、权限、环境、MCP 与云端任务放进同一条证据链,先确认故障发生在哪一层,再做最小修复,并用同一条件复验结果。
学习目标
- 用固定顺序区分安装、认证、上下文、权限与环境问题
- 定位 MCP 服务不可用和本地、云端环境不一致
- 在最小改动后完成可重复的故障复验
先固定故障现场
排障第一步不是“再试一次”,而是保存失败条件。至少记录使用的 Codex 入口、仓库与分支、当前目录、原始报错、触发命令,以及问题只发生在本地还是云端。不要同时重装 CLI、切账号、改权限和改配置,否则即使恢复也无法确认根因。
在 CLI 可执行的机器上,先采集一个最小诊断快照。下面的脚本会确认二进制位置、当前目录、Git 根目录,并调用 codex doctor 生成本机诊断报告。
set -u
if ! command -v codex >/dev/null 2>&1; then
printf 'codex=<NOT_FOUND>\n'
exit 127
fi
printf 'codex=%s\n' "$(command -v codex)"
printf 'cwd=%s\n' "$PWD"
git rev-parse --show-toplevel 2>/dev/null || printf '<NOT_A_GIT_REPOSITORY>\n'
codex doctor预期输出
codex=<PATH>/codex
cwd=<PATH>
<REPOSITORY_ROOT_OR_NOT_A_GIT_REPOSITORY>
<CODEX_DIAGNOSTIC_REPORT>实际路径和诊断内容会随机器不同。若第一行就得到 <NOT_FOUND>,优先修复安装或 PATH;若二进制存在,再继续查看认证、配置、运行时、Git 和终端等诊断项。交互式会话能启动时,还可以用 /status 核对当前目录、模型、权限与可写范围。
按层定位而不是重试
同一个“Codex 不能工作”可能来自完全不同的层。按从入口到外部依赖的顺序排查,可以避免把权限问题误判成认证失败,也能避免在错误仓库里继续调试。
| 层级 | 典型现象 | 先验证什么 | 常见修复 |
|---|---|---|---|
| 安装 | codex 找不到或启动异常 |
二进制位置、诊断报告、版本更新路径 | 修复 PATH,使用受支持的安装或更新方式 |
| 认证 | 无法进入会话、账号或工作区不符合预期 | 当前登录身份、工作区、认证诊断 | 重新完成登录,并确认进入正确账号与工作区 |
| 上下文 | 读错文件、找不到项目约束 | pwd、Git 根目录、相关 AGENTS.md |
从正确仓库启动,必要时显式指定工作目录 |
| 权限 | 能读不能写,命令或网络被阻止 | /status、/permissions、沙箱拒绝信息 |
只增加任务需要的权限或目录,不扩大到整机 |
| 环境 | 构建工具、运行时或依赖缺失 | PATH、语言版本、依赖安装状态 |
让 Codex 使用与项目一致的工具链 |
| MCP | 工具缺失、启动超时、OAuth 失败 | codex mcp list、TUI 中的 /mcp、服务端日志 |
修复命令或 URL、环境变量、认证和超时设置 |
| 云端任务 | 本地通过、云端失败 | 仓库、依赖、变量、密钥、网络与任务日志 | 把本机隐式条件显式写入云端环境配置 |

处理 MCP 与云端差异
MCP 排障先确认“配置存在”还是“服务可用”。codex mcp list 用来查看已配置服务,TUI 中的 /mcp 用来确认当前会话看到的活动服务;需要 OAuth 的服务应单独完成认证。若服务能启动但工具调用超时,再检查服务端进程、环境变量、网络可达性以及启动和工具执行超时。
云端任务则要把“我的电脑上已经有”全部视为可疑前提。云端环境是隔离的,仓库之外的全局包、本地凭据、私有证书、代理配置和未声明的环境变量不会因为本地存在就自动成立。遇到本地通过、云端失败时,从任务日志最早的异常开始,依次核对 checkout、依赖安装、构建命令、密钥、外网访问和运行时版本。
如果错误只在某个表面出现,例如 CLI 正常而云端异常,不要继续修改公共代码。先构造最小复现:同一提交、同一命令、尽可能相同的运行时和依赖。差异越少,越容易证明问题属于环境而不是代码。
修复后做同条件复验
有效修复必须能解释“哪条证据改变了”。复验时保持原始仓库、分支、输入和目标命令不变,只保留一个已经确认的修复项;然后再次运行原失败命令,并检查副作用,例如权限是否过宽、MCP 是否仍可认证、云端环境是否能从零初始化。
最后记录三件事:现象是什么、根因证据是什么、最小修复是什么。若问题以后可能复发,就把修复落到 AGENTS.md、环境配置、依赖锁定、MCP 配置或团队 Runbook,而不是只留在某个人的终端历史里。