connect

Connect OpenClaw to Telegram (Step-by-Step)

Learn how to connect OpenClaw to Telegram and chat with AI through your favorite messaging app. Complete beginner guide with screenshots.

9 min read
Updated 2026-02-03

What You Will Achieve

By following this guide, you will connect OpenClaw to Telegram. Once connected, you can send messages to your Telegram bot and receive AI-powered responses. This is one of the most popular ways to use OpenClaw because Telegram works on phones, tablets, and computers.

What is a Telegram Bot?

A Telegram bot is like an automated account that can receive and send messages. You will create your own bot, and OpenClaw will control it. When you send a message to your bot, OpenClaw receives it, asks the AI for a response, and sends the reply back to you through Telegram.

Before You Start

Make sure you have completed these steps:

  1. OpenClaw is installed and running on your computer
  2. You have a Telegram account (free to create at telegram.org)
  3. Telegram app is installed on your phone or computer

Check OpenClaw Status First

Before continuing, open your terminal and run openclaw status. You should see "Gateway: running". If not, start OpenClaw first by running openclaw gateway --daemon.

Verify OpenClaw is running:

bash
openclaw status

Expected Result

Gateway: running Port: 18789 Auth: configured

Understanding the Process

Here is what we will do:

  1. Create a Telegram bot using Telegram's official bot creation tool (BotFather)
  2. Get a Bot Token (a secret password that lets OpenClaw control your bot)
  3. Add the token to OpenClaw so it can connect to your bot
  4. Test the connection by sending a message

What is a Bot Token?

A Bot Token is a long string of letters and numbers that acts like a password for your bot. Anyone with this token can control your bot, so keep it secret. It looks something like: 7123456789:AAHxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxx

Step-by-Step Setup

1

Open Telegram and Find BotFather

BotFather is Telegram's official tool for creating bots. It is itself a bot that you chat with to create new bots.

On your phone or computer:

  1. Open the Telegram app
  2. Tap the search icon (magnifying glass)
  3. Type @BotFather in the search box
  4. Look for the account with a blue checkmark (this is the official BotFather)
  5. Tap on BotFather to open a chat

Watch Out for Fakes

There are fake BotFather accounts. The real BotFather has a blue verification checkmark next to its name and the username is exactly @BotFather (capital B and F). Do not use any other account.

Expected Result

You are now in a chat with BotFather. You should see a welcome message and a list of commands.

2

Create Your Bot

Now we will tell BotFather to create a new bot for you.

In the BotFather chat:

  1. Type /newbot and send the message
  2. BotFather will ask: "Alright, a new bot. How are we going to call it?"
  3. Type a name for your bot (this is what people see, like "My AI Assistant")
  4. Send the message
  5. BotFather will ask for a username for your bot
  6. Type a username that ends with bot (like myai_assistant_bot or JohnAIBot)

Choosing a Bot Username

The username must:

  • End with bot or Bot (like myassistant_bot)
  • Be unique (not already taken by another bot)
  • Only contain letters, numbers, and underscores
  • Be at least 5 characters long

If your chosen name is taken, try adding numbers or underscores, like myassistant_2024_bot.

Expected Result

BotFather responds with: "Done! Congratulations on your new bot." You will see your Bot Token displayed in the message. It looks like: 7123456789:AAHdqTxxxxxxxxxxxxxxxxxxxxxxxx

Important: Copy your Bot Token now! You will need it in the next step. Tap and hold the token to copy it, or write it down somewhere safe.

3

Add the Bot Token to OpenClaw

Now we need to tell OpenClaw about your new bot by giving it the token. There are two ways to do this:

Method A: Using Environment Variable (Recommended for beginners)

Set the token as an environment variable before starting OpenClaw:

export TELEGRAM_BOT_TOKEN="7123456789:AAHdqTxxxxxxxxxxxxxxxxxxxxxxxx"

Make It Permanent

To keep this setting after restarting your computer, add the export line to your ~/.bashrc or ~/.zshrc file.

Method B: Using Configuration File

Edit the OpenClaw configuration file at ~/.openclaw/openclaw.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "7123456789:AAHdqTxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}

How to Edit the Config File

  • On Mac/Linux: Run nano ~/.openclaw/openclaw.json in Terminal
  • On Windows (WSL): Run nano ~/.openclaw/openclaw.json in Ubuntu
  • Save the file with Ctrl+O, then exit with Ctrl+X

Expected Result

After saving, your configuration file contains your Telegram bot token.

If you see an error later, double-check that you copied the entire token correctly. The token is quite long and easy to miss characters.

4

Restart the OpenClaw Gateway

For the new channel to work, we need to restart OpenClaw's gateway.

bash
openclaw gateway restart

Wait a few seconds for the gateway to restart.

Expected Result

Stopping gateway... Starting gateway... Gateway started successfully Channels: telegram (connected)

5

Send Your First Message

Now let us test that everything works!

On Telegram:

  1. Go back to Telegram
  2. Search for your bot by its username (the one ending in bot that you created)
  3. Open a chat with your bot
  4. Type a message like "Hello!" and send it

First Message: Pairing Required

The first time you message your bot, OpenClaw needs to verify that you are allowed to use it. This is called "pairing" and it prevents strangers from using your AI.

What happens next:

  1. Your bot will reply with a pairing code (a 6-digit number)
  2. Go to your terminal and run:
bash
openclaw pairing list telegram

You will see your pending pairing request with the code.

  1. Approve the pairing:
bash
openclaw pairing approve telegram 123456

Replace 123456 with the actual pairing code shown.

Expected Result

Pending pairing requests: [1] Telegram: @your_username (Code: 123456)

Approve which request? 1 Pairing approved for @your_username

6

Test Your AI Connection

Now that pairing is complete, send another message to your bot:

  1. Go to Telegram
  2. Open the chat with your bot
  3. Type "What can you help me with?" and send

Expected Result

Your bot should respond with an AI-generated message within a few seconds.

Congratulations!

You have successfully connected OpenClaw to Telegram! You can now chat with AI through Telegram on any device.

Common Problems and Solutions

Bot does not respond at all

Check if OpenClaw is running:

bash
openclaw status

If the gateway is not running, start it:

bash
openclaw gateway --daemon

"Invalid token" error

This means the Bot Token you entered is incorrect.

Solution:

  1. Go back to BotFather on Telegram
  2. Send /mybots
  3. Select your bot
  4. Click "API Token" to see your token again
  5. Copy the entire token carefully
  6. Run openclaw channels remove --channel telegram then openclaw channels add --channel telegram --token YOUR_TOKEN again

Pairing code not appearing

If you sent a message but did not receive a pairing code:

  1. Make sure the gateway is running: openclaw status
  2. Check the logs for errors: openclaw logs --limit 20
  3. Try restarting the gateway: openclaw gateway restart

Bot replies very slowly

Slow responses are usually caused by:

  1. Slow internet connection: Check your internet
  2. AI provider issues: The AI service might be experiencing high load
  3. First message delay: The first message after starting OpenClaw may be slower

"Channel already exists" error

If you already added Telegram before:

bash
openclaw channels remove --channel telegram
openclaw channels add --channel telegram --token YOUR_TOKEN

This removes the old configuration and lets you start fresh.

Bot says "Pairing required" every time

This happens if pairing was not completed or was rejected.

bash
openclaw pairing list telegram

If you see pending requests, approve them:

bash
openclaw pairing approve telegram CODE

Replace CODE with the actual pairing code.

Customizing Your Bot

Change Bot Profile Picture

  1. Open BotFather on Telegram
  2. Send /mybots
  3. Select your bot
  4. Click "Edit Bot"
  5. Click "Edit Botpic"
  6. Send an image to use as profile picture

Change Bot Description

  1. Open BotFather on Telegram
  2. Send /mybots
  3. Select your bot
  4. Click "Edit Bot"
  5. Click "Edit Description"
  6. Type the description users will see when they first open a chat

Add Bot Commands Menu

You can add a menu of commands that appears when users type /:

  1. Send /mybots to BotFather
  2. Select your bot
  3. Click "Edit Bot"
  4. Click "Edit Commands"
  5. Send a list in this format:
help - Show help message
start - Start chatting
status - Check bot status

Security Tips

Keep Your Bot Token Secret

Never share your Bot Token with anyone. If someone gets your token, they can control your bot. If you think your token was leaked, revoke it immediately through BotFather.

To revoke and get a new token:

  1. Open BotFather
  2. Send /mybots
  3. Select your bot
  4. Click "API Token"
  5. Click "Revoke current token"

This will generate a new token. Remember to update OpenClaw with the new token:

bash
openclaw channels remove --channel telegram
openclaw channels add --channel telegram --token YOUR_TOKEN

Using Telegram on Multiple Devices

One great thing about Telegram is that it works on multiple devices at the same time. Once you set up OpenClaw:

  • Chat with your AI on your phone while on the go
  • Continue the conversation on your computer at home
  • Use Telegram Web (web.telegram.org) from any browser

Your conversation history syncs across all devices automatically.

What To Do Next

Now that Telegram is connected, explore these options:

  1. Connect to Discord - Add AI to your Discord server
  2. Connect to WhatsApp - Use AI through WhatsApp
  3. Multi-Channel Setup - Use multiple platforms at once
  4. Your First Agent - Learn to customize AI responses

Need Help?

If you run into problems not covered here, check our Troubleshooting guide or visit the official OpenClaw documentation.

Last updated: February 3, 2026 | Found an error? Contact us

Related Articles

Connect

Connect OpenClaw to Discord (Step-by-Step)

Connect

Connect OpenClaw to WhatsApp (Step-by-Step)

Connect

Use OpenClaw on Multiple Channels