AstrBot Weixin OpenClaw Hub

这是一个 AstrBot 平台适配器插件，用于把多个 OpenClaw 微信连接接入 AstrBot 的多会话系统。

插件注册的平台类型是：

weixin_oc_hub

设计目标

这个插件不是“预先配置多个微信账号”的适配器。

它的目标是“连续扫码注册 OpenClaw 多会话”：

打开 Dashboard
↓
看到一个 OpenClaw 登录二维码
↓
扫码
↓
微信窗口 1 已连接
↓
二维码自动刷新
↓
再扫码
↓
微信窗口 2 已连接
↓
继续循环

每次扫码成功后，插件都会把这个 OpenClaw 连接注册成 AstrBot 的一个独立会话，然后自动生成下一个等待扫码的二维码。

配置示例

普通用户只需要添加一个平台配置：

- id: weixin_oc_hub
  type: weixin_oc_hub
  enable: true
  base_url: https://ilinkai.weixin.qq.com
  bot_type: "3"
  cdn_base_url: https://novac2c.cdn.weixin.qq.com/c2c
  qr_poll_interval: 1
  long_poll_timeout_ms: 35000
  api_timeout_ms: 15000
  auto_register: true
  auto_qr_rotate: true
  max_accounts: 10
  account_key_prefix: wx
  qr_server_enabled: false
  qr_server_host: 127.0.0.1
  qr_server_port: 6196
  qr_server_token: ""
  accounts: []

accounts 默认是空的 JSON 文本：[]。它不是给用户手动填写多个账号槽位用的，而是插件自动维护的已注册连接列表。

使用流程

1. 在 AstrBot 中启用 weixin_oc_hub 平台。
2. 在任意会话发送 /wx 获取当前登录二维码。
3. 使用微信扫码。
4. 扫码成功后，当前连接会注册为 wx_001。
5. 插件会自动创建下一个 pending 登录位，例如 wx_002。
6. 继续发送 /wx 并扫码即可继续注册新的 OpenClaw 会话。

达到 max_accounts 后，插件不会再创建新的 pending 二维码。

二维码页面

插件可以启动一个轻量 HTTP 服务展示当前 pending 二维码。出于安全考虑，Web 页面默认关闭，监听地址默认只绑定本机：

http://127.0.0.1:6196

可用配置：

qr_server_enabled: false
qr_server_host: 127.0.0.1
qr_server_port: 6196
qr_server_token: your-secret-token

设置 qr_server_token 后，访问页面或接口需要携带 token：

GET /?token=your-secret-token
Authorization: Bearer your-secret-token
X-Weixin-OC-Hub-Token: your-secret-token

接口：

GET /             二维码页面
GET /qrcode.png   当前 pending 二维码图片
GET /api/status   Hub 状态 JSON

二维码不再以 ASCII 形式刷到日志里。日志只会提示二维码页面地址，避免长时间运行时日志被刷新内容淹没。

/wx 指令

发送 /wx 会把当前 pending 登录二维码发送到当前会话。

在 QQ/OneBot 会话中，插件会直接通过 QQ 适配器发送二维码并记录返回的 message_id，20 秒后调用 delete_msg 撤回该二维码消息，同时清理本地临时图片文件。

其他平台会继续使用 AstrBot 通用图片发送结果；如果平台没有暴露可撤回的消息 ID，插件只会在 20 秒后清理本地临时图片文件。

会话格式

插件保留稳定的 session ID 规则：

<account_key>%<remote_user_id>

例如：

wx_001%remote_user
wx_002%remote_user

在 AstrBot 内部，对应的统一会话来源类似：

weixin_oc_hub:FriendMessage:wx_001%remote_user
weixin_oc_hub:FriendMessage:wx_002%remote_user

这样不同 OpenClaw 连接会被 AstrBot 视为不同会话。

状态结构

get_stats() 会区分两类状态：

registered_accounts
pending_login

registered_accounts 表示已经扫码成功并注册的连接，只显示连接状态、显示名、key 和最近错误。

pending_login 表示当前等待扫码的连接，二维码只会出现在这里：

pending_login.qrcode
pending_login.qr_status
pending_login.qrcode_img_content

状态恢复

插件重启后：

• accounts 中已注册的连接会自动恢复并启动。
• 如果未达到 max_accounts，插件会自动创建一个新的 pending 二维码。
• 如果已经达到 max_accounts，不会继续创建 pending 登录位。

兼容旧配置

旧版本如果已经有类似配置：

accounts:
  - key: primary

插件会把它当作一个已注册连接尝试加载，不会直接崩溃。

但新版本不再推荐手动维护 accounts 的数组内容。普通用户只需要保留：

accounts: "[]"

后续连接由扫码自动注册。

临时文件

入站媒体会保存到 AstrBot 临时目录：

data/temp/weixin_oc_hub/<account_key>