How to set up OpenClaw on Telegram, step by step

Telegram is the channel most people reach for first with OpenClaw, and it is also where a lot of setups stall. The single most searched OpenClaw Telegram phrase is some version of the pair command, which tells you exactly where people get stuck: the bot is running, a code appeared, and it is not obvious what to do with it.

Step 1: Create a bot with BotFather

Every Telegram bot starts with a token from Telegram's own bot, BotFather. In the Telegram app, search for @BotFather and confirm the handle is exactly that with the blue verification checkmark, since impersonators exist. Send /start if you have never opened the chat before, then send /newbot.

BotFather asks for two things in order. The display name is what users see at the top of the chat, and it can include spaces and emoji. The username must be unique across Telegram, use only Latin letters, numbers, and underscores, and end in bot or _bot, for example myagent_helper_bot. If the username is taken, BotFather asks you to try another.

When both fields are accepted, BotFather replies with a token that looks like 123456789:AAExampLEtoKEN. That string is the bot's credential for the Telegram Bot API. Keep it somewhere safe. Anyone with that token can read and send messages as your bot. If it leaks, open BotFather, choose your bot under /mybots, and use Revoke access token to mint a replacement, which instantly invalidates the old one.

Two BotFather settings to check before you add the bot to groups: /setjoingroups controls whether the bot can be added to groups at all, and /setprivacy controls whether the bot sees every group message or only mentions and replies. OpenClaw's defaults assume privacy mode is on, which matches Telegram's factory setting for new bots.

If this is your first BotFather bot, Code Along with Ron's short walkthrough shows the /newbot exchange and points out where the token appears in the reply.

Step 2: Put the token in your OpenClaw config

OpenClaw reads channel settings from ~/.openclaw/openclaw.json. Add a Telegram block with your token and leave the DM policy on its default of pairing, which is what keeps strangers from talking to your agent:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456789:AAExampLEtoKEN",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

If you would rather not put the token in the file, OpenClaw also reads TELEGRAM_BOT_TOKEN from the environment for the default account. Config values win over the environment when both are set. One thing to know up front: unlike WhatsApp or Discord, Telegram has no openclaw channels login telegram step. You set the token in config or the environment, and that is the whole connection.

Either way the token sits somewhere readable. In openclaw.json it lives in plaintext under your home directory, so on a machine other people can log into, anyone who can read that file or an old backup of it can send and read messages as your bot. Keeping the state directory locked to your own user, or handing the token through TELEGRAM_BOT_TOKEN instead of writing it into the file, is what keeps it out of reach on a shared box.

The dmPolicy field controls who may DM the bot.

That last one fits an intentionally public bot. If you do run one open, decide what it can reach before you flip the policy. Turn off shell and filesystem access and any broad integrations, so a stranger who messages it cannot drive your tools, and treat it as a place to receive and reply rather than a full agent. The complete set of options lives in the Telegram channel docs.

OpenClaw talks to Telegram through long polling by default, calling getUpdates from the gateway process. Webhook mode is optional if you would rather Telegram push updates to your own endpoint, though it asks more of you. Telegram only delivers to a public HTTPS URL with a valid certificate, and you set a secret token that Telegram echoes back on every request so the gateway can confirm an inbound update really came from Telegram and not someone who guessed the URL.

Polling is simpler for a single gateway on a home machine or VPS, and it needs no inbound port open at all. Only one active poller may use a given token at a time; a second gateway or script holding the same token produces HTTP 409 conflicts.

Step 3: Start the gateway and approve the pairing code

Start the gateway so it begins polling Telegram:

openclaw gateway

Now open a chat with your bot in Telegram. Tap Start if the client shows it, then send any message. Because the DM policy is pairing, the bot will not answer yet. Instead it replies with a short pairing code and ignores the message itself.

This is the part that confuses people, so to be clear: you do not type that code into a website or an app. The code is your approval handle, and you approve it from the machine the gateway runs on.

List the pending request and approve it:

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Once approved, message the bot again and it answers. The first sender you approve also becomes the command owner, so owner only commands work for you without extra setup. Pairing codes expire after an hour, so if you waited too long, send a fresh message to get a new one.

Confirm the channel is healthy before you move on:

openclaw channels status --probe

You want a line that shows the bot enabled, configured, and running, with the @username resolved through Telegram's getMe call. A 401 here means the token is wrong or revoked.

If you already know your numeric Telegram user ID and want access to survive without depending on the pairing store, you can instead set dmPolicy: "allowlist" and list your ID under allowFrom. To find that ID, DM the bot and read from.id in openclaw logs --follow, or call getUpdates against the Bot API directly with a curl command as shown in the OpenClaw docs.

Step 4: Add it to a group

Bots behave differently in groups. Add yours to a group and two things apply by default: Telegram's privacy mode limits which messages the bot can see, and OpenClaw requires the bot to be mentioned before it replies. If you want the bot to read every message in a group, disable privacy mode in BotFather with /setprivacy, choose Disable, then remove and re add the bot so Telegram applies the change, or make the bot a group admin.

Both routes change what the bot can read, so weigh them before you flip them. Turning privacy mode off means the bot receives every message in the group, and your agent reads and keeps all of it, so in a room with other people that is their conversation flowing into your agent and any of them can address it and steer it toward the tools you connected. Making the bot an admin lifts privacy the same way and hands it moderation powers such as deleting and pinning, so reserve that for a group you actually run. The read everything path fits a private group that is really just your own workspace. For a shared room, leave privacy mode and the mention requirement on and use the allowFrom list shown below to name exactly who is allowed to trigger the bot.

You also need the group's chat ID, a negative number that starts with -100 for supergroups. After the bot receives a message in the group, read chat.id from openclaw logs --follow, forward a group message to @userinfobot, or inspect getUpdates. Put that ID under channels.telegram.groups to allow the group. Until you add a groups entry, OpenClaw's default groupPolicy: "allowlist" blocks all groups even when the bot is present in Telegram.

A minimal owner only group setup looks like this:

{
  channels: {
    telegram: {
      allowFrom: ["<YOUR_TELEGRAM_USER_ID>"],
      groupPolicy: "allowlist",
      groups: {
        "-1001234567890": {
          requireMention: true,
        },
      },
    },
  },
}

Test from the group with an @mention of the bot. Plain messages in the group do not trigger a reply while requireMention is true. Once the basics work, read the usage guide for day to day commands, streaming previews, and forum topic sessions.

The managed option

None of this is hard once you have done it, but it is four steps and a CLI, and the pairing code is where most first time setups stall. Operator.io is managed OpenClaw with Telegram already connected, so there is no BotFather token to mint, no config file to edit, and no pairing code to chase down. You sign in and your agent is reachable in Telegram immediately, so a free trial gets you a working bot in about a minute. The steps above are the route if you would rather mint the token and run the gateway yourself.