如果您希望更灵活地控制智能体的运行环境,或希望使用您信任的计算资源,可以连接自己的环境。这个环境可以是笔记本电脑、容器或远程沙盒。如果希望由 OpenAI 配置环境,请使用 OpenAI 托管的沙盒。
连接的工作原理
OpenAI 负责运行智能体执行框架。您在自己的环境中运行执行器 codex exec-server。执行器根据执行框架的请求运行 shell 命令、读写文件并使用本地 MCP 服务器。
执行器使用环境 ID 和权限受限的 API 密钥向 API 注册,然后建立 WebSocket 连接以接收命令并返回结果。所有连接均由执行器向外发起。如果连接中断,执行器会重新连接。

准备环境
准备好智能体所需的文件和依赖项。按用户或工作负载隔离环境。共享环境的智能体可以访问相同的文件、凭据和其他资源。
要通过 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 处理程序。请明确由谁负责配置资源,以及采用哪些资源清理策略。