diff --git a/README.md b/README.md index 7509a51..a28bc8f 100644 --- a/README.md +++ b/README.md @@ -200,6 +200,87 @@ Open QQ, find your bot, and send a message! --- +## 🤖 Multi-Account Setup (Multi-Bot) + +Run multiple QQ bots under a single OpenClaw instance. + +### Configuration + +Edit `~/.openclaw/openclaw.json` and add an `accounts` field under `channels.qqbot`: + +```json +{ + "channels": { + "qqbot": { + "enabled": true, + "appId": "111111111", + "clientSecret": "secret-of-bot-1", + + "accounts": { + "bot2": { + "enabled": true, + "appId": "222222222", + "clientSecret": "secret-of-bot-2" + }, + "bot3": { + "enabled": true, + "appId": "333333333", + "clientSecret": "secret-of-bot-3" + } + } + } + } +} +``` + +**Notes:** + +- The top-level `appId` / `clientSecret` is the **default account** (accountId = `"default"`) +- Each key under `accounts` (e.g. `bot2`, `bot3`) is the `accountId` for that bot +- Each account can independently configure `enabled`, `name`, `allowFrom`, `systemPrompt`, etc. +- You may also skip the top-level default account and only configure bots inside `accounts` + +Add a second bot via CLI (if the framework supports the `--account` parameter): + +```bash +openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2" +``` + +### Sending Messages to a Specific Account's Users + +When using `openclaw message send`, specify which bot to use with the `--account` parameter: + +```bash +# Send with the default bot (no --account = uses "default") +openclaw message send --channel "qqbot" \ + --target "qqbot:c2c:OPENID" \ + --message "hello from default bot" + +# Send with bot2 +openclaw message send --channel "qqbot" \ + --account bot2 \ + --target "qqbot:c2c:OPENID" \ + --message "hello from bot2" +``` + +**Target Formats:** + +| Format | Description | +|--------|-------------| +| `qqbot:c2c:OPENID` | Private chat (C2C) | +| `qqbot:group:GROUP_OPENID` | Group chat | +| `qqbot:channel:CHANNEL_ID` | Guild channel | + +> ⚠️ **Important**: Each bot has its own set of user OpenIDs. An OpenID received by Bot A **cannot** be used to send messages via Bot B — this will result in a 500 error. Always use the matching bot's `accountId` to send messages to its users. + +### How It Works + +- When `openclaw gateway` starts, all accounts with `enabled: true` launch their own WebSocket connections +- Each account maintains an independent Token cache (isolated by `appId`), preventing cross-contamination +- Incoming message logs are prefixed with `[qqbot:accountId]` for easy debugging + +--- + ## 🎙️ Voice Configuration (Optional) ### STT (Speech-to-Text) — Transcribe Incoming Voice Messages diff --git a/README.zh.md b/README.zh.md index 2caeec5..61fc87f 100644 --- a/README.zh.md +++ b/README.zh.md @@ -198,6 +198,87 @@ openclaw gateway --- +## 🤖 多账户配置(Multi-Bot) + +支持在同一个 OpenClaw 实例下同时运行多个 QQ 机器人。 + +### 配置方式 + +编辑 `~/.openclaw/openclaw.json`,在 `channels.qqbot` 下增加 `accounts` 字段: + +```json +{ + "channels": { + "qqbot": { + "enabled": true, + "appId": "111111111", + "clientSecret": "secret-of-bot-1", + + "accounts": { + "bot2": { + "enabled": true, + "appId": "222222222", + "clientSecret": "secret-of-bot-2" + }, + "bot3": { + "enabled": true, + "appId": "333333333", + "clientSecret": "secret-of-bot-3" + } + } + } + } +} +``` + +**说明:** + +- 顶层的 `appId` / `clientSecret` 是**默认账户**(accountId = `"default"`) +- `accounts` 下的每个 key(如 `bot2`、`bot3`)就是该账户的 `accountId` +- 每个账户都可以独立配置 `enabled`、`name`、`allowFrom`、`systemPrompt` 等字段 +- 也可以不配顶层默认账户,只在 `accounts` 里配置所有机器人 + +通过 CLI 添加第二个机器人(如果框架支持 `--account` 参数): + +```bash +openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2" +``` + +### 向指定账户的用户发送消息 + +使用 `openclaw message send` 发消息时,需要通过 `--account` 参数指定使用哪个机器人发送: + +```bash +# 使用默认机器人发送(不指定 --account 时自动使用 default) +openclaw message send --channel "qqbot" \ + --target "qqbot:c2c:OPENID" \ + --message "hello from default bot" + +# 使用 bot2 发送 +openclaw message send --channel "qqbot" \ + --account bot2 \ + --target "qqbot:c2c:OPENID" \ + --message "hello from bot2" +``` + +**Target 格式支持:** + +| 格式 | 说明 | +|------|------| +| `qqbot:c2c:OPENID` | 私聊 | +| `qqbot:group:GROUP_OPENID` | 群聊 | +| `qqbot:channel:CHANNEL_ID` | 频道 | + +> ⚠️ **注意**:每个机器人的用户 OpenID 是不同的。机器人 A 收到的用户 OpenID 不能用机器人 B 去发消息,否则会返回 500 错误。必须用对应机器人的 accountId 去给该机器人的用户发消息。 + +### 工作原理 + +- 启动 `openclaw gateway` 后,所有 `enabled: true` 的账户会同时启动 WebSocket 连接 +- 每个账户独立维护 Token 缓存(基于 `appId` 隔离),互不干扰 +- 接收消息时,日志会带上 `[qqbot:accountId]` 前缀方便排查 + +--- + ## 🎙️ 语音能力配置(可选) ### STT(语音转文字)— 自动转录用户发来的语音消息