How do I connect Telegram to OpenClaw? - OpenClaw FAQ

OpenClaw provides full Telegram Bot API integration with support for direct messages, group chats, and mention-based interactions. The gateway handles all the complexity, so you can focus on building your agent.

Step 1: Create a Telegram bot

Open Telegram and chat with @BotFather (the official bot creation tool):

/newbot

Follow the prompts to choose a name and username (must end in bot). @BotFather will generate a bot token — copy this and keep it secure.

Optional: Use /setjoingroups to control whether your bot can be added to groups, or /setprivacy to manage message visibility.

Step 2: Configure the bot token

Set your bot token in OpenClaw's configuration. You can use either environment variables or a config file:

Option A: Environment variable (default account)

export TELEGRAM_BOT_TOKEN="123:ABC-xyzabc"

Option B: Config file (recommended)

Add the token to your openclaw.config.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:ABC-xyzabc"
    }
  }
}

If both env and config are set, config takes precedence. For multi-bot setups, use the accounts pattern — see the full documentation for details.

Step 3: Start the gateway

Start your OpenClaw gateway and Telegram will connect automatically when a valid token is detected:

openclaw gateway start

The gateway will register OpenClaw's native commands (like /status, /reset, /model) in the Telegram bot menu.

Step 4: Start messaging

Direct messages

DM access defaults to pairing mode. Open Telegram and message your bot — you'll receive a pairing code that approves the connection. Approve with:

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

After approval, all messages from that user will reach your agent automatically.

Group chats

Add your bot to any Telegram group. By default, the bot only responds when mentioned with @botname — this prevents noise in busy groups.

For more granular control over group behavior, configure channels.telegram.groups:

{
  "channels": {
    "telegram": {
      "groups": {
        "-1001234567890": {
          "requireMention": false
        }
      }
    }
  }
}

Finding your group Chat ID

Forward any message from the group to @userinfobot or @getidsbot to get the chat ID (a negative number like -1001234567890). Use this ID in your config.

Bottled: Multi-agent support

Set up multiple Telegram bots with different accounts using the accounts configuration. Each account can have independent tokens, capabilities, and policies:

{
  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "botToken": "123:abc",
          "capabilities": {
            "inlineButtons": "allowlist"
          }
        },
        "notifications": {
          "botToken": "456:def"
        }
      }
    }
  }
}

Security Best Practices

Never commit bot tokens to version control
Regenerate tokens via @BotFather if they leak
Use environment variables or encrypted secrets for production
Enable pairing by default for DMs to control access

Troubleshooting

Bot doesn't respond to messages:

Check gateway logs with openclaw logs --follow to see if the bot started successfully and if messages are being received. Verify the token is correct and that channels.telegram.enabled is true.

Bot doesn't respond to non-mention messages in groups:

Telegram's Privacy Mode limits which group messages bots receive. Disable it in @BotFather with /setprivacy → Disable, then remove and re-add the bot to the group.

Commands like /status don't work:

Commands require your Telegram user ID to be authorized. Approve yourself via pairing or add your ID to channels.telegram.allowFrom.

setMyCommands failed in logs:

This usually means outbound connections to Telegram's API (api.telegram.org) are blocked.定型 Check your network configuration and ensure HTTPSd HTTPS/DNS can reach Telegram's servers.