OpenClaw Telegram setup

A Telegram bot is the fastest channel to bring up, because the whole setup is one token from BotFather and one command that stores it. Here is the quick setup step by step, the token precedence rules, the settings that live on Telegram's side rather than in the config, and the transport choice between long polling and a webhook.

Quick setup

• Both BotFather flows end with a token you paste into OpenClaw: the chat flow, where you talk to the BotFather account, confirm the handle is exact, run the new-bot command and save the token, or the web flow in BotFather's web app, which runs in every Telegram client and lets you create the bot in a UI and copy its token.
• The fastest way to configure it is the channels add command with the Telegram channel and the token, which writes the token into the config for you; editing by hand instead means a Telegram block with the channel enabled, the bot token, the pairing DM policy and a wildcard group entry that requires a mention, and the bot-token environment variable is a fallback for the default account only, since named accounts must use the token key or a token file.
• With the default hot reload the running gateway applies the new channel configuration, and the channels status probe checks that Telegram is ready; if the gateway is offline you start it as a managed service or in the terminal, and a changed service environment needs a restart to load.
• Sending any message to the bot creates the pairing request that the pairing list command shows and the approve command accepts, with codes that expire after one hour; adding the bot to a group then needs your numeric user ID for the allowlists and the group chat ID as the key under the groups map, read from the logs, a forwarded-ID bot or the Bot API updates, confirmed with the whoami command once the group is allowed, and negative supergroup IDs go under groups, never in the group sender list.

Telegram does not use openclaw channels login telegram.

Tokens and the Telegram side

Token resolution is account-aware: a token file beats the bot-token key, the bot-token key beats the environment, config always wins over the environment variable, which only resolves for the default account, and after a successful startup OpenClaw caches the bot identity for up to 24 hours so restarts skip an extra getMe call, with a changed or removed token clearing that cache. On Telegram's side, bots default to privacy mode, which limits which group messages they receive; to see all group messages you either disable privacy mode with the set-privacy command or make the bot a group admin, and after toggling privacy mode you remove and re-add the bot in each group so Telegram applies the change. Admin status is controlled in the group settings, and admin bots receive all group messages, which suits always-on group behaviour. The helpful BotFather toggles are the join-groups setting that allows or denies group adds and the privacy setting for group visibility, both also available in BotFather's web app.

Long polling or webhook

• Long polling is the default; webhook mode needs a webhook URL and a webhook secret, with an optional path that defaults to the telegram-webhook route, a host that defaults to loopback, a port that defaults to 8787, and a certificate path for a self-signed PEM in direct-IP or no-domain setups; the listener reserves the health route for health checks, so the webhook path must use a different route, and an existing setup on that route must move, update the URL and the reverse proxy mapping, and verify the listener change with the status probe.
• In long-polling mode OpenClaw saves its restart position after an update is committed to the durable ingress queue, so a failed handler remains retryable from that queue; the local listener binds to loopback on port 8787 by default, and public ingress means a reverse proxy in front of it or an intentionally set wildcard host.
• Webhook mode validates the request guards, the Telegram secret token and the JSON body, commits the update to the durable queue before returning an empty 200, and marks successful durable adoption with an accepted-delivery header that health, routing, authentication, validation and storage-error responses omit, so a reverse proxy can require it rather than inferring acceptance from timing; after the durable write, updates are claimed and processed through the core ingress drain with per-chat and per-topic lanes, and slow agent turns never hold Telegram's delivery acknowledgement.

OpenClaw on Telegram is the channel post this setup belongs to, and OpenClaw Telegram access control what to decide next about who may reach the bot.

Where setups go wrong

Almost every failed Telegram setup is one of three things: a token pasted for a named account through the environment variable that only serves the default account, a group ID put in the sender list instead of the groups map, or privacy mode left on with the mention requirement off. OpenClaw Telegram troubleshooting walks those symptoms in order, and Connect your first channel in five minutes is the five-minute walkthrough for a first channel.

On Diali

On Diali the Telegram channel is connected from the dashboard and the runtime config is generated from it and replaced at each release, so the BotFather steps at the top of this post are the part that stays on your side. Telegram on Diali describes the channel on Diali and Diali security the boundary every connected channel shares.

• One token from BotFather; the CLI writes it for you.
• Pairing codes expire after an hour; group IDs go under groups.
• Long polling by default; webhooks need a secret and a free route.