OpenClaw Telegram Bot Setup: Complete Guide

Telegram is the best way to talk to your OpenClaw agent. It's fast, it's always in your pocket, and the setup takes about 5 minutes. Here's exactly how to do it.

Why Telegram Is the Best Channel for OpenClaw

OpenClaw supports Telegram, WhatsApp, Discord, Signal, and more. But Telegram is the one most people start with. And for good reason.

It's free. The Bot API is open. You don't need a business account or a phone number dedicated to the bot. You create a bot in 30 seconds, paste a token, and you're talking to your AI agent from your phone.

Telegram also has features that make it uniquely powerful for AI agents: forum topics (so you can run multiple agents in one group), inline buttons, voice message support, reactions, and no message length limits that matter in practice.

I run my entire 13-agent team through Telegram. Every agent has its own forum topic. I can message any of them from anywhere.

Step 1: Create Your Bot with BotFather

Every Telegram bot starts with @BotFather. It's Telegram's official bot for creating and managing bots. Here's the process:

1. Open Telegram and search for @BotFather (make sure it has the blue verified checkmark)
2. Send /newbot
3. Choose a display name (example: "Marc Assistant")
4. Choose a username ending in "bot" (example: "marc_assistant_bot")
5. BotFather gives you a token. Copy it. It looks like: 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

That token is your bot's password. Don't share it publicly. If you leak it, go back to BotFather, send /revoke, and generate a new one.

Step 2: Configure OpenClaw

Now tell OpenClaw about your bot. You have two options:

Option A: Environment variable (quick)

export TELEGRAM_BOT_TOKEN="your-token-here"
openclaw gateway restart

Option B: Config file (recommended for multi-channel setups)

Edit your OpenClaw config (usually ~/.openclaw/config.json5):

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-token-here",
      dmPolicy: "pairing",
      groups: {
        "*": { requireMention: true }
      }
    }
  }
}

Then restart the gateway:

openclaw gateway restart

The dmPolicy: "pairing" setting means new users need to be approved before they can chat with your bot. This keeps random strangers from burning through your API credits.

Step 3: Pair Your Account

With pairing mode enabled, here's how to connect:

1. Open Telegram and send any message to your bot
2. On your server, run: openclaw pairing list telegram
3. You'll see a pairing code. Approve it: openclaw pairing approve telegram YOUR_CODE
4. Pairing codes expire after 1 hour, so don't wait too long

That's it. Send a message to your bot and your OpenClaw agent will respond.

Finding your Telegram user ID (you'll need this for allowlist mode):

• DM your bot, then run openclaw logs --follow and look for the from.id field
• Or use the Bot API directly: curl "https://api.telegram.org/bot<token>/getUpdates"
• Or message @userinfobot on Telegram

Step 4: Add Your Bot to Group Chats

DMs are useful. But groups are where things get interesting.

Add your bot to any Telegram group, then configure which groups it should respond in. By default, OpenClaw uses groupPolicy: "allowlist", meaning you need to explicitly allow each group.

To allow a specific group:

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          groupPolicy: "open",
          requireMention: true
        }
      }
    }
  }
}

Replace -1001234567890 with your actual group ID. To find it: add the bot to the group, send a message, and check openclaw logs --follow for the chat.id value. Group IDs are always negative numbers.

The requireMention: true setting means the bot only responds when someone tags it with @botusername. Set it to false if you want the bot to see and respond to every message.

Running Multiple Agents in Forum Topics

This is the power move. Telegram forum groups let you create topics (like channels within a group). OpenClaw can route different agents to different topics.

Here's how I run my setup: one Telegram forum group, 13 topics, 13 agents. Each agent has its own space. They don't interfere with each other.

The config looks like this:

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },
            "3": { agentId: "dan" },
            "5": { agentId: "tyler" }
          }
        }
      }
    }
  }
}

Each topic gets its own session key, so conversations stay isolated. Agent Dan in topic 3 doesn't see what agent Tyler is doing in topic 5.

To find topic IDs: open the forum topic, send a message, and check openclaw logs --follow for message_thread_id.

Voice Messages, Reactions, and Media

Telegram isn't just text. OpenClaw supports the full range of Telegram features:

Voice messages: Send a voice note to your bot. OpenClaw transcribes it automatically (using Whisper or your configured STT provider) and responds. You can also configure your agent to reply with voice using TTS. It works in both DMs and groups.

Reactions: Your agent can react to messages with emoji. It's a lightweight way for the agent to acknowledge something without sending a full reply. Useful in group chats where you don't want the bot to respond to every single message.

Photos and files: Send images and documents. OpenClaw processes them with vision models (for images) or extracts text (for documents). Your agent can send media back too, including images, videos, and files.

Stickers: OpenClaw can describe stickers it receives using vision models and caches the descriptions to avoid repeated API calls. The cache lives at ~/.openclaw/telegram/sticker-cache.json.

Inline buttons: Your agent can send messages with clickable buttons. Great for confirmations, quick actions, or presenting options without typing.

Common Issues and Fixes

Bot doesn't respond to DMs:

• Check that the gateway is running: openclaw gateway status
• Verify your pairing was approved: openclaw pairing list telegram
• Check logs for errors: openclaw logs --follow

Bot doesn't respond in groups:

• Privacy mode might be enabled. Send /setprivacy to BotFather and disable it, then remove and re-add the bot
• Make sure the group ID is in your config under groups
• Check if requireMention is true. If so, tag the bot

Bot responds slowly:

• This is usually the LLM provider, not Telegram. Check your model's response time
• OpenClaw uses long polling by default. If you need faster response times, consider webhook mode

Token issues:

• If you see auth errors, revoke and regenerate your token via BotFather (/revoke)
• Make sure there are no extra spaces or newlines in your token

For more detailed troubleshooting, check the OpenClaw troubleshooting guide.

Ready to install OpenClaw and connect it to Telegram? Head to installopenclawnow.com to get started in minutes.