codex-mcp

Codex CLI 的 MCP 协议封装实现（增强版）

English | 简体中文

---

简介

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。

感谢关注，欢迎 Star