Codex MCP startup interrupted、handshaking failed 与 tool timeout 排查

30 秒分流：你看到的是哪一种 MCP 故障？

先理解五层链路：报错出现的位置不一定是根因

handshaking failed 只描述 Codex client 没拿到完整响应。它不能区分 Node 包缺失、Python 环境错误、macOS dyld、HTTP 403、证书错误或 server 自己崩溃；必须继续向下一层取证。

第一步：确认到底哪个 server 失败

codex mcp list
codex mcp --help

# 在 Codex TUI 中查看当前 MCP server
/mcp

记录 server 名称、来源、是否启用、STDIO 或 HTTP、它在哪个 host 运行。不要只保留“the following servers were not initialized”最后一行；同一会话可能只有一个可选 server 失败，Codex 普通对话仍能继续。

• CLI 和 IDE 同时失败：更偏向共享配置、server 本身或同一 host 环境。
• 只有 WSL、SSH 或容器失败：从远端 host 检查命令、PATH、凭证与网络。
• 只有一个 server 失败：不要删除整个 ~/.codex 或重装所有 MCP。
• 关闭 Codex 时偶发 cancelled / interrupted：结合发生阶段判断是否只是 shutdown 噪声。

第二步：核对有效配置，而不是只看一个 config.toml

OpenAI 当前文档说明，MCP 配置默认存放在 ~/.codex/config.toml；受信任项目也可以使用 .codex/config.toml。ChatGPT 桌面端、Codex CLI 和 IDE 扩展在同一个 Codex host 上共享配置，但 WSL、SSH、容器和另一台设备可能各有自己的 home 与环境。

手写 server 使用 [mcp_servers.<server-name>] 表。STDIO 常见字段包括 command、args、env、env_vars、cwd；HTTP 常见字段包括 url、auth、bearer_token_env_var 与 header 配置。不要把旧客户端、其他 MCP host 或博客里的 JSON 格式直接粘成 Codex TOML。

官方来源：OpenAI Codex MCP（当前会重定向到 ChatGPT Learn MCP 文档）、Configuration Reference。

STDIO server：复制实际命令，在同一 host 手动复现

把有效配置中的 command、args、cwd 和非敏感环境变量还原成一次手动运行。重点不是“命令有没有立即结束”，而是它是否打印真实错误、是否保持运行并等待协议输入。

前排案例证明了一个重要原则：server 可能在 macOS 动态链接阶段就退出，Codex 最后只能报告 initialize 握手失败。增加 timeout 无法修复缺失的动态库符号。

handshaking failed：围绕 initialize 找第一条 server 证据

1. 先看 server stderr 与退出码

   它们比 client 的高层“connection closed”更接近根因。

2. 确认 STDIO 没被日志污染

   server 的普通日志应输出到 stderr，不能破坏协议消息。

3. 核对 server 与客户端版本

   只有某次升级后失败时，记录双方版本并查对应公开 issue。

4. 区分启动阶段与关闭阶段

   shutdown 时的 task cancelled 可能是结果，不等于会话启动必然失败。

5. 做单 server 最小对照

   只暂时禁用已确认故障的可选 server，避免多个错误互相遮蔽。

公开故障参考：openai/codex #6020、#23700。公开 issue 只提供症状和案例证据，不能证明所有环境共享同一根因。

Streamable HTTP：把地址、TLS 和认证分开

远程 MCP server 不会由 Codex 启动本地进程；这里的“failed to start”更可能指 client 初始化失败。记录实际 URL 与 HTTP 状态，但不要公开 token、私有 host 或完整 header。

• 无 HTTP 状态：先看 DNS、TCP、TLS 与企业网络策略。
• 401 / 403：核对 OAuth、ChatGPT session 或 bearer token 来源，不要增加 startup timeout。
• 需要 OAuth：按官方方式运行 codex mcp login <server-name>，并核对 callback URL/port 与提供方登记。
• Bearer token：配置环境变量名称而不是把密钥贴进公开文章或截图。
• 5xx / 429：保存时间、request ID 与服务商状态，减少重试风暴。

10 秒启动、60 秒工具：什么时候才应该调整？

OpenAI 当前 MCP 文档给出的默认值是：startup_timeout_sec = 10，tool_timeout_sec = 60。网上常见“默认 30 秒”的文章可能来自不同版本、不同 host 或未经核对的转载，不应覆盖当前官方参考。

[mcp_servers.example]
# 只有证据表明 server 正常启动但确实需要更久时才调整
startup_timeout_sec = 20

# 只有具体工具正常运行但稳定超过 60 秒时才调整
tool_timeout_sec = 120

codex_apps 初始化失败：先确认它从哪里来

codex_apps 可能来自插件、客户端托管能力或当前 Codex 环境，不一定存在于用户手写的 [mcp_servers.codex_apps]。如果有效配置中没有这个表，不要为了匹配错误文字自行创建一个同名 server。

1. 用 /mcp 查看名称、状态和可用工具。
2. 记录错误发生在 CLI、IDE、桌面端还是关闭会话时。
3. 检查客户端版本、插件来源和 server stderr。
4. 仅在官方文档或有效配置明确支持时调整对应字段。
5. 可选能力不影响当前任务时，可临时禁用相关插件或 server；不要删除全部配置。

安全恢复顺序：一次改变一个变量

1. 保存原始错误和有效配置

   记录 server、transport、版本、host 与发生阶段，对 token 和私有地址脱敏。

2. 确认 server 来源和运行位置

   本机、WSL、SSH、容器与插件托管环境要分开。

3. STDIO 手动运行，HTTP 保存状态

   先得到 stderr、退出码或 HTTP/TLS 证据。

4. 修命令、依赖、认证或协议

   不要在根因未明时同时重装、改 timeout 和删缓存。

5. 按证据小幅调整超时

   记录调整前后启动/工具耗时，保留回滚点。

6. 暂时禁用可选故障 server

   当前配置支持 enabled = false；组织要求的 required = true server 应联系管理员。

7. 提交最小复现

   稳定复现时向 OpenAI、插件作者或 MCP 服务商提供脱敏证据。

一份可处理的 MCP 故障报告要包含什么

不要把整个 ~/.codex、auth.json、环境变量列表、Cookie、OAuth token、私有 URL 或项目数据上传到公开 issue。

Codex MCP 启动失败与超时常见问题

Codex MCP startup interrupted 是什么意思？

它表示一个或多个 MCP server 没有完成初始化，或初始化在会话启动过程中被取消。先在 /mcp 或 codex mcp list 确认具体 server，再检查 transport、启动命令、stderr、initialize 和认证；它不自动等于启动超时。

handshaking with MCP server failed 一定是配置写错吗？

不一定。它只说明 Codex 没收到完整 initialize 响应。命令不存在、依赖缺失、进程崩溃、stdout 被日志污染、HTTP 认证失败、TLS 问题或 server 版本不兼容都可能表现为握手失败。

Codex MCP server 的默认 startup timeout 是多少？

OpenAI 当前 MCP 文档给出的 startup_timeout_sec 默认值是 10 秒。网上常见的 30 秒说法不能替代当前官方配置参考；修改前应先确认 server 确实在正常启动，只是超过 10 秒。

Codex MCP tool timeout 默认是多少？

OpenAI 当前文档给出的 tool_timeout_sec 默认值是 60 秒。它限制单个 MCP 工具运行时间，与 MCP server 启动超时、模型响应流超时和终端命令超时不是一回事。

MCP 超时要不要直接把 timeout 调到 300 秒？

不要作为第一步。命令不存在、进程秒退、认证失败或 initialize 协议错误不会因增加 timeout 修复。先拿到 server stderr 和手动复现证据；只有 server 正常工作但启动或工具确实需要更久时，才按 server 做最小上调。

Codex、IDE 扩展和 ChatGPT 桌面端会共用 MCP 配置吗？

OpenAI 当前文档说明，ChatGPT 桌面端、Codex CLI 和 IDE 扩展在同一个 Codex host 上共享 MCP 配置。WSL、SSH、容器或另一台设备属于不同 host 时，应分别确认实际配置和运行环境。

codex_apps 初始化失败能直接在 config.toml 增加 mcp_servers.codex_apps 吗？

不要在没有配置来源证据时自行创建同名 server。codex_apps 可能来自插件或客户端托管能力，不一定是用户手写的 MCP 表。先用 /mcp、有效配置与日志确认来源、transport 和真实启动命令。

Codex MCP 的 STDIO server 怎么排查？

复制实际 command、args、cwd 和非敏感环境变量，在同一 host 与同一用户环境手动运行；检查 command not found、Node/Python/uv 依赖、架构、动态库、权限和 stderr。STDIO server 正常时可能持续等待输入，不应仅因命令没有退出就认定卡死。

Codex MCP 的 Streamable HTTP server 连接失败怎么办？

核对 URL、DNS/TLS、HTTP 状态、OAuth 或 bearer token 环境变量。需要 OAuth 的 server 应使用 codex mcp login server-name；不要把 token 写进公开日志，也不要把所有 401、403 或证书错误当成启动 timeout。

MCP server 可以临时禁用而不删除配置吗？

可以。当前官方配置支持对单个 server 设置 enabled = false。先备份并只禁用已确认故障且当前任务不需要的 server；required = true 的 server 初始化失败会让启动失败，应结合组织要求处理。

升级 ChatGPT Plus 或 Pro 能修复 MCP startup failed 吗？

通常不能。套餐升级与本地命令、依赖、环境变量、OAuth、TLS、initialize 或工具执行超时无关。只有问题被确认是账号权限或某个套餐不提供对应能力时，套餐才可能相关。

报告 Codex MCP 启动失败需要哪些信息？

提供时间和时区、Codex 与 IDE 版本、host 环境、server 名称与来源、STDIO 或 HTTP、脱敏配置、启动命令、退出码、server stderr、HTTP 状态和最小复现。不要公开 token、Cookie、auth.json、私有 URL 或项目数据。