Zum Inhalt springen
← Back to English edition

Installing OpenClaw – Part 4: Connecting Telegram & WhatsApp

• openclaw

In this part, you'll learn how to connect OpenClaw with Telegram and WhatsApp – from bot creation to permissions and security settings.

Tutorial OpenClaw Telegram WhatsApp Bot Integration

📚 Series: Installing & Setting Up OpenClaw — Part 4 of 8
← Part 3: Configuring Models | Part 5: Skills & Tools →

In previous parts, we installed OpenClaw and configured the AI models. Now it’s time to set up messaging channels so you can reach your agent via Telegram and WhatsApp.

For WhatsApp, OpenClaw uses a web session with QR-code pairing in the standard setup. This is the most direct way to a working channel for private and small team setups.

Prerequisites

✅ Running OpenClaw Gateway (see Part 2)
✅ Phone number for the Telegram Bot
✅ WhatsApp account (personal or Business) on a smartphone

Setting Up Telegram

Step 1: Create a Bot with BotFather

  1. Open Telegram and start a chat with @BotFather.
  2. Create a new bot with /newbot.
  3. Enter a name (e.g., nexus_bot) and a username (must end with bot, e.g., nexus_agent_bot).
  4. Telegram will give you a bot token.

⚠️ Important: Treat this token like a password – never commit it to Git repos or share it publicly.

Step 2: Store the Token Securely

Store the token securely, e.g., as an environment variable or secret:

export TELEGRAM_BOT_TOKEN="123456:ABC-..."

Or in a secrets file:

{
  "telegram": {
    "botToken": "123456:ABC-..."
  }
}

Step 3: Create Channel Config

Create or extend the config file (~/.openclaw/config.yaml):

channels:
  telegram:
    enabled: true
    botToken: "{{secrets.telegram.botToken}}"

Step 4: Secure DMs and Groups

Telegram bots are publicly discoverable. You should restrict permissions:

Limit DMs to Pairing/Allowlist

channels:
  telegram:
    dmPolicy: "allowlist"
    allowFrom:
      - "123456789"  # Your user ID

How to find your user ID:

  • Start a chat with your bot
  • Send a message
  • Check the logs (openclaw gateway logs) or use a helper bot like @userinfobot

Groups Only on @Mention

channels:
  telegram:
    groups:
      "*":
        requireMention: true

Step 5: Restart Gateway

openclaw gateway restart

Step 6: Test

  1. Send a DM to your bot: /start
  2. Check if the gateway processes the message
  3. If pairing is active: follow the instructions in the bot

Setting Up WhatsApp

OpenClaw uses a WhatsApp Web session via the Baileys library in the standard setup. You pair your account via QR code and can then use the channel like any other messenger.

Step 1: Activate Channel

Add the WhatsApp channel to your config file (~/.openclaw/config.yaml):

channels:
  whatsapp:
    enabled: true
    # Additional options are optional; the gateway uses Baileys by default

Step 2: Restart Gateway

openclaw gateway restart

Step 3: Scan QR Code

  1. Open the OpenClaw Web UI (usually http://localhost:18789)
  2. Navigate to Channels → WhatsApp
  3. You’ll see a QR code
  4. Open WhatsApp on your smartphone, tap ⋮ (menu) → Linked devices → Link a device
  5. Scan the QR code with the camera

Step 4: Confirm Session

After scanning, the session remains active as long as your smartphone is connected to the internet. The gateway can now send and receive messages.

Step 5: Test

Send a message to your own number (or a test group) and check if the agent responds.

WhatsApp Business API (For Reference Only)

If you need an official business integration (scaling, webhooks, Meta verification), OpenClaw also offers a whatsapp-business-api channel. For this you need:

The config then looks like this:

channels:
  whatsapp:
    enabled: true
    provider: "business-api"
    accessToken: "{{secrets.whatsapp.accessToken}}"
    webhookUrl: "https://deine-domain.com/webhook/whatsapp"
    verifyToken: "{{secrets.whatsapp.verifyToken}}"

For larger, officially verified setups, this is relevant. For the normal tutorial path, the WhatsApp channel described above is sufficient.

Troubleshooting

Telegram

  • Bot doesn’t respond at all:

    • Is the gateway running? (openclaw gateway status)
    • Token correct? (echo $TELEGRAM_BOT_TOKEN)
    • Channel enabled? (channels.telegram.enabled: true)

  • Bot responds too much in groups:

    • Enable requireMention: true
    • Use group allowlist

  • Bot never responds in groups:

    • Check privacy mode (@BotFather → Bot Settings → Group Privacy)
    • Bot must be administrator (for certain actions)

WhatsApp Web

  • QR code not displayed:

    • Check if the WhatsApp channel in config has enabled: true
    • Restart the gateway

  • Messages don’t arrive:

    • Make sure your smartphone has internet
    • The WhatsApp Web session can break if you use “Log out from all devices” – then you need to scan again

  • Session breaks frequently:

    • Baileys is based on reverse engineering; if WhatsApp changes the protocol, the connection may temporarily break. Wait for an update from OpenClaw/Baileys.

Security Notes

  1. Never commit API tokens – use secrets or environment variables
  2. Restrict DM policy – allow only known users
  3. Enforce group mentions – prevents spam
  4. Check logs – detect suspicious activities early
  5. WhatsApp Web session is as secure as your smartphone – keep it locked and protected

Sources & Further Links

This article is part of the series “Installing & Setting Up OpenClaw”. The next part will be published soon. If you have questions or suggestions, feel free to write to me on Mastodon or via email.