Guide to Connecting OpenClaw with WeChat

Introduction

WeChat is the most widely used instant messaging app in China. Connecting OpenClaw to WeChat gives you a personal AI assistant and enables intelligent Q&A services in group chats. This article covers the various integration methods and their configuration in detail.

Integration Methods Overview

Since WeChat does not offer an official Bot API, OpenClaw relies on third-party bridging solutions to integrate with WeChat:

Important Notice

Note: Personal WeChat integration uses unofficial methods and carries
a risk of account restrictions. It is strongly recommended to use a
secondary account for testing. Never use your primary WeChat account.
The WeCom API is the officially supported method and is recommended
for enterprise deployments.

Method 1: Wechaty Bridge (Recommended)

Wechaty is a mature chatbot SDK, and OpenClaw has built-in support for it.

1.1 Install Wechaty Dependencies

Make sure Node.js 22+ is installed on your system, then install Wechaty:

npm install -g wechaty

1.2 Choose a Puppet

Wechaty uses Puppets to interface with different WeChat protocols:

For a free solution, use wechat4u:

npm install wechaty-puppet-wechat4u

1.3 Configure OpenClaw

Edit ~/.config/openclaw/openclaw.json5:

{
  channels: {
    wechat: {
      enabled: true,
      // Bridging method
      bridge: "wechaty",

      // Wechaty Puppet configuration
      puppet: {
        // Puppet name
        name: "wechaty-puppet-wechat4u",
        // If using a paid puppet, enter the token
        token: ""
      },

      // Trigger settings
      trigger: {
        // Whether to auto-reply in private chats (no keyword required)
        privateAutoReply: true,
        // Group chat trigger keywords (messages must start with these to get a reply)
        groupKeywords: ["@AI", "问一下", "/ask"],
        // Whether @Bot is required in group chats
        groupMentionRequired: true,
        // Whether to respond to your own messages
        selfMessage: false
      },

      // Reply configuration
      reply: {
        // Whether to quote the original message when replying in group chats
        quoteReply: true,
        // Whether to show "typing" status
        showTyping: true,
        // Character count for auto-splitting long text
        maxLength: 4000
      }
    }
  }
}

1.4 Start and Scan to Log In

After configuration, restart OpenClaw:

openclaw restart

View the logs to get the login QR code:

openclaw logs -f --component channel:wechat

The logs will display a QR code (rendered as terminal ASCII art). Scan it with the WeChat account you want to log in, and confirm on your phone.

[INFO] [channel:wechat] Waiting for QR code scan...
[INFO] [channel:wechat] Please scan the following QR code with WeChat:
[INFO] [channel:wechat] ████████████████████████████████
[INFO] [channel:wechat] █                              █
[INFO] [channel:wechat] █  ▄▄▄▄▄ █ █ ▄ █▀▄▀ █ ▄▄▄▄▄  █
[INFO] [channel:wechat] █  ...(QR code content)...     █
[INFO] [channel:wechat] ████████████████████████████████

After a successful scan:

[INFO] [channel:wechat] QR code scanned, waiting for confirmation...
[INFO] [channel:wechat] Login successful! Current account: AI Assistant
[INFO] [channel:wechat] Contacts: 256, Group chats: 15

Method 2: WeCom API

WeCom (Enterprise WeChat) provides an official API that is more stable and secure.

2.1 Create a WeCom Application

1. Log in to the WeCom Admin Console
2. Go to App Management > Self-built Apps > Create App
3. Fill in the app name, upload an icon, and select the visibility scope
4. After creation, note down the AgentId and Secret

2.2 Gather Required Information

You will need the following:

2.3 Configure the Callback URL

In the app's Receive Messages settings, configure the callback URL:

https://your-domain.com/webhook/wechat-work/callback

OpenClaw will automatically handle the WeCom URL verification request.

2.4 OpenClaw Configuration

{
  channels: {
    wechatWork: {
      enabled: true,
      corpId: "ww1234567890abcdef",
      agentId: 1000002,
      secret: "your-app-secret",
      token: "your-callback-token",
      encodingAESKey: "your-encoding-aes-key",

      // Allowed users/departments (empty arrays mean everyone within the app's visibility scope)
      allowedUsers: [],
      allowedDepartments: []
    }
  }
}

Group Chat Configuration Details

Group Chat Trigger Rules

In group chats, specific trigger methods are typically used to prevent the Bot from being overly intrusive:

{
  channels: {
    wechat: {
      trigger: {
        groupMentionRequired: true,
        groupKeywords: ["@AI", "问一下"],
        // Only enable in specified group chats
        allowedGroups: ["Tech Discussion Group", "AI Assistant Test Group"],
        // Or exclude certain groups
        ignoredGroups: ["Family Group", "Work Group"]
      }
    }
  }
}

Group Chat Context Management

{
  channels: {
    wechat: {
      context: {
        // Independent context per user in group chats
        groupContextMode: "per-user",  // "per-user" | "shared"
        // Context retention time (minutes)
        contextTimeout: 30,
        // Maximum number of context message turns
        maxContextTurns: 20
      }
    }
  }
}

Supported Message Types

OpenClaw's support for different WeChat message types:

Persistent Login

To avoid re-scanning the QR code after every restart, OpenClaw automatically saves the login session:

{
  channels: {
    wechat: {
      // Session data save path
      sessionDir: "~/.openclaw/wechat-session/",
      // Session refresh interval (hours)
      sessionRefresh: 12
    }
  }
}

Once session data is saved, OpenClaw automatically restores the login state upon restart without requiring another QR code scan. However, if the session remains inactive for an extended period (typically over a week), it may expire and require a new scan.

Troubleshooting

Cannot Log In After Scanning

# Check if the account is restricted
# Some newly registered or long-inactive accounts may not support the Web protocol
# Solution: switch to the iPad protocol or WeCom method

# Check network connectivity
openclaw doctor

Message Send/Receive Delays

# View message processing logs
openclaw logs --component channel:wechat --level debug

# Common causes:
# 1. Slow AI model response — check model API latency
# 2. Slow proxy network — optimize proxy configuration
# 3. Message queue backlog — check concurrency settings

Bot Not Responding in Group Chats

Check the following:

1. The Bot account is a member of the group chat
2. The group chat name is in the allowedGroups list (if configured)
3. The message meets the trigger conditions (keyword or @mention)
4. Check whether the group chat messages appear in the logs

Summary

WeChat integration is one of the most practical OpenClaw features for use in China. Some recommendations:

• Personal use: Try the Wechaty + wechat4u (free) method for a quick start
• Stability needs: Consider the paid iPad protocol Puppet for better reliability
• Enterprise scenarios: WeCom API is strongly recommended — officially supported with no account ban risk
• Security awareness: When using unofficial protocols, test with a secondary account and perform a proper risk assessment