你在 Codex CLI 里配好 MCP 服务器，一跑就报错：有的说连不上，有的进度条转半天，有的干脆把工具列表返回成空。这类报错信息往往只有一行，看不出是配置写错、进程没起来，还是网络被挡。这篇不讲 MCP 是什么，只讲报错怎么分层看、按什么顺序查、每层该抓哪几个证据，让你少在猜测里绕圈。
在 Codex CLI 里配好一个 MCP 服务器，跑起来却直接报错：有的一行字说连不上，有的进度条转半天没动静，有的不报错但工具列表返回成空。这时候最容易犯的错是立刻去翻配置文件逐行改，结果改了三四处反而不知道是哪一步起的作用。
这篇不讲 MCP 是什么，只讲报错怎么分层看、按什么顺序查、每层该抓哪几个证据。核心思路很简单：先看第一个报错的原文，把它归到某一层，再在那一层里动手。分类不清就动手，等于在猜。
先把报错分层：别一上来就翻配置
MCP 报错大致落在四层：进程启动层、协议握手层、工具枚举层、调用执行层。报错文案长什么样，基本决定了你该从哪层切进去。同一个「失败」字样出现在不同层，原因和修法完全不一样。
- 启动层：报错里出现命令名、路径、权限、模块找不到这类词
- 握手层：报错里出现连接、断开、传输、协议、握手这类词
- 工具枚举层：能连上但工具列表是空的，或者只列出一部分
- 调用执行层：工具能列出来，一调就报参数错误、返回异常或直接超时
还有一个低成本习惯：改配置时一次只改一个变量，改完立刻复跑，把结果记下来。同时改三处再测，即使好了你也不知道是哪处生效，下次同类问题还是不会修。
进程起不来和握手失败怎么分
这两种最容易混，因为表面都是「启动失败」。判断办法是绕开 Codex，直接在你配的那条启动命令上手动跑一遍。手动跑得通、Codex 里起不来，问题多半在环境变量或工作目录；手动也跑不通，就先别怀疑 Codex，把命令本身修好。
| 现象 | 常见原因 | 先查什么 |
|---|---|---|
| 提示找不到命令 | 命令不在当前 PATH 里 | 用绝对路径手动跑一次 |
| 提示没有执行权限 | 可执行位没打开或用了错的解释器 | 看文件权限和启动方式 |
| 一启动就退出 | 依赖没装齐或工作目录不对 | 进到目标目录手动跑，看缺什么 |
| 连上很快断开 | 版本或传输方式对不上 | 确认是本地标准输入输出还是远程 HTTP |
握手层还有一类隐蔽情况：传输方式选错了。本地进程走标准输入输出和走远程 HTTP 是两套东西，配错的话表面上「连上了」，实际协议对不上，很快就被断开。看日志里有没有协议协商阶段的信息，比反复改超时值管用。
工具列表为空、调用参数被拒怎么处理
能连上但工具列表是空的，先别怀疑协议。常见原因是服务器要求鉴权而你没带凭据，或者工具按需加载、需要先触发某个开关，再或者 Codex 侧有过滤配置把它挡掉了。这三条按顺序排一遍，多数空列表都有解释。
- 确认服务器侧是否要求凭据用不带凭据的方式手动调一次，看返回是空列表还是明确的鉴权错误。
- 确认工具是不是按需加载查服务器的加载策略，必要时先调用一次激活动作再看列表。
- 确认 Codex 侧没有过滤看客户端配置里有没有白名单、开关或作用域设置把工具排除了。
- 验证结果改完只复跑工具列表这一步，列表有内容了再进到调用环节。
调用就报错的话，优先核对参数形状，而不是模型能力。高频就三类：类型不符（该传数字传了字符串）、多包了一层（参数被整体塞进某个字段）、必填缺失。做法是先用最小参数跑通一次，再逐项把参数加回去，看是哪一项把请求带崩的。
转圈、超时、日志该留什么
超时最容易被当成一个笼统问题处理，其实要先区分是连接慢、工具执行慢，还是模型生成慢。连接慢是链路和鉴权问题，工具执行慢是服务端任务本身重，模型生成慢和 MCP 关系不大。三者处理方向不同，别用一个超时值硬扛全部。
一个直接有效的动作：把服务器侧日志和 Codex 侧日志的时间戳对齐看。哪一段耗时最长、最先出现异常，卡在哪一跳就一目了然，比单看某一侧日志快得多。
- 时间：调用发起的时刻
- 工具名：这次调的是哪个工具
- 参数摘要：只留字段名和形状，别整段抄参数值
- 耗时：从发出到返回总共多久
- 结果状态：成功、失败还是超时
长期做法就是留一份这样最小化的调用日志。出问题时不用重现现场，翻日志就能定位。日志里别写敏感值，留字段形状就够了。
哪些情况这套排查不适用
上面这套是按客户端视角分的层，有明确边界。碰到下面几种情况，别硬套，换方向更省时间。
- 自研 MCP 服务器且协议实现本身没跑通：问题在服务端，客户端排查只能帮你排除一半
- 中转或代理链路导致的报错：重点在网关和鉴权，不在 MCP 配置本身
- 报错文案指向额度、限流、账号状态：先按这类问题单独处理，别混进 MCP 排查
- 报错来自你装的第三方工具而非 Codex 本身：先确认报错归属，再决定查哪边
判断自己属于哪种情况的办法很直接：如果手动跑服务器进程本身就有问题，就先去修服务端；如果换一个已知可用的 MCP 服务器能正常跑通，那问题就在你原来的那条链路上。
下一步如果你怀疑是所选服务或中转链路的可信度问题，可以对照站内整理的服务清单和检测结果，先排除外部因素再回头调配置。→常见问题
MCP 报错是不是一定出在 Codex 这边？
不一定，而且反过来的概率不低。先手动把 MCP 服务器的启动命令跑一遍，能跑通再怀疑 Codex 侧配置；跑不通就先把服务器依赖、路径、权限理顺。分层排查的意义就是先确定责任在哪一侧，再动手改。
工具明明列出来了，调用却一直失败，问题在哪？
多数是参数形状或鉴权。先用最小必填参数调一次，能通就说明链路没断，再逐个加字段找出出错的那个；如果最小参数也不通，看服务器侧有没有独立鉴权要求。跟模型换不换没什么关系。
日志要开多细才够用？
够定位就够。建议至少记下调用时间、工具名、参数摘要、耗时和返回状态这几项，别把完整请求体全量落盘。真出问题时，有这几项就能判断是没发出去、发出去了没回，还是回了但解析失败。
