mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 10:30:44 +00:00
docs: add WeChat channel guide
This commit is contained in:
Peter Steinberger
@@ -59,6 +59,14 @@
|
||||
"source": "Feishu",
|
||||
"target": "Feishu"
|
||||
},
|
||||
{
|
||||
"source": "WeChat",
|
||||
"target": "微信"
|
||||
},
|
||||
{
|
||||
"source": "Weixin",
|
||||
"target": "微信"
|
||||
},
|
||||
{
|
||||
"source": "Mattermost",
|
||||
"target": "Mattermost"
|
||||
|
||||
@@ -34,7 +34,7 @@ Text is supported everywhere; media and reactions vary by channel.
|
||||
- [Twitch](/channels/twitch) — Twitch chat via IRC connection (bundled plugin).
|
||||
- [Voice Call](/plugins/voice-call) — Telephony via Plivo or Twilio (plugin, installed separately).
|
||||
- [WebChat](/web/webchat) — Gateway WebChat UI over WebSocket.
|
||||
- [WeChat](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin) — Tencent iLink Bot plugin via QR login; private chats only.
|
||||
- [WeChat](/channels/wechat) — Tencent iLink Bot plugin via QR login; private chats only (external plugin).
|
||||
- [WhatsApp](/channels/whatsapp) — Most popular; uses Baileys and requires QR pairing.
|
||||
- [Zalo](/channels/zalo) — Zalo Bot API; Vietnam's popular messenger (bundled plugin).
|
||||
- [Zalo Personal](/channels/zalouser) — Zalo personal account via QR login (bundled plugin).
|
||||
|
||||
168
docs/channels/wechat.md
Normal file
168
docs/channels/wechat.md
Normal file
@@ -0,0 +1,168 @@
|
||||
---
|
||||
summary: "WeChat channel setup through the external openclaw-weixin plugin"
|
||||
read_when:
|
||||
- You want to connect OpenClaw to WeChat or Weixin
|
||||
- You are installing or troubleshooting the openclaw-weixin channel plugin
|
||||
- You need to understand how external channel plugins run beside the Gateway
|
||||
title: "WeChat"
|
||||
---
|
||||
|
||||
# WeChat
|
||||
|
||||
OpenClaw connects to WeChat through Tencent's external
|
||||
`@tencent-weixin/openclaw-weixin` channel plugin.
|
||||
|
||||
Status: external plugin. Direct chats and media are supported. Group chats are not
|
||||
advertised by the current plugin capability metadata.
|
||||
|
||||
## Naming
|
||||
|
||||
- **WeChat** is the user-facing name in these docs.
|
||||
- **Weixin** is the name used by Tencent's package and by the plugin id.
|
||||
- `openclaw-weixin` is the OpenClaw channel id.
|
||||
- `@tencent-weixin/openclaw-weixin` is the npm package.
|
||||
|
||||
Use `openclaw-weixin` in CLI commands and config paths.
|
||||
|
||||
## How it works
|
||||
|
||||
The WeChat code does not live in the OpenClaw core repo. OpenClaw provides the
|
||||
generic channel plugin contract, and the external plugin provides the
|
||||
WeChat-specific runtime:
|
||||
|
||||
1. `openclaw plugins install` installs `@tencent-weixin/openclaw-weixin`.
|
||||
2. The Gateway discovers the plugin manifest and loads the plugin entrypoint.
|
||||
3. The plugin registers channel id `openclaw-weixin`.
|
||||
4. `openclaw channels login --channel openclaw-weixin` starts QR login.
|
||||
5. The plugin stores account credentials under the OpenClaw state directory.
|
||||
6. When the Gateway starts, the plugin starts its Weixin monitor for each
|
||||
configured account.
|
||||
7. Inbound WeChat messages are normalized through the channel contract, routed to
|
||||
the selected OpenClaw agent, and sent back through the plugin outbound path.
|
||||
|
||||
That separation matters: OpenClaw core should stay channel-agnostic. WeChat login,
|
||||
Tencent iLink API calls, media upload/download, context tokens, and account
|
||||
monitoring are owned by the external plugin.
|
||||
|
||||
## Install
|
||||
|
||||
Quick install:
|
||||
|
||||
```bash
|
||||
npx -y @tencent-weixin/openclaw-weixin-cli install
|
||||
```
|
||||
|
||||
Manual install:
|
||||
|
||||
```bash
|
||||
openclaw plugins install "@tencent-weixin/openclaw-weixin"
|
||||
openclaw config set plugins.entries.openclaw-weixin.enabled true
|
||||
```
|
||||
|
||||
Restart the Gateway after install:
|
||||
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
## Login
|
||||
|
||||
Run QR login on the same machine that runs the Gateway:
|
||||
|
||||
```bash
|
||||
openclaw channels login --channel openclaw-weixin
|
||||
```
|
||||
|
||||
Scan the QR code with WeChat on your phone and confirm the login. The plugin saves
|
||||
the account token locally after a successful scan.
|
||||
|
||||
To add another WeChat account, run the same login command again. For multiple
|
||||
accounts, isolate direct-message sessions by account, channel, and sender:
|
||||
|
||||
```bash
|
||||
openclaw config set session.dmScope per-account-channel-peer
|
||||
```
|
||||
|
||||
## Access control
|
||||
|
||||
Direct messages use the normal OpenClaw pairing and allowlist model for channel
|
||||
plugins.
|
||||
|
||||
Approve new senders:
|
||||
|
||||
```bash
|
||||
openclaw pairing list openclaw-weixin
|
||||
openclaw pairing approve openclaw-weixin <CODE>
|
||||
```
|
||||
|
||||
For the full access-control model, see [Pairing](/channels/pairing).
|
||||
|
||||
## Compatibility
|
||||
|
||||
The plugin checks the host OpenClaw version at startup.
|
||||
|
||||
| Plugin line | OpenClaw version | npm tag |
|
||||
| ----------- | ----------------------- | -------- |
|
||||
| `2.x` | `>=2026.3.22` | `latest` |
|
||||
| `1.x` | `>=2026.1.0 <2026.3.22` | `legacy` |
|
||||
|
||||
If the plugin reports that your OpenClaw version is too old, either update
|
||||
OpenClaw or install the legacy plugin line:
|
||||
|
||||
```bash
|
||||
openclaw plugins install @tencent-weixin/openclaw-weixin@legacy
|
||||
```
|
||||
|
||||
## Sidecar process
|
||||
|
||||
The WeChat plugin can run helper work beside the Gateway while it monitors the
|
||||
Tencent iLink API. In issue #68451, that helper path exposed a bug in OpenClaw's
|
||||
generic stale-Gateway cleanup: a child process could try to clean up the parent
|
||||
Gateway process, causing restart loops under process managers such as systemd.
|
||||
|
||||
Current OpenClaw startup cleanup excludes the current process and its ancestors,
|
||||
so a channel helper must not kill the Gateway that launched it. This fix is
|
||||
generic; it is not a WeChat-specific path in core.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Check install and status:
|
||||
|
||||
```bash
|
||||
openclaw plugins list
|
||||
openclaw channels status --probe
|
||||
openclaw --version
|
||||
```
|
||||
|
||||
If the channel shows as installed but does not connect, confirm that the plugin is
|
||||
enabled and restart:
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.openclaw-weixin.enabled true
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
If the Gateway restarts repeatedly after enabling WeChat, update both OpenClaw and
|
||||
the plugin:
|
||||
|
||||
```bash
|
||||
npm view @tencent-weixin/openclaw-weixin version
|
||||
openclaw plugins install "@tencent-weixin/openclaw-weixin" --force
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Temporary disable:
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.openclaw-weixin.enabled false
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
## Related docs
|
||||
|
||||
- Channel overview: [Chat Channels](/channels)
|
||||
- Pairing: [Pairing](/channels/pairing)
|
||||
- Channel routing: [Channel Routing](/channels/channel-routing)
|
||||
- Plugin architecture: [Plugin Architecture](/plugins/architecture)
|
||||
- Channel plugin SDK: [Channel Plugin SDK](/plugins/sdk-channel-plugins)
|
||||
- External package: [@tencent-weixin/openclaw-weixin](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin)
|
||||
@@ -456,6 +456,14 @@
|
||||
"source": "/channels/grammy",
|
||||
"destination": "/channels/telegram"
|
||||
},
|
||||
{
|
||||
"source": "/channels/openclaw-weixin",
|
||||
"destination": "/channels/wechat"
|
||||
},
|
||||
{
|
||||
"source": "/channels/weixin",
|
||||
"destination": "/channels/wechat"
|
||||
},
|
||||
{
|
||||
"source": "/group-messages",
|
||||
"destination": "/channels/group-messages"
|
||||
@@ -1028,6 +1036,7 @@
|
||||
"channels/telegram",
|
||||
"channels/tlon",
|
||||
"channels/twitch",
|
||||
"channels/wechat",
|
||||
"channels/whatsapp",
|
||||
"channels/zalo",
|
||||
"channels/zalouser"
|
||||
|
||||
Reference in New Issue
Block a user