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 的插件目录：

# 以 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 段添加：

{
  "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：

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 心跳，插件会自动重连