For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主导航

自行托管的沙盒

将您的计算资源和文件连接到智能体会话。

如果您希望更好地控制智能体的环境,或使用您信任的计算资源,可以连接自己的环境。该环境可以是笔记本电脑、容器或远程沙盒。如果希望由 OpenAI 预配环境,请使用 OpenAI 托管的沙盒

连接的工作原理

OpenAI 负责运行智能体执行框架。您在自己的环境中运行执行器 codex exec-server。它会根据执行框架的请求运行 Shell 命令、读写文件,以及使用本地 MCP 服务器。

执行器使用环境 ID 和受限 API 密钥向 API 注册,然后通过 WebSocket 建立连接,接收命令并返回结果。所有连接均为出站连接。如果连接中断,执行器会重新连接。

沙盒执行器向 Agents API 发起出站连接,交换命令和结果。沙盒持有环境密钥和环境 ID。

准备您的环境

准备智能体所需的文件和依赖项。按用户或工作负载隔离环境。共享同一环境的智能体可以访问相同的文件、凭据及其他资源。

在环境中创建工作目录并安装 Codex CLI。本示例使用 /workspace

mkdir -p /workspace
npm install -g @openai/codex@alpha

网络访问

允许与以下主机建立出站连接:

  • https://api.openai.com 用于环境注册。
  • wss://codex-cloud-environments.chatgpt.com 用于传输命令和结果。

身份验证

使用 OPENAI_API_KEY 发送应用请求。为其授予用于会话操作的 api.agents.readapi.agents.write 权限,以及用于模型推理的 api.responses.write 权限。如果您的应用需要管理保管库,还需添加 api.vaults.readapi.vaults.write 权限。

在平台控制台的智能体选项卡中创建单独的环境密钥。该密钥必须与会话归属于同一组织、项目以及用户或服务账户。将其他所有权限设为

在您的应用或资源预配服务中,将 OPENAI_EXECUTOR_API_KEY 设为此环境密钥。将其值以 CODEX_API_KEY 的形式传入沙盒,供 codex exec-server 读取。请将应用的 OPENAI_API_KEY 保留在沙盒外。

智能体生成的代码可以读取环境密钥,但该密钥仅允许连接环境,无法授权任何其他 API 操作。请勿将其写入源代码、容器镜像或日志,并在需要时轮换或撤销该密钥。

创建会话

在环境之外的应用中运行此示例。如果您已有自行托管的会话,请复用该会话。

使用您自己的环境创建会话
import OpenAI from "openai";
const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "You are a helpful coding assistant. Write clean code and verify that it works.",
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
  },
});

console.log(session);

session.id 与应用的对话状态一起存储。将 session.environment.idsession.environment.remote_url 传递给执行器。使用远程 URL 时请保持原样,重新连接时也不例外。如需使用已存储的智能体,请参阅配置智能体

您可以跨会话复用环境镜像、workspace_directorycapability_directories。每个会话都有自己的环境 ID,并且需要独立的执行器。API 环境模板仅适用于 OpenAI 托管的环境。

启动执行器

从您的应用中打开会话事件流,以接收连接事件。然后,在环境中运行以下命令,并确保已按上文说明将环境密钥配置为 CODEX_API_KEY。请将占位符替换为 API 返回的环境值:

codex exec-server \
  --remote "<session.environment.remote_url>" \
  --environment-id "<session.environment.id>"

在智能体工作期间,请保持执行器运行。

发送任务并监控连接

在保持事件流打开的同时,从应用中发送输入。智能体需要已连接的环境和用户输入才能开始工作。

事件流会报告以下连接状态:

  • agent.session.environment.pending:会话正在等待执行器连接。
  • agent.session.environment.connected:环境已就绪。
  • agent.session.environment.failed:连接失败。请检查环境错误和执行器日志。

继续关注事件流,获取本轮的执行结果和输出。如需从应用中或通过 Webhook 管理启动、重新连接和关闭,请参阅环境生命周期

沙盒提供商

选择一家沙盒提供商来运行代码和处理文件。请参阅沙盒生命周期,比较由应用管理和由 Webhook 管理的预配方式。

提供商指南
ModalModal 设置
CloudflareCloudflare 设置
VercelVercel 设置
DaytonaDaytona 设置
BlaxelBlaxel 设置
E2BE2B 设置
RunloopRunloop 设置
DigitalOceanDigitalOcean 设置
Oracle Cloud Infrastructure(OCI)OCI 设置

对于由 Webhook 管理的预配,请参考沙盒生命周期,并使用提供商的 SDK 或 API 实现处理程序。明确预配的责任归属和清理策略。