✈️ OpenClaw + Telegram Setup

Telegram is the fastest channel to connect — a single bot token gets you chatting with your agent from your pocket in minutes.

Why start with Telegram

Of all the channels OpenClaw supports, Telegram has the smoothest setup. There's no QR pairing, no phone-side daemon, and no developer-portal scopes to wrestle with. You create a bot, paste a token, and restart the gateway. It runs on Telegram's Bot API through grammY and is production-ready for both direct messages and groups.

01

One token, done

BotFather hands you a single token. No QR codes, no scanning a phone, no extra background process like WhatsApp needs.

02

Feature-rich

DMs, groups, forum topics, inline buttons, reactions, polls, voice notes, video, stickers, images, and documents are all supported.

03

Safe by default

Direct messages use a pairing policy out of the box. Until you approve a sender, strangers who find your bot can't command it.

04

Long polling

The default mode connects outbound to Telegram, so you don't need a public URL or reverse proxy. Webhook mode is optional.

Connect Telegram step by step

This assumes OpenClaw is already installed and you've run onboarding. If not, do the Quick Start first, then come back.

1

Create a bot with @BotFather

Open Telegram and start a chat with @BotFather — confirm the handle is spelled exactly @BotFather, since impostor accounts exist. Send /newbot and follow the prompts to pick a name and a username (the username must end in bot).

BotFather replies with a token that looks like 123456789:ABC-DEF1234ghIkl-zyx57W2v1u123ew11. Treat it like a password — anyone with it can drive your bot.

2

Add the token to OpenClaw

Run the guided channels configuration and paste the token when prompted:

openclaw configure --section channels

This writes the bot token into ~/.openclaw/openclaw.json under channels.telegram. If you prefer environment variables, the default account also reads TELEGRAM_BOT_TOKEN. The resulting config looks like this:

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

Telegram does not use openclaw channels login telegram the way QR-based channels do. The token in config or env is all it needs.

3

Restart the gateway

The Telegram connection is owned by the gateway process, so it needs a restart to pick up the new token:

openclaw gateway restart

Check it came up cleanly:

openclaw gateway status

A getMe returned 401 in the logs means Telegram rejected the token — re-copy it from BotFather and try again.

4

Pair your first DM

With dmPolicy: "pairing" (the default), the very first time you message your bot it won't just start talking — it issues a pairing code instead. Approve it from the CLI:

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

After approval, your DM session is live. Pairing codes expire after one hour, so approve promptly. The first approved pairing also bootstraps the command owner, so owner-only commands work without extra config.

Lock it down: only you can message it

Anyone can find a Telegram bot by its username, so access control matters. OpenClaw gives you three durable DM policies plus pairing.

🔐

DM policies

  • pairing (default) — new senders must be approved via the pairing flow above.
  • allowlist — only numeric Telegram user IDs listed in allowFrom can talk to the bot. Best for one-owner bots.
  • open — requires allowFrom: ["*"]; lets any Telegram account command the bot. Use only for intentionally public bots with tightly restricted tools.
  • disabled — no DMs at all.

For a personal assistant, the most durable setup is dmPolicy: "allowlist" with your numeric user ID, so access lives in config rather than depending on a past pairing approval.

🪪

Find your Telegram user ID

The privacy-friendly way needs no third-party bot: DM your bot, then tail the logs and read the from.id field.

openclaw logs --follow

You can also message @userinfobot on Telegram, but that shares your ID with a third party. Put the numeric ID in channels.telegram.allowFrom and, for owner-only commands, in commands.ownerAllowFrom as telegram:<your id>.

🛡️
Pairing is DM-only

Approving a DM pairing does not authorize that person in groups. Group access comes from explicit config allowlists. See the security guide for the full threat model before exposing the bot widely.

Groups and mention activation

Adding the bot to a group takes two pieces of config: which groups are allowed, and how the bot decides a message is meant for it.

👥

Allow a group

By default the group policy is an allowlist, so a freshly added bot stays silent until you list the group's chat ID under channels.telegram.groups. Negative IDs that start with -100 are Telegram supergroup chat IDs — they belong here, not in groupAllowFrom.

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

Get the group chat ID by reading chat.id from openclaw logs --follow after the bot sees a message, or by inspecting the Bot API getUpdates response.

📣

Mention activation

With requireMention: true the bot only replies when it's addressed. Test it from inside an allowed group:

@<bot_username> ping

Plain group chatter is ignored while a mention is required, which keeps the agent quiet in busy rooms. You can flip activation for the current session on the fly with the session commands /activation always and /activation mention, or set requireMention: false in config to make it permanent.

If the bot should see every group message, Telegram's Privacy Mode must allow it: in BotFather run /setprivacy → Disable, then remove and re-add the bot so Telegram applies the change.

Supported media and features

Telegram is the most capable channel OpenClaw ships with. Beyond plain text, the bot can send and receive a wide range of content.

✨

What works on Telegram

Recommended
✅ DMs ✅ Groups ✅ Forum Topics ✅ Inline Buttons ✅ Reactions ✅ Polls ✅ Voice Notes ✅ Audio & Video ✅ Stickers ✅ Images ✅ Documents

Inbound voice notes are transcribed and framed as untrusted text for the agent. Static stickers are downloaded and described; animated and video stickers are skipped. Outbound, the agent can reply with images, documents, voice notes, and video notes, and can react to messages where reactions are enabled.

You can also send messages or polls from the command line, which is handy for cron jobs and skills:

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message poll --channel telegram --target 123456789 \
  --poll-question "Ship it?" --poll-option "Yes" --poll-option "No"

Targets can be a numeric chat ID, a @username, or a forum topic in the form -1001234567890:topic:42.

💡
Streaming previews

By default Telegram shows partial replies live by editing a preview message as the agent works. Set channels.telegram.streaming to off for final-only delivery if you'd rather not see interim edits.

Quick troubleshooting

🔧

Bot isn't responding?

  • Confirm the gateway is up: openclaw gateway status
  • Watch for skip reasons in openclaw logs --follow
  • For DMs, make sure you approved the pairing or added your numeric ID to allowFrom
  • For groups, confirm the group's chat ID is in channels.telegram.groups and that you mentioned the bot when requireMention is on
  • getUpdates 409 conflicts mean another gateway or script is polling the same token — only one poller can use a token at a time

When in doubt, openclaw doctor --fix migrates stale config keys and repairs common Telegram setup issues.