# @e2b/ai-sdk-sandbox 中文文档

规范地址：https://npmcn.com/package/%40e2b/ai-sdk-sandbox/

版本：0\.3\.0
npm 元数据更新时间：2026-08-28T13:41:04.300Z
中文译文更新时间：2026-11-13T03:13:16.138Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40e2b/ai-sdk-sandbox
原文对照：https://npmcn.com/package/%40e2b/ai-sdk-sandbox/?lang=original
项目主页：https://github.com/e2b-dev/ai-sdk-sandbox#readme
源码仓库：https://github.com/e2b-dev/ai-sdk-sandbox

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：85.6 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：3 个
- 首次发布：2026-08-19T13:41:09.651Z
- 最新版本发布：2026-08-28T13:41:03.971Z
- 近 30 天下载量：18850（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

Vercel AI SDK的 E2B 沙盒提供者

## 安装

```sh
npm install @e2b/ai-sdk-sandbox
```

也可以使用：`pnpm add @e2b/ai-sdk-sandbox`、`yarn add @e2b/ai-sdk-sandbox`、`bun add @e2b/ai-sdk-sandbox`

## README

# AI SDK - E2B 沙盒

_这个软件包是 **实验** 并瞄准AI SDK 7(现在稳定)._

内部运行您的代理密码 [E2B 软件](https://e2b.dev/) 沙盒从 [AI SDK 软件](https://ai-sdk.dev/)这是E2B对应的 [@ai-sdk/ sandbox-vercel (英语)](https://github.com/vercel/ai/tree/main/packages/sandbox-vercel)丢入一个 `HarnessAgent`,或者将一个会话直接交给您的 AI SDK 工具.

绳子本身如何运作 [AI SDK 吊带文件](https://ai-sdk.dev/v7/docs/ai-sdk-harnesses/overview)。 。 。 .

## 设置

```bash
npm i @e2b/ai-sdk-sandbox
```

设定 `E2B_API_KEY` (或通过) `apiKey` )),在设置中. 通话 `createE2BSandbox()` 无法独自到达E2B. 沙盒在您调用时创建 `createSession()`。 。 。 .

## 使用量

```ts
import { createE2BSandbox } from '@e2b/ai-sdk-sandbox';

const e2bSandbox = createE2BSandbox({ template: 'base' });

const sandboxSession = await e2bSandbox.createSession();
// restricted() returns the same sandbox narrowed to the tool-safe surface
// (file I/O, run, spawn) with no lifecycle or network controls — this is what
// you hand an AI SDK tool's execute().
const restrictedSandboxSession = sandboxSession.restricted();

await restrictedSandboxSession.writeTextFile({ path: 'hello.txt', content: 'hi' });

const { stdout } = await restrictedSandboxSession.run({ command: 'cat hello.txt' });
console.log(stdout); // "hi"

await sandboxSession.stop();
```

`restricted()` 给你一个 `Experimental_SandboxSession`页:1 **同样的暗沙盒**,缩小到工具表面(文件 I/O, `run`, (中文(简体) ), `spawn`),仅与下行位相接相接的取景`ports`, (中文(简体) ), `getPortEndpoint`, (中文(简体) ), `setNetworkPolicy`, (中文(简体) ), `stop`已删除。 这就是安全界限: 密码你手持限制视图 无法阻止盒子或改变它的网络政策。 传到AI SDK工具的 `execute()` 通过 `experimental_sandbox`整个会话都用在绳子上 (见 [调制文件](https://ai-sdk.dev/v7/docs/ai-sdk-harnesses/overview) 联 合 国 `restricted()` 合同。 )

### 设置

所有东西都用在你传递给的对象上 `createE2BSandbox(...)`数字 :

```ts
const e2bSandbox = createE2BSandbox({
  template: 'base',                                // any E2B SandboxOpts
  envs: { NODE_ENV: 'production' },
  timeoutMs: 10 * 60 * 1000,                       // optional; defaults to 30 min
  ports: [3000],                                   // provider option
  setupCommands: ['sudo npm install -g pnpm@9'],   // provider option
});
```

任何E2B级的 `[SandboxOpts](https://e2b.dev/docs)` (单位:千美元)`template`, (中文(简体) ), `envs`, (中文(简体) ), `metadata`, (中文(简体) ), `network`,等等)直接通过. 提供商又增加了两个不属于E2B的SDK的选项:

| 选项 | 默认 | 它会做什么 |
| --- | --- | --- |
| `ports` | `[]` | 张贴广告的端口 `session.ports`吊带桥连接着第一个 E2B 可以通过 `getHost`,所以这真的是 只是它广告的列表. |
| `setupCommands` | `[]` | 命令运行一次 在一个新鲜的沙盒, 在绳子靴子之前。 譬如说, `['sudo npm install -g pnpm@9']` 用于 claude-code/codex 适配器. |

有沙盒吗? 通过它作为 `sandbox` 用于重用(当您想要在会话中分享一次时会很困难)。 供应商不会碰它的生命周期,所以 `stop()` 财务报告和审定财务报表 `destroy()` 成为无私之道 清理工作仍属于你.

```ts
import { createE2BSandbox } from '@e2b/ai-sdk-sandbox';
import { Sandbox } from 'e2b';

const e2bSandbox = createE2BSandbox({
  sandbox: await Sandbox.create({ template: 'base' }),
});
```

### 中期网络政策

你可以在已经运行的沙盒上收紧或放松出入口:

```ts
await sandboxSession.setNetworkPolicy?.({
  mode: 'custom',
  allowedHosts: ['api.example.com'],
  deniedCIDRs: ['169.254.169.254/32'],
});
```

### 要求的转变和证书中介

`setRequestTransformations()` 替换管理的规则, `addRequestTransformations()` 添加时不替换。 标题在 `transform.headers` 请求后由 E2B 的 Egress 代理注入 离开沙盒,所以真正的证书 从来没有进入它—— 操纵适配器 3⁄4 ̄ ̧漯B E2B 按主机匹配规则 : (单位:千美元) `path` 匹配器在整个主机中应用,以及 `method`编号 :`queryString`编号 :`headers` 匹配者被拒绝,而不是沉默地扩大。 E2B 允许一次变换 每个主机规则,所以对同一个主机的多个转换被合并到 一条规则( 后发头优先于前发头) 。 规则匹配主机 准确性(规则 `example.com` 不涵盖 `www.example.com`)和 egress代理只转换了HTTPS请求. 网络政策依然存在 权威可以联系到哪些主机 。 见 `examples/request-transformations.ts` 现场检查.

### 运行代理( Claude Code, Codex)

```ts
const agent = new HarnessAgent({
  harness: createClaudeCode(),
  sandbox: createE2BSandbox({
    template: 'pnpm-base', // base image + pnpm + 2GB, built via build-template.ts
    ports: [4000],
  }),
});
```

关于模板的一件事是: Claude-code 适配器安装了自己的被钉住的CLI并用pnpm(它没有使用系统)在沙盒内架起桥来 `claude`) (中文(简体) ). 安装 Claude-code 的 ~ 238 MB 本地二进制, 和 pnpm 搭载它 峰值在 1. 5 GB 左右—— 所以沙盒需要 pnpm **财务报告和审定财务报表** E2B RAM 的 ~ 2 GB 。 E2B RAM 固定在模板构建时间( 你不能每个沙盒设置它) , 所以用 pnpm 烤入的 pnpm 构建 2 GB 模板 `examples/build-template.ts` 并传其名. 一个完整的,可运行的版本生活在 `examples/harness.ts`。 。 。 .

## 很高兴知道

一些E2B特定的行为值得了解:

-   `stop()` **暂停** 沙盒,你待会再拿回来 `resumeSession`。 。 。 . `destroy()` 永远杀死它.
-   继续使用沙盒元数据中的会话编号标记(E2B指定了编号,所以没有名字可以抬头),所以通过一个 `sessionId` 改为 `createSession` 如果你打算继续.
-   `run` 财务报告和审定财务报表 `spawn` 关闭 E2B 的 60 秒/ 命令超时, 这样长的构建和背景服务器不会被切断 。 整个沙盒 `timeoutMs` 仍然适用.
-   当绳子穿过时 `identity` + 键 `onFirstCreate` (例如: claude-code/codex靴子),设置运行 **一次**:它被俘虏为快照并被后会分叉从中取出,而不是重新运行. 该快照通过名称匹配 `listSnapshots`,所以即使冷开始再用它。 对于提前控制的设置,预建的模板会更轻.

## 实例

-   `examples/basic.ts`:会话表面自行(写出、运行、产卵)
-   `examples/harness.ts`: Claude 代码在 E2B 沙盒内工作
-   `examples/resume.ts`暂停一个沙盒,把它捡起来
-   `examples/build-template.ts`: 构建自定义模板( bakes pnpm in) 以通过 `template`

运行其中任何一个 `npm run example:basic` (他们读 `.env`) (中文(简体) ).

## 许可证

麻省理工学院

## 常见问题

### @e2b/ai-sdk-sandbox 是什么？

Vercel AI SDK的 E2B 沙盒提供者

### 如何安装 @e2b/ai-sdk-sandbox？

在项目目录运行 npm install @e2b/ai-sdk-sandbox，或使用 pnpm add / yarn add / bun add。

### @e2b/ai-sdk-sandbox 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @e2b/ai-sdk-sandbox 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @e2b/ai-sdk-sandbox 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @e2b/ai-sdk-sandbox 可以商用吗？

@e2b/ai-sdk-sandbox 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @e2b/ai-sdk-sandbox 的下载量有多少？

根据 npm 官方下载统计，@e2b/ai-sdk-sandbox 在 2026/10/13 – 2026/11/11 这 30 天内被下载 18,850 次，日均约 628 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @e2b/ai-sdk-sandbox 还在维护吗？

最新版本 0\.3\.0 发布于 2026/08/28（2 个月前）；至今共发布 4 个版本，其中过去 12 个月发布了 4 个；首次发布于 2026/08/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。