结论先说
- 先用
codex mcp list和会话内/mcp定位断在哪一步:列表里根本没有该服务器,多半是项目未授信导致.codex/config.toml被跳过,或enabled = false。 - 本地 STDIO 服务首次拉包易超默认 10 秒:把
[mcp_servers.<名字>]里的startup_timeout_sec调大(如30或60),并先在终端单独跑通一次启动命令。 - 环境变量没传进去会导致鉴权失败:固定键值写在
[mcp_servers.<名字>.env],转发本机变量列进env_vars,远程 HTTP 令牌用bearer_token_env_var。 - Windows 原生环境注意
.cmd扩展名:npx在 Windows 上实际是批处理包装脚本,直接写command = "npx"可能找不到可执行文件,建议改写为npx.cmd或完整路径。 - 改完配置必须重启会话或点 Restart,基础添加命令见 /guides/codex-mcp-config。
- Codex 额度升级与注册验证入口:Codex 配额随 ChatGPT 付费套餐提供,国内免境外卡自助开通可见本站 ChatGPT Plus 充值页 与重度开发首选的 ChatGPT Pro 充值页,新号卡在手机验证可查看 Codex 注册验证说明。

图:本站根据 Codex 官方文档:Model Context Protocol 整理的示意图
本文根据 Codex 官方文档《Model Context Protocol》《Configuration Reference》《Environment variables》《Config basics》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。
适用于谁
- 在
config.toml配好了[mcp_servers],但运行 Codex 时提示 MCP 启动超时、连接失败的人; - 会话里输入
/mcp显示列表为空,或者连上了服务器却找不到某个工具的人; - 在 Windows 原生终端或桌面 App 下跑
npx、uvx本地 MCP 总是起不来的人。
一、第一步自检:列表里有没有、项目信不信任
遇到「配好了却看不到工具」,按下面四条顺序排掉最常见的低级卡点:
- 在终端跑
codex mcp list(或加--json):看 Codex 实际解析到的配置里有没有你的服务器;若 TOML 语法写错(例如漏引号、根级键写在了[表]后面),启动就会报错或漏读,结构规则见 /guides/codex-config-toml-complete-guide。 - 检查项目信任状态:如果你把 MCP 配在仓库内的
.codex/config.toml,官方明确规定只有受信任(trusted)的项目才会加载.codex/层配置。未授信项目会静默跳过项目级 MCP。 - 核对开关与白名单:检查该服务器下是否误写了
enabled = false,或者enabled_tools、disabled_tools把目标工具筛掉了。 - 重启客户端并在会话里敲
/mcp:ChatGPT 桌面 App 保存配置后要点 Restart,IDE 扩展要点 Restart extension;进会话输入/mcp(或/mcp verbose)查看实时连接详情。
二、超时排查:startup_timeout_sec 与 tool_timeout_sec

图:本站根据 Codex 官方文档:Configuration Reference 整理的示意图
用 npx -y 或 uvx 启动本地 STDIO 服务器时,第一次运行往往要联网下载依赖包,耗时很容易超过默认的 10 秒,导致 Codex 判定启动超时放弃连接。
按官方配置参考,可在 [mcp_servers.<名字>] 里调整超时参数:
| 配置键 | 默认值 | 排错调整建议 |
|---|---|---|
startup_timeout_sec | 10(秒) | 本地 npx / uvx 冷启动或重型服务,建议调至 30–60 |
tool_timeout_sec | 60(秒) | 查大库、跑浏览器自动化等慢工具,可按需调至 120 以上 |
required | false | 设为 true 时,该 MCP 起不来会直接阻止 Codex 启动,方便暴露错误 |
顶层 mcp_optional_startup_grace_ms | 1000(毫秒) | 控制构建工具列表时等待非必需服务器的宽限时间 |
实用做法是:先把 command 和 args 拼成普通命令,在系统终端里手动跑一遍,让它先把包缓存到本地、确认不报缺依赖错误,再交由 Codex 拉起。
Codex 开发配额与团队版提示:高频跑本地重构与云端任务容易耗尽基础周期限额。需要免境外银行卡自助升级或覆盖升级时,可前往本站 ChatGPT Plus 自助充值 或 ChatGPT Pro 5x/20x 充值说明;团队统一管控权限与共享账单可定制 ChatGPT Business 团队方案。
三、环境变量与远程 OAuth 鉴权排错
很多 MCP 服务器进程虽然起来了,但因为拿不到数据库地址或 API Token 而立刻退出或返回空工具:
- STDIO 本地服务器传变量:子进程不会无条件拿到另一个终端窗口里的临时变量。直接给该服务器赋固定值用子表
[mcp_servers.<名字>.env];要从启动 Codex 的宿主机环境转发已有变量,必须把变量名写进env_vars = ["GITHUB_PERSONAL_ACCESS_TOKEN"]。 - Streamable HTTP 远程服务器传凭证:用 Bearer Token 的服务写
bearer_token_env_var = "MY_MCP_TOKEN"(不要把明文密钥硬编码进会提交 Git 的配置文件);自定义请求头可用http_headers或从环境读取的env_http_headers。环境变量完整读取规则见 /guides/codex-missing-environment-variable。 - 需要 OAuth 登录的远程服务:连接后提示未授权时,运行
codex mcp login <名字>拉起浏览器完成授权(桌面 App 或 IDE 的 MCP 设置页点 Authenticate);令牌失效重登前可先codex mcp logout <名字>。
四、Windows 原生环境命令启动排错
在 macOS 和 Linux 上直接写 command = "npx" 通常没问题,但在 Windows 原生环境下(非 WSL),进程创建接口直接找可执行文件时常会因为找不到 .cmd 批处理包装器或 Node 路径未进系统全局 PATH 而启动失败。
在 Windows 的用户级 config.toml 里,可用以下两种写法解决(路径分隔符用正斜杠可免去转义麻烦):
toml
# 写法一:显式指定 .cmd 扩展名与超时时间
[mcp_servers.context7]
command = "npx.cmd"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 30
# 写法二:从桌面图标启动读不到 PATH 时,写可执行程序完整路径
[mcp_servers.local_uv]
command = "C:/Users/YourName/.local/bin/uvx.exe"
args = ["mcp-server-git"]
startup_timeout_sec = 30
若同时遇到 Windows 本机沙箱报错,可对照 /guides/codex-windows-sandbox-setup-failed。另外官方定价页提醒,挂载过多 MCP 服务器会往每轮请求塞入大量工具描述、加快配额消耗,不常用的服务建议设 enabled = false;日常配额不够用可查看本站 ChatGPT Plus 充值说明。
常见问题
问:配在 config.toml 里的 MCP,打开 ChatGPT 网页版为什么看不到?
答:ChatGPT 网页版不读取本机 config.toml,网页端需要通过插件(Plugins)连接远程工具;本地这份配置仅由桌面 App、CLI 和 IDE 扩展共用。
问:为什么运行 codex mcp-server 提示没有这个子命令?
答:官方已移除旧的 codex mcp-server(把 Codex 自身当作 MCP 服务端暴露的模式);让 Codex 连接外部 MCP 服务器统一用 codex mcp 子命令管理。
问:怎么看某个 MCP 服务器到底报了什么底层错误?
答:先在会话内运行 /mcp verbose 查看状态,或在终端单独复现对应的启动命令,分享日志前注意抹去敏感密钥。
问:跑 Codex 额度不够用,国内没有外币卡怎么快速升级 Plus 或 Pro?
答:可在本站用支付宝、微信支付或 AlipayHK 自助购买卡密兑换 ChatGPT Plus 或 ChatGPT Pro(已有未到期 Plus 直升可选 Pro 5x 可覆盖档),实时价格与售后边界(封号不在质保范围)以页面当天说明为准。
相关教程
- Codex 怎么配置 MCP:codex mcp add 与 config.toml 写法
- Codex 报「missing environment variable」怎么办
- Codex config.toml 完整详解
- Codex 沙箱初始化失败怎么办(Windows)
参考资料
- Codex 官方文档:Model Context Protocol — https://learn.chatgpt.com/docs/extend/mcp
- Codex 官方文档:Configuration Reference — https://learn.chatgpt.com/docs/config-file/config-reference
- Codex 官方文档:Environment variables — https://learn.chatgpt.com/docs/config-file/environment-variables
- Codex 官方文档:Config basics — https://learn.chatgpt.com/docs/config-file/config-basic
0 条评论
还没有评论,来抢沙发~