PuppyIP 资源中心
AI 工具动态 5 分钟 发布于 2026-10-11

Codex 远程 Windows MCP 启动失败?先查3个环境变量

Mac/Linux 上的 Codex 能连接执行端,Windows MCP 却启动不了,值得先查环境变量来源。0.160.1 已修复显式 remote 变量过滤掉 Windows 启动环境的问题;确认版本、远端目录和3个变量,再定位实际失败步骤。

Codex CLI Windows 远程 MCP stdio 环境变量

服务对象与地域限制

PuppyIP 仅面向海外合规企业及其授权人员提供服务,不面向中国大陆地区开放或提供代理服务。本服务仅限用于中国大陆境外的合法业务活动,严禁在中国大陆境内使用本服务。

代理 IP 或服务器位于境外,不改变上述限制。不得通过中转、转接、共享或转售向中国大陆境内的最终使用者提供本服务。使用前请阅读用户服务协议。

本文要点

  • 0.160.1 于10月5日发布,保留 Windows 执行端的 SYSTEMROOT、TEMP、TMP;适用远程 stdio 与显式 remote 环境变量的特定组合。
  • env_vars 的普通字符串和 source = local 读取 Codex 控制端;source = remote 才读取远程执行端。
  • 现行文档用 experimental_environment = remote 选择已有远程执行环境,源码还要求显式 cwd;这不是自动创建 Windows 执行端。
  • 先确认进程启动、MCP 初始化和工具发现,再做获准的最小操作。保留启动变量不等于继承全部秘密,也不能修复授权或协议错误。

先判断是否属于这次修复的组合

OpenAI 于2026年10月5日发布 Codex CLI 0.160.1,修复从 Unix 控制端启动 Windows 远程 stdio MCP 时,显式 remote 环境变量会遗漏 Windows 启动环境的问题。对应 PR 51121 已合并,修复被回移到0.160版本线;这是已发布补丁,不是今天新增的功能。

MCP 让 Codex 调用外部工具;stdio 指客户端通过进程的标准输入和输出与服务器通信。这里的“远程”是进程在执行端启动,别把它与通过 URL 访问的 Streamable HTTP MCP 混为一谈。

假设你在 Mac 或 Linux 控制端使用 Codex,MCP 进程放在 Windows 执行端,并显式要求读取那里的一项环境变量。执行端连接成功,但进程仍在启动阶段失败,就值得检查这条路径;普通本机 Windows MCP 或 HTTP 服务不能直接套用这个结论。

为什么一项 remote 变量会影响 Windows 启动?

修复代码显示:显式 remote 变量会启用允许列表,只把默认项和指定项交给子进程。0.160.1 在这份列表中补上 SYSTEMROOT、TEMP、TMP,让 Windows 的系统目录和临时目录输入继续可用。它保留的是执行端自己的值,不是把 Mac/Linux 的目录复制过去。

这三个变量是否存在、目录是否可用,仍由 Windows 执行端的实际环境决定。源码同时保留对未请求秘密的过滤,不能把代码中的 inherit: All 单独理解为“所有 token 都会传给 MCP”。不要为排错而改成全量环境继承。

步骤一:确认真正运行的 CLI 和进程位置

先在实际启动 Codex 的控制端核对 CLI 版本和可执行文件位置,记录当前 MCP 的 command、args 与启动阶段错误。若仍使用受影响旧版,按团队批准的安装渠道选用包含该修复的版本;0.160.1 是可核实的修复发布点,不能据此称它为当前最新版。

再检查实际配置是否让 stdio 进程在 Windows 执行端启动。现行官方文档使用 experimental_environment = remote,在已有远程执行环境可用时选择该路径;不可变源码要求显式 cwd。确认工作目录和命令在 Windows 端存在,使用获准目录,不把控制端路径当远端路径。

步骤二:把变量名称和取值位置分开

查看对应的 mcp_servers 配置:env 用于设置变量值,env_vars 用于允许并转发变量。现行文档示例中的普通字符串 "LOCAL_TOKEN" 以及 source = "local" 都从 Codex 控制端取值;同名变量存在于 Windows 端,不会让普通字符串自动改读远端。

若获准读取执行端的指定变量,现行文档的写法是 env_vars = [{ name = "REMOTE_TOKEN", source = "remote" }],并要求 remote MCP stdio。REMOTE_TOKEN 只是官方示例变量名,不是真实凭据;按应用需要选名称,不在配置说明、截图或求助日志里填秘密值。

由有权限的维护者在 Windows 执行端核对 SYSTEMROOT、TEMP、TMP 是否可用,以及对应目录是否存在并可访问。不要用控制端的临时目录覆盖它们。该补丁保留已有输入,不负责创建目录、补装运行时或授予文件权限。

步骤三:启动成功后,再确认 MCP 能用

保存获准的配置调整后,按使用入口的重启方式重新加载 MCP。现行文档可用 codex mcp list 查看配置服务,Codex TUI 的 /mcp 查看活动服务;列表里有名称,还要结合启动日志确认目标进程已经初始化并完成工具发现。

随后在无敏感数据的隔离场景做一次已授权的最小操作,记录结果及原有审批是否正常。进程已启动、工具已出现和某项操作成功,是三个不同检查点;一次成功也不证明其他工具或真实业务流程都能运行。

仍然失败,按错误阶段继续缩小范围

命令找不到,先核 Windows 端的程序、运行时和 cwd;进程启动后退出,查该服务器自己的错误输出;初始化失败,核传输和 MCP 兼容性;工具调用才报错,再核具体操作权限。不要只因控制端与执行端跨系统,就把认证失败或所有超时归因于这3个变量。

保留脱敏后的版本、进程位置、变量来源、目录和失败阶段,调整不奏效时恢复原配置。官方补丁没有承诺统一错误码、修复所有 MCP 服务或特定恢复耗时;本文依据发布记录、源码与现行文档说明排查边界,没有连接真实 Windows 执行端或运行 MCP 安装脚本。

资料来源

常见问题

写上 remote 后,会自动得到一台 Windows 机器吗?

不会。文档明确是在远程执行环境已经可用时选择远程 stdio 启动。仍需具备相应执行端、访问授权、程序和工作目录;配置项不创建机器,也不改变账号或组织资格。

这是 codex mcp-server 弃用的同一个问题吗?

不是。这里是 Codex 启动另一个 MCP 工具进程时的环境保留;codex mcp-server 弃用涉及外部客户端把 Codex 本身当作 MCP server 调用。先确认哪个进程失败,再选择配置排查或集成迁移。

用 URL 连接远程 MCP,需要设置这3个变量吗?

不能把这项 stdio 补丁当作 HTTP 连接的通用修复。Streamable HTTP 使用服务 URL,并按该服务要求处理认证和连接;只有实际服务器进程启动问题才继续核其环境,不能由 URL 连接失败推定缺少 Windows 启动变量。