openclaw-channel-redis-connections

OpenClaw 通道：入站 = 对 Redis List 做 BRPOP（业务侧 LPUSH）；出站 = 对 List 做 LPUSH（固定 List 模式，无 Pub/Sub）。出站 JSON 里 exchange 为空、routingKey 为出站 List key。

权限： 不做 dm / groupPolicy / groupAllowFrom / accounts 等配置，入站一律按全开处理（不在本插件内做白名单校验）。不支持 outboundMode、accounts.<id> 等扩展项（配置里若残留旧字段会被忽略）。

一、网关配置 channels.redis-connections

可写在 channels.redis-connections，或 plugins.entries.redis-connections.config（同名字段以 channels 为准）。仅下列字段会生效；plugins.entries.redis-connections.config 支持扁平或与 UI 一致的 redis-connections 嵌套；旧版键（outboundMode、groupPolicy、dm、accounts 等）在 schema 里已声明，校验可通过，插件仍忽略。

| 字段 | 必填 | 默认 | 说明 | |------|------|------|------| | url | 是 | — | 见下表 | | inboundTopic | 否 | openclaw:inbound | 入站 List key | | outboundTopic | 否 | openclaw:reply | 出站 List key（LPUSH） |

url 写法（简写时逻辑库固定 0）：

| 形式 | 含义 | |------|------| | host:port | 无密码 → redis://host:port/0 | | host:port@password | 第一个 @ 左侧为 host:port，右侧为密码（密码里可再含 @） | | [IPv6]:port / [IPv6]:port@password | IPv6 须加方括号 | | redis:// / rediss:// 开头 | 整串原样交给客户端 |

示例：

{
  "channels": {
    "redis-connections": {
      "url": "127.0.0.1:6379"
    }
  }
}

{
  "channels": {
    "redis-connections": {
      "url": "redis.example.com:6379@your-secret",
      "inboundTopic": "myapp.questions",
      "outboundTopic": "myapp.answers"
    }
  }
}

行为摘要： BRPOP 超时 5 秒一轮以便热更新；入站元素须为合法 JSON 且含下文三字段。与 middware-forward-control 默认 List 键 openclaw:inbound / openclaw:reply 一致。

二、安装与常见问题

先 openclaw plugins install openclaw-channel-redis-connections，再按需 openclaw plugins update redis-connections，改配置后 openclaw gateway restart。包内声明 openclaw.hooks: []（无捆绑 Hook，满足 CLI 校验）。publisher.js 不内联 ioredis，由扩展目录下的 npm install 安装依赖；与 consumer 相同，均使用官方 ioredis 包，避免安装器对「单文件内 env + 网络」的误报。

duplicate plugin id + .openclaw-install-stage-*： 停网关后 rm -rf ~/.openclaw/extensions/.openclaw-install-stage-*；CLI 管理扩展时可去掉重复的 plugins.entries.redis-connections。

LPUSH 无反应： LPUSH 的 Redis / DB / key 须与网关 url、inboundTopic 一致；日志搜 [redis-connections]。

偶发收不到入站： 消费者在每个 BRPOP 超时（默认 5s）后会 PING 一次；失败则关闭连接并由外层循环重建。若仍异常，搜日志 consume_stale_after_brpop_timeout / brpop_fatal / consumer_reconnect_soon。（不使用 enableOfflineQueue: false，以免重连间隙出现 “Stream isn't writeable”。）

三、消息格式与试跑

入站（LPUSH 到 inboundTopic 的一条 List 元素）

须为合法 JSON 对象；conversationName、senderId、text 均为必填字符串，去空格后非空；多余字段忽略。

| 字段 | 说明 | |------|------| | conversationName | 会话标识 → 稳定 peerId | | senderId | 发送方业务 ID（写入上下文） | | text | 送入 Agent 的正文 |

示例（整段作为 List 里一个元素，单行字符串）：

{
  "conversationName": "support-thread-1",
  "senderId": "user-zhang",
  "text": "用户问题全文"
}

出站（网关 LPUSH 到 outboundTopic 的一条 List 元素）

单行 JSON 字符串；exchange 恒为 ""，routingKey 为当前配置的 outboundTopic（默认 openclaw:reply）。peerId 为 16 位十六进制（由 conversationName 推导）。控制台/配对辅助消息里 senderId 可能为 console / system。

| 字段 | 说明 | |------|------| | schemaVersion | 固定 1 | | event | 如 message.reply | | peerId | 内部路由短 id | | conversationName | 与入站一致 | | senderId | 与触发本轮回复的入站 senderId 一致（多段回复每段相同） | | text | 本段回复正文 | | timestamp | ISO-8601 | | exchange | "" | | routingKey | 出站 List key |

示例：

{
  "schemaVersion": 1,
  "event": "message.reply",
  "peerId": "24279d28272f936f",
  "conversationName": "support-thread-1",
  "senderId": "user-zhang",
  "text": "Agent 的一段回复",
  "timestamp": "2026-04-08T12:00:00.000Z",
  "exchange": "",
  "routingKey": "openclaw:reply"
}

redis-cli 试跑

redis-cli -u "$REDIS_URL" LPUSH "$INBOUND_KEY" '{"conversationName":"support-thread-1","senderId":"user-001","text":"你好"}'
redis-cli -u "$REDIS_URL" BRPOP "$OUTBOUND_KEY" 0

会话： 由 conversationName 隔离；出站仅由 outboundTopic 决定。网关重启后续聊需再收到同 conversationName 的入站。

四、源码与发布

cd packages/openclaw-channel-redis-connections
npm install && npm run build && npm run verify:bundle

npm publish --access public 或 ./publish.sh。