概述

在当前 AI 辅助编程的浪潮下，开发者面对的最大挑战不是模型能力的单点突破，而是如何让多种 AI 工具高效、智能地协同工作。Claude Code 擅长需求分析和架构设计，Codex 在代码生成和细节优化上表现出色。而 CodexMCP 项目正是连接它们的桥梁，通过 MCP 协议让二者优势互补，为 AI 编程协作带来革命性提升 。

一、项目背景与定位

CodexMCP 的核心使命是“多 AI 协同下的高效开发”。它支持多轮对话与并行任务，可以持久化会话上下文，让 Claude Code 负责需求分析、架构规划、代码重构，Codex 专注算法实现、bug 定位和代码审查。与官方 Codex MCP 实现相比，CodexMCP 增加了推理详情追踪、错误处理等企业级特性，极大地提升了工具间的信息流动和任务调度能力。

二、快速开始

前置要求：

• 已安装并配置 Claude Code 和 Codex。
• 建议 Windows 用户在 WSL 下体验，提升性能与兼容性。

安装步骤：

1. 移除官方 MCP（如果已安装）
   claude mcp remove codex
2. 安装 CodexMCP
   claude mcp add codex -s user --transport stdio -- uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp
3. 验证安装
   终端运行 claude mcp list，若显示 codex: uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp - ✓ Connected 即为安装成功。

可选：进一步优化 Claude Code 提示词，建议在 ~/.claude/CLAUDE.md 添加官方推荐内容，实现更优协同体验。

## Core Instruction for CodeX MCP

在任何时刻，你必须思考当前过程可以如何与codex进行协作，如何调用Codex 为你提供的MCP工具作为你客观全面分析的保障。
其中你**务必执行**以下几个步骤：
**1** 在你对用户需求形成初步分析后，将用户需求、初始思路告知codex，并要求其完善需求分析和实施计划。
**2** 在实施具体编码任务前，**必须向codex索要代码实现原型（要求codex仅给出unified diff patch，严禁对代码做任何真实修改）**。在获取代码原型后，你**只能以此为逻辑参考，再次对代码修改进行重写**，形成企业生产级别、可读性极高、可维护性极高的代码后，才能实施具体编程修改任务。
**3** 无论何时，只要完成切实编码行为后，**必须立即使用codex review代码改动和对应需求完成程度**。
**4** codex只能给出参考，你**必须有自己的思考，甚至需要对codex的回答提出置疑**。尽信书则不如无书，你与codex的最终使命都是达成统一、全面、精准的意见，所以你们必须不断争辩已找到通向真理的唯一途径。


## Codex Tool Invocation Specification

 1. 工具概述

  codex MCP 提供了一个工具 `codex`，用于执行 AI 辅助的编码任务。该工具**通过 MCP 协议调用**，无需使用命令行。

  2. 工具参数

  **必选**参数：
  - PROMPT (string): 发送给 codex 的任务指令
  - cd (Path): codex 执行任务的工作目录根路径

  可选参数：
  - sandbox (string): 沙箱策略，可选值：
    - "read-only" (默认): 只读模式，最安全
    - "workspace-write": 允许在工作区写入
    - "danger-full-access": 完全访问权限
  - SESSION_ID (UUID | null): 用于继续之前的会话以与codex进行多轮交互，默认为 None（开启新会话）
  - skip_git_repo_check (boolean): 是否允许在非 Git 仓库中运行，默认 False
  - return_all_messages (boolean): 是否返回所有消息（包括推理、工具调用等），默认 False

  返回值：
  {
    "success": true,
    "SESSION_ID": "uuid-string",
    "agent_messages": "agent回复的文本内容",
    "all_messages": []  // 仅当 return_all_messages=True 时包含
  }
  或失败时：
  {
    "success": false,
    "error": "错误信息"
  }

  3. 使用方式

  开启新对话：
  - 不传 SESSION_ID 参数（或传 None）
  - 工具会返回新的 SESSION_ID 用于后续对话

  继续之前的对话：
  - 将之前返回的 SESSION_ID 作为参数传入
  - 同一会话的上下文会被保留

  4. 调用规范

  **必须遵守**：
  - 每次调用 codex 工具时，必须保存返回的 SESSION_ID，以便后续继续对话
  - cd 参数必须指向存在的目录，否则工具会静默失败
  - 严禁codex对代码进行实际修改，使用 sandbox="read-only" 以避免意外，并要求codex仅给出unified diff patch即可

  推荐用法：
  - 如需详细追踪 codex 的推理过程和工具调用，设置 return_all_messages=True
  - 对于精准定位、debug、代码原型快速编写等任务，优先使用 codex 工具

  5. 注意事项

  - 会话管理：始终追踪 SESSION_ID，避免会话混乱
  - 工作目录：确保 cd 参数指向正确且存在的目录
  - 错误处理：检查返回值的 success 字段，处理可能的错误

三、核心功能解读

• 会话持久化：上下文信息多轮保存，实现跨模型深度协作。
• 并行执行：多模型任务分发，解锁性能上限。
• 推理追踪与错误处理：企业场景下的可追溯性与稳定性保障。

开发者只需专注于业务逻辑，模型分工、人机协同全部交给 CodexMCP 智能调度。

四、常见问题与贡献方式

• CodexMCP 完全开源且可免费商用，遵循 MIT 协议。
• 支持多种操作系统（Windows、Linux/macOS），适配主流 Python 环境。
• 欢迎参与贡献，可提交 PR、建议、文档等。

五、总结

CodexMCP 让 AI 编程协作迈入新阶段，为开发者提供了一个同时集成 Claude Code 的全局架构能力和 Codex 的代码生成能力的智能管控平台。不论是个人开发还是团队协作，都将成为高效生产力的加速器。如果你也在探索 AI 驱动的软件工程，不妨试试 CodexMCP，开启你的多 AI 时代