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.

Optional BotFather Settings

While you are in BotFather, configure these additional settings to make your bot look professional:

• /setdescription: The text users see when they first open a chat with your bot. Write something like "Your personal AI assistant powered by OpenClaw. Send a message to get started."
• /setabouttext: Shows in the bot's profile. Keep it short: "AI agent that manages tasks, answers questions, and runs automations."
• /setuserpic: Upload a profile photo. A custom avatar makes the bot feel more personal. Use your brand logo or a distinct icon.
• /setcommands: Add command hints that show up when users type "/". For example: status - Check agent status and help - Show available commands. These are cosmetic hints only. OpenClaw handles command processing internally.

None of these are required. But they take 2 minutes and make the bot feel polished instead of half-finished.

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.

Notification Configuration

By default, your bot sends regular Telegram messages with full notifications. You can control this per-message:

• Silent messages: Your agent can send messages with notification disabled. Useful for non-urgent updates like daily summaries or background task completions. The message still appears in the chat but the user's phone does not buzz.
• Scheduled delivery: Your agent can post cron job results at specific times. Pair this with Telegram's "mute chat" feature to batch notifications. I mute my agent topics and check them on my own schedule.
• Priority flagging: Set up your AGENTS.md so the agent knows what counts as urgent. Urgent items get a regular notification. Everything else goes silent. This prevents notification fatigue while still catching the important stuff.

Channels vs Groups vs DMs

Telegram has three conversation types. Each works differently with OpenClaw:

Type	Best For	Bot Behavior
DM (direct message)	Personal assistant usage	Full two-way conversation. The primary way most people interact with their agent.
Group chat	Team collaboration	Bot responds to mentions or all messages depending on config. Multiple people can interact.
Forum group (topics)	Multi-agent setups	Each topic routes to a different agent. Best for running many agents from one place.
Channel	Broadcasting	Bot can post to channels but cannot receive messages from them. One-way only. Good for automated announcements.

For solo founders, start with DMs. That is the simplest setup: one bot, one conversation, full access to your agent. As you add more agents, switch to a forum group. That is how I run my 13-agent team without drowning in separate chats.

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.

Best Practices for a Production Telegram Setup

After months of running 13 agents through Telegram, here is what I have learned:

• Use forum topics over separate bots. Creating a new bot for every agent seems logical, but it clutters your Telegram sidebar. One forum group with topic-per-agent is cleaner and easier to manage.
• Pin important messages. Your agent can pin messages in chats. Use this for daily briefings, active project links, or anything you reference frequently.
• Set up an allowlist, not pairing. Pairing is convenient for initial setup, but allowlist mode is more robust for production. Your user ID is permanent. Pairing sessions can expire or get lost during gateway restarts.
• Use Telegram's built-in folders. Move your agent chats into a custom Telegram folder. This keeps them organized and separate from personal conversations. On mobile, you can swipe between folders for fast access.
• Gateway as a daemon. On a Mac Mini or VPS, run openclaw gateway as a background service that starts automatically on boot. Use launchd on macOS or systemd on Linux. This ensures your bot survives reboots without manual intervention.
• Monitor uptime. Set up a simple cron job that pings your bot every hour and alerts you if it does not respond. This catches silent failures before you notice them manually.

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

Frequently Asked Questions

How do I create an OpenClaw Telegram bot?

Open Telegram, message @BotFather, use /newbot to create a bot, and copy the token. Add the token to your OpenClaw gateway configuration during onboarding. Your OpenClaw agent will now respond to messages sent to your Telegram bot.

Can I control OpenClaw from Telegram?

Yes, Telegram is one of the most popular ways to interact with OpenClaw. You can send text commands, voice messages, images, and files to your bot. The agent processes them and responds directly in the chat.

Does the OpenClaw Telegram bot support voice messages?

Yes, OpenClaw's Telegram integration supports voice messages, text, images, files, reactions, and inline buttons. You can speak to your agent and it will transcribe and process your voice message automatically.

Can I use my OpenClaw Telegram bot in group chats?

Yes, you can add your OpenClaw bot to Telegram group chats. Configure it to respond to direct mentions or all messages. The agent can participate in group discussions, answer questions, and moderate content based on your instructions.

Is the OpenClaw Telegram bot always available?

Yes, as long as your OpenClaw instance is running (on a Mac Mini, VPS, or always-on machine), the Telegram bot responds 24/7. Messages are processed in real-time through the Telegram Bot API.