Codex CLI 启动时出现 MCP server timed out、startup failed 或握手超时，说明 Codex 已尝试拉起 MCP 服务，但在规定时间内没有收到可用响应。原因可能是启动命令找不到、运行目录不对、环境变量缺失，也可能是服务首次下载依赖耗时过长。直接把超时时间调得很大只能掩盖症状，正确顺序是先在同一环境中手工启动服务，再判断是否需要调整 startup_timeout_sec。

一、先分清启动超时和工具调用超时

启动超时发生在 Codex 建立 MCP 连接之前，通常一进入项目或第一次启用服务就报错。工具调用超时则是服务已经连上，某个具体工具执行太久。两者对应不同阶段，不能只看到 timeout 就修改同一个数值。

保留错误中出现的服务器名称、启动命令、等待时长和退出码。若日志提示进程立即退出，重点检查命令和参数；若进程持续存在但没有完成握手，检查标准输入输出协议、依赖初始化和启动时间。先确定卡在哪一步，后面的修复才有意义。

二、在 Codex 之外手工运行启动命令

把配置中的 command 与 args 组合成完整命令，在相同 shell、相同用户和相同目录中运行。命令若直接报 command not found、模块缺失或权限不足，问题与 Codex 无关，应先修 MCP 服务自身。手工启动时不要附带真实密钥到命令行，敏感值应由环境变量或安全存储注入。

有些 MCP 服务采用标准输入输出通信，手工运行后会安静等待，看起来像“卡住”。此时检查进程是否仍在、标准错误是否有日志，并按服务文档使用调试方式。不要因为没有普通网页界面就认定服务失效。

三、命令路径要适合 Codex 的启动环境

交互终端能运行某个短命令，不代表 Codex 子进程一定拥有相同 PATH。版本管理器、PowerShell profile、shell 别名和临时变量可能只在人工终端中加载。使用命令解析工具找出真实可执行路径，再确认 Codex 启动时能够访问。

团队配置不应依赖某个人主目录里的绝对路径，也不要假设所有电脑都装在相同位置。更稳妥的做法是提供项目初始化脚本，验证运行时和依赖后再启动服务。Windows、WSL 与容器的路径格式不同，配置必须与实际运行环境一致。

四、核对 args、cwd 和引号

启动参数被拆分错误时，程序可能把路径的一部分当成新参数。带空格的目录、JSON 参数和嵌套引号尤其容易出错。逐项核对 command 与 args，不要把整条 shell 命令随意塞进一个参数字段。能直接调用可执行文件时，避免再套一层复杂 shell。

部分服务要求从项目根目录启动，以便读取配置或依赖。若 Codex 使用另一工作目录，服务可能反复查找文件直到超时。检查当前项目路径和 MCP 配置支持的工作目录设置；无法显式设置时，让启动脚本先切换到确定目录。

五、环境变量只传必要项

API 地址、访问令牌或运行模式缺失时，MCP 服务可能启动后等待配置。确认变量名称与服务文档一致，值由当前 Codex 进程继承或在 MCP 配置中安全提供。不要打印完整环境，也不要把密钥写入仓库中的 config.toml。

变量刚修改后，旧终端和桌面进程不会自动刷新。完全退出并重新启动 Codex，再观察日志。若系统环境、用户环境和启动脚本都设置了同名变量，先减少为一个来源，避免旧值覆盖新值。

如果大家想体验一线 AI 编程模型 codex 和 claude，用它们完成代码修改、测试和审查，可以参考以下教程文档进行接入配置，接入配置好后即可使用。文档教程：https://my.feishu.cn/wiki/NIgLwuuj1ibzJIkLGM0cgVNinzg

六、何时调整 startup_timeout_sec

只有服务可以手工正常启动，并且日志表明首次初始化确实需要更长时间时，才考虑增加 startup_timeout_sec。比如第一次下载依赖、建立本地索引或启动较重的运行时，默认等待可能不够。调整后记录实际启动耗时，不要直接设成无限等待。

如果每次启动都接近超时上限，应优化服务启动过程：预先安装依赖、避免启动时扫描整个磁盘、减少不必要网络请求。超时时间是容错，不是性能修复。团队模板应给出保守值，并说明为何需要修改。

七、查看标准错误和 Codex 日志

MCP 的协议数据通常走标准输出，调试日志应写入标准错误。服务若把普通日志混进协议输出，握手可能失败。检查服务的日志配置，确保不会在协议通道打印欢迎语、进度条或调试文本。

使用 Codex 的调试日志定位进程是否创建、何时退出以及返回了什么。分享日志时删除密钥、内部域名和用户路径中的敏感部分。只截最后一行往往不够，至少保留启动前后完整时间段。

八、分别验证连接和工具调用

服务显示已连接后，先调用一个只读、快速工具，确认协议和权限正常。随后再测试需要网络、文件写入或外部认证的工具。连接成功但工具失败，应转入工具权限、参数和业务服务排查，不再调整启动超时。

多个 MCP 服务同时启用时，先只保留故障服务，避免日志交错。单服务稳定后逐个恢复，并记录每个服务的启动耗时。这样可以发现资源争用或端口冲突，而不是把所有问题归到 Codex。

九、形成可复现的修复清单

最终记录服务器名称、命令来源、运行时版本、工作目录、必要变量、正常启动耗时和验证工具。配置模板只保存非敏感字段，密钥由各环境注入。以后再遇到 MCP server timed out，按“阶段、手工启动、路径、参数、目录、变量、超时、日志”的顺序检查，通常可以在不重装 Codex 的情况下找到根因。