Codex SDK

Codex SDK

使用 Codex SDK 以编程方式控制本地智能体和对话线程，了解 TypeScript、Python 与 app-server 集成路径，并将 Codex 接入自定义应用和自动化流程，并帮助开发者在脚本、CI 和自有产品中查找命令参数、协议边界、输入输出、权限控制和排查线索，把 Codex 稳定接入自动化流程。

Codex SDK#

Codex 中文站说明： 本页围绕“Codex SDK”重新补充了中文使用场景和验证重点。界面名称可能随 Codex 版本更新，请以当前客户端为准。

以编程方式控制本地 Codex 智能体

如果你已经在使用 Codex CLI、IDE 扩展或 Codex 云端，也可以进一步通过 SDK 以编程方式控制它。

SDK 适合下面这些场景：

  • 需要把 Codex 接入自己的 CI/CD 流程
  • 需要构建能够与 Codex 协作完成复杂工程任务的自定义智能体
  • 需要把 Codex 集成进内部工具和工作流
  • 需要在自己的应用里嵌入 Codex

Codex SDK 适合面向编码任务的 Codex 对话线程。如果 Codex 只是更大编排工作流中的一个专门角色，请改为把 Codex CLI 作为 MCP server 运行，并用 Agents SDK 编排。

TypeScript 库#

TypeScript SDK 提供了一种比非交互模式更全面、更灵活的服务端集成方式。

这个库应该运行在服务端环境中，要求 Node.js 18 或更高版本。

安装#

安装方式：

bash
npm install @openai/codex-sdk

用法#

先启动一个对话线程，再用提示词运行它：

typescript

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

如果你想在同一个对话线程中继续执行，可以再次调用 run()；如果你要恢复一条过去的对话线程，可以提供对话线程 ID：

typescript
// running the same thread
const result = await thread.run("Implement the plan");

console.log(result.finalResponse);

// resuming past thread

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

console.log(result2.finalResponse);

更多细节请查看 TypeScript 仓库。

Python 库#

Python SDK 通过 JSON-RPC 控制本地的 Codex app-server。它要求 Python 3.10 或更高版本。已发布的 SDK 构建产物包含固定版本的 Codex CLI 运行时依赖。

安装#

安装 SDK：

bash
pip install openai-codex

已发布的 SDK 构建产物会自动使用其固定的运行时。只有当你明确想针对某个本地 Codex 可执行文件运行时，才传入 CodexConfig(codex_bin=...)。

Python SDK 仍处于 beta 阶段时，pip install openai-codex 会选择最新发布的 beta 构建版本。等到稳定版 SDK 发布后，如需选择更新的预发布版本，请使用 pip install --pre openai-codex。

用法#

启动 Codex，创建对话线程并运行提示词：

python
from openai_codex import Codex, Sandbox

with Codex() as codex:
thread = codex.thread_start(
model="gpt-5.4",
sandbox=Sandbox.workspace_write,
)
result = thread.run("Make a plan to diagnose and fix the CI failures")
print(result.final_response)

如果你的应用本身已经是异步的，可以使用 AsyncCodex：

python
import asyncio

from openai_codex import AsyncCodex

async def main() -> None:
async with AsyncCodex() as codex:
thread = await codex.thread_start(model="gpt-5.4")
result = await thread.run("Implement the plan")
print(result.final_response)

asyncio.run(main())

沙箱预设#

创建对话线程或为后续会话轮次改变文件系统访问权限时，可以使用相同的 Sandbox 预设：

python
from openai_codex import Codex, Sandbox

with Codex() as codex:
thread = codex.thread_start(sandbox=Sandbox.workspace_write)
thread.run("Make the requested change.")
review = thread.run("Review the diff only.", sandbox=Sandbox.read_only)

可用预设：

  • Sandbox.read_only：读取文件，但不允许写入。
  • Sandbox.workspace_write：读取文件，并可在工作区和已配置 writable roots 内写入。
  • Sandbox.full_access：不施加文件系统访问限制。

省略 sandbox= 时，app-server 会使用其配置的默认值。传给 run(...) 或 turn(...) 的 sandbox 会应用于当前会话轮次及该对话线程后续会话轮次。

更多细节请查看 Python 仓库。

本站实践建议#

实践“Codex SDK”时，先完成一个最小可运行示例，再补充鉴权、错误处理和自动化测试。这样更容易区分接入问题、模型问题与业务代码问题。

Codex API 与国内使用#

在实践“Codex SDK”相关功能时，如需为 Codex 配置 OpenAI-compatible API，可以前往 APIBest 获取 API Key。第三方服务的模型映射、价格、额度和数据处理方式以 APIBest 当前说明为准。