Codex SDK 实战指南

版本说明：本文中的功能点根据 OpenAI 官方 Codex SDK 文档，于 2026-03-22 核对。

1. Codex SDK 解决什么问题

如果你已经会用 Codex CLI、IDE 扩展 或 Codex Web，下一步常见需求就是：

我想把 Codex 接进自己的内部工具
我想在 CI/CD 里自动触发 Codex
我想写一个上层系统，让它多次调用同一个 Codex 线程
我不想只靠命令行，我想在代码里控制 Codex

这时候就该用 Codex SDK。

OpenAI 官方把它定位成：以程序方式控制 Codex 的本地 agent。它尤其适合服务端、自动化脚本和工程平台集成。

2. 它和 CLI、Web、codex exec 有什么区别

方式	最适合的场景
`Codex CLI`	人直接在终端里协作开发
`Codex IDE 扩展`	结合当前文件、选区、`@file` 上下文开发
`Codex Web`	没有本地环境时快速委派云端任务
`codex exec`	非交互、一次性、脚本化执行
`Codex SDK`	在程序里启动、复用、恢复 Codex 线程

可以把它理解成这样：

codex exec 更像“命令行批处理”
Codex SDK 更像“你自己写一个控制器，持续调度 Codex”

如果你只想把 Codex 放进 CI 里跑一次任务，codex exec 往往够用。
如果你要把 Codex 嵌进你自己的平台、后台任务系统或内部工作台，Codex SDK 更合适。

3. 官方当前形态

根据官方文档，当前 Codex SDK 重点是：

提供 TypeScript 库
适合服务端使用
需要 Node.js 18+
支持开启线程、继续同一线程、恢复历史线程

安装命令：

bash

npm install @openai/codex-sdk

4. 最小示例

官方文档给出的最核心用法是：先创建 Codex 实例，再启动一个线程，然后让线程运行任务。

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);

如果你还要继续同一个上下文，可以继续在同一线程上运行：

const result = await thread.run("Implement the plan");
console.log(result);

如果你已经有历史线程 ID，也可以恢复：

const threadId = "<thread-id>";
const thread2 = codex.resumeThread(threadId);
const result2 = await thread2.run("Pick up where you left off");

console.log(result2);

5. 什么时候该用 Codex SDK

场景一：把 Codex 接进 CI/CD

比如你希望每次构建失败时，自动让 Codex：

读取构建日志
分析失败原因
产出修复建议
在安全范围内提交最小修复

这类场景既可以用 codex exec，也可以用 Codex SDK。
如果流程很固定、只跑一次，优先 codex exec。
如果你需要把多个阶段串起来、保存线程状态、接入你自己的审批系统，优先 Codex SDK。

场景二：做企业内部工程工具

例如你们想做一个“代码库健康巡检系统”，每天自动挑出：

测试失败模块
依赖升级风险
重复代码热点
安全扫描结果

然后把这些问题分发给 Codex 分析，这类平台型需求就很适合 Codex SDK。

场景三：做带记忆的工程助手

如果你希望你的系统能记住“上次分析到哪里了”，那线程能力就很关键。
这正是 startThread()、继续 run()、以及 resumeThread() 的价值所在。

6. 给课程和团队的教学建议

如果你要把这部分教给学生或团队，推荐顺序是：

原因很简单：
如果还没真正用过 Codex，就很容易把 SDK 理解成“另一个普通 API 包”。
但实际上，它更像是“把你已经熟悉的 Codex 工作方式，变成可编排的程序接口”。

7. 和 OpenAI Agents SDK 的关系

这两个名字看起来很像，但用途不一样：

工具	更适合什么
`Codex SDK`	控制 Codex 这个工程代理，处理代码仓库、修复、测试、工程任务
`OpenAI Agents SDK`	构建你自己的通用 agent 应用、工作流和产品级交互体验

一个很实用的理解方式是：

想“控制 Codex 干工程活”，看 Codex SDK
想“搭一个你自己的 agent 产品”，看 OpenAI Agents SDK

Codex SDK 实战指南 ​

1. Codex SDK 解决什么问题 ​

2. 它和 CLI、Web、codex exec 有什么区别 ​

3. 官方当前形态 ​

4. 最小示例 ​

5. 什么时候该用 Codex SDK ​

场景一：把 Codex 接进 CI/CD ​

场景二：做企业内部工程工具 ​

场景三：做带记忆的工程助手 ​

6. 给课程和团队的教学建议 ​

7. 和 OpenAI Agents SDK 的关系 ​

官方参考 ​