How to Connect OpenClaw to Telegram (and Lock It to Your Account)

Telegram is the right first channel for OpenClaw, and the reason is diagnosability. BotFather issues a token in about two minutes, everything runs over a documented Bot API, and when something breaks the failure has a name you can search. Compare that to WhatsApp, where linking is QR-only and a lost session means scanning again from the phone.

OpenClaw’s own documentation describes Telegram support as “production-ready for bot DMs and groups”, with long polling as the default transport and webhook mode optional. So the setup is short. This guide spends its length on the two things that actually cost people an evening: restricting the bot to you, and the three ways it goes quiet.

Step 1: Create the bot

Open Telegram and message @BotFather — confirm the handle is exactly that, since impersonators exist. Then:

1. Send /newbot
2. Give it a display name
3. Give it a username ending in bot or _bot
4. Copy the token BotFather returns

There’s also a web flow — BotFather’s mini app works in any Telegram client including web.telegram.org — if you’d rather click than type commands.

Treat that token as a password. Telegram bot tokens don’t expire, so a leaked one stays valid until you regenerate it.

Step 2: Find your numeric user ID

You need this before writing the config, and OpenClaw’s docs rank the methods by privacy:

Safest — DM your new bot, then on the server read the incoming message:

openclaw logs --follow

Look for from.id in the entry for your message.

Official Bot API — after DMing the bot:

curl "https://api.telegram.org/bot<bot_token>/getUpdates"

Third-party, less private — @userinfobot or @getidsbot. These work, but you’re handing your identity to someone else’s bot to save thirty seconds.

Note it must be the numeric ID. OpenClaw’s setup accepts numeric IDs only; @username entries from older configs need openclaw doctor --fix to resolve.

Step 3: Configure the token and lock it down

The minimal config from OpenClaw’s documentation looks like this:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

That works. For a bot only you should use, don’t ship it. Use an allowlist instead:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "allowlist",
      allowFrom: ["123456789"],        // your numeric user ID
    },
  },
  commands: {
    ownerAllowFrom: ["telegram:123456789"],
  },
}

Two reasons this matters, both from the docs.

First, open is genuinely open. OpenClaw warns that dmPolicy: "open" with allowFrom: ["*"] “lets any Telegram account that finds or guesses the bot username command the bot.” Bot usernames are guessable. Its recommendation is explicit: “one-owner bots should use allowlist with numeric user IDs.”

Second, pairing is narrower than people think. From the docs: “DM pairing approval does not mean ‘this sender is authorized everywhere.’ Pairing grants DM access only.” Group sender authorisation comes from config allowlists and never inherits DM pairing approvals — a deliberate security boundary. So approving yourself once in a DM does not authorise you in a group, and it certainly doesn’t restrict anyone else there.

The commands.ownerAllowFrom line is the other half. Owner-only commands and exec approvals check that list separately, so to be authorised for both DMs and commands with one identity you need your ID in both places.

If you prefer the pairing flow, the docs’ sequence is:

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Pairing codes expire after an hour.

Token precedence is worth knowing if you have several places set: tokenFile beats botToken beats the TELEGRAM_BOT_TOKEN environment variable, and the env var only resolves for the default account.

Step 4: Start it and send the first message

openclaw gateway

DM your bot. You should get a reply. If you don’t, skip to the failure modes below rather than changing config at random.

Useful checks at this point:

openclaw channels status
openclaw channels status --probe
openclaw doctor

--probe verifies explicit numeric group IDs; a wildcard "*" cannot be membership-probed, so it can’t tell you whether a wildcard group config is actually working.

Step 5: Add it to a group (optional)

Group access needs two separate things allowed, and confusing them is the most common setup failure:

• Which groups — channels.telegram.groups, keyed by the group’s chat ID
• Which senders in them — groupPolicy and groupAllowFrom

The default groupPolicy is allowlist, which means all groups are blocked until you add entries. If channels.telegram is missing from your config entirely, the runtime still defaults to fail-closed. Silence in a group is usually the config working as designed.

Get the group chat ID from openclaw logs --follow or the Bot API, then:

{
  channels: {
    telegram: {
      groups: { "-1001234567890": { requireMention: true } },
    },
  },
}

Supergroup IDs start with -100 and are negative. They belong under groups — not in groupAllowFrom, which takes user IDs and silently ignores non-numeric entries. The docs’ recommended pattern for a one-owner bot: your user ID in allowFrom, groupAllowFrom left unset, target groups listed under groups.

Once the group is allowed, /whoami@<bot_username> confirms both the user and group IDs it sees.

The three failures that actually happen

It only answers when mentioned

Telegram bots ship with Privacy Mode on, which limits which group messages they receive at all. If you’ve set requireMention: false and it’s still silent on ordinary messages, privacy mode is why.

The fix has a step almost everyone misses:

1. BotFather → /setprivacy → Disable
2. Remove the bot from the group and add it back

That second step is required — Telegram only applies the change on re-add. Making the bot a group admin achieves the same visibility without touching privacy mode, and admin bots receive all group messages.

No reply at all

Two distinct causes, and the logs separate them.

getMe returned 401 is a token problem. Re-copy or regenerate it in BotFather and update botToken, tokenFile, or TELEGRAM_BOT_TOKEN. A deleteWebhook 401 at startup is the same fault surfacing earlier.

A leftover webhook is the subtler one. Long polling is the default, but if a webhook was ever set on that token it conflicts — and it shows up as a getUpdates conflict, not as an obvious “webhook is set” message. OpenClaw rebuilds the transport and retries webhook cleanup, so this often resolves itself; if it doesn’t, clear the webhook explicitly before starting.

Also seen on VPS hosts: TypeError: fetch failed or Network request for 'getUpdates' failed!. These are usually IPv6 — some hosts resolve api.telegram.org to IPv6 first and broken IPv6 egress causes intermittent failures. Force IPv4:

channels:
  telegram:
    network:
      autoSelectFamily: false

Polling stall detected in the logs means OpenClaw restarted polling after 120 seconds without a completed long-poll — usually the same underlying network problem.

Commands work partially

Command authorisation is separate from channel access and still applies even when group policy is open. If the bot chats but won’t run commands, your sender identity isn’t authorised for commands — check commands.ownerAllowFrom.

If you see setMyCommands failed with BOT_COMMANDS_TOO_MUCH, the native command menu has too many entries; reduce plugin and custom commands or disable native menus.

Before you leave it running

An OpenClaw instance reachable from Telegram is an agent someone can talk to. Three things worth doing once:

• Confirm the allowlist is numeric and yours. /whoami@<bot_username> tells you which IDs the bot actually sees.
• Rotate the token if it’s ever been in a paste, a screenshot or a repo. Tokens don’t expire on their own.
• Check the machine isn’t exposed elsewhere. The Telegram channel can be locked down while the agent’s own port sits open to the internet — a separate problem covered in is your self-hosted AI agent exposed?.

If you haven’t set up the server yet, self-hosting OpenClaw on a VPS covers the install with hardening first, and what OpenClaw is covers what you’re actually running. For a managed starting point, Hostinger’s OpenClaw template prices the shortcut.

How we checked this

Every command, config key and error string in this guide comes from OpenClaw’s own Telegram channel documentation in the project repository, read in August 2026 — including the BotFather flow, the dmPolicy options and their security notes, the privacy-mode remove-and-re-add requirement, the getUpdates conflict behaviour, and the group allowlist semantics. Several third-party guides for this exact topic are AI-generated and contain config keys that don’t exist, so we’ve stayed on the official docs and quoted them where the wording matters.

What we have not done: we did not run this setup end to end for this article, so treat the sequence as a faithful reading of the documentation rather than a lab report. Config schemas move — openclaw doctor is the authority on whether your file is valid for the version you’re running, and it will tell you faster than any article can.

This guide has no affiliate links — nothing in the setup above requires a paid product. The Hostinger template linked earlier is covered in a separate article, where it is disclosed.

FAQ

How do I get an OpenClaw Telegram bot token?

Message @BotFather in Telegram, send /newbot, choose a display name and a username ending in bot, and copy the token it returns. Put it in channels.telegram.botToken or the TELEGRAM_BOT_TOKEN environment variable — Telegram doesn’t use openclaw channels login.

Why does my bot only respond to commands in a group?

Telegram’s Privacy Mode is on by default and limits which group messages bots receive. Disable it with /setprivacy in BotFather, then remove and re-add the bot to the group — the change only applies on re-add. Making the bot a group admin has the same effect.

How do I stop other people using my bot?

Set dmPolicy: "allowlist" with your numeric user ID in allowFrom, and put telegram:<your id> in commands.ownerAllowFrom. Avoid dmPolicy: "open" with allowFrom: ["*"], which the docs warn lets anyone who guesses the bot username command it.

Does approving a pairing request secure my bot?

Only for DMs. Pairing grants DM access and nothing else — group sender authorisation comes from explicit config allowlists and never inherits pairing approvals. For a one-owner bot, use an allowlist rather than relying on a past pairing approval.

My bot doesn’t respond at all. Where do I start?

Read the logs. getMe returned 401 means the token is wrong. A getUpdates conflict means a webhook is still registered on that token. TypeError: fetch failed usually means IPv6 egress problems reaching api.telegram.org — force IPv4 with network.autoSelectFamily: false.

How do I find my numeric Telegram user ID?

DM your bot and read from.id from openclaw logs --follow, or call getUpdates on the Bot API with your token. Third-party ID bots work but hand your identity to someone else’s bot.

Should I use webhooks instead of polling?

Not unless you need to. Long polling is the default and needs no inbound port or public domain. Webhook mode exists via webhookUrl and webhookSecret if you want it, but it adds a public endpoint to secure — and a stale webhook is one of the failure modes above.