codex-persistent-mcp

English | 簡體中文 | 繁體中文

一個很薄的 MCP（stdio）Server：把會話持久化交給本機 codex-cli，使得透過 MCP 呼叫也能產生真實 session，之後使用者可以用 codex resume 接力繼續聊。

快速開始（建議：npx 自動更新）

$3

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

驗證：

`bash
claude mcp list
claude mcp get codex-persistent
`

$3

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

驗證：

`bash
codex mcp list --json
codex mcp get codex-persistent --json
`

$3

Antigravity 支援用 --add-mcp 新增 MCP server：

`bash
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 進入同一會話補充資訊/接力對話。
- 透過 MCP 建立的會話會在同一專案目錄（CWD）的 codex resume 中可見。

依賴

- Node.js（建議 18+）
- codex-cli（本專案開發時使用 codex-cli 0.77.0）

安裝與建置

`bash
npm install
npm run build
`

全域安裝（可選）

發佈到 npm 之後，可以全域安裝成 CLI：

`bash
npm install -g codex-persistent-mcp
`

執行

`bash
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 ""
- 續寫會話：
- codex exec --skip-git-repo-check --json -C resume ""

然後解析 --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 能穩定區分：

- 帶 <<>> 的訊息：來自 AI agent via MCP（回覆給 agent）
- 不帶該標識的訊息：來自使用者本人（例如手動 codex resume）

每次呼叫的 model + reasoning 覆蓋

預設情況下，Codex CLI 會讀取 ~/.codex/config.toml（例如 model 與 model_reasoning_effort）。

本 MCP 支援對單次呼叫即時覆蓋：

- model：透傳為 codex exec -m ，只對本次請求生效
- reasoning_effort：透傳為 codex exec -c model_reasoning_effort="..."，只對本次請求生效

不傳上述欄位時，會完全遵循 Codex CLI 的預設配置。

在 Claude Code 裡設定這個 MCP

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

建議用 add-json 設定（可同時設定 env，並用 npx -y 方式啟動）：

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

若要固定版本（可重現）：

`bash
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"}}'
`

驗證：

`bash
claude mcp list
claude mcp get codex-persistent
`

在 Codex CLI 裡設定這個 MCP

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

1) 先 build：

`bash
npm run build
`

2) 新增為 stdio MCP server：

`bash
codex mcp add --env CODEX_BIN=/absolute/path/to/codex codex-persistent -- node /absolute/path/to/this/repo/dist/server.js
`

若已全域安裝：

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

若已發佈到 npm（無需 clone）：

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

驗證：

`bash
codex mcp list --json
codex mcp get codex-persistent --json
`

版本固定與自動更新

npx -y codex-persistent-mcp 一般會拉取最新版本，方便但可重現性較差。

如果要固定版本：

`bash
npx -y codex-persistent-mcp@0.1.3
`

建議用法（雙 Agent 把關）

- plan 前：把「需求 + 計畫草稿」送給 codex_plan，取得漏項/風險/追問/測試建議。
- 收尾前：把「變更摘要 + 測試結果 + 未決問題」送給 codex_review，做最終把關。
- 任意時刻：直接 codex resume 手動接力繼續聊。

常見問題

$3

常見原因是 PATH 未繼承（例如 nvm）。解法：

- 設定時顯式指定 CODEX_BIN=/absolute/path/to/codex（用 which codex 找路徑）

$3

傳入專案根目錄可讓 Codex 記錄正確的工作區上下文，並讓 codex resume 在該專案目錄下預設就能看到該會話。

$3

部分 npm 帳號在發佈套件時會被要求啟用兩步驗證（2FA），或使用可繞過 2FA 的自動化/細粒度 token。

- 啟用寫入 2FA：
- npm profile enable-2fa auth-and-writes
- 然後帶 OTP 發佈：
- npm publish --otp=123456`