用 Codex SDK 整合 Agent

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

三個入口的邊界

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 頁目前重點列出兩類庫：

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

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 整合定義一個固定輸入輸出協議：

{
  "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
}

輸出也要可解析：

{
  "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
• Non-interactive mode
• App Server
• OpenAI Codex SDK source