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