使用说明

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

使用说明

codex-mcp

解决什么问题

架构

安装

前置依赖

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

方式 2：从源码安装

方式 3：npx 直接运行

CLI 使用

委托任务

查看任务状态

审查验收

返工

重试

启动 MCP Server

全局选项

MCP Server 配置

方式 1：claude mcp add（推荐）

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

方式 3：项目级 .mcp.json

方式 4：从源码启动

MCP 工具

delegate-task — 委托新任务给 Codex

check-task — 查看任务状态

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

rework-task — 发起返工

retry-task — 从 blocked 恢复重试

典型使用场景

任务状态机

安全机制

项目结构

开发

本地调试

许可

相关 MCP

规范工作流管理工具

协议桥接服务器

智能记忆与任务管理服务器

任务与记忆管理服务器

任务管理工具

任务管理服务