AI Agent / 系统课时
使用 Codex SDK
使用 Codex SDK
Codex SDK 适合把编码代理嵌入脚本、服务或内部工具。本课用一个最小线程走通三个动作:创建新线程、在同一线程继续多轮任务,以及拿线程 ID 重建句柄并恢复上下文。
学习目标
- 理解 Thread、Turn 与线程 ID 的职责边界
- 用 TypeScript 启动线程并连续执行多轮任务
- 正确保存线程 ID,并在后续进程中恢复会话
先分清线程与轮次
一个 Thread 保存连续工作的会话上下文,一个 Turn 是线程中的一次执行。启动线程后第一次调用 run() 会产生实际会话;之后对同一个 Thread 再次调用 run(),Codex 会沿用此前上下文,而不是重新开始。
TypeScript SDK 的线程 ID 在第一轮开始后才会被填充。需要跨进程恢复时,保存的是这个 ID;重新启动程序后,再用 resumeThread(id) 构造线程句柄并继续执行。Python SDK 的对应关系是 thread_start()、同一线程重复 run(),以及 thread_resume(id)。

用 TypeScript 跑通三种动作
准备 Node.js 18+、已可用的 Codex 认证,并在 Git 仓库目录中安装 @openai/codex-sdk。下面的程序只要求 Codex 读取仓库,不要求修改文件,因此适合先验证线程生命周期。
import { Codex } from "@openai/codex-sdk";
const codex = new Codex();
const cwd = process.cwd();
const thread = codex.startThread({ workingDirectory: cwd });
const first = await thread.run(
"只读分析当前仓库:用一句话说明它的主要用途,不要修改文件。"
);
if (!thread.id) {
throw new Error("第一轮完成后仍未获得 thread id");
}
const threadId = thread.id;
// 继续同一 Thread,第二轮能够利用第一轮已经建立的上下文。
const second = await thread.run(
"继续上一轮:列出两个最重要的入口文件,不要修改文件。"
);
// 用已保存的 ID 重建句柄,模拟进程重启后的恢复。
const resumed = codex.resumeThread(threadId, { workingDirectory: cwd });
const third = await resumed.run(
"恢复这个线程后,用一句话说明我们刚才分析了什么。"
);
console.log(`THREAD_ID=${threadId}`);
console.log(`FIRST=${first.finalResponse}`);
console.log(`SECOND=${second.finalResponse}`);
console.log(`RESUMED=${third.finalResponse}`);预期输出
THREAD_ID=<ID>
FIRST=<VALUE>
SECOND=<VALUE>
RESUMED=<VALUE><ID> 是实际线程 ID,三个 <VALUE> 取决于当前仓库与模型输出。关键验证点不是文案完全一致,而是第二轮能引用第一轮上下文,恢复后的第三轮仍能说明此前做过的分析。
恢复时真正需要保留什么
TypeScript SDK 会把可恢复线程持久化到 Codex 会话目录。业务系统至少应保存线程 ID,并把它和自己的任务 ID、仓库或工作区标识建立映射。恢复时还要重新提供正确的工作目录等线程选项,否则即使对话上下文存在,Codex 也可能面对不同的代码环境。
| 动作 | TypeScript | Python |
|---|---|---|
| 新建线程 | startThread() |
thread_start() |
| 继续线程 | 同一对象重复 run() |
同一对象重复 run() |
| 恢复线程 | resumeThread(id) |
thread_resume(id) |
选择继续、恢复还是新建
同一业务任务的连续步骤,例如“先定位失败测试,再实施修复”,应复用同一个 Thread。程序重启、队列任务重新调度或 Web 请求跨进程时,使用已保存 ID 恢复。与旧任务无关的新需求应创建新线程,避免历史上下文污染判断。
如果需要实时展示工具调用、文件变化或中间事件,TypeScript 可以从 run() 切换到 runStreamed();普通后台任务只需要最终结果时,run() 更简单。无论使用哪种方式,都应把线程 ID 当作业务状态的一部分持久化,而不是只保存最终回答。