將 Codex 接入 Agents SDK

Codex 可以作為 MCP server 執行，其他 MCP client 可以連線它。常見做法是用 OpenAI Agents SDK 編排多個 agent，再讓其中一個 agent 呼叫 Codex 完成程式碼任務。

這不是新手第一天必須掌握的功能。先把 Codex CLI、sandbox、approval 和 diff review 用穩，再把它放進自動化編排。

Codex with Agents SDK

官方 Codex MCP server 與 Agents SDK 編排指南。

MCP integration

先理解 MCP client/server 的基本邊界。

Codex SDK

如果只需要程式化呼叫 Codex，先比較 SDK 路徑。

它解決什麼

flowchart LR
    Planner["Planner agent"] --> SDK["Agents SDK"]
    SDK --> CodexMCP["Codex MCP server"]
    CodexMCP --> Repo["repo task"]
    Repo --> Reviewer["Reviewer agent / human review"]

本地使用 Codex 時，你直接和 Codex 對話。接入 Agents SDK 後，上層 agent 可以分工：

Planner：拆需求，不改程式碼。
Implementer：呼叫 Codex 做最小實現。
Reviewer：檢查 diff、測試和風險。
SDK：負責 handoff、guardrails、trace 和流程編排。

Codex 在這裡不是聊天視窗，而是可以被其他 agent 呼叫的程式碼執行能力。

什麼時候值得用

適合：

可重複的軟體交付流程。
需要完整 traces 方便覆盤。
多個 agent 需要明確分工。
已經能管理 sandbox、approval、working directory。

不適合：

只是讓 Codex 修一個 bug。
還不熟悉 MCP。
不清楚 Agents SDK 的 handoff 和工具呼叫模型。
沒有測試和回復機制。

Codex MCP server 暴露什麼

啟動 Codex MCP server：

codex mcp-server

用 MCP Inspector 檢查：

npx @modelcontextprotocol/inspector codex mcp-server

tools/list 會看到兩個核心工具：

codex：開始一個新的 Codex session。
codex-reply：用 threadId 繼續已有 session。

新實現要儲存 threadId。官方保留 conversationId 作為相容別名，但新流程不要依賴它。

呼叫時傳清邊界

codex 工具最重要的輸入不是“寫什麼程式碼”，而是邊界：

prompt：任務本身。
cwd：在哪個目錄工作。
sandbox：能不能寫檔案，能碰到哪裡。
approval-policy：什麼時候需要批准。
model 或 profile：使用哪套配置。
config：本次呼叫覆蓋哪些配置。

如果這些不清楚，上層 agent 會把模糊任務交給 Codex，結果不可控。

第一次怎麼試

不要一開始就做多 agent 自動交付。建議順序：

執行 codex mcp-server，確認能啟動。
用 Inspector 發 tools/list，確認看到 codex 和 codex-reply。
用只讀任務測試 codex。
讀取返回裡的 structuredContent.threadId。
用 codex-reply 繼續同一任務。
確認 trace 裡能看到 Codex 呼叫和結果。

這條鏈路跑通，再接 Agents SDK。

編排心態

不要把所有 agent 都設計成“會寫程式碼”。更穩的分工是：

Planner 只拆任務，不碰檔案。
Implementer 只呼叫 Codex 做最小實現。
Reviewer 只檢查 diff、測試和風險。

這和手動使用 Codex 的經驗一致：先計劃，再動手，再複核。SDK 只是把這個流程變成可執行的程式。

安全邊界

接入 SDK 後，風險會增加，因為觸發 Codex 的可能是另一個 agent 的輸出。

建議：

預設使用 read-only 或 workspace-write，不預設 full access。
自動流程裡保留審批或可審查 trace。
cwd 必須明確，避免 Codex 在錯誤目錄工作。
實現 agent 只做小任務，複雜需求先由 planner 拆分。
執行後必須檢查 diff 和測試結果。

常見坑

沒儲存 threadId，導致每次呼叫都像新會話。
cwd 傳錯，Codex 在錯誤專案裡工作。
自動流程預設給太高許可權。
planner、implementer、reviewer 職責混在一起。
只看 SDK trace 是否成功，不看實際 diff 和測試結果。

第一次接入時，把目標壓到很小：能啟動、能列工具、能發一次只讀任務、能用同一個 threadId 繼續。

驗收清單

MCP server 能穩定啟動。
tools/list 能看到兩個 Codex 工具。
codex 呼叫能返回結果和 threadId。
codex-reply 能繼續同一 session。
Agents SDK trace 中能看到 handoff 和 Codex 呼叫。
生成的程式碼改動可以被測試和 review。