Codex app-server MCP 桥接

想直接接入并开始使用？请先看 使用指南。

English documentation

安全问题请阅读 安全策略 并私下报告；参与贡献前请阅读 贡献指南。版本变更记录见 CHANGELOG.md。

本项目让 Claude Code 通过本地 stdio MCP 调用独立的 Codex app-server 会话，默认适用于提问、代码分析和只读审查；用户显式启用 workspace-write 后，也可在任务工作区内修改代码。它不会连接或继承当前 Codex 桌面聊天上下文；没有 threadId 时创建新会话，提供 threadId 时恢复该会话。

Claude Code → MCP stdio → 本桥接程序 → Codex app-server stdio → 独立 Codex thread

兼容性、安装与登录

最低 Node.js 版本为 20。已在 Windows 上核实 Node.js v24.14.1、npm 11.11.0、Codex CLI 0.154.0，并以该 Codex 版本生成协议定义核对字段。实现使用 Node.js 的跨平台 spawn(..., { shell: false })；macOS 和 Linux 尚未实际验证，不对此作出已验证声明。

$mcpDir = '<codex-app-server-mcp 所在目录>'
Set-Location $mcpDir
npm.cmd install
codex --version
codex login
node .\server.mjs

桥接优先使用 CODEX_EXECUTABLE；未设置时从 PATH 查找 codex（Windows 也查找 .exe、.cmd 和 .bat）。找不到时工具返回明确配置说明。桥接不会读取、复制、打印或硬编码令牌、API Key 或 Codex 全局配置。

Windows PowerShell：

$env:CODEX_EXECUTABLE = 'C:\Program Files\OpenAI\Codex\bin\codex.exe'
node D:\path\to\codex-app-server-mcp\server.mjs

macOS / Linux：

export CODEX_EXECUTABLE="$(command -v codex)" # 可省略，让程序从 PATH 查找
node /path/to/codex-app-server-mcp/server.mjs

未登录时，请在普通终端执行 codex login 后重启桥接。若本机 Codex 协议不兼容，初始化或对应 JSON-RPC 请求会以方法名和服务端错误明确失败，不会静默降级。

Related MCP server: Claude Code Subagent MCP

MCP 工具

codex_start({ prompt, cwd, threadId?, model? }) 按启动时的沙箱配置启动任务。prompt 必须非空；cwd 必须是存在的绝对目录。它立即返回 jobId、threadId 和已获得时的 turnId。同一桥接进程只允许一个活动任务，第二个调用会收到 busy；恢复既有 thread 时 cwd 必须与该 thread 初始 cwd 相同。

codex_status({ jobId, cursor?, waitMs? }) 返回任务状态 starting、running、waiting_for_input、completed、failed 或 cancelled，以及已收到的助手回复、错误、进度和关联 ID。传入上次结果的 outputCursor 作为 cursor 时，assistantReply 只包含增量；waitMs 支持最多 30 秒的长轮询。启动结果和状态均包含 sandboxMode，工具描述也显示当前模式。最多保留 100 个任务，每项回复最多 256 KiB，截断会标为 outputTruncated: true。

codex_cancel({ jobId }) 使用 app-server turn/interrupt 请求中断。返回 requested 仅表示已发出请求；只有收到匹配 turn/completed 的 interrupted 才确认 cancelled。重复取消和已结束任务有稳定结果。

codex_start({"prompt":"只回复 CODEX_OK，不读取或修改任何文件。","cwd":"D:\\project"})
codex_status({"jobId":"..."})
codex_cancel({"jobId":"..."})

codex_models({ cursor?, limit? }) 从当前 Codex app-server 实时读取可用模型。返回模型 ID、显示名称、描述、默认推理强度、支持的推理强度、可用性提示以及 nextCursor；Claude 可先调用此工具展示列表，再将用户选中的 model 传给下一次 codex_start。

codex_steer({ jobId, prompt }) 可向运行中的普通 turn 补充指令；codex_review({ threadId, target, delivery? }) 启动原生审查；codex_compact({ threadId }) 异步压缩长会话。Codex 需要澄清时，使用 codex_pending_input({ jobId }) 取得问题与 inputId，再由 codex_answer_input({ inputId, answers }) 明确回答；该流程不能批准命令或文件变更。codex_doctor() 显示连接、可执行文件、沙箱、目录白名单和可选任务索引配置。

设置 CODEX_STATE_PATH 后，桥接将以原子写入的本地 JSON 索引保留不含 prompt/回复/凭据的任务元数据；重启时已运行任务标为 unknown，不会自动重试，可使用保存的 threadId 手动恢复。

权限、超时和关闭

未设置 CODEX_SANDBOX_MODE 时使用 read-only。用户可显式设置为 workspace-write，其他值（包括空字符串和拼写错误）会导致启动失败。可写模式必须同时设置 CODEX_ALLOWED_ROOTS（分号分隔的目录列表或 JSON 字符串数组），任务 cwd 必须位于白名单内；未设置白名单时可写任务会拒绝启动。新建与恢复 thread 都明确设定当前沙箱和 approvalPolicy: "never"；每个 turn 再指定相应策略：只读为 { type: "readOnly", networkAccess: false }；可写为 { type: "workspaceWrite", writableRoots: [cwd], networkAccess: false }。never 代表不发起交互审批，不代表自动批准。服务端提出的命令、文件改动和权限审批一律拒绝；用户输入会进入等待状态，须通过 codex_pending_input 和 codex_answer_input 明确回答，未知服务端请求收到 JSON-RPC -32601，不会悬挂。工作区内写入在 workspace-write 下由沙箱直接允许，无需自动批准请求；超出沙箱的请求仍被拒绝。工具不接受改变沙箱或审批策略的参数，也不会使用危险绕过选项。

初始化超时为 20 秒，普通 RPC 超时为 30 秒。Codex 子进程退出、初始化失败或 JSON-RPC 失败会让活动任务失败，绝不误报成功。stdin 关闭、SIGINT 或 SIGTERM 时只关闭本桥接启动的 app-server，并清理计时器和待处理请求。

注册 Claude Code

已按当前 Claude Code 文档核对：stdio 选项和 --scope 必须放在服务名前，-- 后才是启动命令。请自行执行：

$mcpDir = '<codex-app-server-mcp 所在目录>'
$nodeExe = (Get-Command node.exe).Source
claude mcp add --transport stdio --scope user codex-agent -- "$nodeExe" (Join-Path $mcpDir 'server.mjs')
claude mcp get codex-agent

卸载命令：

claude mcp remove codex-agent --scope user

测试与分发

npm.cmd test
npm.cmd run test:real
npm.cmd pack --dry-run
npm.cmd pack

npm test 运行 JSONL 分块、启动响应前事件、忙状态、取消确认、子进程退出，以及使用官方 MCP 客户端 SDK 从外部进程启动服务的初始化、tools/list、不存在 cwd、未知 job 检查。test:real 额外验证真实 Codex 简短答复与 threadId 上下文恢复；它需要网络、有效登录和可用额度。测试只使用项目内 test-tmp，不会访问业务项目。模拟不会替代真实端到端成功。

npm 的 files 白名单仅包含运行必需的 server.mjs、lib/、README 和 LICENSE，排除测试、测试临时目录、日志、凭据、本地配置和会话数据。npm pack 仅在本地生成 tarball，不会发布到 npm。

两种 Codex 连接模式

MCP 服务应由 Claude Code、Cursor 等 MCP 客户端按其 command、args 和 env 配置自动启动；无需手动运行桥接进程或使用平台专属启动脚本。首次仍需在项目目录执行一次 npm.cmd install（或 npm install）。

两种模式向 Claude Code 暴露相同的 codex_start、codex_status、codex_cancel、codex_models、codex_steer、codex_review、codex_compact、codex_pending_input、codex_answer_input 和 codex_doctor 工具。每次启动只选择一种模式：设置 CODEX_APP_SERVER_URL 即为远程模式；未设置时为本地模式。

本地模式

本地模式由桥接程序以 spawn(codex, ['app-server', '--listen', 'stdio://']) 启动并管理子进程。cwd 是桥接机器上的存在目录，必须是绝对路径。桥接关闭时只停止它自己启动的 app-server。

Windows PowerShell：

Remove-Item Env:CODEX_APP_SERVER_URL -ErrorAction Ignore
$env:CODEX_EXECUTABLE = 'C:\Program Files\OpenAI\Codex\bin\codex.exe' # 或让程序从 PATH 查找
node D:\path\to\codex-app-server-mcp\server.mjs

macOS / Linux：

unset CODEX_APP_SERVER_URL
export CODEX_EXECUTABLE="$(command -v codex)" # 可省略
node /path/to/codex-app-server-mcp/server.mjs

远程模式

远程模式不会启动、重启或终止任何 Codex 进程；它只连接既有 app-server。cwd 是远程 Codex 执行环境中的绝对路径，桥接不会在本机检查它是否存在，远程 app-server 会验证它。

配置 CODEX_APP_SERVER_URL。跨机器连接必须使用 wss://；ws:// 仅接受 localhost、127.0.0.1 或 ::1，用于同机服务或 SSH 隧道。URL 不得内嵌用户名、密码或 Token。

Bearer Token 可任选其一提供：CODEX_REMOTE_BEARER_TOKEN，或 CODEX_REMOTE_TOKEN_FILE 指向只含 Token 的秘密文件。Token 只用于 WebSocket 握手的 Authorization: Bearer … 请求头，不会写入日志、任务状态或 README 示例。优先使用秘密文件。

Windows PowerShell（TLS 反向代理后的远程服务）：

$env:CODEX_APP_SERVER_URL = 'wss://codex.example.internal/app-server'
$env:CODEX_REMOTE_TOKEN_FILE = 'C:\secure\codex-app-server.token'
Remove-Item Env:CODEX_EXECUTABLE -ErrorAction Ignore
node D:\path\to\codex-app-server-mcp\server.mjs

macOS / Linux（TLS 反向代理后的远程服务）：

export CODEX_APP_SERVER_URL='wss://codex.example.internal/app-server'
export CODEX_REMOTE_TOKEN_FILE="$HOME/.config/codex-app-server.token"
node /path/to/codex-app-server-mcp/server.mjs

使用 SSH 隧道时，远程主机上的 app-server 应仅监听 loopback；在本机建立隧道后使用本地 ws://：

# 远程主机：使用其安全的 Token 文件启动 app-server
codex app-server --listen ws://127.0.0.1:4500 --ws-auth capability-token --ws-token-file /secure/codex-app-server.token
# 本机：保持隧道运行
ssh -N -L 4500:127.0.0.1:4500 user@codex-host
export CODEX_APP_SERVER_URL='ws://127.0.0.1:4500'
export CODEX_REMOTE_TOKEN_FILE="$HOME/.config/codex-app-server.token"
node /path/to/codex-app-server-mcp/server.mjs

远程 WebSocket 在任务运行时断开，任务会显示 status: "unknown" 与断线原因。桥接不会自动重连后重发该任务，避免重复执行；可以在确认远程状态后手动发起新任务。关闭桥接只关闭其 WebSocket 客户端连接，不会向远程 app-server 发送终止信号。

本地模式的真实 Codex 测试仍依赖本机登录和可访问的用户 Home。远程模式已使用本地受控 WebSocket 服务验证握手 Bearer 头、远程 cwd 透传和断线为 unknown；尚未针对外部真实远程 Codex 端点运行集成测试。

沙箱开关：默认只读，用户显式启用写入

在 Claude 项目的 .mcp.json 中，保留现有 codex-agent 的 command、args 和 env，在它的 env 对象中增加：

"CODEX_SANDBOX_MODE": "workspace-write"

保存后重启该项目的 Claude / MCP 连接。恢复只读时改为 read-only；删除该键将回退到进程环境，环境也未设置时才使用只读默认值。

这是一项启动配置，不是 Claude 可以通过 prompt 或 codex_start 参数自行切换的权限。每个桥接实例启动后固定使用该模式，新建、恢复会话及每次任务均重新发送对应权限。支持本地和远程连接；远程的 cwd 与可写目录属于远程执行环境。

写入范围是任务 cwd 工作区及 Codex 标准沙箱允许的临时目录，受服务端和平台的额外限制约束。不会开启网络或全磁盘访问。当前 cwd 仍由调用方提供，因此请明确任务目录。配置为 workspace-write 并不保证外部依赖下载或工作区外的全局缓存写入成功。

若为调试而手动启动，可仅使用环境变量：

$env:CODEX_SANDBOX_MODE = 'workspace-write'
$env:CODEX_ALLOWED_ROOTS = 'D:\projects\my-app'
node .\server.mjs

验证：npm.cmd test 包含默认值、非法配置、新建/恢复会话的双层权限、远程策略、审批拒绝和 MCP 工具描述检查。 真实沙箱文件测试使用独立临时目录（不修改业务仓库）：

$env:CODEX_RUN_SANDBOX_REAL = '1'
npm.cmd run test:sandbox-real

真实测试依次检查默认只读不能创建文件、显式开启写入能创建文件，以及恢复可写会话到只读后不能再次创建文件。需有效 Codex 登录和可用网络；未执行真实测试不能视为沙箱执行验证通过。

指定模型

在项目 .mcp.json 的 codex-agent.env 中设置 CODEX_MODEL 为账号可用的模型 ID，保存后重启 Claude / MCP。示例（将占位符替换为实际模型 ID）：

"CODEX_MODEL": "YOUR_MODEL_ID",
"CODEX_SANDBOX_MODE": "workspace-write"

未设置 CODEX_MODEL 时不传 model：新会话使用 Codex 默认配置，恢复会话遵循 Codex 对已有会话的默认行为。显式设置后，新建、恢复会话和每个 turn 均传入该模型。空值会报错；不自动替换账号不支持的模型，不修改 Codex 全局配置。该设置适用于本地和远程模式，也可通过启动环境传入。任务状态的 requestedModel 表示请求的模型 ID（未设置时为 null），不冒充服务端确认的实际模型。

通过话术切换模型

codex_start 现在接受可选 model 参数。对 Claude 说“通过 codex-agent，使用模型 <实际模型 ID> 审查当前项目”，Claude 应把模型 ID 传入 model，而不是仅写进 prompt。 优先级为：本次 model 参数 > CODEX_MODEL 启动配置 > Codex 默认。支持在下一次调用中沿用 threadId 并更换 model，兼容性和账号权限由服务端验证；不自动替换不支持的模型。运行中的任务不能中途切换，需等待结束或取消后再调用。未指定 model 且未配置 CODEX_MODEL 时，恢复已有会话遵循服务端已有模型设置。

注意：可通过话术选择模型，但不能通过话术改变沙箱权限；写入权限仍必须由用户配置 CODEX_SANDBOX_MODE。