Codex MCP 连接失败怎么排查？STDIO、HTTP、OAuth 与超时完整清单

先说结论：不要把所有 MCP 故障都当作超时

这篇文章适合已经添加 MCP server，但在 ChatGPT 桌面端、Codex CLI 或 IDE 扩展中看不到 server、无法认证、没有工具，或者调用工具一直超时的开发者。OpenAI 当前文档说明，本地 Codex 客户端可以连接 STDIO 与 Streamable HTTP 两类 MCP server；桌面端、CLI 和 IDE 扩展在同一 Codex host 上共享 MCP 配置。

排查应按“配置是否生效→传输能否建立→认证是否完成→初始化是否结束→工具是否被发现→单次工具是否执行成功”推进。只有确认 server 正在正常启动但确实来不及就绪时，才考虑上调 startup_timeout_sec；HTTP 返回 401 / 403、命令不存在或工具被禁用，都不会因为增加等待时间而自动修复。

可从GPTUPCN 首页进入本站 Codex 实践栏目，配合Codex 权限与沙箱实践阅读。GPTUPCN 是第三方中文技术与服务入口，并非 OpenAI 官方；配置字段和产品行为应以当前官方文档及你所使用的 Codex 版本为准。

第一步：确认配置从哪里读取

Codex 默认把 MCP 配置放在用户级 ~/.codex/config.toml，也可以在受信任项目中使用项目级 .codex/config.toml。每个 server 使用 [mcp_servers.<server-name>] 表。先确认文件路径、TOML 语法和 server 名称，再确认当前项目是否受信任；不要看到文件存在就假定客户端已经加载。

桌面端可在 Settings 的 MCP servers 查看状态，保存后按官方流程 Restart；IDE 扩展也需要保存并重启扩展。CLI 可用 codex mcp list 查看已配置 server，在 TUI 中用 /mcp 查看活动状态。ChatGPT 网页不会读取本地 Codex 配置，网页场景需要安装提供远程 MCP 工具的插件，因此“CLI 有、网页没有”可能是执行面不同，不是同一配置丢失。

• 确认 section 名称是 mcp_servers，而不是自行改写的近似名称
• 确认用户级与项目级配置没有同名 server 造成误判
• 修改后重启对应客户端，再查看 server 状态
• 先用一个最小 server 验证配置链路，不要一次加入很多依赖
• 记录运行环境：桌面端、CLI、IDE 或 ChatGPT 网页

第二步：按 STDIO 与 Streamable HTTP 分流

STDIO server 由 Codex 启动本地命令，核心字段是 command；args、env、env_vars 和 cwd 用于补充参数、环境变量与工作目录。Streamable HTTP server 通过 url 访问远程地址，可使用 bearer token、OAuth、静态请求头或从环境变量读取的请求头。把 HTTP 地址写进 command，或把本地启动命令写进 url，都会在连接最前面失败。

STDIO 启动失败：从同一工作目录手动验证命令

STDIO 模式首先是一个本地进程问题。把 config.toml 中的 command 与 args 还原成可在终端中执行的命令，在配置的 cwd 下手动运行，确认可执行文件存在、依赖已安装、参数顺序正确，且当前 Codex host 能读取所需环境变量。某些命令在交互式终端可用，但图形应用启动时 PATH 不同，因此应优先使用稳定的可执行文件路径或确保客户端环境中能解析命令。

env 是为 server 显式设置变量，env_vars 是允许并转发已有环境变量。缺少变量时，进程可能启动后立即退出。不要把令牌写进文章、仓库或错误截图；使用环境变量并只开放 server 真正需要的名称。若项目有复杂 Setup Script，可先参考Codex 云端环境初始化排查的依赖分层方法，但要注意 MCP STDIO 运行在当前 Codex host，而不是自动继承所有 shell 状态。

HTTP 与 OAuth：先看状态码，再决定重新登录

Streamable HTTP server 至少需要正确的 url。若 server 使用 bearer token，可通过 bearer_token_env_var 指定令牌所在的环境变量；需要其他头部时，可使用 http_headers、env_http_headers，或在本地 HTTP 连接中使用输出 JSON 请求头的 helper。敏感值优先来自环境或凭据存储，不要硬编码进可共享的 config.toml。

OAuth server 可执行 codex mcp login <server-name>，桌面端或 IDE 列表中则选择 Authenticate。官方文档说明，Codex 会根据 server 元数据处理 OAuth，并校验回调与 issuer；自定义回调时必须注册 Codex 显示的准确地址。401 通常指没有可用凭据或凭据被拒，403 还可能表示 scope 不足。先解决认证与权限，再重新加载 server，不要用更长超时掩盖认证错误。

• 确认 HTTP URL 的路径也正确，不只检查域名
• 确认令牌变量存在于运行 Codex 的环境，而不是另一个终端会话
• OAuth 登录后重新加载或重启客户端并再次查看 /mcp
• 回调失败时核对浏览器、监听端口、防火墙与注册地址
• 截图前隐藏 token、Authorization 头、Cookie 和回调 code

启动超时与工具超时不是一回事

官方配置目前给出的 startup_timeout_sec 默认值为 10 秒，用于等待 server 启动；tool_timeout_sec 默认值为 60 秒，用于单个工具执行。前者失败说明初始化阶段没有按时就绪，后者说明 server 已经连接，但某次工具调用没有在时限内结束。只有在日志证明进程或远程服务仍在正常初始化时，才小幅增加启动等待；若命令秒退、URL 不通或认证失败，等待更久没有意义。

对工具超时，先缩小输入、检查外部 API、文件规模、网络与限流，再决定是否调高 tool_timeout_sec。把所有工具统一设成很长时间，会让真正的死锁或错误更晚暴露。需要稳定自动化时，可结合Codex 定时任务权限与验收清单为工具调用设置明确输入、输出和停止条件。

连接成功但工具不出现：检查开关与工具策略

server 建立连接后仍可能因为 enabled=false、enabled_tools 白名单或 disabled_tools 黑名单而不暴露某些工具；官方说明 disabled_tools 会在 enabled_tools 之后应用。required=true 的含义是启用的 server 初始化失败时让启动失败，它不是“强制发现工具”的按钮，不应作为普通排障手段。

先在 /mcp 或客户端 server 列表确认连接状态，再检查工具过滤规则。找到一个只读、低风险工具做最小调用，记录工具名、输入和实际返回；成功后再逐步开放其他工具。需要写文件或联网的工具还会受 Codex 权限和 sandbox 影响，连接成功并不代表每次外部动作都自动获得授权。

最小验收清单：从列表可见到真实调用

完整验收至少包含五步：server 在目标客户端中可见；状态显示已连接或已认证；预期工具出现在目录；一个只读工具能返回可验证结果；需要写入或外部动作时，权限提示符合预期。把这些证据写进项目说明，后续升级依赖、迁移电脑或修改 config.toml 时就能快速判断回归发生在哪一层。

排障记录不要保存真实 token、Cookie、OAuth code 或客户数据。可参考Codex 任务验收与测试证据记录版本、配置来源、server 名、传输类型、状态码、耗时和脱敏错误。结构化证据比一句“连不上”更容易让团队或 server 维护者复现。

结论：先定位连接阶段，再修改对应配置

Codex MCP 排障的核心是把“server 不见了”拆成配置、传输、认证、初始化、工具发现和工具执行六层。STDIO 先验证本地命令与环境，HTTP 先验证 URL 与认证，超时只在对应阶段有证据时调整。最后用一个只读工具完成真实调用，才能证明 MCP 已经从配置文件走到了可用能力。