Codex SDK

身份 非官方简体中文镜像

翻译状态 AI 翻译

来源版本 官方未提供

同步日期 2026-07-31

官方原文 learn.chatgpt.com

如需完整文档索引，请参阅 llms.txt。文档页面的 Markdown 版本可通过在页面后追加 .md 来获取 URL。

如果你使用 Codex 通过 Codex CLI、 IDE 扩展，或 Codex cloud，也可以通过编程方式控制它。

在以下情况下，你需要使用 SDK：

• 将 Codex 集成到 CI/CD 流程中
• 创建能够与 Codex 交互以执行复杂工程任务的智能体
• 将 Codex 构建到你自己的内部工具和工作流中
• 在你自己的应用中集成 Codex

使用 Codex SDK 处理以编码为重点的 Codex 线程。如果 Codex 是更广泛编排工作流中的一个专家， 请将 Codex CLI 作为 MCP 服务器运行，并使用 Agents SDK对其进行编排。

如果你拥有 beta 访问权限，并且需要带有结构化 安全发现和覆盖范围的仓库或变更扫描，请使用 Codex Security TypeScript SDK。

TypeScript 库

这个 TypeScript 库让你的应用能够启动、继续和恢复本地 Codex 线程。

在服务器端使用该库；它要求 Node.js 18 或更高版本。

安装

要开始使用，请安装 Codex SDK 使用 npm：

npm install @openai/codex-sdk

使用

启动一个 Codex 线程，并使用你的提示词运行它。

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 来恢复过去的线程。

// 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 通过本地 Codex app-server 进行控制，基于 JSON-RPC。它需要 Python 3.10 或更高版本。已发布的 SDK 构建包含固定的 Codex CLI 运行时依赖。

安装

如需安装 SDK，请运行：

pip install openai-codex

已发布的 SDK 构建会自动使用其固定的运行时。仅当你有意针对特定本地 CodexConfig(codex_bin=...) 可执行文件运行时，才传入 Codex 。

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

使用

启动 Codex，创建一个线程，并运行提示词：

from openai_codex import Codex, Sandbox

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

如果你的应用已经是异步的，请使用 AsyncCodex：

import asyncio

from openai_codex import AsyncCodex


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


asyncio.run(main())

沙箱预设

在创建线程或为后续轮次更改其文件系统 Sandbox 访问权限时，使用相同的 预设：

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：读取文件，并在工作区和配置的可写根目录中写入。
• Sandbox.full_access：运行时不受文件系统访问限制。

当你省略 sandbox=时，app-server 会使用其配置的默认值。传递给 或 run(...) 的沙箱 turn(...) 会应用于该轮以及该线程上之后的轮次 。

如需了解详情，请参阅 Python 仓库。