Skip to content

README.zh-Hans.md

Latest commit

 

History

History
236 lines (152 loc) · 6.84 KB

README.zh-Hans.md

File metadata and controls

236 lines (152 loc) · 6.84 KB

codex-persistent-mcp

English | 简体中文 | 繁體中文

一个很薄的 MCP（stdio）Server：把会话持久化交给本机 codex-cli，使得通过 MCP 调用也能生成真实 session，之后用户可以用 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 server：

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

解决的问题

  • 其他 Agent 通过 MCP 调用 Codex，也能产生真实可恢复的 session。
  • MCP server 重启/关闭不丢上下文（上下文存于 Codex CLI 的 session store）。
  • 用户可随时用 codex resume <session_id> 进入同一会话补充信息/接力对话。
  • 通过 MCP 创建的会话会在同一项目目录（CWD）的 codex resume 中可见。

依赖

  • Node.js（建议 18+）
  • codex-cli（本项目开发时使用 codex-cli 0.77.0）

安装与构建

npm install
npm run build

全局安装（可选）

发布到 npm 之后，可以全局安装成 CLI：

npm install -g codex-persistent-mcp

运行

npm start

MCP 工具

本 server 暴露 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）

每次 tool call 都会 spawn 一个 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
  • 收集 item.completed（类型为 agent_message）并返回最后一条作为 reply

同一个 session_id 的并发请求会被串行化，避免对同一会话乱序写入。

环境变量

  • CODEX_BIN：codex 可执行文件路径（默认 codex）
  • CODEX_PERSISTENT_MCP_ORIGIN：注入到每次请求里的标识（默认 codex-persistent-mcp）

工作目录（cwd）

Codex 会在 session 元数据里记录工作目录，并且 codex resume 默认会按工作目录过滤会话列表。

  • 新建会话（不传 session_id）时：必须传 cwd（项目根目录）。
  • 续写会话（传 session_id）时：cwd 可省略，server 会复用或从 Codex 本地 session store 推断。

“AI vs 人” 标记

Codex CLI 默认并不知道输入是来自 MCP 的其他 AI 还是用户本人。

本 server 会在每次请求前自动注入一个 header，让 Codex 能稳定区分：

  • 带 <<<MCP_CONTEXT_BEGIN>>> 的消息：来自 AI agent via MCP（回复给 agent）
  • 不带该标识的消息：来自用户本人（例如手动 codex resume）

每次调用的 model + reasoning 覆盖

默认情况下，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 的默认配置。

在 Claude Code 里配置这个 MCP

Claude Code 提供 claude mcp ... 管理命令。

推荐用 add-json 配置（可以同时设置 env，并用 npx -y 方式启动）：

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

如果你想固定版本（可复现）：

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

验证：

claude mcp list
claude mcp get codex-persistent

在 Codex CLI 里配置这个 MCP

Codex CLI 提供 codex mcp ... 管理命令。

  1. 先 build：
npm run build
  1. 添加为 stdio MCP server：
codex mcp add --env CODEX_BIN=/absolute/path/to/codex codex-persistent -- node /absolute/path/to/this/repo/dist/server.js

如果已全局安装：

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

如果已发布到 npm（无需 clone）：

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

验证：

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

版本固定与自动更新

npx -y codex-persistent-mcp 一般会拉取最新版本，方便但可复现性更差。

如果要固定版本：

npx -y codex-persistent-mcp@0.1.3

推荐用法（双 Agent 把关）

  • plan 前：把“需求 + 计划草稿”发给 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 的自动化/细粒度 token。

  • 开启写入 2FA：
    • npm profile enable-2fa auth-and-writes
  • 然后带 OTP 发布：
    • npm publish --otp=123456