How to Connect OpenClaw to Telegram: Bot Setup Guide

Channels & Integrations · 10 min read

How to Set Up OpenClaw on Telegram (Complete Guide)

Last updated: February 2026 · Reading time: 7 minutes · Difficulty: Beginner-friendly

Telegram is the easiest messaging channel to set up with OpenClaw. No QR code scanning, no device linking, no session credentials to worry about. You create a bot through Telegram's official BotFather, paste a token into your config, and you're done.

It's also the safest channel. Unlike WhatsApp (which uses the unofficial Baileys library), Telegram has an official Bot API designed specifically for this kind of use. Your personal account stays completely separate — the assistant runs as its own bot with its own identity.

If you're new to OpenClaw or trying to decide which channel to start with, start here.

Before You Start

OpenClaw installed and running. If you haven't done this yet, follow our setup guide first. This guide covers only the Telegram connection.

A Telegram account. Your personal one is fine. You'll create a bot through Telegram's built-in bot management system.

That's it. No phone linking, no additional apps, no OAuth flows.

Step 1: Create a Telegram Bot

Open Telegram on your phone or desktop and search for @BotFather. This is Telegram's official bot for managing bots — it's verified with a blue checkmark.

Start a conversation and send:

/newbot

BotFather asks you two questions:

Choose a name for your bot. This is the display name people see — something like "My Assistant" or "Fred's AI" or whatever you want. It doesn't need to be unique.
Choose a username. This must be unique and end in "bot". Something like freds_assistant_bot or myopenclaw_bot. If your first choice is taken, try adding numbers or underscores.

BotFather responds with your bot token — a long string that looks like:

7234567890:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw

Copy this token. You'll need it in the next step.

Step 2: Add the Token to OpenClaw

You have two options for adding the token.

Option A: During onboarding (new installs)

If you haven't finished the onboarding wizard yet, it asks about messaging channels. Select Telegram and paste the token when prompted.

openclaw onboard

Option B: Edit your config (existing installs)

Open your config file:

nano ~/.openclaw/openclaw.json

Add (or update) the Telegram section:

{
    "agent": {
        "model": "anthropic/claude-sonnet-4-5"
    },
    "channels": {
        "telegram": {
            "botToken": "7234567890:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw"
        }
    }
}

Replace the token with your actual one from BotFather.

You can also use an environment variable instead of hardcoding the token:

export TELEGRAM_BOT_TOKEN="7234567890:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw"

Environment variables take priority over the config file, and they're slightly more secure since the token doesn't sit in a plaintext JSON file.

Save and restart:

openclaw restart

Step 3: Message Your Bot

Open Telegram, search for your bot by its username (the one ending in "bot"), and send a message:

Hey, are you there?

You should get a response within a few seconds. That's it — your Telegram assistant is live.

Step 4: Set Up DM Pairing (Security)

By default, OpenClaw uses DM pairing on Telegram. This means when a stranger messages your bot, they get a short pairing code instead of a response. The bot won't process their messages until you approve them.

To approve someone:

openclaw pairing approve telegram <code>

Where <code> is the pairing code they received.

If you want to restrict access further, set up an explicit allowlist:

{
    "channels": {
        "telegram": {
            "allowFrom": ["your_telegram_username", "trusted_friend"]
        }
    }
}

Only users in this list can interact with your bot. Everyone else gets ignored entirely.

This matters because unlike WhatsApp (where people need your phone number to message you), anyone who finds your Telegram bot's username can try to talk to it. Keep pairing enabled or use an allowlist.

Setting Up Group Chats

Telegram group chats are where OpenClaw really shines. Add your bot to a group and it becomes a shared assistant for everyone in that group.

First, add group support to your config:

{
    "channels": {
        "telegram": {
            "botToken": "YOUR_TOKEN",
            "groups": {
                "*": {
                    "requireMention": true
                }
            }
        }
    }
}

The "*" allows all groups. The requireMention flag means the bot only responds when someone @mentions it — it won't jump into every conversation.

Now add your bot to a Telegram group. You can mention it like @myopenclaw_bot what's the weather tomorrow? and it responds to that specific question without interfering with normal group conversation.

To restrict to specific groups instead of allowing all:

{
    "channels": {
        "telegram": {
            "groups": {
                "My Family Group": {
                    "requireMention": true
                },
                "Work Team": {
                    "requireMention": true
                }
            }
        }
    }
}

Cost warning: In group chats, every message from every member gets processed by the gateway (even if the bot doesn't respond), which consumes tokens. With requireMention enabled, the AI model is only called when the bot is mentioned, but the gateway still sees all messages. Keep groups small and purposeful.

Customizing Your Bot's Profile

BotFather lets you customize how your bot looks in Telegram. Send /mybots to BotFather, select your bot, and you can change:

Profile photo — Give your bot an avatar. A simple icon or the OpenClaw lobster logo works well.

Description — What people see before they start a conversation. Something like "Personal AI assistant powered by OpenClaw."

About text — A short bio that appears on the bot's profile.

Commands list — You can register slash commands that appear when someone types / in the chat. Send /setcommands to BotFather, select your bot, and paste:

new - Start a fresh conversation
compact - Summarize and trim context
status - Show session info and usage
think - Set thinking level (off/low/high)

These are the OpenClaw chat commands mapped as Telegram commands. Users can now tap them instead of typing.

Webhooks vs Polling

By default, OpenClaw uses long polling to receive Telegram messages — it repeatedly asks Telegram's servers "any new messages?" This works fine for personal use.

For better performance (especially on a VPS), you can switch to webhooks — where Telegram pushes messages to your server instead of OpenClaw pulling them. This is faster and uses less bandwidth.

Add webhook configuration to your config:

{
    "channels": {
        "telegram": {
            "botToken": "YOUR_TOKEN",
            "webhookUrl": "https://your-server.example.com/telegram/webhook",
            "webhookSecret": "a-random-secret-string-here"
        }
    }
}

This requires your server to be reachable from the internet with HTTPS. If you're using Tailscale Funnel, that works. A VPS with a domain and SSL certificate works too.

For most personal setups, polling is perfectly fine. Don't bother with webhooks unless you notice lag or you're running the bot for multiple users.

Handling Media

Your Telegram bot can process all the media types Telegram supports.

Photos: Send a photo and ask "what's in this image?" or "read the text in this picture." Works great for receipt scanning, document photos, or identifying things.

Voice messages: Send a voice note and the assistant transcribes it, then responds to the content. Some people have entire conversations with their assistant purely through voice notes.

Documents: Send PDFs, text files, or spreadsheets. The assistant can summarize them, extract data, or answer questions about their content.

Videos: Short clips can be processed. Useful for "what's happening in this video?" or "transcribe what they're saying."

Stickers and GIFs: The assistant can see and describe these, though there's rarely a practical use case beyond entertainment.

Telegram compresses media less aggressively than WhatsApp, so image quality is generally better for things like reading text in photos.

Chat Commands

These slash commands work in any Telegram conversation with your bot:

Command	What it does
`/new` or `/reset`	Start a fresh conversation
`/compact`	Summarize and trim conversation context
`/status`	Show model, token count, and session info
`/think high`	Enable deep thinking for complex questions
`/think off`	Faster, cheaper responses
`/verbose on`	Detailed responses
`/verbose off`	Concise responses
`/usage full`	Show per-message cost breakdown
`/restart`	Restart the gateway (owner only)

The most useful daily commands: /new when switching topics (saves tokens), /compact when conversations get long (keeps things fast), and /status to monitor your API spending.

Telegram vs WhatsApp: Which Should You Use?

Both work well. Here's how they compare for OpenClaw use.

	Telegram	WhatsApp
Setup difficulty	Easy (bot token)	Moderate (QR code linking)
Official API	Yes (Bot API)	No (unofficial Baileys library)
Account risk	None	Low (ToS technically violated)
Connection stability	Excellent (never drops)	Good (can disconnect after 14 days offline)
Group chats	Excellent (mention-based)	Good (mention-based)
Media quality	Higher	More compressed
Where your friends are	Maybe	Probably

The last row is what matters most. If everyone you message is on WhatsApp, having your assistant there too means you'll actually use it. If you're comfortable with Telegram, it's technically the better platform for OpenClaw.

Many people run both. Telegram for personal AI assistant use, WhatsApp because that's where their contacts are. OpenClaw handles both simultaneously.

→ Set up WhatsApp too

Troubleshooting

Bot doesn't respond

Check the gateway logs:

openclaw doctor

The most common cause is a wrong or expired bot token. Regenerate your token through BotFather (/mybots → select bot → API Token → Revoke token) and update your config.

"403 Forbidden" in logs

Your bot token is invalid. Double-check you copied the full token including the colon in the middle. If you revoked and regenerated the token, make sure the new one is in your config.

Bot responds slowly

Send /compact to trim conversation context. Long conversation histories are the biggest cause of slow responses. If it's still slow, check whether your AI model is the bottleneck — Sonnet is faster than Opus.

Bot responds to random people

DM pairing should prevent this by default. If you disabled it, enable it again or set up an explicit allowlist. Check your config for dmPolicy: "open" and remove it.

Can't add bot to a group

Make sure the bot has group permissions. In BotFather, send /mybots, select your bot, then Bot Settings → Allow Groups. Ensure "Group Privacy" is either on or off depending on your needs — when privacy mode is on, the bot only sees messages that mention it or are replies to its messages (which is what you usually want).

Frequently Asked Questions

Can I run multiple Telegram bots?

Yes. Create multiple bots through BotFather and configure each with its own token. OpenClaw can route different bots to different agents with separate workspaces and configurations. Useful if you want one bot for personal use and another for a team.

Will my Telegram account get banned?

No. You're using the official Telegram Bot API, which is designed for exactly this purpose. Unlike WhatsApp, there's zero platform risk.

Is Telegram or WhatsApp cheaper to run?

They're the same. The cost is in the AI model tokens, not the messaging platform. The same conversation costs the same regardless of which channel it happens on.

Can people find my bot through Telegram search?

Yes, if they search for the exact username. But with DM pairing enabled, finding the bot doesn't mean they can use it. They'd need you to approve their pairing code.

New to OpenClaw? Start with our setup guide. Want to run your bot 24/7? Check our hosting comparison or Docker guide. Curious about costs? See our full breakdown.