How to Connect OpenClaw to Telegram

Prerequisites

• ✓A Telegram account with access to @BotFather to create and manage bot tokens.
• ✓An existing OpenClaw gateway setup where you can edit the gateway config and restart it.
• ✓Node 22+ if you plan to debug polling or network instability issues mentioned in the Telegram docs.
• ✓Ability to run the OpenClaw CLI commands like `openclaw gateway`, `openclaw pairing`, `openclaw logs`, and `openclaw message` on your gateway host.

Steps

1. 1

   Create a Telegram bot token with BotFather

   Start on the Telegram side so you have a real bot token to plug into OpenClaw. Make sure you talk to the real @BotFather account and keep the token handy, since everything else depends on it.

   textCopy

   Open Telegram and chat with **@BotFather** (confirm the handle is exactly `@BotFather`).Run `/newbot`, follow prompts, and save the token.

2. 2

   Configure the Telegram channel in OpenClaw

   Wire your bot token into the OpenClaw gateway config and enable Telegram. This is also where you set the DM policy and default group behavior so you do not accidentally expose the bot to every chat.

   jsonCopy

   {
     channels: {
       telegram: {
         enabled: true,
         botToken: "123:abc",
         dmPolicy: "pairing",
         groups: { "*": { requireMention: true } },
       },
     },
   }
   
   Env fallback: `TELEGRAM_BOT_TOKEN=...` (default account only). Telegram does **not** use `openclaw channels login telegram`; configure token in config/env, then start gateway.

3. 3

   Start the OpenClaw gateway and approve the first DM pairing

   Bring the gateway up so it can connect to Telegram and receive your first DM. Then use the pairing commands to approve your own Telegram account, which unlocks DM access under the `pairing` policy.

   bashCopy

   openclaw gateway
   openclaw pairing list telegram
   openclaw pairing approve telegram <CODE>
   
   Pairing codes expire after 1 hour.

4. 4

   Add the bot to a Telegram group and align group policy

   Once DMs work, add the bot to a group and decide how group access should work. You control which groups are allowed and whether the bot requires mentions, so you avoid noisy or accidental triggers.

   textCopy

   Add the bot to your group, then set `channels.telegram.groups` and `groupPolicy` to match your access model.
   
   Token resolution order is account-aware. In practice, config values win over env fallback, and `TELEGRAM_BOT_TOKEN` only applies to the default account.

5. 5

   Find your Telegram user ID for allowlists and group access

   Use your numeric Telegram user ID when you move beyond pairing into allowlists for DMs or groups. This keeps access rules durable in config instead of relying on past pairing approvals.

   bashCopy

   Safer (no third-party bot):
   1.   DM your bot.
   2.   Run `openclaw logs --follow`.
   3.   Read `from.id`.
   
   Official Bot API method:
   
   curl "https://api.telegram.org/bot<bot_token>/getUpdates"
   
   Third-party method (less private): `@userinfobot` or `@getidsbot`.

6. 6

   Tune group access and mention behavior for your bot

   Lock down which groups and senders can trigger the bot so it behaves predictably in shared chats. Use `groups`, `groupPolicy`, and `groupAllowFrom` to scope access, and flip `requireMention` when you want the bot to respond without explicit mentions.

   jsonCopy

   {
     channels: {
       telegram: {
         groups: {
           "-1001234567890": {
             groupPolicy: "open",
             requireMention: false,
           },
         },
       },
     },
   }
   
   {
     channels: {
       telegram: {
         groups: {
           "-1001234567890": {
             requireMention: true,
             allowFrom: ["8734062810", "745123456"],
           },
         },
       },
     },
   }
   
   Group replies require mention by default.Mention can come from:
   *   native `@botusername` mention, or
   *   mention patterns in: 
       *   `agents.list[].groupChat.mentionPatterns`
       *   `messages.groupChat.mentionPatterns`
   
   Session-level command toggles:
   *   `/activation always`
   *   `/activation mention`
   
   Persistent config example:
   
   {
     channels: {
       telegram: {
         groups: {
           "*": { requireMention: false },
         },
       },
     },
   }

Configuration

Troubleshooting

Bot does not respond to non mention group messages

*   If `requireMention=false`, Telegram privacy mode must allow full visibility. 
    *   BotFather: `/setprivacy` -> Disable
    *   then remove + re-add bot to group

*   `openclaw channels status` warns when config expects unmentioned group messages.
*   `openclaw channels status --probe` can check explicit numeric group IDs; wildcard `"*"` cannot be membership-probed.
*   quick session test: `/activation always`.

Bot not seeing group messages at all

*   when `channels.telegram.groups` exists, group must be listed (or include `"*"`)
*   verify bot membership in group
*   review logs: `openclaw logs --follow` for skip reasons

Commands work partially or not at all

*   authorize your sender identity (pairing and/or numeric `allowFrom`)
*   command authorization still applies even when group policy is `open`
*   `setMyCommands failed` with `BOT_COMMANDS_TOO_MUCH` means the native menu has too many entries; reduce plugin/skill/custom commands or disable native menus
*   `setMyCommands failed` with network/fetch errors usually indicates DNS/HTTPS reachability issues to `api.telegram.org`

Polling or network instability

*   Node 22+ + custom fetch/proxy can trigger immediate abort behavior if AbortSignal types mismatch.
*   Some hosts resolve `api.telegram.org` to IPv6 first; broken IPv6 egress can cause intermittent Telegram API failures.
*   If logs include `TypeError: fetch failed` or `Network request for 'getUpdates' failed!`, OpenClaw now retries these as recoverable network errors.
*   On VPS hosts with unstable direct egress/TLS, route Telegram API calls through `channels.telegram.proxy`:

channels:
  telegram:
    proxy: socks5://<user>:<password>@proxy-host:1080

*   Node 22+ defaults to `autoSelectFamily=true` (except WSL2) and `dnsResultOrder=ipv4first`.
*   If your host is WSL2 or explicitly works better with IPv4-only behavior, force family selection:

channels:
  telegram:
    network:
      autoSelectFamily: false

*   RFC 2544 benchmark-range answers (`198.18.0.0/15`) are already allowed for Telegram media downloads by default. If a trusted fake-IP or transparent proxy rewrites `api.telegram.org` to some other private/internal/special-use address during media downloads, you can opt in to the Telegram-only bypass:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

*   The same opt-in is available per account at `channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
*   If your proxy resolves Telegram media hosts into `198.18.x.x`, leave the dangerous flag off first. Telegram media already allows the RFC 2544 benchmark range by default.

*   Environment overrides (temporary): 
    *   `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
    *   `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
    *   `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`

*   Validate DNS answers:

dig +short api.telegram.org A
dig +short api.telegram.org AAAA

Frequently asked questions