跪拜 Guibai
← Back to the summary

The Hidden Complexity of Wiring AI Agents into Telegram, WhatsApp, and WeChat

WeChat Work / Telegram / WhatsApp Integration

paste-image-1782439134425.png

Connecting an Agent to a chat app seems simple — just "receive messages, send messages."

But once you go live, you'll find the difficulty isn't in sending a reply, but in these issues:

This lecture uses three types of channels — WeChat Work / WeChat, Telegram, and WhatsApp — to explain the design approach for integrating OpenClaw with chat entry points.

Conclusion first: Channel is the entry point, not the entire permission boundary

OpenClaw's message channel is responsible for standardizing external messages and routing them to the Agent.

But a secure and usable integration scheme must at least design for:

Just configuring a token or scanning a QR code to log in is far from "ready to go live."

Integration forms for three types of channels

Telegram

Telegram is a typical Bot API form.

Process:

  1. Create a bot via BotFather
  2. Configure botToken
  3. Set dmPolicy / allowFrom
  4. Configure groups and requireMention
  5. Start Gateway
  6. Approve pairing or use allowlist

Official documentation reminds: Telegram uses long polling by default; webhook is optional. In groups, you also need to consider Privacy Mode, admin permissions, group chat ID, and user ID.

Typical configuration:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groupPolicy: "allowlist",
      groups: {
        "-1001234567890": { requireMention: true },
      },
    },
  },
}

WhatsApp

WhatsApp uses the Gateway's web channel, which starts automatically after linking a session.

You need to care about:

Typical configuration:

{
  web: { enabled: true },
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
      groupPolicy: "allowlist",
    },
  },
}

WeChat Work / WeChat

In the OpenClaw documentation, WeChat is connected via an external plugin @tencent-weixin/openclaw-weixin.

This point is important: WeChat's login, Tencent iLink API, media upload/download, and account monitoring are not in the OpenClaw core, but are implemented by an external channel plugin.

Simplified process:

  1. Install the openclaw-weixin plugin
  2. Enable the plugin
  3. Restart Gateway
  4. Scan QR code to log in
  5. Plugin saves account credentials
  6. Gateway loads the plugin on startup and starts the monitor
  7. Messages are standardized via the channel contract and routed to the Agent

Example commands:

npx -y @tencent-weixin/openclaw-weixin-cli install
openclaw gateway restart
openclaw channels login --channel openclaw-weixin

If you're talking about WeChat Work (Enterprise WeChat) rather than personal WeChat, you need to first confirm whether the target channel already has a corresponding plugin or whether you need to integrate it yourself using the channel plugin SDK. Don't confuse "WeChat Work bot webhook" with "personal WeChat login plugin."

Entry control: pairing, allowlist, open

Common DM policy options:

In production environments, default recommendations:

Be especially careful with group chats

Group chats have at least two layers of control:

  1. Can this group trigger the bot?
  2. Which person in this group can trigger it?

Also consider:

This is why group chats should start with requireMention: true.

Session isolation

By default, OpenClaw allows DMs to share a main session, which is convenient for single-user assistants.

But if multiple users can DM the same bot, isolation must be enabled:

{
  session: {
    dmScope: "per-channel-peer",
  },
}

For multi-account scenarios, this is recommended:

{
  session: {
    dmScope: "per-account-channel-peer",
  },
}

Otherwise, Alice's context could affect Bob's session.

Multi-Agent and bindings

If a single Gateway serves multiple people or multiple business lines, don't rely solely on session separation.

Multiple Agents can each have their own:

Then use bindings to route a specific channel account, group, or user to the corresponding Agent.

This is suitable for:

Common misconceptions

Misconception 1: Being able to receive messages means integration is complete

Not enough. You also need to handle permissions, group chats, sessions, tools, and health checks.

Misconception 2: After pairing, the user is authorized everywhere

Not necessarily. The Telegram documentation clearly distinguishes between DM pairing and group sender authorization.

Misconception 3: Everyone in the group can use tools without issues

If tools can read files, send messages, or run commands, group members effectively share the same delegated tool authority.

Misconception 4: WeChat Work, WeChat, and Weixin are integrated the same way

Not necessarily. The personal WeChat plugin, WeChat Work bot, and enterprise app callback are different integration models.

Final summary

Chat channels are not simple entry points; they are the intersection of permissions, routing, and context.

One sentence summary:

First design who can speak, which Agent they speak to, what context is shared, and which tools can be used — then configure Telegram, WhatsApp, or WeChat.

Homework for this section

  1. Design groups, groupPolicy, and requireMention for a Telegram group.
  2. Write out the session isolation strategy for single-account and multi-account WhatsApp.
  3. Determine whether your WeChat/WeChat Work requirement falls under a plugin, webhook, or self-built channel.
  4. List the allowed and prohibited tools for a chat entry point.

Preview of the next section

The next section covers the web automation assistant: from requirements to the Browser execution chain.

References