---

Codex Windows MCP 安装避坑指南

对于 Windows 用户来说，配置各类开发工具链时常会遇到因平台差异引发的“水土不服”。Codex 及其强大的 MCP (Model Context Protocol) 生态也不例外。

本指南将聚焦于 Windows 环境，从安装、配置到最关键的 MCP 服务连接，一步步带你绕开常见陷阱，让你的 AI 编码助手在 Windows 上也能顺畅运行。

---

第一步：基础环境安装 (Node.js & Codex CLI)

这是所有工作的第一步，也是最不容易出错的一步。

1. 安装 Node.js: 确保你已安装 Node.js 18 或更高版本。建议从 Node.js 官网 下载LTS版本。
2. 安装 Codex CLI: 打开 PowerShell (建议 pwsh) 或传统的 cmd，执行以下命令：

   npm i -g @openai/codex
   

3. 验证安装: 安装完成后，执行 codex --version，如果能看到版本号输出，说明 CLI 已成功安装。

---

第二步：核心配置 (config.toml)

配置文件是平台无关的，只需注意 env_key 的命名，后续将在 Windows 环境变量中用到它。

• 文件位置: %USERPROFILE%\.codex\config.toml (可以直接在文件管理器的地址栏输入 ~/.codex/ 并回车)。

• 基础配置示例:

  model = "gpt-5-codex"
  model_provider = "packycode"
  model_reasoning_effort = "high"
  disable_response_storage = true
  network_access = "enabled"
  
  [model_providers.packycode]
  name = "packycode"
  base_url = "https://codex-api.packycode.com/v1"
  wire_api = "responses"
  # 记住这个 key，下一步要用
  env_key = "PACKYCODE_CODEX_KEY" 
  

---

第三步：避坑关键 - 设置 Windows 环境变量

在 Windows 上，环境变量的设置和生效机制是新手最容易出错的地方。

• 错误做法: 在当前 cmd 窗口中使用 set PACKYCODE_CODEX_KEY=sk-xxx。这种方式只在当前窗口有效，关闭后即失效。

• 推荐做法: 使用 setx 命令将其永久写入系统，这样所有新打开的终端都能读取到。

  # 在 cmd 或 PowerShell 中执行，注意 key 和 value
  setx PACKYCODE_CODEX_KEY "sk-xxx"
  

• 【重要】: 执行完 setx 命令后，必须重启你的终端（PowerShell/cmd），新的环境变量才会生效！

---

第四步：核心难点 - 在 Windows 上配置 MCP 服务

这是本指南的重点。由于 Windows 的命令执行机制与 Linux/macOS 不同，直接照搬官方文档的 MCP 配置大概率会失败。关键在于使用 cmd /c 来调用 npx 或其他 Node.js 命令。

在你的 config.toml 文件中，追加以下 MCP 服务器配置。下面是你提供的、已经验证可行的 Windows 配置范例：

# ===============================================
#  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-timezone=Asia/Shanghai"]
env = { SystemRoot = 'C:\\WINDOWS', COMSPEC = 'C:\\WINDOWS\\system32\\cmd.exe'}
startup_timeout_ms = 20000

[mcp_servers.mcp-deepwiki]
command = "cmd"
args = ["/c", "npx", "-y", "mcp-deepwiki@latest"]
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 的命令解释器。
• args = ["/c", "npx", ...] : "/c" 参数表示执行完紧跟其后的命令 (npx ...) 后就关闭 cmd 窗口。这是在 Windows 上调用外部脚本的标准模式。
• env = { ... }: 为命令执行提供必要的系统环境变量，确保 cmd 和其他系统工具能被正确找到。
• startup_timeout_ms = 20000: 首次启动 MCP 服务时，npx 需要下载依赖，可能会比较慢。将超时时间设置长一些（如 20 秒）可以有效防止因网络问题导致的启动失败。

---

第五步：VS Code / Cursor 插件配置

这部分与其它系统差别不大，但同样有需要注意的地方。

1. 在插件商店搜索 “Codex” 并安装。0.5.8 版本是公认的稳定版，如果新版遇到问题，可考虑降级。
2. 在插件设置中找到 API Key 相关配置，将你的 sk-xxx 密钥填入。建议通过写入 ~/.codex/auth.json 文件来完成，避免明文暴露在 settings.json 中。

   // ~/.codex/auth.json
   { "OPENAI_API_KEY": "sk-xxx" }
   

3. 避坑提示：如果插件出现按钮无法点击、侧边栏卡死等现象，大概率是配置文件冲突。可以尝试完全卸载插件，并手动删除 ~/.codex/ 目录下的 VSCode 或 Cursor 相关状态文件，然后重装插件。

---

Windows 专属问题速查 (FAQ)

• 问题：命令行启动 MCP 服务时无响应或报错。

  • 排查: 99% 的可能是 config.toml 中 MCP 的配置不正确。请仔细核对本指南第四步中的 Windows 范例，确保 command、args 和 env 都已正确设置。

• 问题：在 Codex CLI 中使用 @ 搜索文件时，弹出的是空白窗口。

  • 排查: 这是典型的 Windows 终端编码问题。
    1. 确保你的 PowerShell 或 cmd 编码为 UTF-8。执行 chcp 65001 可以临时切换。
    2. 从根本上解决，可以在 PowerShell 的 $PROFILE 文件中加入 $OutputEncoding = [System.Text.Encoding]::UTF8。
    3. 同时，避免项目路径中含有中文或特殊字符。

• 问题：setx 设置了环境变量，但在新终端里 Codex 依然提示找不到 Key。

  • 排查:
    1. 确认 config.toml 中的 env_key 名称与你用 setx 设置的完全一致（大小写敏感）。
    2. 确认你已经重启了所有的终端窗口。
    3. 可以打开一个新的 cmd 窗口，输入 set PACKYCODE_CODEX_KEY 并回车，检查是否能输出你设置的密钥值。

---

收工前的 Checklist

• 已通过 setx 正确设置环境变量，并重启了终端。
• config.toml 中所有的 MCP 服务都已改成 Windows 专属的 cmd /c 格式。
• 了解 chcp 65001 命令，以备 @ 搜索功能异常时使用。
• CLI 能正常 codex -m gpt-5-codex 进入，并且 MCP 服务能被成功加载（启动时会打印日志）。
• VS Code 插件连接正常，可以唤出聊天和 TODO 列表。