OpenClaw Telegram Pairing: How to Connect Your Bot [2026]

How Do You Create a Telegram Bot?

Creating a Telegram bot takes about two minutes. Here is the exact process:

1. Open Telegram on your phone or desktop.
2. Search for @BotFather — this is Telegram's official bot for creating and managing bots. Look for the blue verified checkmark.
3. Send /newbot to BotFather.
4. Choose a display name. This is what users see in the chat header. It can contain spaces and special characters. Example: "My AI Assistant"
5. Choose a username. This must end in "bot" and be unique across all of Telegram. Example: "myai_assistant_bot"
6. Copy the API token. BotFather responds with a message containing your token. It looks like: 7123456789:AAHjk3lm_nopqrst-UVwxyz1234567890

Save this token securely. Anyone who has this token can control your bot — send messages, read conversations, and change settings. Do not share it publicly, commit it to a public repository, or post it in chat messages.

If your token is ever compromised, immediately go to BotFather, send /revoke, and select your bot to generate a new token. The old token becomes invalid instantly.

How Do You Add the Token to OpenClaw?

There are two ways to add the token to OpenClaw:

Method 1: Environment variable (recommended).

Add the token to your .env file:

TELEGRAM_BOT_TOKEN=7123456789:AAHjk3lm_nopqrst-UVwxyz1234567890

Then restart OpenClaw:

docker compose restart

Method 2: Setup wizard.

If you are running the setup wizard (first-time setup), paste the token in the Telegram field during the messaging platform step. The wizard saves it to config.json automatically.

After adding the token, check the OpenClaw logs to verify the connection:

docker compose logs openclaw | grep -i telegram

You should see:

[telegram] Connected as @myai_assistant_bot
[telegram] Polling for updates...

If you see an error instead, the token is likely wrong. Double-check that you copied the entire token including the colon and both parts.

How Do You Disable Group Privacy?

By default, Telegram bots can only see messages that mention them directly (@botname) or are commands (starting with /). In group chats, the bot cannot see regular messages. To change this:

1. Open Telegram and message @BotFather.
2. Send /setprivacy.
3. Select your bot from the list.
4. Choose Disable.

BotFather responds with: "Privacy mode is disabled for @myai_assistant_bot. The bot will be able to receive all messages in groups."

After disabling privacy, remove and re-add the bot to any existing groups. The privacy setting change only takes effect for groups the bot joins after the change. Groups the bot was already in will still operate under the old privacy setting.

Note: disabling group privacy means the bot receives every message in every group it belongs to. If the bot is in a busy group, this can increase API costs significantly. Use the TELEGRAM_GROUP_MODE setting in OpenClaw to control how the agent handles group messages (respond to all, respond only when mentioned, or respond only to commands).

How Do You Test the Connection?

After configuring the token and restarting OpenClaw:

1. Open Telegram and find your bot (search for its username).
2. Send /start — this is required for all new bot conversations in Telegram. The bot cannot message you until you initiate contact.
3. Send a test message — something simple like "Hello, are you working?"
4. Wait for a response. The first response may take 5-15 seconds as the AI model processes the request.

If the bot responds, pairing is complete. Your OpenClaw agent is now connected to Telegram.

If the bot does not respond within 30 seconds, check the OpenClaw logs for errors:

docker compose logs --tail=50 openclaw

Look for error messages related to Telegram, the model API (authentication failures, rate limits), or general startup errors.

How Do You Restrict Which Users Can Interact?

By default, anyone who finds your bot on Telegram can message it. Each message triggers an AI model API call, which costs money. You should restrict access to authorized users.

Find your Telegram user ID. Message @userinfobot on Telegram. It replies with your user ID (a number like 123456789).

Set allowed users in .env:

TELEGRAM_ALLOWED_USERS=123456789,987654321

Comma-separated list of user IDs. Only these users can interact with the bot. Messages from other users are silently ignored.

For group chats, you can also restrict which groups the bot operates in:

TELEGRAM_ALLOWED_GROUPS=-1001234567890,-1009876543210

Group IDs in Telegram start with -100. You can find a group's ID by adding @userinfobot to the group and checking its response.

If you want the bot to respond to unauthorized users with a specific message (instead of ignoring them silently), set:

TELEGRAM_UNAUTHORIZED_MESSAGE="This bot is private. Contact the owner for access."

How Do You Troubleshoot Pairing Issues?

Here are the most common issues and their fixes:

"Telegram connection failed: Unauthorized" — The bot token is invalid. Go to BotFather, check that the token matches, or revoke and generate a new one.

Bot does not respond but no errors in logs — You probably have not sent /start to the bot. Telegram requires users to initiate contact before the bot can respond.

"Telegram conflict: terminated by other getUpdates request" — Another OpenClaw instance (or another bot framework) is using the same token. Each token can only have one active polling connection. Stop the other instance or create a new bot.

Bot responds in DM but not in groups — Group privacy is enabled. Follow the steps above to disable it via BotFather, then remove and re-add the bot to the group.

"Connection timeout" or "Network unreachable" — Your server cannot reach api.telegram.org. This is common on corporate networks, some cloud providers, and in countries where Telegram is restricted. Check firewall rules and DNS resolution. If Telegram is blocked, you may need to configure a proxy.

Slow responses (30+ seconds) — This is usually an AI model API issue, not a Telegram issue. Check your model provider's status page. Also check if you are hitting rate limits. OpenClaw logs the model response time for each request.

Messages appear in logs but bot does not reply — Check if the user is in TELEGRAM_ALLOWED_USERS. Also check if the AI model returned an error (insufficient credits, context length exceeded, etc.).