AI Agent / 系统课时

排查常见运行问题

排查常见运行问题

运行异常最怕凭感觉反复重装。本课把安装、认证、上下文、权限、环境、MCP 与云端任务放进同一条证据链,先确认故障发生在哪一层,再做最小修复,并用同一条件复验结果。

学习目标

  • 用固定顺序区分安装、认证、上下文、权限与环境问题
  • 定位 MCP 服务不可用和本地、云端环境不一致
  • 在最小改动后完成可重复的故障复验

先固定故障现场

排障第一步不是“再试一次”,而是保存失败条件。至少记录使用的 Codex 入口、仓库与分支、当前目录、原始报错、触发命令,以及问题只发生在本地还是云端。不要同时重装 CLI、切账号、改权限和改配置,否则即使恢复也无法确认根因。

在 CLI 可执行的机器上,先采集一个最小诊断快照。下面的脚本会确认二进制位置、当前目录、Git 根目录,并调用 codex doctor 生成本机诊断报告。

bash
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

预期输出

text
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、环境变量、认证和超时设置
云端任务 本地通过、云端失败 仓库、依赖、变量、密钥、网络与任务日志 把本机隐式条件显式写入云端环境配置

Codex 运行问题分层排查流程

处理 MCP 与云端差异

MCP 排障先确认“配置存在”还是“服务可用”。codex mcp list 用来查看已配置服务,TUI 中的 /mcp 用来确认当前会话看到的活动服务;需要 OAuth 的服务应单独完成认证。若服务能启动但工具调用超时,再检查服务端进程、环境变量、网络可达性以及启动和工具执行超时。

云端任务则要把“我的电脑上已经有”全部视为可疑前提。云端环境是隔离的,仓库之外的全局包、本地凭据、私有证书、代理配置和未声明的环境变量不会因为本地存在就自动成立。遇到本地通过、云端失败时,从任务日志最早的异常开始,依次核对 checkout、依赖安装、构建命令、密钥、外网访问和运行时版本。

如果错误只在某个表面出现,例如 CLI 正常而云端异常,不要继续修改公共代码。先构造最小复现:同一提交、同一命令、尽可能相同的运行时和依赖。差异越少,越容易证明问题属于环境而不是代码。

修复后做同条件复验

有效修复必须能解释“哪条证据改变了”。复验时保持原始仓库、分支、输入和目标命令不变,只保留一个已经确认的修复项;然后再次运行原失败命令,并检查副作用,例如权限是否过宽、MCP 是否仍可认证、云端环境是否能从零初始化。

最后记录三件事:现象是什么、根因证据是什么、最小修复是什么。若问题以后可能复发,就把修复落到 AGENTS.md、环境配置、依赖锁定、MCP 配置或团队 Runbook,而不是只留在某个人的终端历史里。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查常见运行问题

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通