Codex .mcp.json、MCP OAuth 预刷新与 /app Desktop Handoff

2026 年 6 月 8 日，OpenAI 发布 Codex rust-v0.138.0。此次版本的亮点不在于某个单一功能，而是一组面向运营商的改进：更强的可脚本化能力、更好的大规模部署可靠性，以及对历史上容易触发静默故障的凭证过期和工作区根路径解析问题的修复。

更新内容

Plugin JSON 自动化 — 运营商 plugin JSON API。 codex plugin add、codex plugin remove 及 marketplace 命令现在支持 --json 结构化输出。plugin list 的 JSON 中包含每个 plugin 的 marketplace 来源；plugin 详情 payload 现在暴露默认 prompt、远程 MCP 服务器及不可用 app 模板。对于跨开发者机队统一管理 Codex plugin 配置的团队，这使得通过 shell 脚本或 CI 工具自动化 plugin 状态成为可能，无需依赖交互式 TUI。

/app CLI 到 Desktop 切换。 新增 /app 命令，可将当前 CLI 会话切换到 macOS 或 Windows 原生 Codex Desktop，同时保留会话上下文。Windows 工作区启动也可以直接进入 Desktop，而非停在手动提示处。对于通过 CLI 进行初始化或 CI 触发会话、后续希望开发者在更丰富的 Desktop UX 中继续工作的团队而言，此功能可显著降低上下文切换成本。

MCP OAuth 凭证预刷新。 启动时现在会提前刷新已过期的 OAuth 驱动 MCP 凭证，然后再开始会话。此前，使用 stale token 的 OAuth 安全 MCP 服务器会在首次调用时失败——通常发生在会话中途——迫使开发者手动重新认证，中断 agent 的执行流。预刷新意味着 Codex 在启动期间就完成凭证校验和续期，第一次实际工具调用得以成功。

AGENTS.md 远程和符号链接工作区加载修复。 工作区指令加载对远程仓库和符号链接根路径现在更加准确。此前，当工作区根路径是符号链接或远程克隆路径时，Codex 会加载错误的 AGENTS.md 甚至根本不加载。对于使用 monorepo 结构、共享 NFS/SMB 挂载或容器卷挂载（符号链接常见）的团队，此修复意义重大。

账户 token 用量 API。 App-server 集成现在可以通过 API 读取账户级 token 用量数据，无需依赖独立的 OpenAI API 用量端点，便于在 Codex app-server 协议之上构建成本归因工具。

启动与可靠性改进。 TUI 启动现在复用 plugin 发现结果，仅在关键路径加载 hook 元数据，降低启动延迟。新增 /usr/bin/bash 支持和更短的 Linux 代理 socket 路径，提升跨受限环境的兼容性。resume --last 通过状态数据库查找最新匹配会话，而非扫描全量本地历史，加快了大型本地会话存储的恢复速度。大型 MCP/Ollama 流和长消息历史的处理速度也有显著提升。

为何重要

Plugin JSON 自动化改进最直接影响大规模管理 Codex 的团队。如果贵组织在开发者机队中维护一套标准 plugin 集合，通过 codex plugin add --json 和 codex plugin list --json 脚本化 plugin 状态已完全可行。可以将输出通过管道传给校验脚本、与期望状态 manifest 进行 diff，或集成到 MDM/配置管理工作流中。

MCP OAuth 预刷新针对的是对长时间或无人值守 Codex 会话影响最大的一类故障。OAuth token 通常在小时级窗口内过期。一个运行多小时编码任务的 agent 可能在中途遇到 stale token，发生静默失败或产生令人困惑的错误，导致任务未完成。启动时预刷新关闭了这一缺口——尽管对于极长会话仍可能需要会话中途凭证续期策略。

AGENTS.md 符号链接修复直接影响使用容器化开发环境、dev container 或 monorepo 布局的团队。错误的 AGENTS.md 加载意味着 Codex 获取了整个会话的错误上下文，而这类问题很难诊断，因为启动表面上一切正常。

路由与运营商视角

Plugin JSON 自动化与 token 用量 API 结合，为路由层运营商提供了一个关键模式：自动化 Codex 会话审计。通过共享路由 gateway 运行多个 Codex 实例的运营商，现在可以脚本化 plugin 状态校验和每会话 token 消费查询，无需人工检查。结合 gateway 层面可用的运营商治理控制，工程平台团队拥有了两个互补的数据来源——gateway 级路由遥测和 Codex 原生 token 用量——用于成本归因和合规。

AGENTS.md 修复对通过共享挂载或容器化环境交付工作区指令的运营商同样重要。如果贵机队通过带符号链接根路径的容器卷挂载配置 Codex 工作区，此修复意味着 Codex 将正确加载机队统一 AGENTS.md，其中通常包含路由 gateway URL、provider 配置或团队特定工具授权。

后续关注

Plugin JSON 路线图似乎正朝着 plugin 状态完全机器可读的方向推进——默认 prompt、远程 MCP 服务器和 app 模板现在均在详情 payload 中可见，这是配置管理工具的基础。如果贵组织维护自定义 Codex plugin，现在是基于 JSON 输出开始构建自动化的最佳时机，赶在 schema 进一步稳定之前。

MCP OAuth 预刷新仅适用于 OAuth 驱动的 MCP 服务器（streamable HTTP）。使用 stdio-based MCP 服务器的团队不受此次变更影响，但应确认其认证方式是否在覆盖范围内。

对于通过代理或中间层（如 TheRouter）路由 Codex 的团队：openai_base_url 仍是项目配置受限键——不能在项目本地 .codex/config.toml 中设置。通过自定义 base URL 路由必须在用户或 app-server 层面配置，不能通过项目文件推送。