codex-mcp-go
Codex CLI 的 MCP 协议封装实现
⭐ 如果觉得好用，请给个 Star 吧！您的支持是我们更新的动力~ ⭐
English | 简体中文
简介
codex-mcp-go 是一个基于 Go 语言实现的 MCP (Model Context Protocol) 服务器。它封装了 OpenAI 的 Codex CLI，使其能够作为 MCP 工具被 KiloCode、Roo Code、Cline 等各种 "Vibe Coding" AI 客户端调用。
这个项目的初衷很简单：让强者更强，让专才专用。
在我自己的工作流中（在 KiloCode 里使用 Gemini 3.0 Pro），我发现像 Gemini 这样的先进模型拥有强大的规划能力和想象力，但在修复自己生成的复杂代码时偶尔会“卡壳”。而 Codex，这位老练的“代码老师傅”，虽然在宏大叙事上稍逊一筹，但在具体的代码实现、Bug 修复和遵循精确指令方面却无人能及。
所以，为什么不让它们合作呢？
受到 codexmcp (Python 实现) 的启发，我决定用我更喜欢的 Go 语言，边学 mcp-go-sdk 边重复造了这个轮子，主要目的是练手并打造一个更适合我自己的工具。
现在，你可以用一句话，在任何支持 MCP 的 Vibe Coding 工具中，让 Gemini 或 Claude 这样的“总指挥”去调用 Codex 这个“特种兵”来完成最棘手的编码任务。
主要特性：
- 会话管理：支持
SESSION_ID维持多轮对话上下文。 - 沙箱控制：提供
read-only、workspace-write等安全策略。 - 并发支持：基于 Go 协程，支持多客户端并发调用。
- 单文件部署：编译为单一二进制文件，无运行时依赖。
快速开始
1. 前置要求
本工具依赖 OpenAI 的 codex CLI。请确保您已安装并配置好它。
安装 Codex CLI:
# 使用 npm 安装 (推荐)
npm i -g @openai/codex
# 或者参考官方仓库
# https://github.com/openai/codex-cli
2. 安装 MCP Server
方式一：使用 npx (推荐)
无需安装 Go 环境，直接运行：
npx @zenfun510/codex-mcp-go
方式二：手动下载
从 Releases 页面下载对应平台的二进制文件。
方式三：源码构建
需要 Go 1.24+ 环境。
git clone https://github.com/w31r4/codex-mcp-go.git
cd codex-mcp-go
go build -o codex-mcp-go cmd/server/main.go
3. 配置 MCP 客户端
根据您使用的 AI 客户端，选择对应的配置方式。
方式 A：使用 npx (推荐)
claude mcp add codex -s user --transport stdio -- npx -y @zenfun510/codex-mcp-go
在 Roo Code 的 MCP 设置中添加：
{
"mcpServers": {
"codex": {
"command": "npx",
"args": ["-y", "@zenfun510/codex-mcp-go"],
"env": {
"OPENAI_API_KEY": "your-api-key"
}
}
}
}
配置文件路径参考：
- VSCode:
~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json - Cursor:
~/.config/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
在 ~/.kilocode/mcp.json 中添加：
{
"mcpServers": {
"codex": {
"command": "npx",
"args": ["-y", "@zenfun510/codex-mcp-go"],
"env": {
"OPENAI_API_KEY": "your-api-key"
}
}
}
}
- 打开 Cursor 设置 -> Features -> MCP
- 点击 "Add New MCP Server"
- 填写配置：
- Name:
codex - Type:
stdio - Command:
npx - Args:
-y @zenfun510/codex-mcp-go
- Name:
方式 B：使用本地二进制文件
如果您已通过 go build 构建了二进制文件（假设路径为 /path/to/codex-mcp-go），可使用以下配置：
claude mcp add codex -s user --transport stdio -- /path/to/codex-mcp-go
{
"mcpServers": {
"codex": {
"command": "/path/to/codex-mcp-go",
"args": [],
"env": {
"OPENAI_API_KEY": "your-api-key"
}
}
}
}
- 打开 Cursor 设置 -> Features -> MCP
- 点击 "Add New MCP Server"
- 填写配置：
- Name:
codex - Type:
stdio - Command:
/path/to/codex-mcp-go - Args: (留空)
- Name:
4. 验证
cat <<'EOF' | ./codex-mcp-go
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{}}}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF
需先完成 initialize 握手，然后才能调用 tools/list。若返回包含 codex 工具的 JSON 数据，即表示运行正常。
5.（可选）服务端配置（配置文件 + 环境变量）
支持通过 TOML 配置文件 或 环境变量 调整运行策略。优先级：默认值 < 配置文件 < 环境变量。
./codex-mcp-go --config ./codex-mcp.example.toml
# 或
CODEX_MCP_CONFIG=./codex-mcp.example.toml ./codex-mcp-go
环境变量（会覆盖配置文件）：
CODEX_MCP_SERVER_NAME/CODEX_MCP_VERSIONCODEX_DEFAULT_TIMEOUT/CODEX_MAX_TIMEOUT/CODEX_NO_OUTPUT_TIMEOUT（单位：秒）CODEX_MAX_BUFFERED_LINES/CODEX_EXECUTABLE_PATHCODEX_ALLOWED_MODELS/CODEX_ALLOWED_PROFILES（逗号分隔；*表示允许任意值；默认空=全部拒绝）CODEX_DEFAULT_SANDBOX/CODEX_ALLOWED_SANDBOX_MODES（逗号分隔）CODEX_ALLOWED_WORK_DIRS（逗号分隔的目录前缀列表；空=不限制）CODEX_DISABLE_YOLO（true/false）CODEX_LOG_LEVEL/CODEX_LOG_FORMAT/CODEX_LOG_OUTPUT/CODEX_LOG_FILE
推荐的系统提示词 (System Prompts)
为了获得最佳体验，建议根据您使用的客户端类型配置相应的系统提示词。
1. 智能体模式 (KiloCode / Roo Code / Cline / Claude Code)
适用于能够自主规划和执行多步任务的 Agent。
对于 KiloCode / Roo Code / Cline 用户： 本项目提供了针对不同客户端的预配置专家模式文件。请根据您使用的客户端选择对应的文件导入：
- KiloCode:
codex-engineer-kilocode.yaml - Roo Code:
codex-engineer-roocode.yaml - Cline:
codex-engineer-cline.yaml
导入后，您将获得经过调优的 "Codex 协作专家" 模式，该模式已针对您的客户端进行了身份认同适配。
对于 Claude Code 或手动配置： 请将以下内容添加到您的 Agent 配置或作为任务的初始指令：
## 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
- image (List[Path] | null): 附加一个或多个图片文件到初始提示词，默认为 None
- model (string | null): 指定使用的模型，默认为 None（使用用户默认配置）
- yolo (boolean | null): 无需审批运行所有命令（跳过沙箱），默认 False
- profile (string | null): 从 `~/.codex/config.toml` 加载的配置文件名称，默认为 None（使用用户默认配置）
3. 调用规范
**必须遵守**：
- 每次调用 codex 工具时，必须保存返回的 SESSION_ID，以便后续继续对话
- cd 参数必须指向存在的目录，否则工具会静默失败
- 严禁codex对代码进行实际修改，使用 sandbox="read-only" 以避免意外，并要求codex仅给出unified diff patch即可
推荐用法：
- 如需详细追踪 codex 的推理过程和工具调用，设置 return_all_messages=True
- 对于精准定位、debug、代码原型快速编写等任务，优先使用 codex 工具
2. 辅助编程模式
适用于作为 IDE 插件运行的助手。建议添加到 .clinerules (Roo Code) 或 "Rules for AI" (Cursor) 中：
# 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
运行时行为： 默认 30 分钟总超时（上限 30 分钟），无输出看门狗默认关闭；出现错误行、非零退出会携带最近输出返回，便于定位卡住原因。若网络慢或 MCP 客户端自身有较短的 RPC 超时，调用时保持 timeout_seconds=1800，以避免过早被取消。
默认策略： sandbox=read-only、yolo=false、skip_git_repo_check=false；model/profile 默认拒绝，需显式放行；timeout_seconds=1800（最多 1800）、no_output_seconds=0（关闭）。
功能对比
1. 与官方 Codex CLI 对比
2. 与 Python 版本 (codexmcp) 对比
故障排查
- 连接失败：检查
codexCLI 是否在 PATH 中，或确认 Go 版本 >= 1.24。 - 无权限：检查二进制文件是否有执行权限 (
chmod +x)。 - Session 丢失：确保客户端正确传递了上一次调用返回的
SESSION_ID。
开源协议
本项目采用 MIT License 开源协议。
致谢
本项目深受 codexmcp (Python 实现) 的启发。感谢 GuDaStudio 团队在探索 Codex MCP 集成方面所做的开创性工作。
再次感谢您的关注！别忘了点个 Star 哦~ 🌟
