跳转到内容

沙盒客户端

使用本页来选择沙盒工作应在何处运行。在大多数情况下，SandboxAgent 定义保持不变，而沙盒客户端及其特定选项会在 sandbox 运行选项中变化。

决策指南

Section titled “决策指南”
目标起步选择原因
在 macOS 或 Linux 上实现最快的本地迭代UnixLocalSandboxClient无需额外服务依赖，且本地文件系统工作流简单。
基础容器隔离DockerSandboxClient在 Docker 中使用指定镜像运行工作。
托管执行或生产环境风格的隔离托管沙盒客户端将工作区边界转移到由提供方管理的环境中。

本地客户端

Section titled “本地客户端”

对大多数用户来说，建议从以下两种沙盒客户端之一开始：

客户端安装要求适用场景
UnixLocalSandboxClient无在 macOS 或 Linux 上进行最快的本地迭代。是本地开发的良好默认选择。
DockerSandboxClient本地可用 Docker CLI您希望获得容器隔离，或使用特定镜像实现本地环境一致性。

Unix 本地模式是开始基于本地文件系统进行开发的最简单方式。当您需要更强的环境隔离或生产环境风格的一致性时，再迁移到 Docker 或托管提供方。

要从 Unix 本地切换到 Docker，请保持智能体定义不变，仅更改客户端：

使用 Docker
import { run } from '@openai/agents';
import { SandboxAgent } from '@openai/agents/sandbox';
import { DockerSandboxClient } from '@openai/agents/sandbox/local';


const agent = new SandboxAgent({
  name: 'Workspace reviewer',
  model: 'gpt-5.5',
  instructions: 'Inspect the sandbox workspace before answering.',
});


const result = await run(agent, 'Inspect the workspace.', {
  sandbox: {
    client: new DockerSandboxClient({ image: 'node:22-bookworm-slim' }),
  },
});


console.log(result.finalOutput);

同一个智能体通常可以使用任一本地客户端运行：

在本地客户端之间切换
import {
  DockerSandboxClient,
  UnixLocalSandboxClient,
} from '@openai/agents/sandbox/local';


const client = process.env.USE_DOCKER
  ? new DockerSandboxClient({ image: 'node:22-bookworm-slim' })
  : new UnixLocalSandboxClient();

会话归属

Section titled “会话归属”

有两种生命周期风格。

风格传入内容谁来关闭会话适用场景
SDK 托管sandbox: { client }runner沙盒只需要为单次运行存在。
开发者托管sandbox: { session }您的代码您需要事后检查文件、复用同一个活动会话，或协调多次运行。

当您自行创建会话时，也需要自行关闭它：

自行管理沙盒会话生命周期
import { run } from '@openai/agents';
import { Manifest, SandboxAgent } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';


const manifest = new Manifest();
const agent = new SandboxAgent({
  name: 'Workspace reviewer',
  model: 'gpt-5.5',
  instructions: 'Inspect the sandbox workspace before answering.',
});


const client = new UnixLocalSandboxClient();
const session = await client.create({ manifest });


try {
  await run(agent, 'First pass.', { sandbox: { session } });
  await run(agent, 'Follow-up pass.', { sandbox: { session } });
} finally {
  await session.close?.();
}

恢复与快照

Section titled “恢复与快照”

沙盒状态与对话状态是分离的：

  • SDK 对话状态保存在 result.history、SDK Session、conversationId 或 previousResponseId 中。
  • 沙盒状态保存在活动沙盒会话、序列化后的 sessionState、RunState 的沙盒负载或快照中。

当您希望通过沙盒客户端重新连接到同一个后端会话时，请使用 sessionState。当您希望从已保存的工作区内容生成一个全新会话时，请使用快照。

序列化并恢复沙盒状态
import { Manifest } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';


const manifest = new Manifest();
const client = new UnixLocalSandboxClient({
  snapshot: { type: 'local', baseDir: '/tmp/my-sandbox-snapshots' },
});


const session = await client.create({ manifest });
const state = await client.serializeSessionState?.(session.state);
await session.close?.();


if (state) {
  const restored = await client.resume?.(
    await client.deserializeSessionState!(state),
  );
  await restored?.close?.();
}

当您暂停或恢复一个更大的工作流时，RunState 也可以保留由 runner 管理的沙盒状态。如果沙盒生命周期是在序列化运行之外管理的，请使用显式 sessionState。

Manifest 实体化

Section titled “Manifest 实体化”

Manifest 条目会在智能体运行前准备完成。您可以按单次运行或按客户端创建调用来调整实体化并发度：

调整 Manifest 实体化并发度
import { run } from '@openai/agents';
import { SandboxAgent } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';


const agent = new SandboxAgent({
  name: 'Repository inspector',
  model: 'gpt-5.5',
  instructions: 'Inspect the repository before answering.',
});


await run(agent, 'Inspect the repo.', {
  sandbox: {
    client: new UnixLocalSandboxClient(),
    concurrencyLimits: {
      manifestEntries: 4,
      localDirFiles: 16,
    },
  },
});

manifestEntries 限制顶层条目工作的并行度。localDirFiles 限制 localDir() 条目内文件复制的并发度。

挂载与远程存储

Section titled “挂载与远程存储”

挂载条目用于描述要暴露哪些存储；挂载策略用于描述沙盒后端如何附加这些存储。从 @openai/agents/sandbox 导入内置挂载条目和通用策略。

常见挂载选项：

  • mountPath：存储在沙盒中出现的位置。相对路径会在 manifest 根目录下解析；绝对路径则按原样使用。
  • readOnly：当沙盒不应回写到挂载存储时设置此项。
  • mountStrategy：使用同时匹配挂载条目和沙盒后端的策略。

挂载会被视为临时工作区条目。快照和持久化流程会分离或跳过挂载路径，而不是将挂载的远程存储复制到已保存的工作区中。

通用本地/容器策略：

策略或模式适用场景说明
inContainerMountStrategy(...)沙盒镜像可以运行挂载命令，例如 rclone、mount-s3 或 blobfuse2。作为通用策略提供；是否支持取决于后端。
dockerVolumeMountStrategy(...)Docker 应在容器启动前附加一个由卷驱动支持的挂载。仅适用于 Docker。
localBindMountStrategy()本地后端应将一个本地绝对路径绑定到工作区中。在允许的情况下，由本地工作区实体化支持。

后端支持是显式定义的：

后端挂载说明
UnixLocalSandboxClient通过本地工作区模型支持本地 bind 风格挂载。
DockerSandboxClient支持本地 bind 挂载，以及 Docker 可以附加存储时的 Docker volume 风格策略。
托管提供方提供方特定策略与各自的提供方实现一起提供。请查看该提供方文档，了解支持的挂载和所需设置。

不要假设某个挂载条目可在所有后端上工作。如果某个客户端无法强制执行 manifest 元数据、身份或挂载行为，它应尽早失败，而不是静默忽略 manifest 的该部分。

支持的托管平台

Section titled “支持的托管平台”

当您需要托管环境时，通常可以继续使用同一个 SandboxAgent 定义，只需在 sandbox 运行选项中更改沙盒客户端。

托管提供方实现可通过 @openai/agents-extensions 的提供方子路径获得。请查看提供方文档，了解确切的环境变量、可运行示例、端口行为、PTY 支持、快照行为和清理行为。

安装 @openai/agents-extensions 并满足其包级 peer 依赖。每个提供方还可能需要提供方 SDK 包或后端设置：

客户端导入路径提供方要求
BlaxelSandboxClient@openai/agents-extensions/sandbox/blaxelnpm peer：@blaxel/core
CloudflareSandboxClient@openai/agents-extensions/sandbox/cloudflareCloudflare Sandbox bridge Worker URL 和 Worker auth
DaytonaSandboxClient@openai/agents-extensions/sandbox/daytonanpm peer：@daytonaio/sdk
E2BSandboxClient@openai/agents-extensions/sandbox/e2bnpm peer：e2b 或 @e2b/code-interpreter
ModalSandboxClient@openai/agents-extensions/sandbox/modalnpm peer：modal
RunloopSandboxClient@openai/agents-extensions/sandbox/runloopnpm peer：@runloop/api-client
VercelSandboxClient@openai/agents-extensions/sandbox/vercelnpm peer：@vercel/sandbox

CloudflareSandboxClient 不会导入 Cloudflare npm SDK。它会通过 HTTP 与已部署的 Cloudflare Sandbox bridge Worker 通信。

托管沙盒客户端会暴露提供方特定的挂载策略。请选择最适合您的存储提供方的后端和挂载策略：

后端挂载说明
Docker支持 s3Mount()、gcsMount()、r2Mount()、azureBlobMount()、boxMount() 和 s3FilesMount()，并可搭配 inContainerMountStrategy() 和 dockerVolumeMountStrategy() 等本地策略使用。
ModalSandboxClient支持使用 ModalCloudBucketMountStrategy 对 S3、R2 和基于 HMAC 认证的 GCS 挂载条目进行云存储桶挂载。
CloudflareSandboxClient支持使用 CloudflareBucketMountStrategy 对 S3、R2 和基于 HMAC 认证的 GCS 挂载条目进行 Cloudflare 存储桶挂载。
BlaxelSandboxClient支持使用 BlaxelCloudBucketMountStrategy 对 S3、R2 和 GCS 挂载条目进行云存储桶挂载。它还支持使用 BlaxelDriveMount 和 BlaxelDriveMountStrategy 挂载持久化 Blaxel Drives。
DaytonaSandboxClient支持使用 DaytonaCloudBucketMountStrategy 对 S3、GCS、R2、Azure Blob 和 Box 挂载条目进行基于 rclone 的挂载。
E2BSandboxClient支持使用 E2BCloudBucketMountStrategy 对 S3、GCS、R2、Azure Blob 和 Box 挂载条目进行基于 rclone 的挂载。
RunloopSandboxClient支持使用 RunloopCloudBucketMountStrategy 对 S3、GCS、R2、Azure Blob 和 Box 挂载条目进行基于 rclone 的挂载。
VercelSandboxClient当前未暴露托管特定的挂载策略。请改用 manifest 文件、仓库、快照或其他工作区输入。

下表总结了各后端可直接挂载的远程存储条目：

后端AWS S3Cloudflare R2GCSAzure Blob StorageBoxS3 Files
Docker是是是是是是
ModalSandboxClient是是是否否否
CloudflareSandboxClient是是是否否否
BlaxelSandboxClient是是是否否否
DaytonaSandboxClient是是是是是否
E2BSandboxClient是是是是是否
RunloopSandboxClient是是是是是否
VercelSandboxClient否否否否否否

暴露端口

Section titled “暴露端口”

当后端支持时，沙盒客户端可通过 resolveExposedPort(port) 暴露端点。

客户端行为
UnixLocalSandboxClient将已配置端口解析为 127.0.0.1。
DockerSandboxClient发布已配置的容器端口，并解析其主机端点。

当您需要后端强制执行允许列表时，请在客户端选项中声明端口：

暴露端口
import { DockerSandboxClient } from '@openai/agents/sandbox/local';


const client = new DockerSandboxClient({
  image: 'node:22-bookworm-slim',
  exposedPorts: [3000],
});

能力支持矩阵

Section titled “能力支持矩阵”
能力Unix 本地Docker
exec_command支持支持
PTY write_stdin支持支持
apply_patch支持通过工作区文件 API 支持
view_image支持通过工作区文件 API 支持
命令的 runAs当主机能够解析并切换到该用户时支持受容器/用户设置限制
本地快照支持支持
本地/Docker 挂载本地 bind 风格支持bind 和 Docker volume 风格支持

本地 PTY 支持会在 SDK 进程中使用一个小型 Python 3 bridge。该 bridge 仅用于 tty: true 会话，因为 Node.js 不提供内置 PTY API，而 SDK 需要标准 POSIX PTY 行为来支持交互式 stdin、信号处理和退出状态报告。请在运行 SDK 代码的环境中安装 python3，或将 OPENAI_AGENTS_PYTHON 设置为一个 Python 3 可执行文件。这与 Docker 沙盒镜像内部安装的 Python 版本（如果有）是分开的。

托管提供方支持因提供方而异。请查看提供方特定文档，了解确切选项、环境变量、端口行为、PTY 支持、快照行为和清理行为。