如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

自托管沙盒

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

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

连接的工作原理

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

执行器使用环境 ID 和权限受限的 API 密钥向 API 注册,然后建立 WebSocket 连接以接收命令并返回结果。所有连接均由执行器向外发起。如果连接中断,执行器会重新连接。

沙盒执行器向 Agents API 发起出站连接,接收命令并返回结果。环境密钥和环境 ID 保存在沙盒中。

准备环境

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

要通过 review: "auto_review" 启用自动审核模式,请在支持沙盒隔离且允许 Codex 创建沙盒的容器中运行标准执行器。自动审核模式采用的权限配置以 workspace-write 为基准,并限制网络访问。启用前,请确认环境满足自动审核模式的先决条件。

在环境中创建工作目录并安装 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.read 和 api.agents.write 权限以执行会话操作,并授予 api.responses.write 权限以进行模型推理。如果您的应用管理凭据库,还需授予 api.vaults.read 和 api.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.id 和 session.environment.remote_url 传给执行器。请原样使用远程 URL,重新连接时也应如此。有关如何使用已保存的智能体,请参阅配置智能体。

您可以在多个会话中复用环境镜像、workspace_directory 和 capability_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 管理这两种资源配置方式的比较,请参阅沙盒生命周期。

提供商 指南
AWS Lambda MicroVMs 配置 AWS
Blaxel 配置 Blaxel
Cloudflare 配置 Cloudflare
Databricks Sandbox 配置 Databricks
Daytona 配置 Daytona
DigitalOcean 配置 DigitalOcean
E2B 配置 E2B
Modal 配置 Modal
Oracle Cloud Infrastructure (OCI) 配置 OCI
Render 配置 Render
Vercel 配置 Vercel

如果通过 webhook 管理资源配置,请参照沙盒生命周期,使用提供商的 SDK 或 API 实现 webhook 处理程序。请明确由谁负责配置资源,以及采用哪些资源清理策略。