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

准备您的环境
准备智能体所需的文件和依赖项。按用户或工作负载隔离环境。共享同一环境的智能体可以访问相同的文件、凭据及其他资源。
在环境中创建工作目录并安装 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 管理的预配方式。
| 提供商 | 指南 |
|---|---|
| Modal | Modal 设置 |
| Cloudflare | Cloudflare 设置 |
| Vercel | Vercel 设置 |
| Daytona | Daytona 设置 |
| Blaxel | Blaxel 设置 |
| E2B | E2B 设置 |
| Runloop | Runloop 设置 |
| DigitalOcean | DigitalOcean 设置 |
| Oracle Cloud Infrastructure(OCI) | OCI 设置 |
对于由 Webhook 管理的预配,请参考沙盒生命周期,并使用提供商的 SDK 或 API 实现处理程序。明确预配的责任归属和清理策略。