codex-mcp

一个 MCP Server，让 Claude Code 通过 MCP 协议将编码任务委托给 Codex 执行。

解决什么问题

Claude Code 擅长理解需求、拆分任务、审查代码，但逐行写代码效率受限。Codex 擅长在 sandbox 中快速实现代码，但缺乏全局视野和审查能力。

手动在两个工具间切换的问题：

• 需要人工复制粘贴上下文，容易丢失信息
• 没有统一的状态管理，任务进度散落在聊天记录中
• Codex 可能越界修改不该动的文件，缺乏自动化的安全检查
• 返工缺乏流程控制，可能无限循环

codex-mcp 通过 MCP 工具自动化整个委托流程：Claude Code 调用 delegate-task 发起任务，调用 check-task 查看状态，调用 accept-task 审查验收——全程不离开 Claude Code。

核心保障：

• 安全边界 — 双层约束（sandbox 硬约束 + Allowed Paths 软约束），越界自动拒绝验收
• 结果验收 — 自动校验返回结果完整性（Summary / Tests / Files Changed），不完整则要求补全
• 返工控制 — 最多 3 次返工，超限自动阻塞，防止无限循环
• 并发安全 — 同仓库串行调度，不同仓库可并行
• 异常恢复 — MCP 调用失败、线程丢失均有明确恢复路径

架构

Claude Code
    │  调用 MCP 工具 / CLI 命令
    ▼
codex-mcp (本项目)         ← CLI + MCP Server
    │  任务管理 / 安全校验 / 结果验收
    │  调用 codex exec --json subprocess
    ▼
Codex CLI (codex exec)     ← 直接 subprocess 调用
    │
    ▼
Codex 执行环境 (sandbox)
    │
    ▼
目标仓库

codex-mcp 提供两种使用方式：CLI 命令和 MCP Server，共享同一套服务层。底层通过 codex exec --json subprocess 调用 Codex（无需嵌套 MCP Client），从 JSON 事件流中提取 thread_id 和 agent_messages。

安装

前置依赖

• Node.js >= 18
• Codex CLI 已安装并可用（codex 命令在 PATH 中）

方式 1：全局安装（推荐）

npm install -g codex-mcp

方式 2：从源码安装

git clone <repo-url> && cd codex-mcp
npm install
npm run build
npm link        # 注册全局命令 codex-mcp

方式 3：npx 直接运行

npx codex-mcp --help
npx codex-mcp serve

CLI 使用

安装后可通过 codex-mcp 命令使用：

codex-mcp --help

委托任务

# 创建新任务并委托给 Codex
codex-mcp delegate --goal "实现 OAuth2 登录" --paths src/auth/,src/types/ \
  --constraints "不修改数据库 schema" \
  --criteria "单元测试通过"

# 从已有任务文件委托
codex-mcp delegate --file T-001

查看任务状态

codex-mcp check T-001
codex-mcp check T-001 --pretty    # 格式化输出

审查验收

codex-mcp accept T-001

返工

codex-mcp rework T-001 --items "修复越界问题,补充边界测试"

重试

codex-mcp retry T-001    # 从 blocked 恢复为 todo

启动 MCP Server

codex-mcp serve

全局选项

选项	说明
--pretty	人类可读 JSON 输出（默认紧凑 JSON）
--cwd <dir>	指定工作目录（默认当前目录）
--codex-cmd <cmd>	指定 Codex 命令（默认 codex，也可通过 CODEX_CMD 环境变量设置）

所有命令输出 JSON 格式（AI 友好），--pretty 时格式化缩进。

MCP Server 配置

方式 1：claude mcp add（推荐）

claude mcp add codex-mcp -s user -- npx codex-mcp serve

方式 2：编辑 ~/.claude/settings.json

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

方式 3：项目级 .mcp.json

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

方式 4：从源码启动

{
  "mcpServers": {
    "codex-mcp": {
      "command": "node",
      "args": ["<path-to-codex-mcp>/dist/serve.js"]
    }
  }
}

配置后 Claude Code 即可使用 codex-mcp 暴露的 MCP 工具。

MCP 工具

codex-mcp 向 Claude Code 暴露以下 5 个工具（CLI 和 MCP Server 共享同一逻辑）：

delegate-task — 委托新任务给 Codex

自动生成任务 ID、创建任务文件、委托给 Codex 执行。

参数	类型	必填	说明
goal	string	是	任务目标
allowedPaths	string[]	是	允许 Codex 修改的路径列表
constraints	string	否	约束条件
acceptanceCriteria	string	否	验收标准
cwd	string	否	项目根目录，默认当前目录

返回：{ taskId, threadId, status, filePath }

check-task — 查看任务状态

参数	类型	必填	说明
taskId	string	是	任务 ID（如 T-001）

返回：{ taskId, status, reworkCount, goal, codexThreadId, lastCodexResultSummary, lastCodexTestReport }

accept-task — 审查并验收 Codex 返回的结果

运行完整审查流水线：解析结果 → 权限检查 → 完整性校验 → 越界检测。

参数	类型	必填	说明
taskId	string	是	任务 ID

返回：{ taskId, action, reason, status }

action 取值：

• done — 验收通过
• rework — 需要返工（越界/质量不达标）
• blocked — 阻塞（返工超限/权限拒绝/补全失败）
• boundary_confirmation — 需要 Claude Code 确认是否扩大改动范围

rework-task — 发起返工

参数	类型	必填	说明
taskId	string	是	任务 ID
reviewItems	string[]	是	需要修改的具体项

返回：{ taskId, threadId, status, reworkCount }

retry-task — 从 blocked 恢复重试

参数	类型	必填	说明
taskId	string	是	任务 ID

返回：{ taskId, status }

典型使用场景

在 Claude Code 中对话：

用户：把 src/auth/ 下的登录逻辑改成支持 OAuth2

Claude Code：
  1. 拆分任务，定义 allowedPaths: ["src/auth/", "src/types/auth.ts"]
  2. 调用 delegate-task 委托给 Codex
  3. Codex 在 sandbox 中实现，返回结果
  4. 调用 accept-task 自动审查：
     - 检查结果完整性（Summary/Tests/Files Changed）
     - 检查是否越界修改了 allowedPaths 之外的文件
     - 全部通过 → done
     - 越界 → 自动调用 rework-task 要求回滚

任务状态机

todo ──→ doing ──→ review ──→ done
  │        │         │ ↺
  └→ blocked ←───────┘
         │
         └→ todo (retry-task)

转换	触发条件
todo → doing	delegate-task 调用成功
doing → review	Codex 返回结果
review → done	accept-task 验收通过
review → doing	rework-task 发起返工（最多 3 次）
review → blocked	返工超限 / 越界且超限
* → blocked	MCP 调用失败 / 权限拒绝
blocked → todo	retry-task 人工重试

安全机制

硬约束：sandbox=workspace-write 限制 Codex 只能写入 cwd 及其子目录，操作系统级别阻止仓库外写入。

软约束：developer-instructions 注入 Allowed Paths 列表，指示 Codex 只在指定路径内工作。Codex 可能不严格遵守，因此 accept-task 在验收时自动核查 Files Changed 是否越界，越界则拒绝验收。

项目结构

src/
├── cli/
│   ├── index.ts              # CLI 入口（parseArgs 分发）
│   ├── task-io.ts            # 任务文件 filesystem I/O
│   ├── codex-runner.ts       # codex exec --json subprocess 封装（实现 McpCaller）
│   └── services.ts           # 共享服务层（CLI + MCP 共用）
├── mcp-server/
│   └── index.ts              # MCP Server 工具注册
├── main.ts                   # bin 入口：CLI
├── serve.ts                  # bin 入口：MCP Server
├── types/                    # TaskDocument, MCP 接口, 结果类型
├── task-manager/             # 状态机, 任务文件读写, 返工控制, 审查验收
├── delegation-engine/        # Prompt 生成, MCP 调用封装
├── result-processor/         # 结果解析, 完整性校验, 补全请求
├── security/                 # 越界检测, developer-instructions, 确认处理
├── scheduler/                # 并发锁, 调度器
└── error-handler/            # MCP 异常处理, 线程恢复

agents/tasks/                 # 任务文件事实源（Markdown 格式）

开发

npm install             # 安装依赖
npm run build           # TypeScript 编译
npm test                # 运行全部测试（151 个）

本地调试

# 直接运行 CLI（无需 build）
npx tsx src/main.ts --help
npx tsx src/main.ts check T-001 --pretty

# 构建后运行
npm run build
node dist/main.js check T-001

# 启动 MCP Server
node dist/serve.js

许可

MIT