Telegram Bot Setup

Connect OpenClaw to Telegram in 10 minutes. BotFather token, one config update, done. Talk to your self-hosted AI agent from anywhere.

10 min Beginner Free Updated May 2026
01 / Introduction

Your Agent, Now in Your Pocket

Discord works great at a desk. Telegram is great everywhere else. It's faster, lighter, and the mobile experience is genuinely excellent - which matters when you want to ask your AI something while you're standing in line at the grocery store.

Adding Telegram takes about ten minutes. You create a bot through Telegram's @BotFather, grab a token, drop it into your OpenClaw config, and you're done. One agent - two channels. Both work at the same time.

What You Need Before Starting

Prerequisites
  • OpenClaw installed and running - AWS EC2 or mini PC setup complete. If you haven't done that yet, start with AWS EC2 Setup or Mini PC Setup.
  • A Telegram account - free, takes two minutes at telegram.org or the mobile app. Any phone number works.
  • SSH access to your server - you'll need to paste a command or edit a config file. Nothing complicated.

That's it. No API keys to buy, no developer portal to navigate, no permissions to configure. Telegram makes bot creation deliberately simple.

Why Telegram Instead of (or Alongside) Discord?

Mobilebetter experience
Telegram's mobile app is noticeably faster than Discord's. If you're asking your agent quick questions from your phone, Telegram feels snappier and uses less battery.
Simplicityjust a chat
No server to manage, no channels, no roles. You find your bot by username, tap Start, and you're talking. That's the whole onboarding process on Telegram's end.
Already therefor some people
A lot of people already use Telegram daily for family groups or work chats. Having your AI agent live in the same app you already have open is genuinely convenient.
Both at onceno compromise
You don't have to choose. One OpenClaw instance handles Discord and Telegram simultaneously. Same agent, same memory, same config - you just pick whichever app you feel like using in the moment.

What You're Building

By the end of this tutorial:

  • ✓ A Telegram bot created via @BotFather
  • ✓ Bot token added to your OpenClaw config
  • ✓ Telegram channel active alongside any existing channels
  • ✓ First real conversation from your phone
Time estimate: about 10 minutes. The BotFather process takes two minutes. The OpenClaw config update takes one. The rest is waiting for a restart and sending your first message. Genuinely one of the fastest setups in these tutorials.
02 / Create Your Bot

BotFather - Two Minutes to a Token

BotFather is Telegram's official bot for creating bots. Yes, that's a bit circular. It's a verified Telegram account that handles the whole creation flow through a simple conversation. No web portals, no developer accounts, no payment methods. Just chat.

Watch out for fakes. BotFather has a blue verified checkmark next to its name. Search for @BotFather and confirm the checkmark before you start. Impersonators exist and they want your tokens.

Step 1 - Open BotFather

1aTelegram
Open Telegram (mobile or desktop - either works) and search for @BotFather
1bTelegram
Confirm you're looking at the right one - it should have a blue verified checkmark next to the name, and the username should be exactly @BotFather
1cTelegram
Tap Start (or send /start) to begin the conversation. BotFather will respond with a list of commands.

Step 2 - Create a New Bot

2aBotFather
Send the command: /newbot
2bName
BotFather asks: "Alright, a new bot. How are we going to call it? Please choose a name for your bot."

This is the display name - what people see in chat. It can be anything. Something like My OpenClaw or ClawBot works fine. You can change this later.
2cUsername
BotFather asks: "Good. Now let's choose a username for your bot. It must end in 'bot'."

This is the permanent handle - used in search and in direct links like t.me/yourbotname. It must be unique across all of Telegram and must end in bot. Try something like myopenclaw_bot or YourNameClawBot. If it's taken, add some numbers or try a different name.
Username rules: 5-32 characters, letters, numbers, and underscores only. Must end in bot. Case-insensitive - MyBot and mybot are the same. You can't change the username once it's set, so pick something you won't regret.

Step 3 - Save Your Token

When the username is accepted, BotFather responds with something like this:

📱 BotFather response
Done! Congratulations on your new bot. You will find it at t.me/myopenclaw_bot.
You can now add a description, about section and profile picture for your bot,
see /help for a list of commands.

Use this token to access the HTTP API:
7123456789:AAHdqTcvCH1vGWJxfSeofSPs0Urc3yXmxuM

Keep your token secure and store it safely, it can be used by anyone to
control your bot.

That long string after the colon is your bot token. Copy it now and save it somewhere safe - a password manager or a private notes app. You'll paste it into OpenClaw in the next section.

Treat this like a password. Anyone with your bot token can send messages as your bot and interact with your OpenClaw agent. If it ever gets exposed - a screenshot shared online, a GitHub commit - go back to BotFather, send /revoke, select your bot, and grab a new token. Update your OpenClaw config and restart the gateway. Takes two minutes to close the hole.
Token formatreference
Telegram bot tokens always follow the pattern: XXXXXXXXX:YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
Numbers, then a colon, then a mix of letters and numbers. If yours looks like that, you've got the right thing.

Optional: Set a Description

BotFather lets you set a description and profile photo for your bot. This is completely optional and doesn't affect how OpenClaw works - skip it for now and come back later if you want.

If you do want to set a description now: send /setdescription to BotFather, select your bot, and type whatever you want. It's the text people see before they start a chat.

Bot created. You now have a Telegram bot with a token. That's the hard part done - next is dropping the token into OpenClaw and restarting the gateway.
03 / Connect to OpenClaw

Add Telegram to Your Config

You have a bot token. Now you tell OpenClaw about it. There are two ways to do this: the interactive openclaw channels add command (easiest), or editing the config file directly (more control). Either gets you to the same place.

Method 1 - Interactive (Recommended)

SSH into your server and run:

☁️ Server
openclaw channels add

OpenClaw will walk you through a short wizard:

Channelselect
Select Telegram from the list of available channels
Tokenpaste it
Paste the bot token you got from BotFather. It looks like 7123456789:AAHdqTcvCH1vGWJxfSeofSPs0Urc3yXmxuM
dmPolicypairing
Choose pairing. This means new users have to be explicitly approved before they can chat with your agent. Keeps random people out if they ever find your bot username.

The wizard writes the config for you and can restart the gateway automatically. If it asks whether to restart, say yes.

Method 2 - Edit openclaw.json Directly

If you prefer to see exactly what's happening, or the interactive command isn't available, edit the config file directly. First, make a backup:

☁️ Server
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
nano ~/.openclaw/openclaw.json

Use Ctrl+W in nano to search for channels. You'll either find an existing channels block (if Discord is already set up) or you won't see one at all.

If you already have Discord:

📄 Add telegram alongside Discord
channels: {
  discord: {
    enabled: true,
    token: "${DISCORD_BOT_TOKEN}",
    dmPolicy: "pairing"
  },
  telegram: {
    enabled: true,
    token: "YOUR_TELEGRAM_BOT_TOKEN",
    dmPolicy: "pairing"
  }
}

If you don't have any channels yet:

📄 Add after the gateway block
channels: {
  telegram: {
    enabled: true,
    token: "YOUR_TELEGRAM_BOT_TOKEN",
    dmPolicy: "pairing"
  }
}
Don't paste your token in plaintext if you can help it. It works for testing, but the right way is to use an environment variable reference: token: "${TELEGRAM_BOT_TOKEN}". Then set the variable in your shell profile or systemd service file. Full walkthrough in Securing Your Secrets.

Save and exit: Ctrl+O, Enter, Ctrl+X.

Validate and Restart

Before restarting, check for typos:

☁️ Server
openclaw doctor

openclaw doctor parses your config, checks for schema errors, and tells you if any environment variables are missing - without actually restarting anything. If it says something is wrong, fix it before moving on.

Once doctor is happy, restart the gateway:

☁️ Server
openclaw gateway restart

Give it 15-20 seconds. The gateway is now polling Telegram's servers for incoming messages. Your bot is alive - it just hasn't said hello yet.

Hot-reload note. OpenClaw's hybrid reload mode can apply channel config without a full restart. If you edited the file and saved, it might have picked up the change already. Running openclaw gateway restart explicitly is always safe - it just makes sure.
Telegram is connected. Your bot is online and waiting for someone to say hi. That someone is you, in the next section.
04 / Your First Chat

Say Hello

Your bot is running. Now you find it on Telegram, tap Start, and have your first conversation with your self-hosted AI agent from your phone.

Step 1 - Find Your Bot

SearchTelegram
Open Telegram and search for your bot's username - the one you set in BotFather. For example, if you named it myopenclaw_bot, search for that exactly.
Starttap it
Tap the bot in the search results, then tap Start at the bottom of the screen (or send /start). This opens a DM chat with your bot.

You can also use the direct link BotFather gave you: t.me/yourbotname. Open it in Telegram and tap Start.

Step 2 - Handle Pairing (if prompted)

If you set dmPolicy: "pairing", your bot might respond with a message asking for a pairing code - something like:

📱 Telegram - bot response
Hi! This OpenClaw instance requires pairing.
Please send your pairing code: /pair XXXXXX

Or have an admin run:
  openclaw pairing approve telegram XXXXXX

To approve yourself, SSH to your server and run the command it shows:

☁️ Server
openclaw pairing approve telegram XXXXXX

Replace XXXXXX with the actual code from the Telegram message. Once approved, go back to Telegram and send any message - you're connected.

Not seeing a pairing prompt? Some OpenClaw configurations skip the pairing step on first contact if the bot isn't set to require it. If your bot just responds normally, you're already paired. Lucky you - skip ahead to Step 3.

Step 3 - Talk to Your Agent

Once connected, just type. No commands, no @mentions. This is a direct message chat - everything you send goes straight to your OpenClaw agent.

Try something simple first:

📱 Telegram - try this
What time is it on my server right now?

Or if you have memory files set up:

📱 Telegram
Remind me what I asked you to help me with yesterday.
That's it. You're talking to your self-hosted AI agent from Telegram. Running on your hardware, using your config, with your memory files - accessible from anywhere in the world with a mobile signal. That's a genuinely powerful setup you built yourself.

DMs vs Groups

Direct messages (what you just set up) are the best way to use OpenClaw on Telegram. Just you and your agent, no noise, no @mentions needed. This is where you'll spend most of your time.

You can also add your bot to a Telegram group, but there's a catch: Telegram's default "privacy mode" means bots in groups only receive messages that start with /. So if you type something normally in a group, your bot won't see it.

To use OpenClaw naturally in a group (without slash commands), you'd need to disable privacy mode via BotFather. For now, stick with DMs - they work perfectly out of the box and are the right tool for personal AI use.

05 / Tips & Security

Lock It Down, Use It Well

Your agent is running. These are the things worth knowing before you start using it heavily - security settings that matter, how to tighten access, and what to do if something goes wrong.

Lock Down Who Can Access Your Bot

The default dmPolicy: "pairing" means new users need to be explicitly approved before they can chat. That's a good baseline. But you can go tighter.

If this bot is only ever going to be you, switch to an allowlist. You'll need your Telegram user ID - the easiest way to find it is to message @userinfobot on Telegram. It'll reply with your user ID number instantly.

📄 ~/.openclaw/openclaw.json - allowlist only me
channels: {
  telegram: {
    enabled: true,
    token: "${TELEGRAM_BOT_TOKEN}",
    dmPolicy: "allowlist",
    allowFrom: ["telegram:YOUR_TELEGRAM_USER_ID"]
  }
}

With an allowlist, anyone who isn't you gets no response at all - not even a pairing prompt. The bot just silently ignores them. That's the tightest setting available.

pairingdefault
New users must be approved before they can chat. Good if you want to share access with specific people without editing the config each time.
allowlisttightest
Only the user IDs you list can interact with the bot. Everyone else is silently ignored. Best option for a personal-only agent.
openavoid this
Anyone who finds your bot username can use it freely. Not recommended for personal agents - you're paying for every conversation with your API budget.

After editing the config, run openclaw doctor to validate, then openclaw gateway restart to apply.

Protect Your Bot Token

Your Telegram bot token is basically a password for your agent. A few hard rules:

Nevershare it
Don't paste it in a Discord server, a GitHub commit, a screenshot, or anywhere someone could see it. It gives whoever has it full control over your bot.
Useenv variable
Instead of pasting the raw token in openclaw.json, use token: "${TELEGRAM_BOT_TOKEN}" and set the variable in your systemd service or shell profile. Full guide: Securing Your Secrets.
If it leaksrevoke immediately
Go to @BotFather on Telegram, send /revoke, select your bot, confirm. BotFather issues a new token. Paste it into your OpenClaw config and restart the gateway. The old token is dead instantly.

Using Your Bot in Groups (Optional)

By default, Telegram bots in group chats can only read messages that start with /. This is "privacy mode" - it's on by default and it's a good thing for most bots. For OpenClaw in a group, this means you'd type /ask What should I make for dinner? instead of just typing normally.

If you want your bot to read all messages in a group without the / prefix, you can disable privacy mode:

1BotFather
Open a chat with @BotFather
2BotFather
Send /setprivacy
3BotFather
Select your bot
4BotFather
Select Disable
5Telegram
Remove the bot from the group and re-add it - the change takes effect on rejoin
Think before disabling privacy mode. With privacy mode off, your bot reads every message in every group it's added to. If someone adds your bot to a busy group, it'll try to respond to everything. Stick to DMs unless you have a specific group use case that needs this.

If Something Isn't Working

Bot not respondingcheck status
openclaw status - is the gateway actually running? If not, openclaw gateway restart.
Gateway errorscheck logs
openclaw logs --follow - look for Telegram-related errors. A bad token shows up here immediately as an authentication error.
Config won't loadvalidate first
openclaw doctor - tells you exactly what's wrong with your config before you try to restart anything.
Wrong tokeneasy fix
Go back to @BotFather, send /mybots, select your bot, tap API Token to see the current token. Update your config and restart.
06 / Next Steps

What to Do With It

You have a Telegram bot talking to your OpenClaw agent. The basics are done. Here's what makes it genuinely useful rather than just technically functional.

Make It Know You

Out of the box, your agent has no context about who you are, what you work on, or how you like things done. Memory files fix that. A well-configured SOUL.md and USER.md turns a generic AI response machine into something that actually knows you.

The Memory Architecture tutorial covers the whole system - what files do what, what to put in them, and how to structure preferences so they actually stick across conversations.

Teach It Shortcuts

Skills let you build slash commands that trigger specific behaviors. From Telegram, you could type /status and get a server health check, or /brief and get a daily summary of whatever matters to you. These are just markdown files in your workspace - no programming required.

The Skills & Slash Commands tutorial walks through building your first few with real examples.

Add More Channels

If you haven't set up Discord yet, it pairs well with Telegram - use Telegram on mobile, Discord on desktop. Same agent, same memory, you just pick whichever app you're already in.

The Discord setup section of the EC2 tutorial covers the full process. If OpenClaw is already running, you only need the Discord section - skip everything before it.

Secure Your Credentials

If your Telegram bot token is currently sitting as plaintext in openclaw.json, that's fine for testing but not great long-term. Moving it to an environment variable takes five minutes and means it's never exposed in the config file.

The Securing Your Secrets tutorial covers environment variables, systemd service file secrets, and what to do if a credential ever leaks.

Use It Daily

The biggest thing you can do to get value out of this setup is just use it. Ask it things you'd normally Google. Have it draft messages. Use it when you're on the go and need a quick answer from something that actually knows context about your life.

It gets more useful as you add memory files, skills, and context. But even the basic setup - just a chat window to your own AI - is worth using every day.

Telegram setup complete. Your self-hosted AI agent is now accessible from wherever you are, on a device that fits in your pocket. That's a genuinely powerful thing you built from scratch. Use it well. 🦞