跳转到内容

沙盒客户端

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

决策指南

Section titled “决策指南”
目标从哪里开始原因
在 macOS 或 Linux 上进行最快的本地迭代UnixLocalSandboxClient没有额外的服务依赖，并且提供简单的本地文件系统工作流。
基本容器隔离DockerSandboxClient使用特定镜像在 Docker 中运行工作。
托管执行或生产风格隔离托管沙盒客户端将工作区边界移动到由提供商管理的环境中。

本地客户端

Section titled “本地客户端”

对于大多数用户，请从以下两个沙盒客户端之一开始：

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

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

要从 Unix-local 切换到 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 }运行器沙盒只需要在一次运行期间存在。
开发者拥有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 也可以保留由运行器管理的沙盒状态。当沙盒生命周期在序列化运行之外管理时，请使用显式的 sessionState。

清单物化

Section titled “清单物化”

清单条目会在智能体运行前准备好。你可以按每次运行或每次客户端创建调用来调整物化并发：

调整清单物化并发
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：存储在沙盒中出现的位置。相对路径会在清单根目录下解析；绝对路径会按原样使用。
  • readOnly：当沙盒不应写回已挂载存储时，请设置此项。
  • mountStrategy：使用同时匹配挂载条目和沙盒后端的策略。

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

通用本地/容器策略：

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

后端支持是有意显式定义的：

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

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

支持的托管平台

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 桥接 Worker URL 和 Worker 认证
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 桥接 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目前未暴露托管专用的挂载策略。请改用清单文件、仓库、快照或其他工作区输入。

下表总结了每个后端可以直接挂载哪些远程存储条目：

后端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-localDocker
exec_command支持支持
PTY write_stdin支持支持
apply_patch支持通过工作区文件 API 支持
view_image支持通过工作区文件 API 支持
命令的 runAs当主机可以解析并切换到该用户时支持受容器/用户设置限制
本地快照支持支持
本地/Docker 挂载本地绑定风格支持绑定和 Docker 卷风格支持

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

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