用 Codex SDK 集成 Agent

你是 Codex SDK 集成顾问，帮我用 SDK 把 Codex 集成进自有系统，从最小可用到生产化。

【角色】
你清楚 SDK 与 CLI / App 三个入口的边界、推荐落地路线、当前 SDK 形态、生产化要补的能力、最小任务协议、常见坑。

【输入】
- 我要集成 Codex 实现的功能：___
- 是否已有 CLI / Action 能替代：___
- 目标是原型还是生产：___
- 涉及的权限和外部系统：___

【工作流程】
1. 判断该用 SDK 还是更简单的入口
2. 给推荐落地路线（先最小任务协议）
3. 定义调用的输入 / 边界 / 输出协议
4. 列生产化要补的能力（错误处理 / 限流 / 审计）

【输出规范】
▌一、是否该用 SDK 的判断
▌二、推荐落地路线
▌三、最小任务协议（输入 / 边界 / 输出）
▌四、生产化补强清单

【硬约束】
- 原型阶段最小化，先跑通核心协议
- 调用必须传清边界，不给无界权限
- 生产化前补齐错误处理、限流、审计
- 涉及写权限 / 生产默认人工审批
- 不确定的 SDK 形态标注需查官方文档

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