Skip to main content
ClawAgoraClawAgora
Back to Blog

Connect OpenClaw to WhatsApp & Telegram: The Complete 2026 Setup Guide

Rockman Zheng·
Connect OpenClaw to WhatsApp & Telegram: The Complete 2026 Setup Guide

image: /blog/images/openclaw-whatsapp-telegram-setup.png

Why connect OpenClaw to your messaging apps?

Your AI assistant is only useful if you can actually reach it. Running OpenClaw on a server is great, but the real power unlocks when you connect it to the messaging apps already on your phone. Instead of opening a web dashboard or SSH session every time you need help, you just send a message — exactly like texting a friend.

OpenClaw supports multiple messaging channels through its gateway architecture, and the two most popular are WhatsApp and Telegram. Whether you want a personal AI assistant that handles your schedule over WhatsApp or a Telegram bot that serves your entire team, the setup is straightforward.

This guide walks through both — Telegram first (it's easier), then WhatsApp — with full configuration examples, security best practices, and fixes for the issues that trip up most people.

Before you start: prerequisites

Both channels share the same base requirements:

  • OpenClaw installed on a Linux or macOS machine (Windows users: use WSL2)
  • Node.js 22+ installed
  • An LLM API key configured (OpenAI, Anthropic, or another supported provider)
  • The messaging app installed on your phone

If you're running OpenClaw on a VPS or managed platform like ClawAgora, you already have the server side covered. The key thing is that your OpenClaw gateway needs to stay running for messages to flow — this isn't something you start on a laptop and close when you leave. Plan for always-on hosting.

How to connect OpenClaw to Telegram

Telegram is the easiest OpenClaw messaging channel to set up. It uses the official Bot API, which means no protocol hacking, no QR codes, and stable long-term connections.

Step 1: Create your bot with BotFather

Open Telegram on your phone or desktop. Search for @BotFather and start a conversation:

  1. Send /newbot
  2. Choose a display name (e.g., "My OpenClaw Assistant")
  3. Choose a username — it must end in bot (e.g., my_openclaw_bot)
  4. BotFather gives you a bot token — copy it. It looks like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Keep this token private. Anyone who has it can control your bot.

Step 2: Configure OpenClaw

Add your Telegram bot token and access policy to the OpenClaw configuration:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
      dmPolicy: "pairing",
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

Alternatively, set the token as an environment variable: TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz.

The dmPolicy: "pairing" setting means new users must be approved before they can chat with your bot. This prevents strangers from using your LLM credits.

Step 3: Start the gateway and approve pairing

Start the OpenClaw gateway:

openclaw gateway

Now open Telegram and send any message to your bot. The gateway will hold the message pending pairing. Approve it from the terminal:

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

That's it. Your OpenClaw Telegram bot is live. Every message you send gets processed by your configured LLM and replied to within the chat.

Telegram group chat setup

To add your bot to group chats, there's one important caveat: Telegram bots default to Privacy Mode, which means they can only see messages that directly mention them or are replies to their messages.

You have two options:

  1. Disable Privacy Mode — Go back to BotFather, send /setprivacy, select your bot, and choose "Disable." Then remove and re-add the bot to each group.
  2. Make the bot a group admin — Admin bots bypass privacy restrictions automatically.

Configure group-specific access in your OpenClaw config:

groups: {
  "-1001234567890": {
    groupPolicy: "open",
    requireMention: false,
  },
}

Important: The allowFrom field expects numeric Telegram user IDs, not usernames. To find your user ID, DM the bot and check the logs with openclaw logs --follow — look for the from.id field.

How to connect OpenClaw to WhatsApp

WhatsApp setup is a bit more involved than Telegram. Instead of an official bot API, OpenClaw connects via the WhatsApp Web protocol (using the Baileys library). You pair it the same way you'd link WhatsApp Web on a new computer — by scanning a QR code.

Step 1: Configure access policy

Before linking your WhatsApp, set up the access policy:

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

Replace the phone number with your actual number in E.164 format (country code + number, no spaces or dashes). The allowFrom field is critical — without it, anyone who knows the number can message your agent and burn through your LLM API credits.

Step 2: Link WhatsApp via QR code

Run the login command:

openclaw channels login --channel whatsapp

A QR code appears in your terminal. Open WhatsApp on your phone:

  1. Go to Settings → Linked Devices
  2. Tap Link a Device
  3. Scan the QR code displayed in your terminal

The connection is established. If you have multiple WhatsApp accounts or want a named connection, use --account:

openclaw channels login --channel whatsapp --account work

Step 3: Start the gateway and approve pairing

Start the gateway process:

openclaw gateway

Send a test message to the WhatsApp number you linked. Then approve the pairing:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Your OpenClaw WhatsApp connection is now live. Messages flow through the gateway to your LLM and back.

Dedicated number vs. personal number

OpenClaw recommends using a dedicated phone number for WhatsApp when possible. Here's why:

  • Cleaner allowlists — You don't need to filter out personal messages
  • No self-chat confusion — Your own messages won't trigger the agent
  • Simpler security — The dedicated number only handles AI conversations

If you prefer using your personal number, enable selfChatMode: true in your config and be aware that the agent may respond to your own messages in certain conditions.

Running both channels at the same time

One of OpenClaw's strengths is running multiple messaging channels simultaneously through a single gateway. Configure both channels in the same config:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-telegram-token",
      dmPolicy: "pairing",
    },
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"],
    },
  },
}

Start the gateway once:

openclaw gateway

Both channels connect through the same process. Messages from Telegram and WhatsApp are routed into OpenClaw's session store, meaning your assistant has shared context across platforms. You can start a conversation on Telegram and continue it on WhatsApp if identities are bound to the same user.

Use openclaw channels status to verify both channels are connected and openclaw channels list to see all configured channels.

Security best practices for OpenClaw messaging channels

Connecting OpenClaw to messaging apps means exposing your LLM to incoming messages. Lock it down:

  1. Always use allowlists — Set allowFrom with specific phone numbers (WhatsApp) or user IDs (Telegram). Never leave access wide open.
  2. Use pairing mode — dmPolicy: "pairing" requires explicit approval for each new user. Pairing codes expire after 1 hour with a max of 3 pending per channel.
  3. Restrict group access — Use groupPolicy: "allowlist" and configure individual groups in the groups object rather than using wildcard open policies.
  4. Monitor logs — Run openclaw channels logs periodically to check for unexpected access attempts.
  5. Keep OpenClaw updated — Especially for the WhatsApp channel, since the WhatsApp Web protocol can change when Meta pushes updates.

Common issues and troubleshooting

WhatsApp QR code won't scan or keeps expiring

QR codes expire after about one hour. If the scan fails, run openclaw channels login --channel whatsapp again for a fresh code. Make sure your phone and server can reach the internet — the pairing requires both sides to connect to WhatsApp's servers.

Telegram bot doesn't respond in groups

This is almost always Privacy Mode. Bots can't see regular group messages by default. Fix it with /setprivacy in BotFather → Disable, then remove and re-add the bot to each group. Alternatively, promote the bot to group admin.

"Pairing required" errors

You need to approve the pairing code before messages are processed. Run openclaw pairing list <channel> to see pending requests, then openclaw pairing approve <channel> <CODE>. If no pairings appear, the allowFrom list may be blocking the user before the pairing step.

WhatsApp disconnects after a few days

The WhatsApp Web session stores credentials on disk and can occasionally drop. This is a known characteristic of the Baileys library — when Meta updates the WhatsApp Web protocol, the session may need to be re-linked. Run openclaw channels login --channel whatsapp again to reconnect.

Messages are received but no response is sent

Check that your LLM API key is valid and has credits. Run openclaw logs --follow to see if the gateway is receiving messages and whether the LLM call is failing. Common causes: expired API key, rate limiting, or a misconfigured model name.

Group chat IDs in the wrong place

A frequent config mistake: putting group chat IDs (negative numbers like -1001234567890) in the groupAllowFrom field. That field is for user IDs only. Group IDs go under channels.telegram.groups as keys.

The easier path: pre-configured templates on ClawAgora

Setting up OpenClaw messaging channels isn't hard, but it does require editing config files, managing a server, and keeping the gateway running 24/7. If you'd rather skip the infrastructure work, ClawAgora offers managed OpenClaw hosting with workspace templates that can pre-configure channel settings.

A template can ship with channel scaffolding — allowlist patterns, group policies, and a ready-made SOUL.md that gives your assistant a personality from the first message. Combined with always-on managed hosting, you go from sign-up to a working WhatsApp and Telegram AI assistant without touching a terminal.

Whether you self-host or use a managed platform, the end result is the same: your AI assistant, available in the messaging apps you already use, ready to help whenever you need it.

Useful commands reference

Command What it does
openclaw channels list View all configured channels
openclaw channels status Check connection status for each channel
openclaw channels login --channel <name> Link a new channel (WhatsApp QR, etc.)
openclaw channels capabilities See per-channel feature support
openclaw channels logs Monitor channel activity
openclaw pairing list <channel> View pending pairing requests
openclaw pairing approve <channel> <code> Approve a pairing request
openclaw gateway Start the gateway process

Further reading