How to configure Telegram Bot for OpenClaw

Video walkthrough

Prerequisites

• An Agent37 account and an OpenClaw instance

• Access to your instance in the Agent37 dashboard (the Channels tab; the Terminal is optional for CLI setup)

Step 1: Create a Telegram bot (BotFather)

1. Open Telegram and search for @BotFather.

2. Start a chat and send /newbot.
• Give your bot a name (e.g., “My OpenClaw Assistant”).
• Give it a username (must end in bot, e.g., my_openclaw_assistant_bot).

3. Copy the Bot Token BotFather returns.
• This token is your API key. Keep it secret.

• The bot name is just a display label. The username is the unique handle, and Telegram requires it to end in bot (for example my_openclaw_assistant_bot).

• The token looks like 123456789:ABCdefGhIJKlmNoPQRsTUvWXyz123456. Copy the whole string. A missing character at either end is enough to break authentication.

• Lost the token? Open BotFather, run /mybots, select your bot, and choose API Token to view it again.

Step 2: Open your instance's Channels tab

1. Go to the Agent37 dashboard: https://www.agent37.com/dashboard

2. Create an instance (or open an existing one).

3. Make sure the bot is running, open the Channels tab, and click Set up Telegram. Telegram now uses an in-app setup flow, no terminal needed.

Step 3: Paste your bot token (Step 1 of 2)

openclaw configure

• Where will the gateway run? → Select Local

• Select Section to Configure? → Channel

• Configure / Link

• Select Channel → Telegram

• Enter Telegram bot token → Paste the token you copied

• Navigate to Finish → Continue

Where the token lives (config and environment)

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456789:ABCdefGhIJKlmNoPQRsTUvWXyz123456",
      "dmPolicy": "pairing"
    }
  }
}

• You can put the literal token in botToken, or point tokenFile at a file on disk that contains it.

• The TELEGRAM_BOT_TOKEN environment variable works as a fallback, but only for the default account. Named accounts in a multi-account setup must use botToken or tokenFile.

• If more than one is set, tokenFile wins over botToken, which wins over the environment variable.

Step 4: Pair the bot (approve pairing code)

1. In Telegram, open your bot and send /start.

2. Copy the 8-character pairing code the bot replies with and paste it into the same setup panel (Step 2 of 2), then click Approve pairing code. From the terminal, the equivalent is:

openclaw pairing approve telegram <code>

• Pairing codes expire after one hour. If setup drags on, run openclaw pairing list telegram to see which codes are still pending.

• Approval is per Telegram account, keyed to the numeric user ID, not the username.

• Pairing grants direct message access only. It does not authorize that person in group chats; groups have their own allowlists, covered below.

Step 5: Restart and test

1. The dashboard flow restarts the gateway for you. If you used the CLI instead, restart the instance from the dashboard so the bot connection becomes active.

2. Send a message to your bot to confirm it responds.

Who can DM your bot: dmPolicy and the allowlist

• pairing (the default): unknown senders get a pairing code, and you approve each one from the terminal. This is what you used in Step 4.

• allowlist: only the numeric Telegram user IDs listed in allowFrom get through. No codes, no approvals, just a fixed list.

• open: anyone who finds the bot can use it. OpenClaw requires you to also set allowFrom to ["*"], so you cannot open the bot up by accident.

• disabled: the bot ignores all direct messages.

{
  "channels": {
    "telegram": {
      "dmPolicy": "allowlist",
      "allowFrom": ["123456789"]
    }
  }
}

Groups vs direct messages

• Which groups the bot will work in. groupPolicy defaults to allowlist, which means every group is blocked until you add its chat ID under channels.telegram.groups. Group chat IDs are negative numbers starting with -100.

• Which people inside an allowed group can trigger the bot. groupAllowFrom lists their numeric user IDs; if you leave it unset, it falls back to your allowFrom list.

{
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "pairing",
      "allowFrom": ["<YOUR_TELEGRAM_USER_ID>"],
      "groupPolicy": "allowlist",
      "groups": {
        "<GROUP_CHAT_ID>": { "requireMention": true }
      }
    }
  }
}

• requireMention defaults to true: in groups, the bot stays silent unless someone mentions it, for example @my_openclaw_assistant_bot ping. Set it to false in a group where the bot should respond to everything.

• A common mistake: negative group chat IDs belong under groups, never in groupAllowFrom. That field is for user IDs only, and non-numeric entries are ignored.

Common failure modes

• The bot never responds. Check the basics in order: the instance is running, the token was pasted correctly, pairing was approved, and Telegram was actually selected during openclaw configure.

• getMe returned 401 in the logs. Telegram rejected the token. Either it was mistyped, or it was regenerated in BotFather without you noticing. Get the current value from /mybots and update botToken, tokenFile, or TELEGRAM_BOT_TOKEN.

• The pairing code no longer works. Codes expire after one hour. Run openclaw pairing list telegram to see what is pending and approve a fresh code.

• Persistent 409 conflicts on getUpdates. Two things are polling Telegram with the same token, usually a second gateway or a leftover script. Only one active poller can use a bot token at a time; stop the other one.

• The bot ignores group messages. The group is not listed under channels.telegram.groups, requireMention is still true and nobody mentioned the bot, or Privacy Mode is still hiding messages from it.

• setMyCommands fails with network errors. Outbound DNS or HTTPS to api.telegram.org is blocked from wherever the gateway runs.

Security notes

• Treat the bot token like a password. Anyone holding it can read and send messages as your bot. Keep it out of screenshots, shared chats, and repositories. If it leaks, regenerate it in BotFather and update your config with the new value.

• Do not run an open bot casually. dmPolicy: "open" with allowFrom: ["*"] means any Telegram account that finds or guesses the username can command your agent. Reserve that combination for intentionally public bots with tightly restricted tools.

• Remember what is on the other end. Messages to this bot drive an agent running on your instance, so allowlist only accounts you would trust with that access. For a one-owner bot, prefer an explicit allowFrom list of numeric IDs over relying on old pairing approvals.

• Group access is deliberately separate. Group senders are authorized by explicit config allowlists, never by DM pairing history. That boundary is a feature; do not shortcut it with a wildcard.