openclaw-channel-rabbitmq-connections

OpenClaw 通道：网关从 RabbitMQ 指定队列 消费消息交给 Agent；Agent 回复 publish 到你配置的 replyExchange + replyRoutingKey。每条出站 JSON 内会带上 exchange / routingKey 字段，便于下游按 topic 路由识别。

固定行为（不可在网关配置）：prefetch = 1、非 JSON body 视为纯文本、发布持久化消息、不在插件内 assertExchange。

与 rabbitmq-forward-control（HTTP 入站）联用

业务侧若没有直连 AMQP，只有 HTTP，可部署 rabbitmq-forward-control：它提供 POST /api/ingest，将 body 发布到你配置的 exchange，请求里的 topic 即 AMQP routing key（topic 交换机下为路由键）。插件只消费 queue，不声明入站 exchange，因此你需要在 RabbitMQ 上：

1. 使用与 forward-control 相同的 exchange 名与类型（通常为 topic）。
2. 创建与 channels.rabbitmq-connections.queue 一致的队列，并把该队列 绑定到上述 exchange，binding key 能覆盖 HTTP 侧传入的 topic（例如 ingress.openclaw.#）。

HTTP 请求的 body 应为本 README 下文 「入站消息体」 中的 JSON（或纯文本）。出站仍由网关发到 replyExchange / replyRoutingKey；若要把 Agent 回复再转钉钉，可在 Broker 上为出站 exchange 增加绑定队列，并在 forward-control 里配置 forwarder 消费该队列。

逐步配置、Mermaid 拓扑、curl 示例与自检表（单文档）：同仓库包 rabbitmq-forward-control 内 docs/openclaw-integration.md；已安装 npm 包时见 node_modules/rabbitmq-forward-control/docs/openclaw-integration.md。

安装与重启

OpenClaw 会在加载配置时校验 channels.*：若网关尚未注册 rabbitmq-connections 通道，提前写好 channels.rabbitmq-connections 会报 unknown channel id，plugins install 也会失败（配置先被判定非法）。

推荐顺序：

1. 编辑 ~/.openclaw/openclaw.json（Raw JSON）：
   • 暂时删掉 整块 channels.rabbitmq-connections（装完插件再加回）。
   • 若日志提示 stale，删掉 plugins.entries.rabbitmq-connections 以及 plugins.allow 里针对 rabbitmq-connections 的项（旧安装残留；只保留 openclaw plugins install 这一种方式即可）。
2. 执行安装（任选其一）：

openclaw plugins install openclaw-channel-rabbitmq-connections
# 已装过则：
openclaw plugins update rabbitmq-connections

3. 再把 channels.rabbitmq-connections 按下文示例合并进配置，保存。
4. 重启网关：

openclaw gateway restart

可选：执行 openclaw doctor --fix 自动清理部分无效插件配置（以 CLI 提示为准）。

故障排除（amqplib / duplicate plugin）

1. 报错路径里是 .openclaw-install-stage-…

若日志为：

Cannot find package 'amqplib' imported from .../.openclaw/extensions/.openclaw-install-stage-XXXX/dist/src/publisher.js

说明网关仍在加载历史暂存目录里的旧代码（当时尚未 esbuild 打包），与当前 rabbitmq-connections 正式目录无关。

处理（在网关机器上）：

1. 先停网关（避免占用目录）。
2. 删掉所有安装暂存目录（名随机，统一按前缀删）：

rm -rf ~/.openclaw/extensions/.openclaw-install-stage-*

3. 可选：做一次干净重装插件目录后再更新：

rm -rf ~/.openclaw/extensions/rabbitmq-connections
openclaw plugins install openclaw-channel-rabbitmq-connections
# 或
openclaw plugins update rabbitmq-connections

4. 再启动网关。

2. duplicate plugin id（rabbitmq-connections）

表示同一插件 ID 被加载了多次，常见组合：

• 配置里 plugins.entries.rabbitmq-connections 与 openclaw plugins install 装的扩展同时存在；
• 再加上未删除的 .openclaw-install-stage-*，警告里会出现多条路径。

处理：只保留一种接入方式——例如只用官方 install/update 时，从 Raw JSON 里去掉重复的 plugins.entries.rabbitmq-connections 块（或改为与文档一致、不重复注册）；并执行上一节的 rm -rf .../.openclaw-install-stage-*。

3. 自检正式目录里的 publisher.js

0.1.3+ 正确产物应 约 260KB+ 且不应再 import npm 包 amqplib：

wc -c ~/.openclaw/extensions/rabbitmq-connections/dist/src/publisher.js
# 应远大于 100000；若只有几 KB，说明该目录仍是旧包，需重装

4. unknown channel id: rabbitmq-connections / Config invalid

含义：当前 openclaw.json 里已有 channels.rabbitmq-connections，但网关还没有加载注册该 ID 的插件（或插件未成功启用）。

**处理：**按上文 「安装与重启」 的顺序操作——先去掉 channels.rabbitmq-connections，装好插件后再把通道配置加回去。同时删掉 plugins.entries / plugins.allow 里已失效的 rabbitmq-connections 项（见安装步骤第 1 步）。

5. Socket closed abruptly during opening handshake

几乎总是 url 端口写错：15672 是管理界面的 HTTP 端口，不能用于 amqp://。AMQP 默认端口是 5672（TLS 常见 5671）。把 url 里的端口改为 Broker 的 AMQP 监听端口 即可。另需确认防火墙/安全组放行该端口，且用户名、密码、vhost（路径里 / 之后）与 RabbitMQ 一致。

6. 队列不存在导致网关崩溃（NOT_FOUND - no queue）

0.1.5 起：已为 AMQP connection / channel 注册 error 监听，并对 consume 启动失败 做捕获；队列未声明时只会打日志并退避重连，不应再拖垮整个 OpenClaw 进程。请在 Broker 上先创建 queue 配置中的队列（或绑定到交换机），插件连上后即可正常消费。

网关配置（仅必要项）

在 Raw JSON 中合并 channels.rabbitmq-connections：

{
  "channels": {
    "rabbitmq-connections": {
      "url": "amqp://guest:[email protected]:5672/",
      "queue": "openclaw.inbound",
      "replyExchange": "openclaw.topic",
      "replyRoutingKey": "agent.reply"
    }
  }
}

| 字段 | 必填 | 说明 | |------|------|------| | url | 与 host 二选一 | amqp:// 须用 AMQP 端口（默认 5672），不要用管理页端口 15672；也可用 host / port / … 拼装 | | queue | 是 | 网关 consume 的队列名 | | replyRoutingKey | 是 | 出站 routing key（topic 场景即路由键）；写入每条回复 JSON | | replyExchange | 否 | 出站 exchange；省略或 "" 为 默认 exchange |

多账号时可用 accounts.<id> 覆盖上述字段（与通道级合并：各账号字段单独覆盖）。

入站如何投递（插件不配置入站 topic）

插件只订阅配置里的 queue，不声明队列、不配置「入站用哪个 routing key」。

你需要在 RabbitMQ 管理端或运维脚本 完成：

1. 创建（或使用已有）交换机，例如 topic：events.topic。
2. 创建队列 openclaw.inbound（与配置 queue 一致）。
3. 绑定：events.topic → 队列 openclaw.inbound，binding key 按你的业务设定（如 ingress.user.#）。
4. 业务侧 publish 到 events.topic，routing key 命中上述 pattern，消息即进入 openclaw.inbound，网关即可消费。

消息 body 仍用下方 JSON（或纯文本）；AMQP 的 routing key 仅用于 RabbitMQ 路由进队，不必在 JSON 里重复配置。

入站消息体

JSON（推荐）

{
  "schemaVersion": 1,
  "event": "message.received",
  "text": "用户问题全文",
  "conversationId": "可选；不传则用 队列名:messageId 等生成",
  "groupName": "可选，Claw 展示名",
  "metadata": { "可选": "随每条 agent 回复 JSON 原样带回" }
}

纯文本

整条 body UTF-8 作为 text，conversationId 自动生成。

出站（Agent 回复）JSON

每条发布载荷包含 实际投递目标，供下游订阅同一 topic 或做过滤：

{
  "schemaVersion": 1,
  "event": "message.reply",
  "peerId": "16 位十六进制",
  "conversationId": "会话键",
  "text": "Agent 的一段回复",
  "timestamp": "ISO-8601",
  "exchange": "与配置 replyExchange 一致（默认 exchange 时可能为空字符串）",
  "routingKey": "与配置 replyRoutingKey 一致",
  "metadata": {}
}

下游可绑定 replyExchange（若为非空）并订阅 routingKey（或与 pattern 匹配）。

会话与控制台出站

• peerId 由 conversationId 哈希得到；出站目标仅来自配置 replyExchange / replyRoutingKey（入站 JSON 不支持覆盖 topic）。
• 仅重启网关后要从控制台续聊旧会话，需先再收到一条该会话的入站以刷新 peer 缓存。

源码与发布

目录：packages/openclaw-channel-rabbitmq-connections。发布前：npm install && npm run build，再 npm publish --access public。发布时会 esbuild 将 amqplib 打进 dist/src/publisher.js，并在 tarball 里 bundleDependencies 附带 node_modules/amqplib（双保险，避免 OpenClaw 安装阶段未装依赖时报错）。prepublishOnly 含校验，未打包成功会无法发布。