Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.suji.fr/llms.txt

Use this file to discover all available pages before exploring further.

Connecting Telegram to OpenClaw lets your bot receive and respond to messages on Telegram. Once connected, anyone who messages the bot is talking to your OpenClaw agent — in direct messages and in group chats.

​
What you’ll need

  • A Telegram account (any free account works).
  • The Telegram app on your phone/desktop, or Telegram Web.
  • A running OpenClaw install on a Suji VM.

​
Create a Telegram Bot

Every Telegram bot is created through BotFather, Telegram’s official tool for registering and managing bots. You’ll chat with BotFather like a normal Telegram conversation.
1

Open BotFather

Open Telegram and search for @BotFather in the search bar, or click this link directly: @BotFather.BotFather is verified by Telegram and has a blue checkmark next to its name. Make sure you’re messaging the real BotFather and not an impersonator.
2

Start a conversation

Click Start (or type /start) to begin interacting with BotFather. It will reply with a list of available commands.
3

Create a new bot

Type /newbot and send it. BotFather will ask you two things:
  1. A display name for your bot — This is the name users see in chats. It can be anything, like My Store Assistant or Acme Support Bot. You can change this later.
  2. A username for your bot — This is the unique @username that people use to find your bot. It must end in bot (for example: my_store_bot, AcmeSupportBot, or acme_help_bot). Usernames are case-insensitive and cannot be changed after creation.
If the username you want is taken, try adding a prefix or suffix. For example, if support_bot is taken, try acme_support_bot or support_bot_123.
4

Copy the bot token

After you choose a valid username, BotFather will reply with a congratulations message that includes your bot token. It looks something like this:
123456789:ABCdefGHIjklMNOpqrSTUvwxYZ1234567890
The token is made up of two parts separated by a colon: a numeric bot ID and an alphanumeric secret string. Copy the entire token — you’ll paste it into Suji in the next section.
Keep your bot token secret. Anyone who has your token can fully control your bot — read messages, send messages, and change settings. Never share it publicly or commit it to a code repository.
5

Configure privacy mode (for group chats)

By default, Telegram bots in group chats can only see messages that are either directed at them (using /commands) or replies to their messages. This is called privacy mode, and it’s enabled by default.If you want your bot to read and respond to all messages in a group chat (not just commands and replies), you need to disable privacy mode:
  1. Send /setprivacy to BotFather
  2. Select your bot from the list
  3. Choose Disable
BotFather will confirm that privacy mode has been disabled.
If your bot will only be used in direct messages (one-on-one chats), you can skip this step. Privacy mode only affects group chat behavior.
After changing the privacy mode, you need to remove and re-add the bot to any existing group chats for the change to take effect. New groups added after the change will work automatically.

​
Connect it to OpenClaw

You can wire the token up at two points:

​
During install

In the OpenClaw install form, tick Telegram in the Channels multiselect and paste your bot token into the Telegram bot token field. Click Deploy — OpenClaw connects to Telegram on first boot.

​
After install

If you didn’t add Telegram at install time, open the OpenClaw install detail page → Edit Install → tick Telegram → paste the token → Save. Suji redeploys OpenClaw with the new env. Existing channels keep working through the redeploy.

​
Verify

  1. Open Telegram and search for your bot by @username.
  2. Click Start or type /start.
  3. Send any message — your OpenClaw agent should reply.
If it doesn’t reply, see the troubleshooting block below.
Make sure OpenClaw has finished its first-connection setup (tokenized URL + device pairing) so the Control UI is reachable. An unconfigured agent may not behave as expected.

​
Troubleshooting

Check, in order:
  • VM and install are running. Dashboard → instance must be running; the OpenClaw install must also be running.
  • You started the bot. Telegram requires the user to press Start (or send /start) before the bot can send messages.
  • Token is exactly right. Even a stray space invalidates it. Re-copy from BotFather.
  • Install logs. Dashboard → Logs → pick OpenClaw → look for [telegram] lines around the time you sent the message. If you don’t see any, the token never authenticated.
  1. Open @BotFather → /mybot → select your bot. Confirm it exists.
  2. If you need a fresh token, send /token (gets the current one) or /revoke (revokes + regenerates). Revoking takes effect immediately.
  3. In Suji: install detail page → Edit Install → paste the new Telegram token → Save.
Some delay is expected — OpenClaw queues the message and waits on the AI provider. If it’s consistently slow:
  • Resource pressure — Metrics tab shows CPU/memory near the cap; resize the VM up.
  • AI provider latency — the upstream LLM is the slow path; try a faster model.
  • Complex prompts — long system prompts and tool use add round trips.
If your bot works in direct messages but ignores messages in group chats, privacy mode is likely still enabled. By default, bots in groups can only see commands (messages starting with /) and direct replies to the bot.To fix this:
  1. Send /setprivacy to @BotFather
  2. Select your bot
  3. Choose Disable
  4. Remove the bot from the group and re-add it — this step is required for the change to take effect in existing groups
After re-adding the bot, it should be able to see and respond to all messages in the group.