Clawberth
Back to blog
March 12, 2026 8 min read

OpenClaw Telegram Setup Guide: Bot Token, Pairing, and Groups — All in One Place

A complete, step-by-step guide to connecting OpenClaw to Telegram. Covers BotFather setup, bot token configuration, pairing, group chat policies, privacy mode, and advanced features like custom commands and forum topics.

telegram setup tutorial

If you’re running a self-hosted AI agent with OpenClaw, Telegram is one of the best channels to connect it to. It’s fast, it’s everywhere, and OpenClaw’s Telegram integration is production-ready — built on grammY with long polling by default. No webhooks to configure, no public URLs to expose.

This guide walks you through the entire process: creating a bot, wiring it into OpenClaw, approving your first pairing request, and setting up group chats. By the end, your AI agent will be live on Telegram, ready to respond to DMs and group mentions.

Prerequisites

Before you start, make sure you have:

  • A running OpenClaw instance. If you haven’t installed OpenClaw yet, start with the install guide.
  • A Telegram account. You’ll need this to create a bot and test it.
  • Terminal access to the machine running OpenClaw.

That’s it. No domain name, no SSL certificate, no port forwarding. Long polling means your OpenClaw instance reaches out to Telegram — not the other way around.

Step 1: Create Your Bot with @BotFather

Open Telegram and search for @BotFather. This is Telegram’s official bot for creating and managing bots.

  1. Send /newbot to BotFather.
  2. Choose a display name for your bot (e.g., “My AI Assistant”).
  3. Choose a username — it must end in bot (e.g., my_openclaw_bot).
  4. BotFather will reply with your bot token. It looks something like this:
7123456789:AAF1xYz-abcDEFghiJKLmnoPQRstuVWxyz

Copy this token and keep it safe. Anyone with this token can control your bot. Don’t commit it to a public repo, don’t paste it in group chats.

Tip: While you’re in BotFather, you can also set a profile picture with /setuserpic and a description with /setdescription. Makes your bot feel more polished when people first discover it.

Step 2: Configure OpenClaw

Here’s the important thing to know: Telegram does not use openclaw channels login telegram. Unlike some other channels, there’s no OAuth flow. You configure the bot token directly in your openclaw.json config file.

Open your OpenClaw configuration file:

nano ~/.openclaw/openclaw.json

Add or update the channels.telegram section:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "7123456789:AAF1xYz-abcDEFghiJKLmnoPQRstuVWxyz",
      "dmPolicy": "pairing"
    }
  }
}

That’s the minimal config. Three fields:

  • enabled: Turns the Telegram channel on.
  • botToken: The token you got from BotFather.
  • dmPolicy: Controls who can DM your bot. We’ll use "pairing" to start — more on this below.

Environment Variable Fallback

If you prefer not to store the token in your config file (common in containerized deployments), you can set it as an environment variable instead:

export TELEGRAM_BOT_TOKEN="7123456789:AAF1xYz-abcDEFghiJKLmnoPQRstuVWxyz"

OpenClaw will check for this environment variable if botToken isn’t set in the config. This is useful for Docker setups, systemd services, or any environment where you manage secrets separately.

Step 3: Start the Gateway and Approve Pairing

With the config in place, start (or restart) the OpenClaw gateway:

openclaw gateway start

Now open Telegram and send any message to your bot. Since dmPolicy is set to "pairing", the bot won’t respond yet — instead, it generates a pairing code. You’ll see this in the gateway logs:

openclaw logs --follow

Look for a line containing the pairing code. It’ll be a short alphanumeric string. To approve it:

openclaw pairing approve telegram CODE

Replace CODE with the actual pairing code from the logs.

That’s it. Your Telegram account is now paired with your OpenClaw agent. Send another message to the bot, and you’ll get a response.

A few things to know about pairing:

  • Pairing codes expire after 1 hour. If you wait too long, just send another message to the bot to generate a fresh code.
  • Each Telegram user needs their own pairing. If a friend wants access, they DM the bot, and you approve their code separately.
  • Pairing is persistent. Once approved, you don’t need to re-pair after restarts.

Understanding DM Policies

The dmPolicy field controls who can talk to your bot in direct messages. There are four options:

PolicyBehavior
"pairing"New users must be approved via pairing code. This is the default.
"allowlist"Only pre-approved user IDs can interact. No pairing flow.
"open"Anyone can DM the bot. No restrictions.
"disabled"DMs are ignored entirely.

For most self-hosted setups, "pairing" is the right choice. It gives you control without requiring you to look up user IDs in advance.

If you want to use "allowlist", you’ll need numeric Telegram user IDs in the allowFrom array:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "7123456789:AAF1xYz-abcDEFghiJKLmnoPQRstuVWxyz",
      "dmPolicy": "allowlist",
      "allowFrom": [123456789, 987654321]
    }
  }
}

Important: These must be numeric user IDs, not usernames. To find your Telegram user ID, DM your bot and check the logs:

openclaw logs --follow

Look for the from.id field in the incoming message — that’s your numeric user ID.

Step 4: Setting Up Group Chats

Getting your bot into a group chat requires a bit more configuration, plus an understanding of Telegram’s privacy mode.

Privacy Mode

By default, Telegram bots can only see messages that directly mention them or are replies to their messages. This is called privacy mode, and it’s enabled by default for all new bots.

You have two options:

  1. Disable privacy mode via BotFather: Send /setprivacy → select your bot → choose Disable. This lets the bot see all messages in the group.
  2. Make the bot a group admin. Admin bots automatically receive all messages regardless of privacy settings.

Critical: After changing the privacy mode setting, you must remove and re-add the bot to every group for the change to take effect. Telegram caches the privacy setting at the time the bot joins.

Group Policy Configuration

Add groupPolicy and related fields to your config:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "7123456789:AAF1xYz-abcDEFghiJKLmnoPQRstuVWxyz",
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "groupAllowFrom": [123456789, 987654321],
      "requireMention": true
    }
  }
}

Key details:

  • groupPolicy: Works like dmPolicy but for group chats. Use "allowlist" to restrict which users can trigger the bot in groups.
  • groupAllowFrom: An array of user IDs (not chat IDs!) that are allowed to interact with the bot in group chats.
  • requireMention: Defaults to true. When enabled, the bot only responds when explicitly mentioned (@your_bot_name) in group messages. Set to false if you want the bot to respond to everything (only recommended with privacy mode disabled and a narrow allowlist).

Common Mistakes

A quick list of things that trip people up:

  1. Using openclaw channels login telegram — This command doesn’t apply to Telegram. Configure the token in openclaw.json or use the environment variable.

  2. Putting usernames in allowFrom — It’s [123456789], not ["@username"]. Telegram user IDs are always numeric.

  3. Forgetting to re-add the bot after changing privacy mode — The privacy setting is cached when the bot joins a group. Toggle it, then remove and re-add.

  4. Using chat IDs instead of user IDs in groupAllowFrom — This field takes user IDs. The bot checks who sent the message, not which chat it came from.

  5. Expired pairing codes — They last 1 hour. If approval fails, have the user send a new message to generate a fresh code.

Advanced Features

Once the basics are working, OpenClaw’s Telegram integration has some nice extras.

Streaming Responses

OpenClaw streams responses to Telegram by default using partial message updates. Your bot will appear to “type” its response progressively, similar to how ChatGPT works. The default streaming mode is partial — no extra configuration needed.

Custom Commands

You can define custom slash commands that appear in Telegram’s command menu:

{
  "channels": {
    "telegram": {
      "customCommands": [
        { "command": "summarize", "description": "Summarize a URL or text" },
        { "command": "translate", "description": "Translate text to English" },
        { "command": "reset", "description": "Clear conversation context" }
      ]
    }
  }
}

These commands show up as suggestions when users type / in the chat.

Forum Topics

If your Telegram group uses forum topics (threads), OpenClaw supports topic isolation automatically. Each forum topic gets its own conversation context via the :topic:threadId suffix, so conversations in different threads don’t bleed into each other. Just add the bot to a forum-enabled group and it handles topic separation out of the box.

Troubleshooting

Bot doesn’t respond at all?

  • Check openclaw gateway status — is the gateway running?
  • Check openclaw logs --follow — are messages arriving?
  • Verify enabled: true in the config.

Bot responds in DMs but not in groups?

  • Check privacy mode (disable it or make bot admin).
  • Remove and re-add the bot to the group.
  • Verify groupPolicy allows the user.

“Legacy @username entries” warnings?

  • Run openclaw doctor --fix — this resolves old-format entries from earlier OpenClaw versions that used @usernames instead of numeric IDs.

Pairing code not appearing in logs?

  • Make sure dmPolicy is set to "pairing", not "disabled".
  • Check that you’re looking at the right gateway instance’s logs.

Wrapping Up

You now have a fully functional AI agent on Telegram — accessible via DMs and group chats, with fine-grained access control. The long-polling model means no exposed ports, no webhook URLs, and no SSL certificates to manage. Just a bot token and a few lines of config.

Want Telegram without the setup headaches? We’re building managed hosting where channels come pre-configured and monitored. Join the waitlist and we’ll let you know when it’s ready.