---
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="/docs/codex/official/01-products/28-non-interactive">
    一次性 CI、批处理和脚本任务先从 `codex exec` 开始。
  </Card>
  <Card title="App Server" href="/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)
