1. Windows 上跑 Codex MCP为什么总在 config.toml 这一步卡住如果你在 Windows 上装过 Codex 的 MCP 服务大概率经历过这种场景CLI 装好了codex --version也能打印版本号结果一启动就报MCP server failed to start或者干脆卡住不动日志里只有一行spawn npx ENOENT。这不是你配置写错了而是 Windows 的命令执行机制和 Linux/macOS 根本不一样。MCPModel Context Protocol本质上是让 Codex 通过标准输入输出跟外部工具进程通信。在 macOS 上command npx直接就能跑但在 Windows 上npx是一个.cmd批处理脚本不是可执行文件Codex 用spawn直接调用它会找不到目标。正确做法是让cmd /c去代理执行这也是本篇要解决的核心问题。这篇指南面向三类人刚在 Windows 装完 Codex CLI 想接 MCP 的新手、config.toml 写了但服务起不来的开发者、以及想把模型请求统一走一个 API 通道比如 TaoToken减少多 Key 管理成本的人。我会从 config.toml 骨架写起给出可直接复制的 Windows 专属配置片段再逐条验证 MCP 是否真的加载成功。全程 PowerShell cmd 实测不涉及任何网络工具纯本地配置排障。2. 前置准备Node.js、Codex CLI 与 TaoToken 统一通道在动 config.toml 之前先把地基打牢。这一章不注水只讲跟后面配置直接相关的部分。2.1 Node.js 与 Codex CLI 安装Node.js 建议 18 LTS 以上装完后在 PowerShell 里确认node -v npm -v然后全局安装 Codex CLInpm i -g openai/codex codex --version如果codex --version报「不是内部或外部命令」说明 npm 全局 bin 目录没进 PATH。用npm config get prefix看路径把它加到系统环境变量 Path 里重启终端再试。2.2 为什么建议走 TaoToken 统一 KeyCodex 的 config.toml 里每个 model_provider 都要配一个env_key如果你同时用多个模型或工具环境变量会越堆越多。TaoToken 提供统一的 API 通道一个 Key 就能覆盖对话、编码等场景config.toml 里只需要维护一个 provider 段。它的 API 地址是https://taotoken.net/api兼容 OpenAI 风格的base_url写法。你可以在控制台创建 Key然后在 config.toml 里通过env_key引用避免把明文 Key 写进配置文件。具体接入动作放在第 3 章这里先记住Key 走环境变量不写死在 toml 里。2.3 目录与文件位置确认Codex 的配置目录在%USERPROFILE%\.codex\。在文件资源管理器地址栏输入%USERPROFILE%\.codex回车即可打开。如果目录不存在手动建一个New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.codexconfig.toml 就放在这个目录下。后面所有 MCP 配置都追加到这个文件里。3. 可复制配置config.toml 骨架与 Windows MCP 段这一章是全文核心给出完整可复制的配置。建议先备份原文件再整体替换或追加。3.1 基础 provider 段含 TaoToken 接入先写模型 provider 部分。env_key填一个你自定义的环境变量名比如TAOTOKEN_API_KEY下一步会用setx写入真实值model gpt-5-codex model_provider taotoken model_reasoning_effort high disable_response_storage true network_access enabled [model_providers.taotoken] name taotoken base_url https://taotoken.net/api wire_api responses env_key TAOTOKEN_API_KEY这里wire_api responses对应 Codex 的响应式接口base_url指向 TaoToken 的 API 通道。Key 本身不在这里出现只引用变量名。3.2 Windows 环境变量写入避坑重点新手最常犯的错是在当前窗口用set TAOTOKEN_API_KEYsk-xxx关掉窗口就失效。正确做法是用setx永久写入setx TAOTOKEN_API_KEY sk-你的实际Key执行完必须重启终端新变量才会被读取。验证方法开一个新的 PowerShell输入$env:TAOTOKEN_API_KEY能打印出 Key 就说明生效了。注意setx有长度限制约 1024 字符普通 Key 没问题。3.3 MCP 服务段Windows 专属 cmd /c 写法这是全文最关键的一段。所有 MCP 服务都必须用cmd /c包裹并显式传入SystemRoot和COMSPEC否则子进程找不到系统命令。直接复制以下内容追加到 config.toml# # MCP Servers for Windows # [mcp_servers.context7] command cmd args [/c, npx, -y, upstash/context7-mcp] env { SystemRoot C:\\WINDOWS, COMSPEC C:\\WINDOWS\\system32\\cmd.exe } startup_timeout_ms 20000 [mcp_servers.mcp-server-time] command cmd args [/c, uvx, mcp-server-time, --local-timezoneAsia/Shanghai] env { SystemRoot C:\\WINDOWS, COMSPEC C:\\WINDOWS\\system32\\cmd.exe } startup_timeout_ms 20000 [mcp_servers.sequential-thinking] command cmd args [/c, npx, -y, modelcontextprotocol/server-sequential-thinking] env { SystemRoot C:\\WINDOWS, COMSPEC C:\\WINDOWS\\system32\\cmd.exe } startup_timeout_ms 20000 [mcp_servers.duckduckgo-search] type stdio command cmd args [/c, uvx, duckduckgo-mcp-server] env { SystemRoot C:\\WINDOWS, COMSPEC C:\\WINDOWS\\system32\\cmd.exe } startup_timeout_ms 20000逐项解释关键参数command cmd告诉 Codex 用 Windows 命令解释器启动而不是直接 spawn 一个不存在的可执行文件。args [/c, npx, ...]中的/c表示执行完后面的命令就关闭 cmd 窗口这是 Windows 调用批处理脚本的标准模式。env { SystemRoot ..., COMSPEC ... }为子进程提供系统路径变量缺少它时cmd可能找不到npx或uvx。startup_timeout_ms 20000把启动超时拉到 20 秒。首次运行npx需要下载依赖网络稍慢就会超过默认超时导致误报启动失败。注意uvx来自 Python 的 uv 工具链如果没装mcp-server-time和duckduckgo-search会启动失败。可以先只保留context7和sequential-thinking两个纯 Node 服务跑通后再加。4. 验证请求确认 MCP 真的加载成功配置写完不代表能用必须逐条验证。这一章给出可执行的验证动作和预期结果。4.1 验证 CLI 与 provider 连通先确认 Codex 能读到配置并连上模型通道codex -m gpt-5-codex 用一句话说明你当前使用的模型如果返回正常文本说明base_url和env_key都生效了。若报 401回到第 3.2 节检查环境变量是否重启终端后仍能打印。4.2 验证 MCP 服务加载日志启动 Codex 时加详细日志观察 MCP 是否被拉起codex --verbose启动日志里应该能看到类似MCP server context7 started的行。如果某个服务显示failed to start先单独在 PowerShell 里手动跑一遍它的命令比如cmd /c npx -y upstash/context7-mcp手动能跑通说明配置格式没问题跑不通就是依赖或网络问题。4.3 在会话中调用 MCP 工具进入 Codex 交互模式后直接让它调用 MCP 工具比如用 context7 查一下 React 19 的 use 钩子用法如果模型能返回基于 context7 的结果说明 MCP 链路完整。这一步是最终验收前面配置再漂亮这里调不通就是白搭。4.4 验证结果对照表验证项命令预期结果CLI 安装codex --version打印版本号环境变量$env:TAOTOKEN_API_KEY打印 Keyprovider 连通codex -m gpt-5-codex hi返回文本MCP 加载codex --verbose日志含 started工具调用会话内调用 context7返回工具结果5. 本篇常见错排查这一章按报错现象归类方便你对号入座。5.1 spawn npx ENOENT / 服务无响应99% 是 MCP 段没写成cmd /c格式。检查command是否为cmdargs第一项是否为/c。另外确认env里的COMSPEC路径拼写正确C:\\WINDOWS\\system32\\cmd.exe在 toml 里要双反斜杠转义。5.2 setx 后新终端仍读不到 Key先确认config.toml里的env_key名称和setx设置的完全一致大小写敏感。再确认你重启的是所有终端窗口包括 VS Code 内置终端。可以在新 cmd 里执行set TAOTOKEN_API_KEY检查是否输出值。5.3 搜索文件弹出空白窗口这是 Windows 终端编码问题。临时切换用chcp 65001永久解决可以在 PowerShell 的$PROFILE里加$OutputEncoding [System.Text.Encoding]::UTF8同时避免项目路径含中文或特殊字符这类路径在 MCP 子进程里容易乱码。5.4 首次启动超时npx首次下载依赖可能超过 20 秒。可以先把startup_timeout_ms调到 60000跑通一次让依赖进缓存再调回 20000。或者提前手动执行一次npx -y upstash/context7-mcp预热。5.5 插件侧配置冲突VS Code / Cursor 的 Codex 插件如果出现按钮点不动、侧边栏卡死多半是~/.codex/下的状态文件冲突。完全卸载插件手动删除~/.codex/里插件相关状态文件再重装。API Key 建议写进~/.codex/auth.json避免明文暴露在settings.json{ OPENAI_API_KEY: sk-你的实际Key }6. 收尾把 Key 和接入文档放在手边配置跑通后日常最常打交道的两件事管理 API Key、查接入文档。TaoToken 的 Key 在控制台创建和轮换接入细节在文档里都有对应说明。如果你后面要长期跑编码任务或 Agent可以考虑 Coding Plan 这类按量方案减少频繁换 Key 的麻烦。创建和管理 Keyhttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite模型对话验证https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite长期编码方案https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite最后留一个我踩过的坑config.toml 里 MCP 段和 provider 段的顺序不影响解析但每个[mcp_servers.xxx]段之间不能有空行夹着注释以外的内容否则 toml 解析会报错。改完配置后养成习惯先codex --verbose看一遍加载日志确认所有服务都 started再进交互模式干活。这样出问题时你能第一时间定位是配置层还是调用层省下大量瞎试的时间。
