自托管沙箱

完整文档索引请参阅 llms.txt。在页面 URL 后附加 .md 即可获取 Markdown 格式的文档页面。

当您希望对 Agent 的运行环境拥有更多控制权，或希望使用自己信任的计算资源时，可以接入自己的环境。该环境可以是笔记本电脑、容器或远程沙箱。如需由 OpenAI 提供环境，请使用 OpenAI 托管沙箱。

连接方式

OpenAI 运行 Agent 框架。您在自己的环境中运行 codex exec-server（执行器）。执行器按照框架的请求执行 Shell 命令、读写文件，并使用本地 MCP 服务器。

执行器使用环境 ID 和受限 API 密钥向 API 注册，随后通过 WebSocket 建立连接以接收命令并返回结果。所有连接均为出站连接。若连接断开，执行器将自动重连。

准备环境

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

在环境中创建工作目录并安装 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 以进行模型推理。若您的应用程序管理 Vault，还需添加 api.vaults.read 和 api.vaults.write。

在平台控制台的 Agents 标签页 中单独创建一个环境密钥。该密钥必须与拥有会话的组织、项目及用户或服务账号属于同一主体。将其他所有权限设置为 None。

在您的应用程序或制备服务中将 OPENAI_EXECUTOR_API_KEY 设置为此环境密钥。将其值以 CODEX_API_KEY 的形式传入沙箱，供 codex exec-server 读取。将应用程序的 OPENAI_API_KEY 保留在沙箱之外。

Agent 生成的代码可以读取环境密钥，但该密钥仅允许连接环境，无法授权任何其他 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);

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())

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)

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);

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 请原样使用，包括重新连接时也不例外。请参阅配置 Agent 以了解如何使用已存储的 Agent。

您可以跨会话复用环境镜像、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 工作期间请保持执行器持续运行。

发送任务并监控连接

在事件流保持开启的情况下，从应用程序发送输入。Agent 需要同时具备已连接的环境和用户输入才能开始工作。

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

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

继续跟踪事件流以获取本轮的结果和输出。请参阅环境生命周期，了解如何通过应用程序或 Webhook 管理启动、重连和关闭流程。

沙箱提供商

选择沙箱提供商以运行代码和处理文件。请参阅沙箱生命周期，比较应用程序管理和 Webhook 管理的制备方式。

对于 Webhook 管理的制备方式，请使用沙箱生命周期及您的提供商 SDK 或 API 实现处理程序。请明确制备的所有权和清理策略。