Skip to content

README.zh-Hant.md

Latest commit

 

History

History
236 lines (152 loc) · 6.83 KB

README.zh-Hant.md

File metadata and controls

236 lines (152 loc) · 6.83 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","[email protected]"],"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 [email protected]

建議用法（雙 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