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