Claude Agent SDK WebSocket 服务器

一个封装了 Claude Agent SDK 的 WebSocket 服务器，允许通过 WebSocket 与 Claude 进行实时双向通信。您可以将其部署为 E2B 沙盒，并使用 TypeScript 客户端库进行连接。

发布推文 / 讨论

概述

典型工作流程：

1. 构建您的 E2B 镜像 - 使用 bun run build:e2b 将服务器部署为 E2B 沙盒模板。
2. 使用客户端库 - 在您的项目中安装 @dzhng/claude-agent，并连接到您的 E2B 沙盒。
3. 修改服务器（可选） - 如果需要自定义行为，请编辑 packages/server/ 中的服务器代码。
4. 本地测试 - 使用 bun run start:server 和 bun run test:local 测试您的更改，然后再重新构建。

快速入门

1. 设置环境

在根目录下创建一个 .env 文件：

cp .env.example .env

添加您的 API 密钥：

ANTHROPIC_API_KEY=sk-ant-your-api-key-here
E2B_API_KEY=e2b_your-api-key-here

安装依赖项：

bun install

2. 构建您的 E2B 镜像

将服务器构建并部署为 E2B 模板：

bun run build:e2b

这会在 E2B 上创建一个名为 claude-agent-server 的沙盒模板。构建过程如下：

• 基于 Bun 1.3 创建一个沙盒。
• 安装 Git 并克隆此仓库。
• 安装依赖项。
• 配置服务器在端口 3000 上自动启动。

构建可能需要几分钟时间。完成后，您的模板即可使用。

3. 使用客户端库

在您的项目中安装客户端库：

npm install @dzhng/claude-agent
# 或者
bun add @dzhng/claude-agent

连接到您的 E2B 沙盒：

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', // 您的 E2B 模板名称
  debug: true,
})

// 启动客户端（创建 E2B 沙盒并连接）
await client.start()

// 监听来自 Claude 的消息
client.onMessage(message => {
  if (message.type === 'sdk_message') {
    console.log('Claude:', message.data)
  }
})

// 向 Claude 发送消息
client.send({
  type: 'user_message',
  data: {
    type: 'user',
    session_id: 'my-session',
    message: {
      role: 'user',
      content: '你好，Claude！',
    },
  },
})

// 完成后清理
await client.stop()

就是这样！客户端库负责：

• 创建和管理 E2B 沙盒。
• WebSocket 连接。
• 消息序列化。
• 清理和资源管理。

修改服务器

如果您想自定义服务器行为：

1. 编辑服务器代码

服务器代码位于 packages/server/ 中：

• index.ts - 主服务器和 WebSocket 处理。
• message-handler.ts - 消息处理逻辑。
• const.ts - 配置常量。

2. 本地测试

在本地启动服务器：

bun run start:server

在另一个终端中，运行针对本地主机的测试客户端：

bun run test:local

这会运行 packages/client/example-client.ts，连接到 localhost:3000 而不是 E2B。

3. 重新构建 E2B 镜像

当您对更改满意后，重新构建 E2B 模板：

bun run build:e2b

您更新后的服务器将被部署到 E2B，使用相同的模板名称。

可用脚本

bun run build:e2b

将服务器构建并部署为 E2B 模板。这是将服务器部署到云端的主要方式。

bun run test:client

运行示例客户端（packages/client/example-client.ts），连接到 E2B 沙盒。需要在 .env 文件中同时设置 E2B_API_KEY 和 ANTHROPIC_API_KEY。

bun run start:server

在本地 http://localhost:3000 上启动服务器。用于本地开发和测试。

bun run test:local

运行连接到 localhost:3000 的示例客户端。在重新构建 E2B 镜像之前，可用于测试本地服务器的更改。

客户端库 API

安装

npm install @dzhng/claude-agent
# 或者
bun add @dzhng/claude-agent

构造函数选项

interface ClientOptions {
  // 必需（除非使用环境变量）
  anthropicApiKey?: string

  // E2B 配置（如果使用 connectionUrl 则可选）
  e2bApiKey?: string
  template?: string // E2B 模板名称，默认为 'claude-agent-server'
  timeoutMs?: number // 沙盒超时时间，默认为 5 分钟

  // 连接配置
  connectionUrl?: string // 使用此选项连接到本地或自定义服务器，而不是 E2B

  // 其他选项
  debug?: boolean // 启用调试日志

  // 查询配置（传递给服务器）
  agents?: Record<string, AgentDefinition>
  allowedTools?: string[]
  systemPrompt?:
    | string
    | { type: 'preset'; preset: 'claude_code'; append?: string }
  model?: string
}

方法

• async start() - 初始化客户端并连接到服务器。
• send(message: WSInputMessage) - 向代理发送消息。
• onMessage(handler: (message: WSOutputMessage) => void) - 注册消息处理器（返回取消注册函数）。
• async stop() - 断开连接并清理资源。

示例：连接到 E2B

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',
  debug: true,
})

await client.start()

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

client.send({
  type: 'user_message',
  data: {
    type: 'user',
    session_id: 'session-1',
    message: { role: 'user', content: '你好' },
  },
})

await client.stop()

示例：连接到本地服务器

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

await client.start()

更多详细信息，请参阅 packages/client/README.md。

服务器 API 参考

注意： 如果您正在使用 @dzhng/claude-agent 库，则无需直接与这些端点交互。客户端会为您处理配置和 WebSocket 连接。本节适用于希望直接连接到服务器或构建自己的客户端的高级用户。

服务器运行在 http://localhost:3000（或您的 E2B 沙盒 URL）上，提供以下服务：

• 配置端点：http://localhost:3000/config
• WebSocket 端点：ws://localhost:3000/ws

配置 API

POST /config

设置 Claude Agent SDK 查询的配置：

type QueryConfig = {
  agents?: Record<string, AgentDefinition>
  allowedTools?: string[]
  systemPrompt?:
    | string
    | {
        type: 'preset'
        preset: 'claude_code'
        append?: string
      }
  model?: string
  anthropicApiKey?: string
}

示例：

curl -X POST http://localhost:3000/config \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "You are a helpful assistant.",
    "allowedTools": ["read_file", "write_file"],
    "anthropicApiKey": "sk-ant-...",
    "model": "claude-3-5-sonnet-20241022",
    "agents": {
      "myAgent": {
        "name": "My Custom Agent",
        "description": "A custom agent"
      }
    }
  }'

响应：

{
  "success": true,
  "config": {
    "systemPrompt": "You are a helpful assistant.",
    "allowedTools": ["read_file", "write_file"],
    "agents": { ... }
  }
}

GET /config

获取当前配置：

curl http://localhost:3000/config

响应：

{
  "config": {
    "systemPrompt": "You are a helpful assistant.",
    "allowedTools": ["read_file", "write_file"]
  }
}

WebSocket API

连接

连接到 WebSocket 端点：

const ws = new WebSocket('ws://localhost:3000/ws')

注意： 服务器一次只接受 一个活动连接。如果已有其他客户端连接，新的连接尝试将被拒绝，并返回错误消息。

消息格式

发送消息（客户端 → 服务器）

type WSInputMessage =
  | {
      type: 'user_message'
      data: SDKUserMessage
    }
  | {
      type: 'interrupt'
    }

用户消息：

发送封装的 SDKUserMessage：

{
  "type": "user_message",
  "data": {
    "type": "user",
    "session_id": "your-session-id",
    "parent_tool_use_id": null,
    "message": {
      "role": "user",
      "content": "Hello, Claude!"
    }
  }
}

结构：

• type：必须为 "user_message"
• data：包含以下内容的 SDKUserMessage 对象：
  • type：必须为 "user"
  • session_id：您的会话标识符（字符串）
  • message：包含 role 和 content 的对象
    • role：必须为 "user"
    • content：消息内容（字符串）
  • parent_tool_use_id：可选，用于工具使用响应
  • uuid：可选，消息 UUID（未提供时自动生成）

中断消息：

发送中断以停止当前代理操作：

{
  "type": "interrupt"
}

接收消息（服务器 → 客户端）

type WSOutputMessage =
  | { type: 'connected' }
  | { type: 'sdk_message'; data: unknown }
  | { type: 'error'; error: string }

连接确认：

{
  "type": "connected"
}

SDK 消息（来自 Claude 的响应）：

{
  "type": "sdk_message",
  "data": {
    "type": "assistant",
    "session_id": "...",
    "message": {
      /* Claude 的响应 */
    }
  }
}

错误消息：

{
  "type": "error",
  "error": "Error description"
}

架构

服务器是一个简单的 1对1 中继，用于在单个 WebSocket 客户端和 Claude Agent SDK 之间进行通信：

1. 配置（可选）：客户端可以通过 POST 到 /config 来设置代理、允许的工具和系统提示。
2. 客户端连接：建立 WebSocket 连接（一次仅允许一个连接）。
3. 客户端发送消息：客户端发送用户消息（或中断消息）。
4. 消息排队：服务器将消息加入队列，并使用 SDK 处理它们。
5. SDK 处理：SDK 查询流使用配置选项处理消息。
6. 响应中继：SDK 响应会立即发送回已连接的 WebSocket 客户端。
7. 清理：当客户端断开连接时，服务器将准备好接受新的连接。

关键设计原则：

• 连接前配置：在连接之前，通过 /config 端点配置查询选项。
• 惰性初始化：只有在建立第一个 WebSocket 连接时，查询流才会启动。
• 单连接限制：服务器会在已有连接时拒绝其他连接尝试。
• 简单中继：服务器在 WebSocket 和 SDK 之间中继消息，不进行会话管理。
• 消息队列：传入的消息会被排队，并由 SDK 流处理。
• 中断支持：客户端可以发送中断消息来停止正在进行的操作。
• 直接路由：所有 SDK 响应都会发送到唯一的活动 WebSocket 客户端。

项目结构

代码库采用 monorepo 结构：

claude-agent-server/
├── packages/
│   ├── server/           # 主服务器实现
│   │   ├── index.ts
│   │   ├── message-handler.ts
│   │   └── ...
│   ├── client/           # 客户端库及示例
│   │   ├── src/
│   │   └── example-client.ts
│   └── e2b-build/        # E2B 构建脚本
│       └── build.prod.ts
├── package.json          # 根 package.json（工作区）
└── README.md

测试

Web 测试客户端

在浏览器中打开 http://localhost:3000/ 即可访问内置测试客户端。您可以：

• 向 Claude 发送消息
• 查看实时响应
• 查看 SDK 消息的完整 JSON 结构

命令行测试客户端

运行示例客户端脚本：

bun run test:client

这将连接到服务器（或 E2B 沙盒），发送几条测试消息，并显示响应。

E2B 部署细节

本节提供了有关 E2B 部署的更多详细信息。有关基本设置，请参阅 快速入门 部分。

自定义模板名称

默认情况下，bun run build:e2b 会创建一个名为 claude-agent-server 的模板。要使用其他名称，您可以修改 packages/e2b-build/build.prod.ts 文件，或者在使用客户端时指定：

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

const client = new ClaudeAgentClient({
  template: 'my-custom-template', // 使用您自定义的模板名称
  e2bApiKey: process.env.E2B_API_KEY,
  anthropicApiKey: process.env.ANTHROPIC_API_KEY,
})

await client.start()

E2B 沙盒的工作原理

当您使用带有 E2B 的客户端库时：

1. 沙盒创建：根据您构建的模板（默认为 claude-agent-server）创建一个新的沙盒。
2. 自动启动：服务器会在沙盒内的 3000 端口上自动启动（通过 build.prod.ts 中的 setStartCmd 配置）。
3. 安全端点：E2B 为您的沙盒提供 HTTPS 和 WSS 端点。
4. 隔离：每个沙盒都在完全隔离的状态下运行，拥有独立的文件系统和资源。
5. 自动清理：当客户端断开连接时，沙盒会被终止。

要使用 E2B 进行测试，只需运行：

bun run test:client

这将运行 packages/client/example-client.ts，该脚本会创建一个 E2B 沙盒，连接到它，执行测试命令，并进行清理。

E2B 模板配置

模板在 packages/e2b-build/build.prod.ts 中定义：

const template = Template()
  .fromBunImage('1.3')                    // 使用 Bun 1.3 基础镜像
  .runCmd('sudo apt install -y git')      // 安装 git
  .gitClone('https://github.com/...', ...) // 克隆仓库
  .setWorkdir('/home/user/app')           // 设置工作目录
  .runCmd('bun install')                  // 安装依赖
  .setStartCmd('bun packages/server/index.ts', waitForPort(3000)) // 启动服务器

您可以自定义此模板以：

• 安装额外的系统软件包
• 预先配置环境变量
• 更改资源限制（CPU、内存）
• 修改启动命令

E2B 与本地开发

本地开发（localhost）：

• 迭代更快
• 可直接访问本地文件系统
• 无沙箱开销
• 适合开发和测试

E2B 部署：

• 隔离的执行环境
• 安全的云沙箱
• 可扩展的基础设施
• 生产就绪
• 无需本地设置

配置

服务器默认使用 3000 端口。您可以在 packages/server/index.ts 中修改：

const server = Bun.serve<SessionData>({
  port: 3000, // 可更改此值
  // ...
})

环境变量

环境变量从根目录下的 .env 文件加载。请参阅快速入门了解设置说明。

API 密钥优先级：

• 如果您通过配置 API（/config 端点）设置了 anthropicApiKey，它将覆盖 ANTHROPIC_API_KEY 环境变量。
• 使用客户端库时，您可以在构造函数选项中传递 anthropicApiKey。

许可证

MIT

Claude Agent Server 快速上手指南

claude-agent-server 是一个基于 WebSocket 的服务端工具，它封装了 Claude Agent SDK，允许通过 WebSocket 与 Claude 进行实时双向通信。该工具通常部署在 E2B 沙箱环境中，并通过 TypeScript 客户端库进行连接。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (推荐 WSL2)
• 运行时: Bun (版本 1.3 或更高，服务器镜像基于 Bun 1.3 构建)
• API 密钥:
  • Anthropic API Key (用于调用 Claude 模型)
  • E2B API Key (用于部署和管理云端沙箱)

安装步骤

1. 克隆项目并安装依赖

首先获取源代码并安装必要的依赖包：

git clone <repository-url>
cd claude-agent-server
bun install

2. 配置环境变量

在项目根目录创建 .env 文件并填入你的 API 密钥：

cp .env.example .env

编辑 .env 文件，内容如下：

ANTHROPIC_API_KEY=sk-ant-your-api-key-here
E2B_API_KEY=e2b_your-api-key-here

3. 构建并部署 E2B 镜像

执行以下命令将服务器构建为 E2B 沙箱模板。此过程会自动创建一个基于 Bun 1.3 的沙箱，安装 git，克隆仓库并配置服务在 3000 端口自动启动。

bun run build:e2b

注意：构建过程可能需要几分钟。完成后，名为 claude-agent-server 的模板即可在 E2B 上使用。

基本使用

1. 在项目中安装客户端库

在你的业务项目中安装官方提供的客户端库：

npm install @dzhng/claude-agent
# 或者使用 bun
bun add @dzhng/claude-agent

2. 连接并交互

创建一个 TypeScript 文件（例如 index.ts），使用以下代码连接到你刚刚部署的 E2B 沙箱并与 Claude 对话：

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', // 对应构建时生成的模板名称
  debug: true,
})

// 启动客户端（创建沙箱并建立 WebSocket 连接）
await client.start()

// 监听来自 Claude 的消息
client.onMessage(message => {
  if (message.type === 'sdk_message') {
    console.log('Claude:', message.data)
  }
})

// 发送消息给 Claude
client.send({
  type: 'user_message',
  data: {
    type: 'user',
    session_id: 'my-session',
    message: {
      role: 'user',
      content: 'Hello, Claude!',
    },
  },
})

// 任务完成后清理资源
await client.stop()

3. 本地开发测试（可选）

如果你修改了服务端代码 (packages/server/)，可以在重新部署到 E2B 之前在本地进行测试：

1. 启动本地服务器：

   bun run start:server
   

2. 在另一个终端运行本地测试客户端：

   bun run test:local
   

确认无误后，再次运行 bun run build:e2b 更新云端模板。