IM Channel Configuration
RC can receive/reply via Telegram, Discord, WeChat (微信), Feishu (飞书),
QQ, Slack, WhatsApp. Channels are OC infrastructure — RC reuses them fully.
Dashboard Channel Management UI
The dashboard has a complete channel management UI in the left sidebar.
Location: Left sidebar → Extensions panel (🔗 chain-link icon) → Channels tab.
What users can do in the Channels tab:
- View all channels with live status (connected / configured / error / disabled)
- WeChat / WhatsApp: Click the Connect button → QR code modal opens → scan with phone
- Enable / Disable any channel via a toggle switch (triggers
config.patch → gateway restart)
- Delete a channel via the red trash button (with confirmation modal)
- Add Channel button at the bottom (sends a chat message asking you for help)
- Ask Agent to Fix / Configure button on error/unconfigured channels (sends chat message)
How to guide users:
- For WeChat / WhatsApp QR login: Direct users to the Channels tab:
"请打开左侧扩展面板 → 通道标签 → 点击微信旁边的 Connect 按钮，在弹出窗口中扫码。"
Do NOT generate QR codes in the chat — the dashboard QR modal handles it.
- For bot-token channels (Telegram, Discord, etc.): Help via chat — guide them to
get a token, then use
config.patch to write it. Or they can click "Ask Agent to Configure".
- The
weixin_login / whatsapp_login agent tools are fallbacks for IM-only contexts
(when the user is chatting from Telegram/Discord and has no dashboard access).
Connection Protocols
Bot-Token Type (Telegram / Discord / Feishu / QQ / Slack)
- Guide user to create a bot on the platform and obtain a token.
- Telegram: Talk to @BotFather →
/newbot → copy token.
- Discord: Discord Developer Portal → Bot section → copy token.
- Feishu: Open platform → create bot → App ID + App Secret.
- Write config via
config.patch:
- Telegram:
{ channels: { telegram: { botToken: "<TOKEN>", enabled: true } } }
- Discord:
{ channels: { discord: { token: "<TOKEN>", enabled: true } } }
- Feishu:
{ channels: { feishu: { appId: "...", appSecret: "...", enabled: true } } }
- Others: see platform OC docs for field names.
- After
config.patch: Gateway auto-restarts via SIGUSR1 (takes ~3–5s). The dashboard
reconnects automatically. No manual restart needed.
- Telegram: user must send "/start" in the bot chat to receive replies.
commands.native must be false (530+ tools exceed IM menu limits).
sync-global-config.cjs auto-fixes this on startup.
WeChat (微信) — QR Scan
Prerequisite: openclaw-weixin plugin installed and in plugins.allow.
Primary path (dashboard): User clicks Connect in the Channels tab → QR modal → scan.
The dashboard handles web.login.start → web.login.wait automatically,
then triggers config.patch to restart gateway and pick up new credentials.
Fallback path (IM-only / no dashboard): Use the weixin_login agent tool:
- Call
weixin_login { action: "start" }.
- Returns QR code URL in markdown:
.
- Display the image to the user and prompt them to scan with WeChat.
- Call
weixin_login { action: "wait", timeoutMs: 120000 }.
- Blocks until the user scans or timeout.
- On success, plugin auto-saves credentials; gateway auto-starts channel.
- WeChat cannot send proactive messages — replies only (contextToken mechanism).
WhatsApp — QR Scan
Primary path: Same as WeChat — user clicks Connect in the Channels tab.
Fallback path (IM-only): Use the whatsapp_login agent tool:
- Call
whatsapp_login { action: "start" }.
- Returns QR code as base64 data URL in markdown:
.
- Call
whatsapp_login { action: "wait", timeoutMs: 120000 }.
- Blocks until the user scans or timeout.
Config & Restart Behavior
Understanding this is critical for troubleshooting:
config.patch → gateway receives SIGUSR1 → drains active tasks (up to 90s)
→ restarts → channels reload from new config. Dashboard auto-reconnects.- Enable/Disable switch in dashboard → calls
config.patch with
{ channels: { <id>: { enabled: true/false } } } → restart.
- Delete button → calls
config.patch with { channels: { <id>: null } } → restart.
- If a channel has an invalid token (e.g., placeholder
<YOUR_TOKEN>), the channel
will crash on startup with 401 Unauthorized and enter an auto-restart loop
(exponential backoff: 5s → 10s → 20s → ... up to 10 attempts). This is normal;
it stops after 10 failures. Fix: provide correct token or disable the channel.
- Drain can be slow (up to 90s) if there are active agent tasks or embedded runs.
This is by design — gateway waits for work to complete before restarting.
In-Channel Behavior
- All RC tools (library, tasks, workspace, monitor) are fully available.
- Keep replies under 2000 characters (IM message limit).
- Do not use Markdown tables (most IM clients do not render them).
approval_card degrades to text: "需要审批: xxx. 回复 yes/no".- Media requires absolute paths via the media parameter.
- Peer ID formats differ: WeChat
xxx@im.wechat, Telegram numeric IDs.
Troubleshooting
Common Errors
| Symptom |
Cause |
Fix |
401: Unauthorized loop |
Invalid or placeholder bot token |
Provide real token via config.patch or disable channel |
| "not configured" |
No credentials found for channel |
For bot-token: set token in config. For WeChat: re-scan QR |
| "Provider not running" |
Channel configured but crashed |
Check logs for error. Common: token expired, network issue |
| Channel not visible |
Plugin not in plugins.allow or plugins.load.paths |
Add to both in config. See 4-point sync below |
better-sqlite3 crash |
Native module ABI mismatch |
Rebuild under conda Node 22 (gateway's Node version) |
| WeChat "not configured" after QR |
Old default account has no token |
Re-scan QR. Dashboard uses best account for status |
Diagnostic Steps
When a channel shows Error or Not Configured:
- Check the token: Read config via
config.get or ask user. Is it a real token
or a placeholder like <YOUR_TOKEN>? Placeholder = 401 errors.
- Check
plugins.allow: The channel plugin ID must be in plugins.allow array.
Example: openclaw-weixin for WeChat, telegram for Telegram (OC built-in).
- Check credentials path (WeChat only): Stored at
~/.openclaw/openclaw-weixin/accounts/<accountId>.json. If missing, user needs to re-scan QR.
- Check gateway logs: Look for
[telegram], [openclaw-weixin] etc. in terminal output.
Common patterns:
401: Unauthorized → invalid tokenENOTFOUND / ETIMEDOUT → network/VPN issuechannel exited → channel crashed, will auto-restart
- Restart gateway if needed:
gateway.restart (requires approval_card).
Or user can Ctrl+C and re-run run.sh.
4-Point Plugin Sync (for new channel plugins)
When adding a new channel plugin, it must be registered in 4 places:
config/openclaw.json → plugins.allow arrayconfig/openclaw.json → plugins.load.paths arrayscripts/ensure-config.cjs → REQUIRED_ALLOW arraydashboard/src/utils/config-patch.ts → RC_CONFIG_DEFAULTS.plugins.allow
Plus the runtime global ~/.openclaw/openclaw.json.
1---
2name: channels-guide
3description: >-
4 Configuration, troubleshooting, and operational guide for Research-Claw IM channels
5 (Telegram, Discord, WeChat, Feishu, Slack, WhatsApp). Covers dashboard UI flow,
6 bot token setup, QR login, config.patch restart behavior, enable/disable/delete,
7 common errors (401, ABI, plugins.allow), and diagnostic procedures.
8---
9
10<!-- MAINTENANCE NOTES:
11 Source: AGENTS.md §8 Channels (extracted during prompt redesign).
12 Update here when adding channel types or protocols.
13 commands.native=false enforced by sync-global-config.cjs.
14 WeChat creds: ~/.openclaw/openclaw-weixin/accounts/
15 Dashboard UI: ExtensionsPanel.tsx ChannelCard + ChannelsTab
16-->
17
18# IM Channel Configuration
19
20RC can receive/reply via Telegram, Discord, WeChat (微信), Feishu (飞书),
21QQ, Slack, WhatsApp. Channels are OC infrastructure — RC reuses them fully.
22
23## Dashboard Channel Management UI
24
25The dashboard has a **complete channel management UI** in the left sidebar.
26
27**Location**: Left sidebar → Extensions panel (🔗 chain-link icon) → **Channels** tab.
28
29### What users can do in the Channels tab:
30- View all channels with live status (connected / configured / error / disabled)
31- **WeChat / WhatsApp**: Click the **Connect** button → QR code modal opens → scan with phone
32- **Enable / Disable** any channel via a toggle switch (triggers `config.patch` → gateway restart)
33- **Delete** a channel via the red trash button (with confirmation modal)
34- **Add Channel** button at the bottom (sends a chat message asking you for help)
35- **Ask Agent to Fix / Configure** button on error/unconfigured channels (sends chat message)
36
37### How to guide users:
38- **For WeChat / WhatsApp QR login**: Direct users to the Channels tab:
39 "请打开左侧扩展面板 → 通道标签 → 点击微信旁边的 Connect 按钮，在弹出窗口中扫码。"
40 Do NOT generate QR codes in the chat — the dashboard QR modal handles it.
41- **For bot-token channels** (Telegram, Discord, etc.): Help via chat — guide them to
42 get a token, then use `config.patch` to write it. Or they can click "Ask Agent to Configure".
43- The `weixin_login` / `whatsapp_login` agent tools are **fallbacks for IM-only contexts**
44 (when the user is chatting from Telegram/Discord and has no dashboard access).
45
46## Connection Protocols
47
48### Bot-Token Type (Telegram / Discord / Feishu / QQ / Slack)
49
501. Guide user to create a bot on the platform and obtain a token.
51 - **Telegram**: Talk to @BotFather → `/newbot` → copy token.
52 - **Discord**: Discord Developer Portal → Bot section → copy token.
53 - **Feishu**: Open platform → create bot → App ID + App Secret.
542. Write config via `config.patch`:
55 - Telegram: `{ channels: { telegram: { botToken: "<TOKEN>", enabled: true } } }`
56 - Discord: `{ channels: { discord: { token: "<TOKEN>", enabled: true } } }`
57 - Feishu: `{ channels: { feishu: { appId: "...", appSecret: "...", enabled: true } } }`
58 - Others: see platform OC docs for field names.
593. **After `config.patch`**: Gateway auto-restarts via SIGUSR1 (takes ~3–5s). The dashboard
60 reconnects automatically. No manual restart needed.
614. Telegram: user must send "/start" in the bot chat to receive replies.
625. `commands.native` must be `false` (530+ tools exceed IM menu limits).
63 `sync-global-config.cjs` auto-fixes this on startup.
64
65### WeChat (微信) — QR Scan
66
67**Prerequisite**: `openclaw-weixin` plugin installed and in `plugins.allow`.
68
69**Primary path (dashboard)**: User clicks Connect in the Channels tab → QR modal → scan.
70The dashboard handles `web.login.start` → `web.login.wait` automatically,
71then triggers `config.patch` to restart gateway and pick up new credentials.
72
73**Fallback path (IM-only / no dashboard)**: Use the `weixin_login` agent tool:
74
751. Call `weixin_login { action: "start" }`.
76 - Returns QR code URL in markdown: ``.
77 - Display the image to the user and prompt them to scan with WeChat.
782. Call `weixin_login { action: "wait", timeoutMs: 120000 }`.
79 - Blocks until the user scans or timeout.
80 - On success, plugin auto-saves credentials; gateway auto-starts channel.
813. WeChat cannot send proactive messages — replies only (contextToken mechanism).
82
83### WhatsApp — QR Scan
84
85**Primary path**: Same as WeChat — user clicks Connect in the Channels tab.
86
87**Fallback path (IM-only)**: Use the `whatsapp_login` agent tool:
88
891. Call `whatsapp_login { action: "start" }`.
90 - Returns QR code as base64 data URL in markdown: ``.
912. Call `whatsapp_login { action: "wait", timeoutMs: 120000 }`.
92 - Blocks until the user scans or timeout.
93
94## Config & Restart Behavior
95
96Understanding this is critical for troubleshooting:
97
981. **`config.patch`** → gateway receives SIGUSR1 → drains active tasks (up to 90s)
99 → restarts → channels reload from new config. Dashboard auto-reconnects.
1002. **Enable/Disable switch** in dashboard → calls `config.patch` with
101 `{ channels: { <id>: { enabled: true/false } } }` → restart.
1023. **Delete button** → calls `config.patch` with `{ channels: { <id>: null } }` → restart.
1034. If a channel has an **invalid token** (e.g., placeholder `<YOUR_TOKEN>`), the channel
104 will crash on startup with 401 Unauthorized and enter an **auto-restart loop**
105 (exponential backoff: 5s → 10s → 20s → ... up to 10 attempts). This is normal;
106 it stops after 10 failures. Fix: provide correct token or disable the channel.
1075. **Drain can be slow** (up to 90s) if there are active agent tasks or embedded runs.
108 This is by design — gateway waits for work to complete before restarting.
109
110## In-Channel Behavior
111
112- All RC tools (library, tasks, workspace, monitor) are **fully available**.
113- Keep replies under 2000 characters (IM message limit).
114- Do not use Markdown tables (most IM clients do not render them).
115- `approval_card` degrades to text: "需要审批: xxx. 回复 yes/no".
116- Media requires absolute paths via the media parameter.
117- Peer ID formats differ: WeChat `xxx@im.wechat`, Telegram numeric IDs.
118
119## Troubleshooting
120
121### Common Errors
122
123| Symptom | Cause | Fix |
124|---------|-------|-----|
125| `401: Unauthorized` loop | Invalid or placeholder bot token | Provide real token via `config.patch` or disable channel |
126| "not configured" | No credentials found for channel | For bot-token: set token in config. For WeChat: re-scan QR |
127| "Provider not running" | Channel configured but crashed | Check logs for error. Common: token expired, network issue |
128| Channel not visible | Plugin not in `plugins.allow` or `plugins.load.paths` | Add to both in config. See 4-point sync below |
129| `better-sqlite3` crash | Native module ABI mismatch | Rebuild under conda Node 22 (gateway's Node version) |
130| WeChat "not configured" after QR | Old default account has no token | Re-scan QR. Dashboard uses best account for status |
131
132### Diagnostic Steps
133
134When a channel shows Error or Not Configured:
135
1361. **Check the token**: Read config via `config.get` or ask user. Is it a real token
137 or a placeholder like `<YOUR_TOKEN>`? Placeholder = 401 errors.
1382. **Check `plugins.allow`**: The channel plugin ID must be in `plugins.allow` array.
139 Example: `openclaw-weixin` for WeChat, `telegram` for Telegram (OC built-in).
1403. **Check credentials path** (WeChat only): Stored at
141 `~/.openclaw/openclaw-weixin/accounts/<accountId>.json`. If missing, user needs to re-scan QR.
1424. **Check gateway logs**: Look for `[telegram]`, `[openclaw-weixin]` etc. in terminal output.
143 Common patterns:
144 - `401: Unauthorized` → invalid token
145 - `ENOTFOUND` / `ETIMEDOUT` → network/VPN issue
146 - `channel exited` → channel crashed, will auto-restart
1475. **Restart gateway** if needed: `gateway.restart` (requires `approval_card`).
148 Or user can Ctrl+C and re-run `run.sh`.
149
150### 4-Point Plugin Sync (for new channel plugins)
151
152When adding a new channel plugin, it must be registered in 4 places:
1531. `config/openclaw.json` → `plugins.allow` array
1542. `config/openclaw.json` → `plugins.load.paths` array
1553. `scripts/ensure-config.cjs` → `REQUIRED_ALLOW` array
1564. `dashboard/src/utils/config-patch.ts` → `RC_CONFIG_DEFAULTS.plugins.allow`
157Plus the runtime global `~/.openclaw/openclaw.json`.
wentorai