OpenAI 自托管沙箱

需要更强环境控制或使用信任的计算资源时，连接自己的环境。可以是笔记本、容器或远程沙箱。希望由OpenAI创建环境时，选择 OpenAI托管沙箱。

连接如何工作

OpenAI运行智能体框架，你在环境内运行执行器 codex exec-server，按框架请求执行shell命令、读写文件和调用本地MCP服务器。

执行器用环境ID和受限密钥注册，再通过WebSocket收命令、返结果。所有连接都是出站连接，断线后执行器会重连。

查看竖版图片

准备环境

启用 review: "auto_review" 时，须在支持沙箱隔离且允许 Codex 创建沙箱的容器中运行标准执行器。自动审查会应用以工作区写入权限为基准、限制网络访问的权限配置。启用前先检查自动审查前置条件。

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

在环境内创建工作目录并安装Codex CLI，示例使用 /workspace：

来源示例 1（bash）：

## [中文] 示例 1：准备环境。
## [中文] 按本段命令安装依赖或运行前面的示例文件；仅安装依赖不会创建或完成智能体任务。
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。

在控制台 Agents选项卡创建独立环境密钥，组织、项目及用户或服务账户归属必须与会话相同，其他所有权限设为 None。

在应用或资源创建服务中以 OPENAI_EXECUTOR_API_KEY 保存，传入沙箱时作为 CODEX_API_KEY，供 codex exec-server 读取。应用 OPENAI_API_KEY 留在沙箱外。

智能体代码可读取环境密钥，但它只授权环境连接，不能授权其他API动作。不要写入源码、镜像或日志，必要时轮换或撤销。

创建会话

在环境外的应用中运行以下示例；已有自托管会话时可复用：

来源示例 2（javascript）：

程序文字说明6：你是乐于助人的编码助手，编写清晰代码并验证其可用性。

程序文字说明7：这段拼接字符串构成编码助手指令：编写清晰代码并验证其可用性。

// [中文] 示例 2：创建会话。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
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);

来源示例 3（python）：

沿用程序文字说明6。

沿用程序文字说明7。

## [中文] 示例 3：创建会话。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
from openai import OpenAI

client = OpenAI()

session = 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"},
)
print(session.to_json())

来源示例 4（go）：

沿用程序文字说明6。

沿用程序文字说明7。

// [中文] 示例 4：创建会话。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
import (
    "context"
    "fmt"

    "github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
    openai.BetaAgentSessionNewParams{
        Agent: openai.BetaAgentSessionNewParamsAgent{
            Model:        openai.String("gpt-6-astra"),
            Instructions: openai.String("You are a helpful coding assistant. Write clean code and verify that it works."),
        },
        Environment: openai.EnvironmentParamUnion{
            OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{WorkspaceDirectory: "/workspace"},
        },
    })
if err != nil {
    panic(err)
}
fmt.Println(result)

来源示例 5（java）：

沿用程序文字说明7。

// [中文] 示例 5：创建会话。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .instructions(
                            "You are a helpful coding assistant. Write clean code and verify"
                                + " that it works.")
                        .build())
                .environment(
                    EnvironmentParam.SelfHosted.builder()
                        .workspaceDirectory("/workspace")
                        .build())
                .build());
System.out.println(result);

来源示例 6（ruby）：

沿用程序文字说明6。

沿用程序文字说明7。

## [中文] 示例 6：创建会话。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
require "openai"

client = OpenAI::Client.new
result = 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"
  }
)
puts result

将 session.id 与应用对话状态一起保存。把 session.environment.id、session.environment.remote_url 传给执行器，远端URL原样使用，重连时也一样。使用已保存智能体见配置指南。

镜像、workspace_directory 和 capability_directories 可以跨会话复用，但每个会话都有自己的环境ID，需独立执行器。API的环境模板只适用于OpenAI托管环境。

启动执行器

应用先打开会话事件流接收连接事件，再在环境内执行下列命令。预先将环境密钥配置为 CODEX_API_KEY，占位符替换为API返回环境值：

来源示例 7（bash）：

## [中文] 示例 7：启动执行器。
## [中文] 在执行环境中启动执行器，连接值来自创建会话的响应；使用环境密钥，不传应用密钥。
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模式需按生命周期指南，结合提供商SDK或API实现处理器，并明确资源创建归属与清理策略。