Skip to content
agent-wechat

OpenClaw Setup

The @agent-wechat/wechat plugin connects OpenClaw to WeChat via agent-wechat.

Prerequisites

  • A WeChat account logged in on your phone — this account will be used by the bot. Keep it logged in on your phone at all times.
  • A second screen — WeChat login requires scanning a QR code with your phone camera. You need the QR code on a screen separate from the phone.
  • An agent-wechat server — either self-hosted via Docker or through Managed Hosting. You need the server URL and auth token.

Local setup (self-hosted)

If you’re running agent-wechat locally or on your own server, you’ll need Docker installed. On macOS, install Colima (brew install colima && colima start) or Docker Desktop.

1. Start the agent-wechat server

See Container Setup for options. The quickest:

Terminal window
npm install -g @agent-wechat/cli
wx up

2. Install the plugin

Terminal window
openclaw plugins install @agent-wechat/wechat

3. Add the WeChat channel

Terminal window
# Uses defaults (localhost:6174, token from ~/.config/agent-wechat/token)
openclaw channels add --channel wechat

4. Restart the gateway

Terminal window
openclaw gateway restart

Remote setup (managed hosting)

If you don’t want to run Docker or manage infrastructure, use Managed Hosting. You’ll receive a server URL and auth token.

1. Install the plugin

Terminal window
openclaw plugins install @agent-wechat/wechat

2. Add the WeChat channel

Terminal window
openclaw channels add --channel wechat --url <your-server-url> --token <your-token>

3. Restart the gateway

Terminal window
openclaw gateway restart

Log in to WeChat

Ask your bot:

“Log in to WeChat”

Your bot generates a QR code image. Alternatively:

Terminal window
openclaw channels login --channel wechat

Display the QR code on a screen separate from your phone. Scan it using WeChat’s built-in scanner (tap + > Scan), then tap Login on the confirmation screen.

Configure policies

Once connected, configure how the bot handles DMs and group chats. See the Configuration page.

Limitations

  • The WeChat account must stay logged in on your phone. Logging out on the phone disconnects the bot.
  • Only one desktop session. You cannot simultaneously use WeChat on another computer or WeChat Web.
  • Infrastructure updates disconnect the bot. If the server restarts, the bot disconnects. Ask your bot to log in again — scan the QR code in WeChat if prompted.