codex-mcp-bridge

codex-mcp-bridge

将 Codex CLI 作为子进程运行的 MCP 服务，可通过 Model Context Protocol 工具提供代码执行、网络搜索和结构化输出。

适用于任何 MCP 客户端：Claude Code、Gemini CLI、Cursor、Windsurf、VS Code，或任何支持 MCP 的工具。

你需要它吗？

如果你正在使用可访问 Shell 的终端 Agent（Claude Code、Codex CLI、Gemini CLI），可以直接调用 Codex CLI。这样速度更快、成本更低，也没有额外开销：

# Review current branch vs main
codex review --base main

# Review uncommitted changes
codex review --uncommitted

# Review with custom focus
codex review --base main "Focus on security and error handling"

# From a worktree (run inside the worktree; `-C` is broken for `review`)
cd /path/to/worktree && codex review --base main

# General analysis
codex exec "Analyze src/utils/parse.ts for edge cases"

以下情况请改用此 MCP 桥接工具：

• 客户端无法访问 Shell（Cursor、Windsurf、Claude Desktop、VS Code）
• 需要通过 JSON Schema 验证的结构化输出（Codex CLI 的 --json 存在已知问题）
• 需要在超时时捕获部分响应，并在配额耗尽时自动切换模型
• 需要子进程隔离：显式环境变量允许列表、不允许 Shell 转义、输出中的秘密信息脱敏、并发请求按 FIFO 排队（最多同时启动 3 个进程，可通过 CODEX_MAX_CONCURRENT 配置）
• 需要通过会话恢复实现多轮对话（sessionId / resetSession，可通过 listSessions 查看）

Worktree 注意事项：Codex CLI 问题 #9084 会导致 codex -C /path review ... 无法正常工作。请在 worktree 内运行 codex review 以规避此问题。

快速开始

npx codex-mcp-bridge

前置条件

• 已安装 Codex CLI（npm i -g @openai/codex）
• 已设置 OPENAI_API_KEY 环境变量，或已完成 codex auth login

Claude Code

claude mcp add codex-bridge -- npx -y codex-mcp-bridge

Gemini CLI

添加到 ~/.gemini/settings.json：

{
  "mcpServers": {
    "codex-bridge": {
      "command": "npx",
      "args": ["-y", "codex-mcp-bridge"]
    }
  }
}

Cursor / Windsurf / VS Code

添加到 MCP 设置中：

{
  "codex-bridge": {
    "command": "npx",
    "args": ["-y", "codex-mcp-bridge"],
    "env": {
      "OPENAI_API_KEY": "sk-..."
    }
  }
}

工具

工具	描述
codex	在文件上下文中执行提示词，支持会话恢复和沙箱控制。通过会话 ID 进行多轮对话。适用于自由形式的代码审查提示词；参见使用此 CLI 进行代码审查。
review	使用 codex exec review --json 进行原生的、感知差异的 Codex 审查。无需调用方提供提示词；支持审查未提交更改、基准分支和提交。
search	通过 codex --search 进行网络搜索。返回综合整理的答案和来源 URL。
query	轻量级文本分析。不提供代码仓库上下文，也不支持会话。在隔离的临时目录中运行。
structured	通过 Ajv 验证 JSON Schema 输出。适用于数据提取、分类，或任何需要机器可解析输出的任务。
ping	健康检查，提供 CLI 版本、功能和并发诊断信息（activeCount、queueDepth）。
mcpStatus	报告 Codex 对其已知各 MCP 服务的状态：认证类型、工具清单以及是否已初始化。可选诊断模式会提供明确的失败状态和错误文本。
listSessions	列出活跃对话会话及其元数据（轮数、模型、时间戳）。

codex

通用执行。支持通过 sessionId 进行多轮对话、设置沙箱级别（read-only、workspace-write、full-auto）以及控制推理力度。传入 resetSession: true 可丢弃当前会话并重新开始。恢复会话前，使用 listSessions 查看活动会话。

关键参数：prompt（必填）、files、model、sessionId、sandbox、reasoningEffort、workingDirectory、timeout（默认 60s）。

search

通过 Codex CLI 的 --search 标志，使用 OpenAI 原生搜索基础设施进行网页搜索。返回综合整理的答案及来源 URL。

关键参数：query（必填）、model、workingDirectory、timeout（默认 120s）。

query

轻量级、非 Agent 式文本分析。在隔离的临时目录中启动，不会泄露桥接程序的仓库上下文。将要分析的文本传入 context 参数。支持 reasoningEffort 和 maxResponseLength。

关键参数：prompt（必填）、context、model、reasoningEffort、timeout（默认 60s）。

review

对 Codex CLI 原生差异感知审查功能的轻量封装。桥接程序将差异选择器传递给 codex exec review --json；审查提示词由上游 Codex 提供。需要通过 workingDirectory 指定一个真实的 git 仓库。

关键参数：mode（必填：uncommitted、base 或 commit）、workingDirectory（必填）、base（base 模式必填）、commit（commit 模式必填）、title、model、timeout（默认 180s）。

structured

将 JSON Schema 嵌入提示词，并使用 Ajv 验证响应。成功时返回整洁的 JSON，失败时返回验证错误。

关键参数：prompt（必填）、schema（必填，JSON 字符串）、files、model、workingDirectory、timeout（默认 60s）。

ping

无需参数。返回 CLI 版本、身份验证状态、模型配置和并发诊断信息（activeCount、queueDepth）。

mcpStatus

报告 Codex 自身的 app-server 协议所看到的各服务 MCP 状态。与其他所有工具不同，它会刻意保留 Codex 的 MCP 服务，也不会强化子进程环境，因为两者都会禁用正在测量的对象。因此，它会启动 ~/.codex/config.toml 中的服务，速度比普通调用慢。若设置 diagnostics: true，且 workingDirectory 位于受信任的项目中，它启动的线程还会启动该项目 .codex/config.toml 中配置的服务。

关键参数：diagnostics（默认 false）、workingDirectory、timeout（每次请求，默认 90s）。

模式	耗时	返回内容
default	~6-9s	清单：身份验证类型、工具名称和数量，以及每个服务的 initialized / unknown 状态。不创建线程，也不写入会话记录。
diagnostics: true	~10-20s	增加明确的 failed 状态和说明原因的错误文本（OAuth 授权已过期、缺少二进制文件、远程拒绝）。启动一个临时线程，不会将其写入磁盘。

解读输出：

• unknown 不代表失败。 这表示清单中没有服务信息，也没有明确的结论。只有 diagnostics: true 才能报告 failed。
• degraded 警告表示不要相信 unknown。 有观察到耗时较长的调用将正常服务报告为未初始化的情况，因此该工具会报告底层调用耗时，并在耗时长到足以引起怀疑时标记结果。
• builtIn 表示 Codex 注入的、未列在配置中的服务；configuredButUnreported 表示配置中列出但 Codex 从未提及的服务。

示例：

atlassian            failed       auth=oAuth  tools=0
    error: MCP client for `atlassian` failed to start: MCP startup failed: failed to
    refresh OAuth tokens for server atlassian: ... invalid_grant: Grant not found
codex_apps           initialized  auth=bearerToken  tools=117  (builtIn)
linear               initialized  auth=oAuth  tools=57
serena               initialized  auth=unsupported  tools=22

所有工具都会附加执行元数据（_meta），其中包含 durationMs、model、fallbackUsed，以及适用时的会话信息。详情请参阅 DESIGN.md。

使用此 CLI 进行代码审查

此桥接程序不捆绑审查提示词。代码审查有三种方式：

原生上游 codex review

codex review --base main
codex review --uncommitted
codex review --base main "Focus on security and error handling"

Codex CLI 内置的、支持差异感知的审查功能。不涉及桥接。如果客户端可以访问 shell，请使用此功能。

用于原生差异感知审查的桥接 review 工具

{
  "tool": "review",
  "arguments": {
    "mode": "base",
    "base": "main",
    "workingDirectory": "/path/to/worktree"
  }
}

桥接会在 workingDirectory 中运行 codex exec review --json，捕获最终审查文本，并返回 threadId、事件计数和经过脱敏的命令输出等审查元数据。它不接受提示词。

使用调用方提供的提示词的桥接 codex 工具

{
  "tool": "codex",
  "arguments": {
    "prompt": "<your review prompt + diff or file references>",
    "sandbox": "read-only"
  }
}

桥接会使用提供的提示词运行 codex exec --sandbox read-only，并返回 stdout。对于自由形式的审查提示词，或无法用 uncommitted、base 或 commit 差异选择器表示的审查输入，请使用此工具。

代表性审查提示词

可作为起点；请随意调整：

Review the following diff:

<diff content>

Look for:
- Bugs that would surface in production
- Missing error handling on user-supplied input
- Tests modified to silence failures rather than verify behaviour
- Security issues (injection, missing auth checks, secret leaks)

For each finding cite file:line, severity (high/medium/low), and a suggested fix.
Skip style/formatting; assume an autoformatter handles those.

桥接不对提示词内容作任何限制。有关原因，请参阅 ADR-001。

配置

变量	默认值	说明
CODEX_DEFAULT_MODEL	(CLI 默认值)	所有工具的默认模型
CODEX_FALLBACK_MODEL	o3	配额用尽时使用的备用模型（设为 none 可禁用）
CODEX_CLI_PATH	codex	CLI 二进制文件的路径
CODEX_MAX_CONCURRENT	3	并发子进程启动数上限
CODEX_MCP_SERVERS	(未设置)	控制哪些 Codex 内部 MCP 服务保持启用。请参阅 DESIGN.md。
CODEX_HOME	~/.codex	子进程用于进行身份验证的根目录

使用第二个 Codex 账户运行桥接

CODEX_HOME 会完整切换身份：身份验证信息、config.toml、技能和线程历史记录都存放在该根目录下，因此第二个根目录就相当于第二套安装。 此桥接发出的每次工具调用都是机器流量，而非有人正在使用的会话，因此它很适合用于工作或团队账户，而交互式 codex 则继续使用个人账户。

请在服务注册中设置它，而不要依赖当前 shell 环境，这样选择就不会受启动客户端的终端影响：

{
  "mcpServers": {
    "codex": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codex-mcp-bridge"],
      "env": {
        "CODEX_HOME": "/home/you/.codex-work",
        "CODEX_DEFAULT_MODEL": "gpt-5.6-sol"
      }
    }
  }
}

设置前请注意以下三点：

• 先使用该根目录登录，因为根目录是否可用取决于其凭据：CODEX_HOME=/home/you/.codex-work codex login（或 codex login --with-api-key）。使用 CODEX_HOME=/home/you/.codex-work codex login status 检查登录状态。
• JSON env 块不支持条件设置。 如果该根目录失去登录状态，桥接启动的每个子进程仍会以它为目标运行，而不会像 shell 包装脚本那样回退到默认根目录。
• 同时设置 CODEX_DEFAULT_MODEL。 桥接会从 CODEX_HOME 解析 config.toml，因此新建的根目录中没有该文件，模型就会退回 CLI 默认值。缺少该文件也会使 CODEX_MCP_SERVERS 的大部分配置不起作用：未配置任何内容时，没有可禁用或继承的内容，也没有可启用的名称；而这恰好符合默认设置的预期。唯一不会被禁用的是原始 TOML 覆盖（以 { 或 [ 开头的值），它会直接作为 -c mcp_servers=... 传递，不会读取 config.toml。

选择 Codex MCP 服务

你的需求……	可考虑
结构化输出、模型回退、并发管理、会话恢复	此桥接
使用 conversationId 进行会话串联、转发回调 URI	@tuannvm/codex-mcp-server
带审批策略的结构化补丁输出	cexll/codex-mcp-server
支持并行子 Agent 的精简 codex exec 包装器	codex-as-mcp
原生 Codex MCP（实验性，无需包装器）	codex mcp serve（文档）

性能

Codex CLI 的启动开销极小（<100ms），因此总耗时主要取决于模型推理。

场景	典型耗时
简单提示词	9-12s
网络搜索	~17s

默认超时时间（60-300s）足以应对常见工作负载。

Bridge 系列

两个 MCP 服务采用相同的架构，但底层 CLI 不同。每个服务都将终端 Agent 封装为子进程，并将其作为 MCP 工具提供。选择与模型提供商匹配的服务，或同时运行两个服务以支持跨模型工作流。

	codex-mcp-bridge	claude-mcp-bridge
CLI	Codex CLI	Claude Code
提供商	OpenAI	Anthropic
工具	codex、review、search、query、structured、ping、listSessions	query、review、search、structured、ping、listSessions
代码审查	review 工具封装原生 codex exec review --json，或使用由调用方提供提示词的 codex 工具	review 工具使用由调用方提供的提示词，并采用强化的隔离默认设置
结构化输出	Ajv 验证	原生 --json-schema
会话恢复	使用支持多轮对话的会话 ID	原生 --resume
预算上限	不支持	原生 --max-budget-usd
推理力度控制	reasoningEffort（low/medium/high）	--effort low/medium/high/max
冷启动	<100ms（耗时主要取决于推理）	~1-2s
身份验证	OPENAI_API_KEY	claude login（订阅）或 ANTHROPIC_API_KEY
费用	按 Token 付费	订阅（已包含）或 API 额度
并发数	3（可配置）	3（可配置）
模型回退	自动重试并使用备用模型	自动重试并使用备用模型

两者共用：子进程环境隔离、路径沙箱、输出脱敏（剥离机密信息）、FIFO 并发队列、MCP 工具注解、_meta 响应元数据、进度心跳。

开发

npm install
npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm test             # Run tests
npm run lint         # ESLint
npm run typecheck    # tsc --noEmit

延伸阅读

• DESIGN.md - 架构、MCP 服务控制语法、会话、输出解析、响应元数据
• SECURITY.md - 环境隔离、路径沙箱、输出脱敏、资源限制
• CHANGELOG.md - 发布历史

许可证

MIT