Claude 代理服务器：使用 Bun E2B 为 Claude 构建 WebSocket 包装器

如果你一直在寻找一种干净、经过实战验证、通过 WebSocket 接口公开 Claude Agent SDK 的方法，claude‑agent‑server 仓库正是你所需要的。该仓库汇集了三大领域的最佳功能：

1. Claude Agent SDK – 与 Claude 模型交互的强大 API。
2. Bun – 一种将 JavaScript 编译为机器码以实现极速性能的运行时。
3. E2B sandbox – 供按需启动的安全隔离环境。

本文将指导你安装代码、构建 E2B sandbox、连接客户端并调整服务器设置。到最后，你将拥有一个可在任何需要的地方运行的完整 ChatGPT 风格助手。

1. 仓库做了什么？

claude‑agent‑server 仓库是一个 monorepo，包含两个主要子包：

主要功能：

• E2B 部署 – build:e2b 脚本将仓库打包为可重用的 sandbox 模板。
• 单一 WebSocket – 同一时间只能有一个客户端连接，简化并发处理。
• 自定义工具 – 可在建立连接前通过 /config 选择允许的工具、系统提示和模型。
• 本地测试客户端 – 运行 bun run test:local 在 localhost:3000 上运行打包示例。
• 可扩展 – 编辑 packages/server/index.ts 或 message-handler.ts 以更改代理行为或添加新命令。

2. 先决条件

如果你是 Bun 新手，请按以下方式安装：

curl fnm.vercel.app | bash -s -- -b "$HOME/.bun"
source "$HOME/.bun/completion.bash"

3. 克隆仓库并安装依赖

git clone https://github.com/dzhng/claude-agent-server.git
cd claude-agent-server
bun install

仓库配备了 .env.example 文件，其中定义了所需的密钥：

cp .env.example .env

编辑文件以指向你的 API 密钥：

ANTHROPIC_API_KEY=sk-ant-·····
E2B_API_KEY=e2b_your-key-here

小贴士： 保持密钥机密；不要提交真实的 .env 文件。

4. 构建 E2B Sandbox 模板

E2B 提供按需、隔离的 sandbox。服务器被打包为可立即部署的模板 claude‑agent‑server。

bun run build:e2b

幕后到底发生了什么？

1. 创建一个基本 Bun‑1.3 镜像。
2. 将仓库克隆到 sandbox。
3. bun install 安装所有运行时依赖项。
4. 服务器在 3000 端口自动启动。
5. 生成的模板已发布到你的 E2B 工作区。

构建完成后，你将看到一个名为 claude‑agent‑server 的 E2B 模板 列表条目。现在它可以在你需要时随时启动新的 sandbox。

5. 使用客户端库

@dzhng/claude‑agent 包是一个薄包装器，用于处理 sandbox 创建、WebSocket 连接和消息处理。请在你的项目中安装它：

# In your own project directory
npm i @dzhng/claude-agent
# or, with Bun
bun add @dzhng/claude-agent

5.1. 快速入门示例

import { ClaudeAgentClient } from '@dzhng/claude-agent';

const client = new ClaudeAgentClient({
  e2bApiKey: process.env.E2B_API_KEY!,
  anthropicApiKey: process.env.ANTHROPIC_API_KEY!,
  template: 'claude-agent-server', // Use the E2B template name
  debug: true,
});

await client.start();

client.onMessage((msg) => {
  if (msg.type === 'sdk_message') {
    console.log('Claude:', msg.data);
  }
});

await client.send({
  type: 'user_message',
  data: {
    type: 'user',
    session_id: 'my-session',
    message: {
      role: 'user',
      content: 'Hello, Claude!',
    },
  },
});

// When you’re done:
await client.stop();

Sandbox 生命周期： 客户端创建一个新的 sandbox，直至调用 stop() 之前保持开启，然后自动拆除，释放资源。

5.2. 连接到本地服务器

在开发过程中，你可能想测试本地服务器。相同的客户端支持 connectionUrl：

const client = new ClaudeAgentClient({
  connectionUrl: 'http://localhost:3000',
  anthropicApiKey: process.env.ANTHROPIC_API_KEY!,
});

现在你可以使用 bun run start:server 启动本地 Bun 服务器，并在控制台查看实时输出。

6. 自定义服务器

服务器被故意设计为轻量级，方便你轻松扩展。

6.1. 编辑核心

主入口点：packages/server/index.ts。它设置 HTTP 与 WebSocket 路由，处理配置，并将传入消息转发给 Claude SDK。

6.2. 修改消息处理

packages/server/message-handler.ts 包含将 SDK 响应转换为 JSON 消息的逻辑。根据需要添加或更改处理器。

6.3. 添加新工具

/config 调用中的 allowedTools 数组限制代理可使用的工具（例如 read_file、write_file）。你可以添加自定义工具定义，并通过 SDK 暴露它们。

7. 本地测试

运行本地实例并使用捆绑的客户端进行测试：

# In the repo root
bun run start:server   # Start on http://localhost:3000

打开另一个终端并调用测试客户端：

bun run test:local

该客户端连接到 localhost:3000，发送若干测试消息，并打印 SDK 响应。在重新构建 E2B 镜像前验证更改的绝佳方式。

8. 构建自定义 E2B 模板名称

默认模板名称为 claude-agent-server，但你可以通过客户端构造函数或编辑构建脚本来更改：

const client = new ClaudeAgentClient({
  template: 'my-custom-claude-template',
  ...
});

or modify packages/e2b-build/build.prod.ts 中的 Template() 实例化。

9. 安全与清理

• Sandbox 仅在客户端连接开启时存活。当调用 stop() 时，E2B 会自动终止 sandbox。
• API 密钥可以通过环境变量或 /config 端点传递。SDK 会尊重你提供的密钥 —— 它 不会 泄露密钥给客户端。
• 服务器一次只允许一个 WebSocket 连接，防止意外过载。

10. 总结与后续步骤

你现在拥有一个可重用的 Claude Agent WebSocket 包装器，可在受限、隔离的环境中部署，并可轻松集成到任何 TypeScript 或 JavaScript 应用中。

• 部署机器人 – 在 Telegram、Discord 或 Slack 机器人中使用客户端库。
• 创建自定义代理 – 扩展服务器以添加领域特定工具。
• 发布起始套件 – 与他人分享你的 sandbox 模板。

欲了解更多信息，请始终参阅完整文档 README 以及仓库中的内联代码注释。祝编码愉快！