For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主导航

OpenAI 托管的沙盒

运行代码并创建可下载的文件,无需管理计算资源。

OpenAI 托管的沙盒为您的智能体提供一个配备 Python、Node.js 和命令行工具的 Linux 工作空间。OpenAI 负责配置并连接沙盒;您的应用负责提供任务 并获取结果。如果您需要使用自己的镜像、计算资源或专用网络, 请选择自托管沙盒

配置沙盒

environment.type 设为 openai_hosted,并且仅添加工作负载 所需的设置。工作目录为 /workspace

  • packages:通过 pythonsystemnpm 列表安装 Python 包、系统包或全局 npm 包。根据需要固定版本,例如 pandas==2.2.3
  • setup_commands:在智能体启动前按顺序运行 Shell 命令,例如 [{ "command": "mkdir -p reports" }]。每条命令都可以单独设置可选的 cwd,默认值为 /workspace
  • files:通过 Files API ID 或内联 base64 内容提供输入文件
  • env:设置值为字符串的环境变量。运行时保留的名称不予接受,包括 PATHCODEX_*OPENAI_API_KEY
  • skillspluginscapability_directories:添加技能插件
  • environment_template_id:在不同会话之间复用已保存的配置。省略的设置会继承模板中的值;覆盖网络设置时不能放宽模板的策略。

系统会在运行设置命令前准备好软件包和输入文件。如果设置命令的退出状态非零,智能体将无法启动。使用设置命令检查所需的依赖项或文件。模板保存的是配置,而非正在运行的工作空间。

控制网络访问

network.access行为
enabled允许出站访问。除非继承了模板策略,否则这是默认行为。
disabled阻止出站访问。
restricted仅允许访问 allowed_domains 中列出的主机。

受限模式接受 1–100 个精确主机名,例如 api.example.com。 不要包含通配符、协议、路径或端口。子域名和重定向 目标需要各自单独的条目。托管的 stdio MCP 服务器目前要求 将访问权限设为 enabled;请参阅 stdio MCP 要求

检查设置是否成功

创建会话的响应表示设置已开始。使用会话的 environment.id 调用 GET /v1/agents/environments/{environment_id} 获取状态: provisioning 表示设置正在进行;connected 表示设置成功。 如果状态为 failed,请读取 agent.session.environment.failed 事件中的 environment.error。 请等到状态变为 connected 后再添加或列出实时文件。

文件与生命周期

每个会话都有独立的工作空间。只要沙盒仍然存在, 文件就会跨轮次保留。每轮完成时,/workspace/outputs 下的文件会 作为不可变产物发布;即使沙盒 过期,这些副本仍可下载。

有关上传、 路径规则、实时文件操作、下载和限制,请参阅文件和产物。 删除会话前,请保存您需要的输出。

沙盒过期

已连接的沙盒会收到保活信号,在轮次之间也不例外。如果活动和保活信号均停止一小时,沙盒可能会被删除。此超时时间无法配置。

使用完毕后,删除会话以请求清理沙盒。如果设置或执行尚在结束过程中, 删除操作返回 409,请等待后重试,并限制 重试次数。关闭事件流不会取消任务。

定价

OpenAI 托管的沙盒按标准容器费率计费。 模型用量按所选模型的 API 费率单独计费。

示例:创建报告

向智能体提供一个包含 102030 的 CSV 文件。智能体会运行 Python 计算 总和,并写入 /workspace/outputs/summary.json

按照 快速入门的前提条件,在应用终端中设置 OPENAI_API_KEY。 请将此密钥保留在沙盒之外。使用包含测试版 Agents API 的 OpenAI SDK 版本。

创建 summary.json
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:
    for event in stream:
        print(event.model_dump_json())

files 中的 base64 值包含 CSV 输入。代码会打印会话事件。 保存 agent.session.created 中的 session.id。在 agent.session.turn.completed 事件发生后, 列出产物,找到 summary.json, 并下载该文件。其内容应为:

{ "total": 60 }

一轮执行完成并不保证每个工具都执行成功。如果任务失败,或 事件流在完成前结束,请检查已保存的会话条目。 使用完毕后,请删除会话

故障排除

问题检查事项
设置失败检查环境失败事件,修复软件包、输入文件或设置命令中的错误,然后再创建新会话。
沙盒请求被阻止检查 network 以及通过重定向访问的所有主机。
实时文件操作失败确认沙盒状态为 connected。如果沙盒已过期,请创建新会话并重新提供输入。
状态或文件列表请求返回 5xx逐步延长重试间隔,并设置重试截止时间。如果错误持续出现,请保留请求 ID。