---
title: "將 Codex 接入 Agents SDK"
description: "把 Codex 作為 MCP server 暴露給 OpenAI Agents SDK，用於可編排的軟體工作流。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

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

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

<Cards>
  <Card title="Codex with Agents SDK" href="https://developers.openai.com/codex/guides/agents-sdk">
    官方 Codex MCP server 與 Agents SDK 編排指南。
  </Card>
  <Card title="MCP integration" href="/zh-Hant/docs/codex/official/03-extensions/08-mcp-integration">
    先理解 MCP client/server 的基本邊界。
  </Card>
  <Card title="Codex SDK" href="/zh-Hant/docs/codex/official/06-team-integration/71-codex-sdk">
    如果只需要程式化呼叫 Codex，先比較 SDK 路徑。
  </Card>
</Cards>

## 它解決什麼

```mermaid
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：

```bash
codex mcp-server
```

用 MCP Inspector 檢查：

```bash
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 自動交付。建議順序：

1. 執行 `codex mcp-server`，確認能啟動。
2. 用 Inspector 發 `tools/list`，確認看到 `codex` 和 `codex-reply`。
3. 用只讀任務測試 `codex`。
4. 讀取返回裡的 `structuredContent.threadId`。
5. 用 `codex-reply` 繼續同一任務。
6. 確認 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。

## 官方資料

- [Codex Agents SDK guide](https://developers.openai.com/codex/guides/agents-sdk)
- [OpenAI Agents SDK MCP integration](https://developers.openai.com/api/docs/guides/agents/integrations-observability#mcp)
