Codex Persistent MCP

🚀 codex-persistent-mcp

codex-persistent-mcp 是一个轻量级的 MCP（标准输入输出）服务器，它将会话持久化功能委托给本地的 codex-cli。这样一来，通过 MCP 进行的调用也能创建真实的会话，用户之后可以使用 codex resume <session_id> 命令继续之前的会话。

🚀 快速开始（推荐：使用 npx 自动更新）

Claude Code

claude mcp add-json --scope user codex-persistent \
  '{"command":"npx","args":["-y","codex-persistent-mcp"],"env":{"CODEX_BIN":"/absolute/path/to/codex"}}'

验证：

claude mcp list
claude mcp get codex-persistent

Codex CLI

codex mcp add codex-persistent --env CODEX_BIN=/absolute/path/to/codex -- npx -y codex-persistent-mcp

验证：

codex mcp list --json
codex mcp get codex-persistent --json

Antigravity

Antigravity 支持通过 --add-mcp 添加 MCP 服务器：

antigravity --add-mcp '{"name":"codex-persistent","command":"npx","args":["-y","codex-persistent-mcp"],"env":{"CODEX_BIN":"/absolute/path/to/codex"}}'

✨ 主要特性

• 其他代理可以通过 MCP 调用 Codex，并且仍然能够获得真实的持久化会话。
• 服务器重启不会丢失上下文（上下文存储在 Codex CLI 的会话存储中）。
• 用户可以随时使用 codex resume <session_id> 命令继续之前的对话。
• 通过 MCP 创建的会话会显示在同一项目（当前工作目录）的 codex resume 列表中。

📦 安装指南

安装与构建

npm install
npm run build

全局安装（可选）

发布到 npm 后，你可以将其作为全局 CLI 工具进行安装：

npm install -g codex-persistent-mcp

运行

npm start

💻 使用示例

基础用法

此服务器提供了 3 个主要工具（所有工具都返回 session_id）：

• codex_chat
  • 输入：session_id?（UUID）、prompt、cwd?、model?、reasoning_effort?、timeout_ms?
  • 输出：session_id、reply、usage?
• codex_plan
  • 输入：session_id?、requirements、plan、constraints?、cwd?、model?、reasoning_effort?、timeout_ms?
  • 输出：session_id、critique、usage?
• codex_review
  • 输入：session_id?、change_summary、test_results?、open_questions?、cwd?、model?、reasoning_effort?、timeout_ms?
  • 输出：session_id、review、usage?

向后兼容的工具名称仍然可用：codex_guard_plan 和 codex_guard_final。

🔧 技术细节

工作原理（codex resume 为何有效）

每次调用工具时，都会生成一个 codex 子进程：

• 新会话：
  • codex exec --skip-git-repo-check --json -C <cwd> "<prompt>"
• 恢复会话：
  • codex exec --skip-git-repo-check --json -C <cwd> resume <session_id> "<prompt>"

服务器会解析 --json 产生的 JSONL 事件流：

• 将 thread.started.thread_id 作为 MCP session_id 读取。
• 收集类型为 agent_message 的 item.completed 事件，并将最终消息作为 reply 返回。

对同一 session_id 的请求会进行序列化处理，以避免写入顺序混乱。

环境变量

• CODEX_BIN：codex 可执行文件的路径（默认值：codex）
• CODEX_PERSISTENT_MCP_ORIGIN：注入到每个提示中的标识符（默认值：codex-persistent-mcp）

工作目录 (cwd)

Codex 会存储包括工作区当前工作目录在内的会话元数据，并且 codex resume 默认会按当前工作目录过滤会话。

• 启动新会话时（没有 session_id），必须传递 cwd（仓库根目录）。
• 恢复会话时（带有 session_id），cwd 是可选的：服务器会从 Codex 的本地会话存储中重用或推断该值。

“AI 与人类”归属

Codex CLI 无法自动识别输入是否通过 MCP 来自另一个 AI。

此服务器会在每个请求中注入一个小标头，以便 Codex 能够可靠地区分：

• 包含 <<<MCP_CONTEXT_BEGIN>>> 的消息 → 通过 MCP 来自 AI 代理（回复给代理）
• 不包含该标头的消息 → 来自人类用户（例如 codex resume）

每个请求的模型和推理覆盖

默认情况下，Codex CLI 会读取 ~/.codex/config.toml 文件（例如 model 和 model_reasoning_effort）。

此 MCP 服务器支持每个请求的覆盖设置：

• model：仅针对该请求传递给 codex exec -m <model>
• reasoning_effort：仅针对该请求作为 codex exec -c model_reasoning_effort="..." 传递

如果不传递这些字段，请求将遵循 Codex CLI 的默认设置。

版本固定与自动更新

npx -y codex-persistent-mcp 通常会拉取最新版本，这很方便，但可重复性较差。

要固定版本，请使用以下命令：

npx -y codex-persistent-mcp@0.1.3

📚 详细文档

建议工作流程（双代理护栏）

• 规划前：将“需求 + 草稿计划”发送给 codex_plan，以获取差距、风险、问题和测试用例。
• 完成前：将“变更摘要 + 测试结果 + 未解决问题”发送给 codex_review 进行最终审查。
• 随时：使用 codex resume <session_id> 手动继续同一会话。

故障排除

codex 未找到

当 PATH 未被继承时（例如使用 nvm），这种情况很常见。可以通过设置以下环境变量来解决：

• CODEX_BIN=/absolute/path/to/codex（使用 which codex 查找路径）

为什么要传递 cwd？

传递项目根目录，以便 Codex 记录正确的工作区上下文，并且 codex resume 默认会在该仓库中显示会话。

npm 发布需要 2FA（维护者）

某些 npm 账户在发布时需要使用双因素认证（2FA），或者使用可以绕过 2FA 的自动化/细粒度令牌。

• 启用写入的 2FA：
  • npm profile enable-2fa auth-and-writes
• 然后使用一次性密码（OTP）进行发布：
  • npm publish --otp=123456