Setting Up Telegram with OpenClaw — Complete Guide

TL;DR: Create a bot with BotFather, copy the token into your OpenClaw config, start the gateway, and send your bot a message. Takes about 10 minutes — or one click on lobsterfarm.

Telegram is one of the most popular ways to talk to your OpenClaw assistant. Unlike WhatsApp (which requires phone-based pairing), Telegram uses a clean bot API. Once set up, you can message your AI from any device — phone, desktop, web — and it just works.

Here's how to set it up from scratch.

Step 1: Create a Bot with BotFather

BotFather is Telegram's official bot for creating other bots. Yes, it's a bot that makes bots.

1. Open Telegram and search for @BotFather (look for the blue verified checkmark)
2. Start a conversation and send /newbot
3. BotFather will ask for a display name — this is what people see in chat. Pick something like "My AI Assistant" or whatever you want
4. Next, it asks for a username — this must end in bot (e.g., my_ai_assistant_bot). It needs to be globally unique, so you might need a few tries
5. BotFather responds with your bot token — a long string that looks like 7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Keep this token secret. Anyone with this token can control your bot. Don't commit it to a public repo, don't paste it in a group chat.

Optional but Recommended

While you're talking to BotFather, you can also:

• Send /setdescription to set what people see when they first open your bot
• Send /setuserpic to give your bot a profile photo
• Send /setcommands to add command suggestions (like /start, /help)

None of these are required for OpenClaw to work, but they make the experience nicer.

Step 2: Configure OpenClaw with the Token

Now you need to tell OpenClaw about your bot. Open your OpenClaw configuration file — typically config.yaml or config.json in your OpenClaw directory.

Using config.yaml

channels:
  telegram:
    enabled: true
    token: "7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Using config.json

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}

Using Environment Variables

If you prefer not to put the token in a config file:

export TELEGRAM_BOT_TOKEN="7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Then reference it in your config or let OpenClaw pick it up automatically (check your version's docs for the exact env var name — it varies slightly between releases).

Step 3: Start the Gateway

With the token configured, start (or restart) the OpenClaw gateway:

clawdbot gateway restart

Watch the logs for confirmation that the Telegram channel connected:

clawdbot gateway logs

You should see something like:

[telegram] Bot connected: @my_ai_assistant_bot
[telegram] Polling for updates...

If you see errors instead, jump to the troubleshooting section below.

Step 4: Pairing Codes (Group Chats & Permissions)

This is the part that trips most people up.

Why Pairing Codes Exist

By default, your OpenClaw bot will respond to anyone who messages it. That's probably fine if it's just you, but if you're adding the bot to a group chat or want to restrict access, you'll need pairing codes.

How Pairing Works

1. When a new user (or group) first messages your bot, OpenClaw generates a pairing code — a short alphanumeric string
2. The bot replies with something like: "Send the pairing code to authorize this chat"
3. You approve the pairing from your admin interface (the OpenClaw dashboard or CLI)
4. Once approved, that chat is permanently authorized

Approving Pairings

Check pending pairings:

clawdbot pairing list

Approve one:

clawdbot pairing approve <code>

Group Chat Specifics

When adding your bot to a Telegram group:

1. Add the bot to the group like any other member
2. The bot needs to be set as an admin (or have "Read Messages" permission) if the group's privacy settings restrict bot access
3. In BotFather, you may need to disable Group Privacy mode: send /setprivacy and choose "Disable" — this lets the bot see all messages in the group, not just commands
4. The group will need to be paired just like a direct message

Common confusion: People add the bot to a group, send messages, and nothing happens. Usually it's because Group Privacy is still enabled in BotFather, or the group hasn't been paired yet.

Step 5: Send Your First Message

Once everything's configured:

1. Open Telegram
2. Find your bot (search for the username you chose, e.g., @my_ai_assistant_bot)
3. Send /start or just say "Hello"
4. If pairing is required, complete the pairing flow
5. Your AI should respond

If it responds — congratulations! You now have a 24/7 AI assistant in your pocket, accessible from every device where you have Telegram.

What You Can Do Now

• Direct messages: Just chat naturally
• Group chats: Add the bot to groups so everyone can interact with it
• Voice messages: Send voice notes — OpenClaw can transcribe and respond
• Images: Send photos for analysis (if your model supports vision)
• Files: Share documents for your AI to read and work with

Common Pitfalls

"Bot token invalid" or 401 errors

• Double-check you copied the entire token (it's long, easy to miss a character)
• Make sure there are no extra spaces or newlines around the token in your config
• Tokens don't expire, but if you regenerated one via BotFather, the old one stops working immediately

Bot doesn't respond to messages

1. Check the gateway is running: clawdbot gateway status
2. Check the logs: clawdbot gateway logs — look for errors
3. Check pairing: The chat might be waiting for pairing approval
4. Check the model: Is your AI model configured and working? Try a different channel to isolate the issue
5. Check Group Privacy: In group chats, send /setprivacy to BotFather and disable privacy mode

"Conflict: terminated by other getUpdates request"

This means something else is also polling the Telegram API with the same token. Common causes:

• You have two instances of OpenClaw running
• You're running a separate bot script that uses the same token
• A previous instance didn't shut down cleanly

Fix: Stop all instances, wait 30 seconds, then start just one.

Bot works in DM but not in groups

• Send /setprivacy to BotFather → select your bot → choose "Disable"
• Make sure the bot is a member of the group (not just invited)
• Some groups require the bot to be an admin

Messages arrive but responses are empty

This usually isn't a Telegram issue — it's a model/auth issue. Check:

• Your API key is valid and has credits
• The model is configured correctly in your OpenClaw config
• See our fix for no output guide

Tips for a Better Experience

Set Up Commands

Tell BotFather about your bot's commands so Telegram shows them as suggestions:

/setcommands

Then paste:

start - Start the bot
help - Show available commands
clear - Clear conversation context

Use Telegram Topics

If you're using a Telegram supergroup with topics enabled, your bot can respond in specific topic threads. This is great for organizing different conversations — one topic for work, another for personal, another for a specific project.

Mobile Notifications

Telegram's notification system works great with AI bots. You can:

• Mute the bot during work hours but keep it unmuted at night (or vice versa)
• Pin important AI responses
• Use "Saved Messages" to forward and save useful responses

The Easy Way

Setting up Telegram with OpenClaw isn't hard, but it is several steps — and if something goes wrong, debugging token issues and pairing codes isn't anyone's idea of fun.

Don't want to manage server infrastructure? lobsterfarm provides managed OpenClaw hosting — deployment, updates, and support handled for you.

Get started with lobsterfarm →