Bus Claw

Name: Bus Claw
Rating: 3.5 (1 reviews)
Author: qqxucn

By qqxucn 👁 14 views ▲ 0 votes

Agent Bus channel plugin for OpenClaw — 让AI Agent通过私有消息总线收发消息

GitHub

Configuration Example

{
  "channels": {
    "bus-claw": {
      "agentId": "小绿",
      "busUrl": "http://你的总线地址:4322",
      "busWsUrl": "ws://你的总线地址:4322/ws",
      "busToken": "你的总线认证令牌",
      "dmPolicy": "open"
    }
  }
}

README

# bus-claw — 私有 Agent 消息总线 OpenClaw 渠道插件

让 OpenClaw 通过私有消息总线（Agent Bus）收发消息的渠道插件。

基于飞书渠道插件（`@larksuite/openclaw-lark`）的入站消息管道架构改造而来，将飞书 API 替换为 Agent Bus 总线 API。

## 架构

```
消息总线 WebSocket
        │
        ▼
  monitor.js ───── BusClient 轮询/监听
        │
        ▼
  event-handlers.js  ── 总线消息 → MessageContext 转换
        │
        ▼
  handler.js ───────── 入站处理管道
        ├─ 账户解析 (accounts.js)
        ├─ 事件解析 (parse.js)
        ├─ 发送者信息补全 (enrich.js)
        ├─ 策略门禁 (gate.js)
        ├─ 内容解++析 (media/quote)
        └─ 权限检查
               │
               ▼
  dispatch.js ──────── Agent 调度
        ├─ 系统命令 /new /reset /stop
        ├─ 私聊消息
        └─ 群消息（含上下文历史）
               │
               ▼
  send.js ──────────── 回复通过总线发回
```

## 快速开始

### 1. 安装

将 `bus-claw` 目录放入 OpenClaw 的插件目录：

```bash
# 以 OpenClaw 容器为例
docker cp bus-claw openclaw-gateway-1:/root/.openclaw/extensions/claw-bus/
docker exec openclaw-gateway-1 bash -c "cd /root/.openclaw/extensions/claw-bus && npm install"
docker restart openclaw-gateway-1
```

> 注：目录名为 `claw-bus`（历史原因），插件 ID 为 `bus-claw`。

### 2. 配置

在 `openclaw.json` 的 `channels` 段添加：

```json
{
  "channels": {
    "bus-claw": {
      "agentId": "小绿",
      "busUrl": "http://你的总线地址:4322",
      "busWsUrl": "ws://你的总线地址:4322/ws",
      "busToken": "你的总线认证令牌",
      "dmPolicy": "open"
    }
  }
}
```

| 字段 | 必填 | 说明 |
|------|------|------|
| `busUrl` | ✅ | 总线 HTTP API 地址 |
| `busWsUrl` | ✅ | 总线 WebSocket 地址（WS 长连接） |
| `busToken` | ✅ | 总线认证 Token |
| `agentId` | ❌ | 本 Agent 在总线上的身份标识（默认 `my-agent`） |
| `dmPolicy` | ❌ | 私聊策略：`open`/`allowlist`/`pairing`/`disabled`（默认 `open`） |

### 3. 验证

查看 OpenClaw 日志应看到：

```
[bus-claw] register called
[bus-claw] runtime set
[bus-claw] channel registered
[bus-claw] starting bus-claw[default]
[channel/monitor] bus connection status: connected
[channel/monitor] bus-claw monitor started
```

## 设计要点

### 插件格式

使用 OpenClaw SDK 旧格式（与飞书插件一致），通过 `register(api)` 注入 runtime：

```js
const plugin = {
    id: 'bus-claw',
    register(api) {
        BusClient.setRuntime(api.runtime);
        api.registerChannel({ plugin: busClawPlugin });
    },
};
```

> ⚠️ 不支持 `defineChannelPluginEntry` + `registerFull` 格式——部分 OpenClaw 版本不兼容。

### 与飞书插件的主要差异

| 特性 | 飞书插件 | bus-claw |
|------|---------|----------|
| 消息来源 | 飞书 Event Callback | 消息总线 WebSocket |
| 消息格式 | Lark Message | Bus Message |
| 回复方式 | 飞书 API sendMessage | 总线 API POST /api/messages |
| 文件/图片 | 飞书云存储 | 暂不支持（纯文本） |
| 流式回复 | CardKit 流式卡片 | 完整回复一次性发送 |
| 群聊 | 支持 | 基础支持（不含@检测等飞书特性） |
| 账户配置 | 多账户 | 单账户 |

### 消息格式约定

总线消息字段映射：

```
from_agent     → chatId / senderId
message_id     → 消息 ID
content        → 消息文本内容
type           → content_type ('text' 默认)
ref_id         → parentId（引用消息 ID）
session_id     → threadId（会话 ID）
```

## 注意事项

1. **只支持 WS 模式**：通过 WebSocket 长连接接收消息
2. **纯文本回复**：目前只支持 text 类型回复
3. **回复引用**：回复时设置 `replyToMessageId` 可实现引用回复
4. **心跳保活**：总线默认 30s 心跳，插件会自动重连

channels