安装与 Hello World

这章的目标：5 分钟内跑通第一个 SDK 程序，让 Codex 用代码回答你的问题。

准备工作（三件事）

开始之前，确认这三样东西都就位了：

1. Node.js 18+

bashCopynode -v
# 输出类似 v20.11.0 就行，只要 >= 18

没装？去 nodejs.org 下载安装，或者用 nvm：

bashCopynvm install 20
nvm use 20

2. Codex CLI 已安装

bashCopycodex --version

看到版本号就说明装好了。没装的话去看 Codex 安装教程。

3. OPENAI_API_KEY 环境变量

bashCopyecho $OPENAI_API_KEY
# 应该输出 sk-... 开头的一串字符

没有的话：

bashCopyexport OPENAI_API_KEY="sk-你的key"

💡 建议把这行加到 ~/.bashrc 或 ~/.zshrc 里，这样每次开终端都自动生效。

创建项目

bashCopymkdir codex-sdk-demo && cd codex-sdk-demo
npm init -y
npm install @openai/codex-sdk
npm install -D typescript tsx @types/node

然后初始化 TypeScript 配置：

bashCopynpx tsc --init

打开 tsconfig.json，确保这几个配置正确：

jsonCopy{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "strict": true,
    "outDir": "./dist"
  }
}

💡 我们用 tsx 来运行 TypeScript，它不需要先编译，写完直接跑。

第一个程序：Hello Codex

创建 hello.ts：

typescriptCopy// hello.ts
import { Codex } from "@openai/codex-sdk";

async function main() {
  // 1. 创建 Codex 实例（自动读取 OPENAI_API_KEY 环境变量）
  const codex = new Codex();

  // 2. 开一个新的对话线程
  const thread = codex.startThread({
    skipGitRepoCheck: true,  // 我们的 demo 目录不是 git 仓库，跳过检查
  });

  // 3. 说一句话，等 AI 回复
  const turn = await thread.run("用一句话介绍你自己，要有趣");

  // 4. 打印结果
  console.log("🤖 AI 说:", turn.finalResponse);
  console.log("📊 消耗 token:", turn.usage);
}

main().catch(console.error);

运行：

bashCopynpx tsx hello.ts

如果一切顺利，你会看到类似这样的输出：

Copy🤖 AI 说: 我是一个住在你终端里的 AI，专长是帮你写代码和偷偷执行 shell 命令。
📊 消耗 token: { input_tokens: 156, cached_input_tokens: 0, output_tokens: 42 }

恭喜！你的第一个 SDK 程序跑通了 🎉

理解返回结果 RunResult

thread.run() 返回一个 RunResult 对象，里面有三样东西：

其中 usage 的结构：

items 数组是重点，后面第 4 章会详细讲。现在只需要知道 finalResponse 就是 AI 说的话。

多轮对话

同一个 thread 对象上连续调用 run()，AI 会记住之前的对话内容：

typescriptCopyimport { Codex } from "@openai/codex-sdk";

async function main() {
  const codex = new Codex();
  const thread = codex.startThread({ skipGitRepoCheck: true });

  // 第一轮
  const turn1 = await thread.run("记住这个数字：42");
  console.log("第一轮:", turn1.finalResponse);

  // 第二轮 — AI 还记得上一轮的内容
  const turn2 = await thread.run("我刚才让你记住的数字是多少？");
  console.log("第二轮:", turn2.finalResponse);

  // 第三轮 — 上下文继续保持
  const turn3 = await thread.run("把那个数字乘以 2 是多少？");
  console.log("第三轮:", turn3.finalResponse);
}

main().catch(console.error);

关键点：多轮对话 = 同一个 Thread 对象调多次 run()。每开一个新 Thread 就是一段新的对话，互不干扰。

常见报错排查

刚开始用，十有八九会遇到点问题。这里是最常见的几个：

如果遇到 "找不到 CLI" 的问题，可以手动指定路径：

typescriptCopyimport { execSync } from "child_process";

const codex = new Codex({
  codexPathOverride: execSync("which codex", { encoding: "utf-8" }).trim(),
});

小结

• 安装 SDK：npm install @openai/codex-sdk
• 三步走：new Codex() → startThread() → run("你的问题")
• run() 返回 { finalResponse, items, usage }
• 多轮对话 = 同一个 Thread 调多次 run()
• 常见问题基本都是环境配置问题

下一章：流式处理 — 学会用 runStreamed() 实时看 AI 在干什么，而不是傻等。