How to Connect OpenClaw to Telegram (2026 Setup Guide)

Connecting OpenClaw to Telegram is one of the most popular setups — it turns your Telegram into a direct line to your personal AI agent. This guide covers everything from creating the bot token to approving your first pairing, plus the most common error users hit.

Before you start

You need OpenClaw installed and the gateway running. If you haven't done that yet: How to Install OpenClaw →

You also need a Telegram account (any device is fine for setup).

Step 1: Create a Telegram bot via BotFather

Open Telegram and search for @BotFather — make sure the handle is exactly that, not a lookalike. Start a chat and send:

/newbot

BotFather will ask for a name (e.g., "My AI Agent") and a username (must end inbot, e.g., myagent_bot). Once you confirm, it gives you a bot token that looks like:

123456789:ABCDefGhIJKlmNoPQRsTUVwxyZ

Copy this token and keep it safe — it's how OpenClaw authenticates with Telegram's API.

Step 2: Add the token to OpenClaw

Open your OpenClaw config file (usually at ~/.openclaw/config.json5) and add the Telegram channel block. The easiest way is via the CLI:

openclaw config set channels.telegram.enabled true
openclaw config set channels.telegram.botToken "123456789:ABCDefGhIJKlmNoPQRsTUVwxyZ"

Or add it directly to your config file:

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

The dmPolicy: "pairing" setting means only approved users can chat with your bot. This is the secure default — without it, anyone who finds your bot can use your API credits.

Step 3: Restart the gateway

openclaw gateway restart

The gateway reads channel config at startup. Changes don't apply until you restart.

Step 4: Send your first message and approve the pairing

Open Telegram and send any message to your new bot. Because pairing is enabled, the message will be held pending approval. In your terminal, check pending pairings:

openclaw pairing list telegram

You'll see your Telegram user ID and a pairing code. Approve it:

openclaw pairing approve telegram <CODE>

Your bot will now respond to your Telegram messages. Send it anything — it uses whatever AI model you configured during setup.

Optional: Add the bot to a group

Add your bot to a Telegram group, then update config to handle group messages. By default, the bot only responds when mentioned directly (@yourbotname):

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

Troubleshooting

"Telegram plugin not available" error: This usually means the gateway started before the Telegram config was saved, or the token is malformed. Double-check the token is exactly as BotFather gave it (no extra spaces), then run openclaw gateway restart. Run openclaw doctor for a full channel health check.
Bot does not respond after pairing: Make sure the gateway is running (openclaw gateway status) and that your AI provider API key is valid. The bot can receive messages but fails silently if the model API call errors out. Check gateway logs: openclaw gateway logs --tail 20
BotFather privacy mode blocking group messages: Telegram bots default to Privacy Mode, which means they only see messages that start with / or mention the bot directly. This is the correct behavior forrequireMention: true. If you want the bot to see all group messages, disable Privacy Mode in BotFather: /setprivacy → select your bot → Disable.

Frequently asked questions

Can I connect multiple Telegram bots?: Yes — OpenClaw supports multiple accounts per channel. Add additional bots underchannels.telegram.accounts in your config.
Is my conversation data sent to Telegram?: Your messages route through Telegram's servers (same as any Telegram message). The AI response is generated by your configured provider (Claude, GPT-5, etc.) — Telegram only sees the text content, not the AI interaction context.
Can I use this on multiple devices?: Yes. Telegram syncs across all your devices, so any device where you're logged into Telegram can send messages to your bot. The bot itself runs on wherever your OpenClaw gateway is hosted.