沙盒客户端

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

Beta 功能

沙盒智能体处于 beta 阶段。API 细节、默认值和支持的能力 可能会在正式可用前发生变化，并且预计会逐步提供更多高级功能。

决策指南

目标	起点	原因
在 macOS 或 Linux 上最快的本地迭代	UnixLocalSandboxClient	无需额外服务依赖，且本地文件系统工作流简单。
基础容器隔离	DockerSandboxClient	在 Docker 内使用指定镜像运行任务。
托管执行或生产式隔离	托管沙盒客户端	将工作区边界移至提供商管理的环境。

本地客户端

大多数用户可以从以下两个沙盒客户端之一开始：

客户端	安装	适用场景
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();

会话所有权

有两种生命周期风格。

风格	传入内容	谁关闭会话	适用场景
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?.();
}

恢复与快照

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

• 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。

清单物化

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

调整清单物化并发度

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() 条目内的文件复制并发度。

挂载与远程存储

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

常见挂载选项：

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

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

通用本地/容器策略：

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

后端支持是有意显式声明的：

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

不要假设一个挂载条目适用于所有后端。如果客户端无法强制执行清单元数据、身份或挂载行为，它应尽早失败，而不是静默忽略清单中的对应部分。

支持的托管平台

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

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

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

客户端	导入路径	提供商要求
BlaxelSandboxClient	@openai/agents-extensions/sandbox/blaxel	npm 对等依赖：@blaxel/core
CloudflareSandboxClient	@openai/agents-extensions/sandbox/cloudflare	Cloudflare Sandbox 桥接 Worker URL 和 Worker 认证
DaytonaSandboxClient	@openai/agents-extensions/sandbox/daytona	npm 对等依赖：@daytonaio/sdk
E2BSandboxClient	@openai/agents-extensions/sandbox/e2b	npm 对等依赖：e2b 或 @e2b/code-interpreter
ModalSandboxClient	@openai/agents-extensions/sandbox/modal	npm 对等依赖：modal
RunloopSandboxClient	@openai/agents-extensions/sandbox/runloop	npm 对等依赖：@runloop/api-client
VercelSandboxClient	@openai/agents-extensions/sandbox/vercel	npm 对等依赖：@vercel/sandbox

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

VercelSandboxClient 会按以下优先级解析每个 PAT 凭证字段：每次创建选项、构造函数选项，然后是 VERCEL_PROJECT_ID、VERCEL_TEAM_ID 和 VERCEL_TOKEN。只有当最终得到的 projectId、teamId 和 token 都非空时，它才会转发凭证。否则，它会省略这三个字段，并让 @vercel/sandbox 解析认证，包括平台 OIDC 或本地提供商凭证。当会话被序列化和恢复时，完整解析出的凭证会被保留。序列化凭证会被视为一个完整三元组，不会与当前选项或环境变量混合；不完整的序列化凭证会先被丢弃，然后再将当前配置解析为回退方案。由于令牌仍会存在于序列化会话状态中，请安全地存储该状态。

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

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

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

后端	AWS S3	Cloudflare R2	GCS	Azure Blob Storage	Box	S3 Files
Docker	是	是	是	是	是	是
ModalSandboxClient	是	是	是	否	否	否
CloudflareSandboxClient	是	是	是	否	否	否
BlaxelSandboxClient	是	是	是	否	否	否
DaytonaSandboxClient	是	是	是	是	是	否
E2BSandboxClient	是	是	是	是	是	否
RunloopSandboxClient	是	是	是	是	是	否
VercelSandboxClient	否	否	否	否	否	否

暴露端口

在后端支持时，沙盒客户端可以通过 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],
});

能力支持矩阵

能力	Unix-local	Docker
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 支持、快照行为和清理行为。