> ## Documentation Index
> Fetch the complete documentation index at: https://docs.4096bytes.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex SDK

> 在应用代码中通过 Codex SDK 接入 4096bytes

Codex SDK 适合把 Codex 能力接入你自己的应用、内部工具或自动化流程。你需要从控制台复制 Base URL、API Key 和模型名，然后在实例化 `Codex` 时传入连接参数。

<Tip>
  Base URL、API Key 和模型名以控制台显示为准。不要从截图、旧文档或其他用户的配置中复制这些值。
</Tip>

## 准备工作

* 已完成 [创建账号](/quickstart/create-account)。
* 已完成 [获取 API Key](/quickstart/get-api-key)。
* 已安装 Node.js 18 或更高版本。
* 已安装 Codex CLI，并确认 `codex --version` 可以正常运行。
* 已准备一个 TypeScript 或 JavaScript 项目。

<Warning>
  API Key 是敏感凭证。不要把 API Key 写入前端代码、提交到仓库，或打印到日志里。
</Warning>

## 使用场景

Codex SDK 适合需要把 Codex 放进现有工程流程的场景。

| 场景        | 适合做什么                                                                               |
| --------- | ----------------------------------------------------------------------------------- |
| CI/CD 自动化 | 在流水线中触发代码检查、问题定位、修复建议或结构化报告。                                                        |
| 自动代码评审    | 在 GitHub Actions、GitLab CI/CD、Azure DevOps Pipelines 或 Jenkins 中运行评审任务，并把结果发布为代码评论。 |
| 内部研发工具    | 在公司内部平台中接入 Codex，用于生成迁移计划、分析仓库状态或辅助排查构建失败。                                          |
| 应用内工程助手   | 在你的应用中启动 Codex 线程，让它处理跨步骤的工程任务。                                                     |
| 结构化输出流程   | 让 Codex 按 JSON schema 返回结果，再由你的程序调用 SCM、Slack、工单系统或其他内部 API。                        |

如果你只是想在本机终端里使用 4096bytes，请先看 [Codex CLI](/clients/codex)。如果你要在代码里控制 Codex，再使用 SDK。

## 安装 SDK

在你的项目中安装 Codex SDK。

```bash theme={null}
npm install @openai/codex-sdk
```

Codex SDK 会调用本机 Codex CLI。如果你还没有安装 Codex CLI，请先安装：

```bash theme={null}
npm install -g @openai/codex
```

安装完成后确认命令可用：

```bash theme={null}
codex --version
```

如果你使用 pnpm 或 yarn，请使用对应的安装命令。

```bash theme={null}
pnpm add @openai/codex-sdk
```

```bash theme={null}
yarn add @openai/codex-sdk
```

## 复制连接参数

<Steps>
  <Step title="打开 API 密钥页面">
    打开控制台，进入 **API 密钥** 页面。
  </Step>

  <Step title="选择 API Key">
    找到要用于 SDK 的 API Key，点击 **使用密钥**。
  </Step>

  <Step title="复制 SDK 参数">
    复制控制台展示的 Base URL、API Key 和模型名。SDK 示例中的占位值都需要替换为控制台中的实时值。
  </Step>
</Steps>

## 配置环境变量

把 API Key、Base URL 和模型名放到服务端环境变量中。

```bash theme={null}
export CODEX_API_KEY="YOUR_4096BYTES_API_KEY"
export CODEX_BASE_URL="YOUR_BASE_URL"
export CODEX_MODEL="YOUR_MODEL_NAME"
```

如果你的运行环境使用 `.env` 文件，可以写成：

```bash theme={null}
CODEX_API_KEY=YOUR_4096BYTES_API_KEY
CODEX_BASE_URL=YOUR_BASE_URL
CODEX_MODEL=YOUR_MODEL_NAME
```

## 初始化 Codex

在服务端代码中创建 `Codex` 实例。把 `apiKey` 和 `baseUrl` 传入构造函数。

```ts theme={null}
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` 请复制控制台显示的值。

## 验证接入

先用一个只读提示词验证连接是否成功。

```ts theme={null}
const result = await thread.run("请只回复 ok，不要修改任何文件。");
```

如果返回正常，再把 SDK 接入到你的真实任务流程中。

## 代码评审示例

OpenAI 的官方 cookbook 展示了一个自动代码评审流程。这个流程会在 CI/CD runner 中触发 Codex，让 Codex 阅读 PR diff，按结构化 JSON schema 输出评审结果，然后由流水线调用 SCM API 发布行内评论。

你可以把这个模式用于：

* PR 自动评审。
* 私有化部署或非 GitHub SCM 的评审流程。
* 根据结构化结果创建工单、发送 Slack 通知或更新内部质量看板。

实现时建议先把任务限制为只读评审。确认输出稳定后，再接入评论发布、工单创建或其他会改变外部状态的动作。

参考官方示例：[Build Code Review with the Codex SDK](https://developers.openai.com/cookbook/examples/codex/build_code_review_with_codex_sdk)。

更多 SDK 用法见 OpenAI 官方文档：[Codex SDK](https://developers.openai.com/codex/sdk)。

## 常见问题

<AccordionGroup>
  <Accordion title="应该使用哪个 Base URL">
    使用控制台当前展示的 Base URL。不要在文档、截图或旧配置中复制固定地址。
  </Accordion>

  <Accordion title="应该使用哪个模型名">
    使用控制台展示的模型名。模型名需要完整复制，包括大小写、连字符和版本后缀。
  </Accordion>

  <Accordion title="可以在浏览器前端调用吗">
    不建议。浏览器前端会暴露 API Key。请在服务端、后端任务或受控的自动化环境中调用 SDK。
  </Accordion>

  <Accordion title="认证失败怎么办">
    检查 API Key 是否复制完整，环境变量是否被运行进程读取，Base URL 是否来自同一个控制台账号或环境。
  </Accordion>
</AccordionGroup>