---
title: "用 Codex SDK 整合 Agent"
description: "判斷什麼時候該用 Codex SDK，什麼時候先用 codex exec，併為團隊自動化設計許可權、結構化輸出和失敗處理。"
verifiedAt: "2026-05-07"
---

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

Codex SDK 適合把 Codex 做進自己的內部系統、產品後臺或團隊工具。它不是新手第一天的入口，也不是 `codex exec` 的簡單替代品。

> [!TIP]
> 先用 CLI 和 `codex exec` 跑通任務，再考慮 SDK。SDK 解決的是“我的程式要管理 Codex 會話”，不是“我想跑一次自動修復”。

<Cards>
  <Card title="Codex SDK" href="https://developers.openai.com/codex/sdk">
    檢視 SDK 的官方說明和當前語言支援。
  </Card>
  <Card title="Non-interactive mode" href="/zh-Hant/docs/codex/official/01-products/28-non-interactive">
    一次性 CI、批處理和指令碼任務先從 `codex exec` 開始。
  </Card>
  <Card title="App Server" href="/zh-Hant/docs/codex/official/01-products/32-app-server">
    富客戶端和遠端 TUI 才需要更底層的 App Server。
  </Card>
</Cards>

## 三個入口的邊界

```mermaid
flowchart TB
    Task["你要整合 Codex"]
    Exec["codex exec<br/>一次性任務"]
    SDK["Codex SDK<br/>程式化會話控制"]
    Server["App Server<br/>富客戶端協議層"]

    Task --> Exec
    Task --> SDK
    Task --> Server
```

`codex exec` 適合：

- CI 裡跑一次審查。
- 批次生成報告。
- 總結日誌。
- 檢查 diff。
- 輸出 JSONL 或結構化結果。

SDK 適合：

- 內部平臺長期管理 Codex 會話。
- 把結果寫回工單、PR、告警或知識庫。
- 儲存 thread 並在後續繼續。
- 需要比 CLI 更細的生命週期控制。
- CI/CD pipeline 中以程式方式控制 Codex。
- 把 Codex 整合到內部應用或 agent system。

App Server 適合：

- 做自己的富客戶端。
- 展示即時事件流、審批、diff 和工具呼叫。
- 遠端 TUI。

## 推薦落地路線

第一步：把任務寫清楚。

先確認 Codex 能穩定完成任務，而不是先寫 SDK 包裝層。

第二步：用 `codex exec` 跑通。

從只讀開始，需要寫檔案時再給 `workspace-write`。輸出先用固定格式或 schema 約束。

第三步：定義任務協議。

例如 PR review 必須輸出風險等級、檔案位置、證據、建議動作、未驗證項。

第四步：再上 SDK。

此時 SDK 負責會話生命週期、系統整合、狀態儲存、重試、許可權和審計。

## 當前 SDK 形態

官方 SDK 頁目前重點列出兩類庫：

| SDK | 狀態 | 要求 | 適合 |
|---|---|---|---|
| TypeScript | 主入口 | Node.js 18+，安裝 `@openai/codex-sdk` | server-side internal tools、CI/CD、團隊自動化平臺。 |
| Python | experimental | Python 3.10+，需要 local checkout of open-source Codex repo | 實驗、notebook、直接控制 local Codex app-server over JSON-RPC。 |

TypeScript SDK 的基本模式是：建立 `Codex`，start thread，run prompt；繼續同一 thread 時再次 `run()`，恢復歷史 thread 時傳 thread id。

```ts
import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run("Make a plan to diagnose and fix the CI failures");

console.log(result);
```

這意味著 SDK 的抽象單位是 thread，而不是“一次 API completion”。你的系統設計也應該圍繞 task、thread、state、result、audit record 來建模。

## 生產化要補的能力

SDK 服務不是“能呼叫模型”就完成。還需要：

- 認證和 secret store。
- 許可權最小化。
- timeout 和 retry。
- 結構化輸出校驗。
- 日誌脫敏。
- 人工接管路徑。
- 失敗原因分類。
- 成本和用量監控。
- 任務級審計。
- thread id 和外部任務 id 的對映。
- 結構化 result 到工單/PR/告警系統的寫回協議。

這些能力缺失時，用 SDK 只會把不穩定流程放大。

## 最小任務協議

給 SDK 整合定義一個固定輸入輸出協議：

```json
{
  "task_id": "ci-2026-05-07-001",
  "mode": "read_only_review",
  "repo": "org/repo",
  "target": "pull_request_123",
  "prompt": "Review the failing checks and summarize likely causes.",
  "allowed_actions": ["read_files", "run_tests"],
  "done_when": ["findings_json_valid", "no_file_changes"],
  "timeout_seconds": 900
}
```

輸出也要可解析：

```json
{
  "task_id": "ci-2026-05-07-001",
  "status": "completed",
  "summary": "...",
  "findings": [],
  "changed_files": [],
  "verification": [],
  "unverified": []
}
```

先讓只讀任務穩定輸出，再放開寫入。寫入任務要額外記錄 diff、驗證命令、失敗原因和人工回復方式。

## 常見坑

- 把 SDK 當高階命令列。
- 一開始就給過大許可權。
- 沒有輸出 schema。
- 不區分 read-only 和 write 任務。
- 把個人 `auth.json` 用進團隊自動化。
- 不記錄 prompt、輸入範圍和工具呼叫。
- 直接做全倉自動修復。

團隊自動化的起點應該是“只讀總結風險”，不是“自動改完併合並”。

## 驗收標準

一個 SDK 整合算合格，至少滿足：

1. 能執行只讀任務，輸出穩定且可解析。
2. 能執行受控寫入任務，修改範圍有限。
3. 能記錄 diff、驗證結果和未驗證項。
4. 失敗時能清楚退出，不吞錯誤。
5. 所有憑據都走 secret store。
6. 使用者能人工審查和撤銷。

SDK 的價值在系統整合層。底層任務本身不穩定時，不要急著產品化。

## 官方資料

- [Codex SDK](https://developers.openai.com/codex/sdk)
- [Non-interactive mode](https://developers.openai.com/codex/noninteractive)
- [App Server](https://developers.openai.com/codex/app-server)
- [OpenAI Codex SDK source](https://github.com/openai/codex/tree/main/sdk)
