Codex代理管理服务

codex mcp

包装的MCP服务器 OpenAI 代码专家 --启动编码代理，轮询其进度，并管理来自任何MCP客户端的权限。支持两者 app-server （全功能）和 exec （不带应用服务器的codex变体的回退）模式。

特性

• 4个工具，功能齐全 — codex, codex_reply, codex_session, codex_check
• 异步非阻塞 --会话在后台运行，轮询结果
• 完整的权限管理 --三层模型：审批策略、沙盒隔离、异步审批仲裁
• 零配置 --继承您的本地 ~/.codex/config.toml 自动地
• 会话管理 --列出、检查、取消、中断、分叉会话
• 事件流 --基于指针的分页，带有pin保护的事件缓冲区
• 静态只读资源 — codex-mcp:///server-info, codex-mcp:///compat-report, codex-mcp:///config, codex-mcp:///gotchas, codex-mcp:///quickstart, codex-mcp:///errors

先决条件

• Node.js >= 18
• OpenAI Codex命令行界面 已安装并配置(codex 在PATH中）

快速开始

npx（不安装）

npx @leo000001/codex-mcp

全局安装

npm install -g @leo000001/codex-mcp
codex-mcp

Windows shell包装器（如果需要）

pwsh -NoProfile -Command "npx -y @leo000001/codex-mcp"

MCP客户端配置

添加到您的MCP客户端配置中（例如Claude Desktop、Cursor等）：

{
  "mcpServers": {
    "codex": {
      "command": "npx",
      "args": ["-y", "@leo000001/codex-mcp"]
    }
  }
}

克劳德代码

claude mcp add codex-mcp -- npx -y @leo000001/codex-mcp

或添加到 ~/.claude/settings.json:

{
  "mcpServers": {
    "codex-mcp": {
      "command": "npx",
      "args": ["-y", "@leo000001/codex-mcp"]
    }
  }
}

STDIO保护模式

codex-mcp 包括用于stdout污染风险的启动飞行前防护。

• CODEX_MCP_STDIO_MODE=auto （默认）：当风险升高时，运行时会发出警告
• CODEX_MCP_STDIO_MODE=strict：在阻断风险（如TTY stdio）方面快速失败，将启发式风险作为警告
• CODEX_MCP_STDIO_MODE=off：禁用飞行前防护

执行回退模式

当codex二进制文件不支持时 app-server （例如，内部变体，如 codex-internal)，codex mcp自动回退到 codex exec --json 模式。

Exec模式支持多回合上下文 通过 codex exec resume.第一回合使用 codex exec，后续使用 codex exec resume <threadId>.

执行模式限制：

• 无批准/用户输入交互
• threadFork/threadResume 扔 EXEC_NOT_SUPPORTED
• sandbox/profile/cwd/outputSchema 覆盖仅适用于第一轮（exec-resume不支持这些标志）

检查 codex-mcp:///server-info clientMode 字段以检测哪个模式处于活动状态。

示例：

CODEX_MCP_STDIO_MODE=strict npx -y @leo000001/codex-mcp

$env:CODEX_MCP_STDIO_MODE = "strict"; npx -y @leo000001/codex-mcp

工具

codex --开始新会话

异步启动Codex代理会话。立即返回 sessionId.

退货： { sessionId, threadId, status: "running" | "idle", pollInterval }

{
  "prompt": "Fix the failing tests in src/",
  "approvalPolicy": "on-request",
  "sandbox": "workspace-write",
  "effort": "high",
  "cwd": "/path/to/project",
  "model": "o4-mini"
}

资源

如果您的MCP客户端支持资源，则此服务器会公开一些 只读 资源：

• codex-mcp:///server-info （JSON）：静态服务器元数据（版本/平台/运行时）
• codex-mcp:///compat-report （JSON）：跨后端适配器兼容性的能力摘要
• codex-mcp:///config （Markdown）：配置映射指南，包括如何使用 codex.advanced.config
• codex-mcp:///gotchas （Markdown）：实际限制/陷阱
• codex-mcp:///quickstart （Markdown）：最小工作流示例
• codex-mcp:///errors （Markdown）：错误代码目录+恢复提示

codex_reply --继续会话

向现有会话发送后续消息。

退货： { sessionId, threadId, status: "running" | "idle", pollInterval }

{
  "sessionId": "sess_abc123",
  "prompt": "Now add error handling for the edge cases"
}

codex_session --管理会话

列出、检查、取消、中断、分叉会话或清理后台终端。

退货：

• action="list" → { sessions: PublicSessionInfo[] }
• action="get" → PublicSessionInfo （或 SensitiveSessionInfo 当 includeSensitive=true)
• action="cancel"|"interrupt" → { success: true, message }
• action="fork" → { sessionId, threadId, status: "idle", pollInterval }
• action="clean_background_terminals" → { success: true, message }

{ "action": "list" }
{ "action": "get", "sessionId": "sess_abc123", "includeSensitive": true }
{ "action": "cancel", "sessionId": "sess_abc123" }
{ "action": "interrupt", "sessionId": "sess_abc123" }
{ "action": "fork", "sessionId": "sess_abc123" }
{ "action": "clean_background_terminals", "sessionId": "sess_abc123" }

codex_check --投票事件和回复

查询正在运行的会话中的事件、响应审批请求或回答用户输入。

回报（投票和回复_*）： { sessionId, status, pollInterval?, cursorResetTo?, events, nextCursor, actions?, result? }

{ "action": "poll", "sessionId": "sess_abc123", "cursor": 0 }
{
  "action": "respond_permission",
  "sessionId": "sess_abc123",
  "requestId": "req_xyz",
  "decision": "accept"
}
{
  "action": "respond_user_input",
  "sessionId": "sess_abc123",
  "requestId": "req_abc",
  "answers": { "question_id": { "answers": ["choice_1"] } }
}

事件轮询语义

codex_check(action="poll") 返回一个带有光标分页的仅追加事件流：

• cursor：您想要的第一个事件id（使用前面的 nextCursor)
• nextCursor：在下一次投票中传递此信息
• cursorResetTo当存在时，较旧的活动会被驱逐；从此光标重新启动以避免出现空白
• maxEvents：每次调用返回的最大事件数
• 如果 cursor 如果省略，codex mcp将从该会话的最后一个使用的游标继续。
• 如果 responseMode 省略，codex mcp使用 minimal.
• pollOptions.includeEvents/includeActions/includeResult 默认 true.
• pollOptions.maxBytes 是可选的，并强制执行尽力而为的有效载荷截断(truncated, truncatedFields).
• respond_* 默认为压缩ACK(events: []，没有光标前进），除非您明确传递 maxEvents.
• poll 默认为 maxEvents=1 保持有效载荷较小；暂时增加（例如 10-20)当你需要更快地赶上的时候。
• 如果 poll 被称为 maxEvents=0，codex mcp将其视为 1 以避免无操作轮询循环。
• 对于 respond_*，更喜欢 maxEvents=0 而不是 1: 0 保持批准ACK最小，并避免在同一呼叫中消耗/重放流事件。使用 1-5 只有当你明确需要即时事件时。
• 对于 poll，保持窗口较小，以减少有效载荷峰值和上下文压力。

事件类型包括 output, progress, approval_request, approval_result, result, error. 批准/结果/错误被固定，以降低驱逐风险。

批准和用户输入

当代理请求批准或用户输入时， poll 包括a actions[] 列表。回复：

• respond_permission: decision 是其中之一 accept, acceptForSession, decline, cancel.
  • 对于命令批准， acceptWithExecpolicyAmendment 支持并要求 execpolicy_amendment.
• respond_user_input：发送 answers 被问题所困扰 id.
• 对于命令批准， actions[] 可能包括 commandActions 和 proposedExecpolicyAmendment 更丰富的评论UI。

待批准后自动拒绝 advanced.approvalTimeoutMs.

Auth回调注释：如果应用服务器发送 account/chatgptAuthTokens/refresh，codex mcp返回JSON-RPC错误 -32000 因为外部ChatGPT令牌刷新超出了此服务器的范围。

会话生命周期和清理

会话在后台自动清理：

• idle >30分钟→ 取消
• running/waiting_approval >4小时→ 取消
• cancelled/error >5分钟→ 从内存中删除

错误模型

工具返回错误如下：

{ "content": [{ "type": "text", "text": "Error [CODE]: message" }], "isError": true }

常见代码包括 INVALID_ARGUMENT, SESSION_NOT_FOUND, SESSION_BUSY, SESSION_NOT_RUNNING, REQUEST_NOT_FOUND, CANCELLED, INTERNAL.

客户端兼容性说明

• 工具响应如下 @modelcontextprotocol/sdks CallToolResult 合同： content （JSON文本以实现广泛兼容性），可选 structuredContent （规范对象），以及 isError. structuredContent 总是物体形状的；当工具返回标量/数组时，codex mcp将其包装为 { "value": ... }.Claude Desktop和其他客户倾向于浮出水面 content 直接显示文本，显示原始JSON blob，因此它们应该回退到 structuredContent 当他们需要键入数据时（只要有结构化输出可用，Cursor就会自动执行此操作）。
• 当操作失败时，我们设置 isError: true 并返回 Error [CODE]: message 在 content 阵列，而不是引发MCP传输错误。这使STDIO通道保持健康，因此即使在工具报告问题时，Claude、Cursor和其他MCP客户端也会保持连接。
• codex-mcp 使用MCP stdio传输(src/index.ts)，因此stdout保留用于换行符分隔的JSON，所有诊断都转到stderr。stdout上的任何其他内容，包括shell/profile横幅（例如PowerShell的哦，我的豪华警告）或打印提示的CLI包装器，都会破坏Claude/Cursor的MCP握手。跑 pwsh -NoProfile，禁用配置文件横幅，或包装命令，以便stdout在将其管道传输到客户端之前保持安静。
• 在内部执行Windows命令 codex app-server 在某些环境中，可能仍会继承PowerShell配置文件的副作用。一旦在stdout上发出codex mcp，就无法对其进行过滤；如果命令回合嘈杂或因配置文件错误而失败，请清理PowerShell配置文件并首选 approvalPolicy="on-failure" / "never" 以减少审批流失。
• 如果Windows命令输出显示mojibake，则在shell中强制UTF-8(chcp 65001 和 $OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new()).
• 启动保护行为由以下因素控制 CODEX_MCP_STDIO_MODE (auto/strict/off).使用 strict 在CI或硬化环境中，在阻断污染风险方面快速失败（同时仍然出现启发式风险警告）。
• 可重试传输/API中断发出为 progress 事件与 data.method="codex-mcp/reconnect" 和 willRetry=true，因此客户端可以显示重新连接状态，而不会将其视为终端故障。
• 审批/用户输入流程取决于 actions[] 返回的数组 codex_check(action="poll").Claude和Cursor从该负载中呈现批准按钮，因此他们需要在 pollInterval，荣誉 cursorResetTo，并在内回复 approvalTimeoutMs 以避免自动下降。

典型工作流程

1. codex(prompt="Fix bug X")           → { sessionId, threadId, status: "running" }
2. codex_check(action="poll", ...)      → events[], status, actions[]
3. codex_check(action="respond_permission", decision="accept")  (if needed)
4. codex_check(action="poll", ...)      → result when status="idle"
5. codex_reply(prompt="Also add tests") → new turn starts
6. codex_check(action="poll", ...)      → poll until done

权限模型

三层保护：

建筑

相同平台假设：codex mcp假设mcp客户端和服务器在同一台机器上运行。所有通信都使用stdio（本地IPC），子进程共享本地文件系统和 ~/.codex/config.toml，以及 cwd 路径指的是本地文件系统。

MCP Client ←stdio→ codex-mcp server ←stdio→ codex app-server ←→ Codex Agent   (app-server mode)
MCP Client ←stdio→ codex-mcp server ←stdio→ codex exec --json ←→ Codex Agent  (exec fallback)
         (same machine, stdio transport)

每个会话都会生成一个独立的子进程。在应用服务器模式下，它通过stdio使用JSON-RPC协议。在exec回退模式下，它使用 codex exec --json JSONL输出 codex exec resume 适用于多回合背景。

发展

git clone https://github.com/xihuai18/codex-mcp.git
cd codex-mcp
npm install
npm run build
npm run typecheck
npm test
npm run check:stdio
npm run check:stdio:strict

端到端本地测试计划（在MCP客户端中安装/配置后）：

• 完整指南（LLM操作员手册）： docs/E2E_LOCAL_TEST_PLAN.md
• 快速英语检查表：运行 codex → 投票与 codex_check(action="poll") → 通过以下方式回复 respond_permission/respond_user_input 如果 actions[] 出现→ 继续轮询，直到 status 是 idle/error/cancelled.

项目政策

• 贡献
• 安全
• 行为准则

许可证

麻省理工学院