OpenAI 托管沙箱

OpenAI 托管沙箱提供带 Python、Node.js 和命令行工具的 Linux 工作区。OpenAI 创建并连接环境，应用提供任务并取回结果。需要自定义镜像、计算资源或私有网络时，选择自托管沙箱。

通过浏览器操作网站的任务，见计算机使用；希望创建会话前准备工作区，见预热沙箱。

配置沙箱

创建会话时把 environment.type 设为 openai_hosted，只添加工作负载需要的设置。沙箱工作目录为 /workspace。

通过 container_size 与 network 选择资源和网络权限。使用环境模板时，省略的设置继承模板。

准备软件包与文件

• packages：通过 python、system 或 npm 列表安装 Python、系统或全局 npm 包。必要时固定版本，例如 pandas==2.2.3。
• files：使用 Files API ID 或内联 Base64 提供输入文件。

运行初始化命令

setup_commands 在智能体启动前按顺序运行 shell 命令，例如 [{ "command": "mkdir -p reports" }] 创建目录。每条命令可设自己的 cwd，默认 /workspace。

软件包与输入文件先准备完，再执行初始化命令。可用命令检查必需依赖和文件；任一命令以非零状态退出，会阻止智能体启动。

设置环境变量

env 用于设置字符串值环境变量，智能体生成的代码可以读取它们。

秘密应使用凭证库，让真实值留在沙箱外。运行时保留名称会被拒绝，包括 PATH、CODEX_* 和 OPENAI_API_KEY。

选择容器规格

创建会话时通过 environment.container_size 选择 CPU 与内存，默认 medium：

例如，在 POST /v1/agents/sessions 中包含以下环境配置，选择 small：

来源示例 1（json）：

{
  "environment": {
    "type": "openai_hosted",
    "container_size": "small"
  }
}

返回会话的 environment.container_size 会报告选定规格。此设置只适用于 OpenAI 托管沙箱。

控制网络访问

受限模式接受1—100个精确主机名，例如 api.example.com，不包含通配符、协议、路径或端口。子域名和重定向目标分别列出。托管 stdio MCP 服务器目前要求 enabled，见 stdio MCP 要求。

添加技能与插件

用 skills、plugins 和 capability_directories 添加技能与插件。

跨会话复用配置

设置 environment_template_id 复用已保存配置。省略设置继承模板，网络覆盖不能放宽模板策略。模板保存的是配置，不是运行中的工作区。

检查初始化是否成功

创建会话响应表示初始化已开始。用会话 environment.id 请求 GET /v1/agents/environments/{environment_id} 检查状态：

添加或列出实时文件前，先等待 connected。

文件与生命周期

每个会话有独立工作区。沙箱存在期间，文件跨轮次保留；轮次完成时，/workspace/outputs 下文件发布为不可变产物，沙箱过期后仍可下载这些副本。

上传、路径规则、实时文件操作、下载和限额见文件与产物。删除会话前保存所需输出。

沙箱过期

已连接沙箱会持续收到保活消息，包括轮次之间。活动与保活停止一小时后，沙箱可能被删除；此超时不可配置。

任务结束后删除会话，以请求清理沙箱。若初始化或执行结束期间删除返回 409，等待后进行有次数上限的重试。关闭事件流不会取消任务。

价格

OpenAI 托管沙箱采用标准容器费率，模型用量另按所选模型的 API 费率计费。

示例：创建报告

向智能体提供含 10、20、30 的 CSV，让它运行 Python 求和，写入 /workspace/outputs/summary.json。

按快速开始前置条件在应用终端设置 OPENAI_API_KEY，密钥留在沙箱外。使用提供 Beta Agents API 的 OpenAI SDK版本。

来源示例 2（javascript）：

程序文字说明28：用Python计算/workspace/amounts.csv的amount列总和，将含total的JSON写入/workspace/outputs/summary.json，再读回验证。

程序文字说明29：此拼接输入要求计算CSV金额列合计、写JSON报告并读回验证。

// [中文] 示例 2：示例：创建报告。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
import OpenAI from "openai";
import { agentFileDestination } from "openai/helpers/beta/agents/filesystem";

const client = new OpenAI();
const stream = await client.beta.agents.sessions.create({
  agent: { model: "gpt-6-astra" },
  environment: {
    type: "openai_hosted",
    network: { access: "disabled" },
    files: [
      {
        type: "inline",
        path: "/workspace/amounts.csv",
        data: "YW1vdW50CjEwCjIwCjMwCg==",
      },
    ],
  },
  input:
    "Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object with the total to /workspace/outputs/summary.json, then read it back to verify it.",
  stream: true,
});

stream.withResultCollection();
try {
  for await (const event of stream) {
    console.log(event);
  }
  const result = await stream.finalResult();
  await client.beta.agents.sessions.artifacts.forResult(result).download({
    path: "/workspace/outputs/summary.json",
    to: agentFileDestination("summary.json"),
  });
} finally {
  stream.controller.abort();
}

来源示例 3（python）：

沿用程序文字说明28。

沿用程序文字说明29。

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

client = OpenAI()
stream = client.beta.agents.sessions.create(
    agent={"model": "gpt-6-astra"},
    environment={
        "type": "openai_hosted",
        "network": {"access": "disabled"},
        "files": [
            {
                "type": "inline",
                "path": "/workspace/amounts.csv",
                "data": "YW1vdW50CjEwCjIwCjMwCg==",
            }
        ],
    },
    input="Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object with the total to /workspace/outputs/summary.json, then read it back to verify it.",
    stream=True,
)

with stream.with_result_collection():
    for event in stream:
        print(event.model_dump_json())
    result = stream.get_final_result()

client.beta.agents.sessions.artifacts.for_result(result).download(
    "/workspace/outputs/summary.json", to="summary.json"
)

来源示例 4（go）：

沿用程序文字说明28。

沿用程序文字说明29。

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

import (
    "context"
    "fmt"
    "os"

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

func main() {
    ctx := context.Background()
    client := openai.NewClient()
    stream := client.Beta.Agents.Sessions.NewStreaming(ctx, openai.BetaAgentSessionNewParams{
        Agent: openai.BetaAgentSessionNewParamsAgent{Model: openai.String("gpt-6-astra")},
        Environment: openai.EnvironmentParamUnion{OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{
            Network: openai.EnvironmentParamOpenAIHostedNetwork{Access: "disabled"},
            Files: []openai.HostedEnvironmentFileParamUnion{{OfParamInline: &openai.HostedEnvironmentFileParamInline{
                Path: "/workspace/amounts.csv",
                Data: "YW1vdW50CjEwCjIwCjMwCg==",
            }}},
        }},
        Input: openai.BetaAgentSessionNewParamsInputUnion{OfString: openai.String("Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object with the total to /workspace/outputs/summary.json, then read it back to verify it.")},
    })
    defer stream.Close()
    openai.BetaAgentSessionWithResultCollection(stream)
    for stream.Next() {
        fmt.Println(stream.Current().RawJSON())
    }

    result, err := openai.BetaAgentSessionFinalResult(stream)
    if err != nil {
        panic(err)
    }
    destination, err := os.Create("summary.json")
    if err != nil {
        panic(err)
    }
    defer destination.Close()
    _, err = client.Beta.Agents.Sessions.Artifacts.ForResult(result).Download(ctx, "/workspace/outputs/summary.json", destination)
    if err != nil {
        panic(err)
    }
    if err := destination.Close(); err != nil {
        panic(err)
    }
}

来源示例 5（java）：

沿用程序文字说明29。

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

public class HostedReport {
  public static void main(String[] args) throws Exception {
    var client = OpenAIOkHttpClient.fromEnv();
    var params =
        SessionCreateParams.builder()
            .agent(SessionCreateParams.Agent.builder().model("gpt-6-astra").build())
            .environment(
                EnvironmentParam.OpenAIHosted.builder()
                    .network(
                        EnvironmentParam.OpenAIHosted.Network.builder()
                            .access(EnvironmentParam.OpenAIHosted.Network.Access.DISABLED)
                            .build())
                    .addFile(
                        HostedEnvironmentFileParam.Inline.builder()
                            .path("/workspace/amounts.csv")
                            .data("YW1vdW50CjEwCjIwCjMwCg==")
                            .build())
                    .build())
            .input(
                "Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object"
                    + " with the total to /workspace/outputs/summary.json, then read it back to"
                    + " verify it.")
            .build();

    try (var stream = client.beta().agents().sessions().createStreaming(params)) {
      AgentTurnResults.withResultCollection(stream);
      stream.stream().forEach(System.out::println);
      var result = AgentTurnResults.getFinalResult(stream);
      AgentArtifactDownloads.forResult(client.beta().agents().sessions().artifacts(), result)
          .download("/workspace/outputs/summary.json", Path.of("summary.json"));
    }
  }
}

来源示例 6（ruby）：

沿用程序文字说明28。

沿用程序文字说明29。

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

client = OpenAI::Client.new
stream = client.beta.agents.sessions.create_streaming(
  agent: { model: "gpt-6-astra" },
  environment: {
    type: :openai_hosted,
    network: { access: :disabled },
    files: [
      {
        type: :inline,
        path: "/workspace/amounts.csv",
        data: "YW1vdW50CjEwCjIwCjMwCg=="
      }
    ]
  },
  input: "Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object with the total to /workspace/outputs/summary.json, then read it back to verify it."
)

begin
  stream.with_result_collection
  stream.each { |event| puts event.to_json }
  result = stream.get_final_result
  puts result.output_text
  client.beta.agents.sessions.artifacts.for_result(result).download(
    path: "/workspace/outputs/summary.json",
    to: Pathname("summary.json")
  )
ensure
  stream.close
end

来源示例 7（bash）：

沿用程序文字说明28。

沿用程序文字说明29。

## [中文] 示例 7：示例：创建报告。
## [中文] 本段涉及的请求或服务地址：https://api.openai.com/v1/agents/sessions；示例占位地址需替换为实际资源。
curl --no-buffer --fail-with-body https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent": {
    "model": "gpt-6-astra"
  },
  "environment": {
    "type": "openai_hosted",
    "network": {
      "access": "disabled"
    },
    "files": [
      {
        "type": "inline",
        "path": "/workspace/amounts.csv",
        "data": "YW1vdW50CjEwCjIwCjMwCg=="
      }
    ]
  },
  "input": "Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object with the total to /workspace/outputs/summary.json, then read it back to verify it.",
  "stream": true
}'

files 中 Base64 值是 CSV 输入，代码会打印会话事件。从 agent.session.created 保存 session.id。收到 agent.session.turn.completed 后，列出产物，找到 summary.json 并下载。内容应为：

来源示例 8（json）：

{ "total": 60 }

轮次完成不保证所有工具都成功。任务失败或流在完成前结束时，检查已保存会话项目。结束后删除会话。

排障