codex-mcp

简介

codex-mcp 是一个基于 Go 的 MCP（Model Context Protocol）服务器，用于将 OpenAI Codex CLI 封装为 MCP 工具，使 Claude Code、KiloCode、Roo Code、Cline 等客户端可以调用 Codex 执行任务。

适用场景：

• 让具备强规划能力的模型调用 Codex 完成高精度实现或修复
• 统一 MCP 调用入口，便于管理会话与监控

功能概览

核心能力

• 会话管理：支持 SESSION_ID 维持多轮对话
• 沙箱策略：read-only / workspace-write / danger-full-access
• 并发支持：多客户端并发调用
• 单文件部署：单一二进制文件，无运行时依赖

增强能力（本 Fork）

• 实时监控仪表盘（默认 http://127.0.0.1:6639）
• 多项目监控与切换
• 结构化错误码与诊断建议
• 指标统计（P50/P95/P99 延迟）
• 调试日志自动保存

快速开始

1. 前置要求

安装并配置 OpenAI Codex CLI：

npm i -g @openai/codex

2. 安装 MCP Server

方式 A：npx（推荐）

npx @zenfun510/codex-mcp-go

方式 B：下载二进制

从 Releases 下载对应平台。

方式 C：源码构建

git clone https://github.com/yimingll/codex-mcp.git
cd codex-mcp
go build -o codex-mcp ./cmd/server

客户端配置

方式 A：npx 启动

Claude Code

claude mcp add codex -s user --transport stdio -- npx -y @zenfun510/codex-mcp-go

Roo Code / KiloCode / 通用 JSON

{
  "mcpServers": {
    "codex": {
      "command": "npx",
      "args": ["-y", "@zenfun510/codex-mcp-go"],
      "env": {
        "OPENAI_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor (Native MCP)

1. Settings → Features → MCP
2. Add New MCP Server
3. 填写：
   • Name: codex
   • Type: stdio
   • Command: npx
   • Args: -y @zenfun510/codex-mcp-go

方式 B：本地二进制

Claude Code

claude mcp add codex -s user --transport stdio -- /path/to/codex-mcp

Roo Code / KiloCode / 通用 JSON

{
  "mcpServers": {
    "codex": {
      "command": "/path/to/codex-mcp",
      "args": [],
      "env": {
        "OPENAI_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor (Native MCP)

1. Settings → Features → MCP
2. Add New MCP Server
3. 填写：
   • Name: codex
   • Type: stdio
   • Command: /path/to/codex-mcp
   • Args: （留空）

验证

cat <<'EOF' | ./codex-mcp
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{}}}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF

返回包含 codex 工具说明即表示正常。

实时监控仪表盘

• 默认地址：http://127.0.0.1:6639
• 若端口被占用（已有监控服务器），新实例会连接到现有服务器
• 多个实例共享同一监控服务

API 端点

| 端点 | 说明 | |------|------| | GET / | Web 仪表盘 | | GET /api/status | 运行状态 | | GET /api/metrics | 执行指标 | | GET /api/projects | 活跃项目 | | GET /stream/events | SSE 事件流 |

自动打开浏览器

启动时默认自动打开浏览器，可通过环境变量禁用：

export CODEX_MCP_OPEN_BROWSER=false

| 值 | 行为 | |----|------| | 未设置 / true / 1 | 自动打开（默认） | | false / 0 | 不自动打开 |

数据存储

默认目录：~/.codex-mcp/

~/.codex-mcp/
└── debug/            # 调试日志目录
    └── no_agent_messages_20240101_120000.log

• 调试日志：仅在 NO_AGENT_MESSAGES 时生成

系统提示词推荐

智能体模式（KiloCode / Roo Code / Cline / Claude Code）

预配置文件：

• KiloCode：codex-engineer-kilocode.yaml
• Roo Code：codex-engineer-roocode.yaml
• Cline：codex-engineer-cline.yaml

Claude Code 或手动配置可使用以下提示词：

## Core Instruction for CodeX MCP

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

辅助编程模式（IDE 插件）

# Codex MCP Tool Rules

You have access to the `codex` tool, which wraps the OpenAI Codex CLI. Use it for complex code generation, debugging, and analysis.

## Workflow
1.  **Consultation**: Before writing complex code, ask Codex for a plan or analysis.
2.  **Prototyping**: Ask Codex for a `unified diff patch` to solve the problem.
    *   **IMPORTANT**: Always use `sandbox="read-only"` when asking for code.
    *   **IMPORTANT**: Do NOT let Codex apply changes directly.
3.  **Implementation**: Read the Codex-generated diff, understand it, and then apply the changes yourself using your own file editing tools.
4.  **Review**: After applying changes, you can ask Codex to review the code.

## Tool Usage
-   **Session**: Always capture and reuse `SESSION_ID` for multi-turn tasks.
-   **Path**: Ensure `cd` is set to the current workspace root.
-   **Safety**: Default to `sandbox="read-only"`. Only use `workspace-write` if explicitly instructed by the user and you are confident in the operation.

工具参数

工具名称：codex

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | PROMPT | string | ✅ | - | 发送给 Codex 的指令 | | cd | string | ✅ | - | 工作目录 | | sandbox | string | ❌ | read-only | read-only / workspace-write / danger-full-access | | SESSION_ID | string | ❌ | "" | 会话 ID | | skip_git_repo_check | bool | ❌ | true | 允许非 Git 目录 | | return_all_messages | bool | ❌ | false | 返回完整推理日志 | | stream_output | bool | ❌ | false | MCP 日志推送输出 | | debug | bool | ❌ | false | 输出调试日志 | | image | []string | ❌ | [] | 附加图片路径 | | yolo | bool | ❌ | false | 跳过所有确认 |

运行时说明

• 沙箱默认 read-only，Codex 仅可读文件

功能对比

与官方 Codex CLI

| 特性 | 官方 Codex CLI | Codex MCP | |------|----------------|-----------| | 基本调用 | ✅ | ✅ | | 多轮对话 | ❌ | ✅ | | 详细日志 | ❌ | ✅ | | 并行支持 | ❌ | ✅ | | 结构化错误 | ❌ | ✅ | | 实时监控 | ❌ | ✅ | | 指标统计 | ❌ | ✅ |

与 Python 版本 (codexmcp)

| 特性 | Go 版本 | Python 版本 | |------|--------|-------------| | 部署 | 单二进制 | 依赖 Python | | 启动速度 | 快 | 慢 | | 资源占用 | 低 | 较高 | | 并发模型 | Goroutine | Threading | | 实时监控 | ✅ | ❌ | | 多项目支持 | ✅ | ❌ | | 适用场景 | 生产环境 | 原型验证 |

故障排查

常见问题

• 连接失败：确认 codex CLI 已安装且在 PATH
• 无权限：检查二进制是否可执行（Linux 需 chmod +x）
• Session 丢失：确保客户端传递 SESSION_ID

错误码

| 错误码 | 说明 | 建议 | |--------|------|------| | CODEX_NOT_FOUND | 未安装 Codex CLI | 安装 @openai/codex | | WORKDIR_NOT_FOUND | 工作目录不存在 | 检查 cd | | NETWORK_TIMEOUT | 网络超时 | 检查网络 | | API_RATE_LIMIT | API 限流 | 稍后重试 | | NO_AGENT_MESSAGES | Codex 无响应 | 查看 ~/.codex-mcp/debug/ | | SANDBOX_VIOLATION | 沙箱限制 | 使用 workspace-write | | CONTEXT_CANCELED | 操作取消 | 无需处理 |

致谢

• 基于 w31r4/codex-mcp-go
• 受 codexmcp 启发

许可协议

本项目使用 MIT License。