Codex SDK 适合把 Codex 能力接入你自己的应用、内部工具或自动化流程。你需要从控制台复制 Base URL、API Key 和模型名，然后在实例化 Codex 时传入连接参数。
Base URL、API Key 和模型名以控制台显示为准。不要从截图、旧文档或其他用户的配置中复制这些值。
准备工作
- 已完成 创建账号。
- 已完成 获取 API Key。
- 已安装 Node.js 18 或更高版本。
- 已安装 Codex CLI，并确认
codex --version 可以正常运行。
- 已准备一个 TypeScript 或 JavaScript 项目。
API Key 是敏感凭证。不要把 API Key 写入前端代码、提交到仓库，或打印到日志里。
使用场景
Codex SDK 适合需要把 Codex 放进现有工程流程的场景。
| 场景 | 适合做什么 |
|---|
| CI/CD 自动化 | 在流水线中触发代码检查、问题定位、修复建议或结构化报告。 |
| 自动代码评审 | 在 GitHub Actions、GitLab CI/CD、Azure DevOps Pipelines 或 Jenkins 中运行评审任务，并把结果发布为代码评论。 |
| 内部研发工具 | 在公司内部平台中接入 Codex，用于生成迁移计划、分析仓库状态或辅助排查构建失败。 |
| 应用内工程助手 | 在你的应用中启动 Codex 线程，让它处理跨步骤的工程任务。 |
| 结构化输出流程 | 让 Codex 按 JSON schema 返回结果，再由你的程序调用 SCM、Slack、工单系统或其他内部 API。 |
安装 SDK
在你的项目中安装 Codex SDK。
npm install @openai/codex-sdk
npm install -g @openai/codex
pnpm add @openai/codex-sdk
yarn add @openai/codex-sdk
复制连接参数
打开 API 密钥页面
打开控制台，进入 API 密钥 页面。
选择 API Key
找到要用于 SDK 的 API Key，点击 使用密钥。
复制 SDK 参数
复制控制台展示的 Base URL、API Key 和模型名。SDK 示例中的占位值都需要替换为控制台中的实时值。
配置环境变量
把 API Key、Base URL 和模型名放到服务端环境变量中。
export CODEX_API_KEY="YOUR_4096BYTES_API_KEY"
export CODEX_BASE_URL="YOUR_BASE_URL"
export CODEX_MODEL="YOUR_MODEL_NAME"
.env 文件，可以写成：
CODEX_API_KEY=YOUR_4096BYTES_API_KEY
CODEX_BASE_URL=YOUR_BASE_URL
CODEX_MODEL=YOUR_MODEL_NAME
初始化 Codex
在服务端代码中创建 Codex 实例。把 apiKey 和 baseUrl 传入构造函数。
import { Codex } from "@openai/codex-sdk";
const apiKey = process.env.CODEX_API_KEY;
const baseUrl = process.env.CODEX_BASE_URL;
const model = process.env.CODEX_MODEL;
if (!apiKey || !baseUrl || !model) {
throw new Error("Missing CODEX_API_KEY, CODEX_BASE_URL, or CODEX_MODEL");
}
const codex = new Codex({
apiKey,
baseUrl,
});
const thread = codex.startThread({
model,
});
const result = await thread.run("请用一句话说明这个项目的用途。");
console.log(result.finalResponse);
CODEX_API_KEY 填写你在控制台创建的 API Key。CODEX_BASE_URL 和 CODEX_MODEL 请复制控制台显示的值。
验证接入
先用一个只读提示词验证连接是否成功。
const result = await thread.run("请只回复 ok，不要修改任何文件。");
代码评审示例
OpenAI 的官方 cookbook 展示了一个自动代码评审流程。这个流程会在 CI/CD runner 中触发 Codex，让 Codex 阅读 PR diff，按结构化 JSON schema 输出评审结果，然后由流水线调用 SCM API 发布行内评论。
你可以把这个模式用于：
- PR 自动评审。
- 私有化部署或非 GitHub SCM 的评审流程。
- 根据结构化结果创建工单、发送 Slack 通知或更新内部质量看板。
实现时建议先把任务限制为只读评审。确认输出稳定后，再接入评论发布、工单创建或其他会改变外部状态的动作。
参考官方示例：Build Code Review with the Codex SDK。
更多 SDK 用法见 OpenAI 官方文档：Codex SDK。
常见问题
使用控制台当前展示的 Base URL。不要在文档、截图或旧配置中复制固定地址。
使用控制台展示的模型名。模型名需要完整复制，包括大小写、连字符和版本后缀。
不建议。浏览器前端会暴露 API Key。请在服务端、后端任务或受控的自动化环境中调用 SDK。
检查 API Key 是否复制完整，环境变量是否被运行进程读取，Base URL 是否来自同一个控制台账号或环境。
