用 Codex SDK 集成 Agent
基于官方 Codex SDK 教程，讲清什么时候该用 SDK、什么时候先用 codex exec，以及新手做团队自动化时最容易踩的坑。
Codex SDK 不是新手第一天就该碰的入口。你先要分清三件事：本地交互用 CLI / IDE / App，流水线自动化先看 codex exec，只有当你要把 Codex 做进自己的内部系统、产品后台或团队工具里，才轮到 SDK。
官方 SDK 页把 TypeScript SDK 定位为“在应用里控制 Codex”，比 non-interactive mode 更完整、更灵活；Python SDK 目前是 experimental，并通过本地 app-server 的 JSON-RPC 控制 Codex。换句话说：SDK 解决的是“我自己的程序要管理 Codex 会话”，不是“我想跑一次自动修复”。
先理解它解决什么问题
新手常把 SDK 当成“更高级的命令行”。这个理解会把事情做复杂。
codex exec 更像一次性任务：CI 失败了，让 Codex 看日志、提修复、输出结果。你给它一个任务，它跑完退出。
SDK 更像把 Codex 接进你的产品：你要创建 thread、继续历史会话、控制模型和上下文、把结果放进自己的系统。它不是只跑一次命令，而是让你的程序拥有“启动、继续、记录、展示、复用 Codex 工作”的能力。
app-server 更底层，适合做富客户端或深度产品集成。普通团队自动化不要从 app-server 开始。
怎么判断该不该用 SDK
适合用 SDK：
- 你要在内部平台里做“代码审查助手”“故障排查助手”“发布检查助手”。
- 你需要保存 thread，并在后续任务里继续同一段上下文。
- 你要把 Codex 的结果接进现有工单、PR、告警、知识库或审批系统。
- 你需要比
codex exec更细的会话控制，而不是只拿最终输出。
不适合一上来就用 SDK：
- 你只是想在 GitHub Actions 里修一次 CI。
- 你只是想批量生成 release note、总结日志、检查 diff。
- 你还没想清楚输出结构、权限边界和失败重试。
- 你没有后端服务，只有本地脚本。
这类情况先用 codex exec。官方 non-interactive mode 明确支持 CI、pre-merge checks、scheduled jobs、管道输出、JSONL 事件和 --output-schema。等一次性自动化稳定了，再抽成 SDK 服务。
新手推荐路线
第一步，先把任务写成清楚的自动化提示词。不要急着写 SDK 包装层。你要先验证：Codex 是否能稳定读懂你的仓库、是否只改该改的地方、是否能输出可解析结果。
第二步，用 codex exec 跑通最小流程。权限从 read-only 开始，需要改文件时才给 workspace-write。CI 里用 CODEX_API_KEY 作为 secret；不要把 ~/.codex/auth.json 放进公开仓库或日志。
第三步，给结果加结构。比如审查结果要固定包含风险等级、文件位置、建议动作。官方支持 --output-schema，这一步可以先不写 SDK。
第四步，如果团队真的需要长期服务，再换 SDK。此时 SDK 负责的是会话生命周期和系统集成：创建 thread、继续 thread、把结果写回你的平台。
TypeScript 和 Python 怎么选
TypeScript SDK 是更适合产品后端的默认选择。官方要求 Node.js 18 或更高版本，安装包是 @openai/codex-sdk。如果你的内部平台本来就是 Node / Next.js / NestJS / Express，这条路更顺。
Python SDK 当前是 experimental。官方说明它通过本地 Codex app-server over JSON-RPC 工作，并且需要 Python 3.10 或更高版本以及本地开源 Codex 仓库 checkout。它更适合做实验、研究脚本或和已有 Python 后端集成，不适合作为新手默认生产入口。
新手常见坑
- 把 SDK 当命令行替代品：结果是写很多包装代码，却没有比
codex exec多解决问题。 - 一开始就给过大权限：CI 自动化先 read-only，需要落盘改动时再给
workspace-write。 - 没有定义输出结构：下游系统只能解析自然语言，后面一定不稳定。
- 忽略密钥边界：CI 里用 secret 注入
CODEX_API_KEY，不要提交认证文件。 - 忽略失败路径：SDK 服务要设计超时、重试、人工接管和日志脱敏。
- 直接做全仓自动修复：新手应该先从“总结失败原因”“给出建议 patch”开始，再逐步放开自动修改。
一个合理的团队落地样子
最稳的团队形态通常是三层。
底层是受控执行环境：CI runner、容器或内部服务器，权限最小化，能安全读取代码和运行测试。
中层是任务协议：每类任务都有固定输入、固定输出、固定验收。例如“审查 PR diff”“总结失败日志”“检查发布风险”。
上层才是 SDK 或平台集成：把任务挂到 PR、工单、Slack、发布系统里，让人可以看到 Codex 做了什么、为什么这么做、是否需要人工确认。
SDK 的价值在第三层。前两层没做好，SDK 只会把不稳定放大。
怎么验收你做对了
先做一个只读任务：让 Codex 总结一个 PR 的风险点，不允许改文件。验收标准是输出稳定、能被程序解析、不会泄露敏感信息。
再做一个受控改动任务：只允许修改测试或一个小模块，跑完自动执行测试。验收标准是失败时能退出并留下清楚原因，成功时能给出 diff 和测试结果。
最后再接入团队平台：把审查意见写回 PR 或工单。验收标准不是“Codex 能说话”，而是团队成员能判断它的建议是否可信、是否可追踪、是否可撤销。