OpenClaw Telegram troubleshooting

A Telegram bot that fails rarely fails loudly; it just does not answer, and the reason is usually one of a short list of settings on the Telegram side, the config side or the network in between. The docs organise the fixes by symptom, so this post does too: the group that ignores everyone, the group the bot cannot see, the commands that half work, the token rejected at startup, and the polling that stalls.

Groups and commands

• When the mention requirement is off, Telegram privacy mode must allow full visibility: set privacy to disabled with BotFather, then remove and re-add the bot to the group; the channels status command warns when the config expects unmentioned group messages, its probe flag checks explicit numeric group IDs while a wildcard cannot be membership-probed, and the activation-always command is a quick session test.
• If the bot sees no group messages at all, check that the group is listed under the groups map, or that the map includes the wildcard, whenever that map exists, verify that the bot is actually a member, and follow the logs for skip reasons.
• Commands that work partially or not at all usually mean the sender identity is not authorised, by pairing or by a numeric allowlist entry, because command authorisation still applies even when the group policy is open; the too-many-commands error from setMyCommands means the native menu overflows, so reduce plugin, skill and custom commands or disable native menus.
• The startup calls that delete and set commands and the typing indicator calls are bounded and retry once through Telegram's transport fallback on a request timeout; persistent network or fetch errors there usually mean DNS or HTTPS to the Bot API host is unreachable.

getMe returned 401 is a Telegram auth failure for the configured bot token.

Token and polling

A 401 from getMe means Telegram rejected the configured token: re-copy or regenerate it in BotFather and update the bot-token key, the token file, the account-level token or the environment variable for the default account. A 401 on deleteWebhook during startup is also an auth failure, and treating it as no webhook exists would only defer the same bad-token failure to a later call. Polling instability has more causes. Node 22 and later with a custom fetch or proxy can abort immediately when the abort-signal types mismatch, some hosts resolve the API host to IPv6 first so broken IPv6 egress causes intermittent failures, and fetch-failed or getUpdates network errors in the logs are retried as recoverable. During polling startup OpenClaw reuses the successful startup getMe probe for grammY, so the runner does not need a second probe before the first getUpdates; if deleteWebhook fails with a transient network error, polling continues instead of making another control-plane call, and a still-active webhook then surfaces as a getUpdates conflict that rebuilds the transport and retries the cleanup. A polling-stall log line means OpenClaw restarts polling and rebuilds the transport after 120 seconds without completed long-poll liveness, and the status probe and the doctor warn when a running polling account has not completed getUpdates after the startup grace, when a webhook account has not completed setWebhook, or when the last successful transport activity is stale.

Network, proxies and DNS

• Telegram honours the process proxy environment for Bot API transport, the upper and lowercase HTTP, HTTPS and ALL proxy variables, with the no-proxy variables still able to bypass the API host; if the OpenClaw proxy URL is set for a service environment and no standard proxy variable is present, Telegram uses that URL too, and on VPS hosts with unstable direct egress or TLS you route the API through a SOCKS5 or HTTP proxy under the channel proxy key.
• If text works but attachments fail with a DNS error, bare proxy variables still leave media downloads subject to local DNS checks: set the channel proxy to a trusted HTTP or SOCKS5 proxy so it resolves the media hosts, or configure a managed network proxy, keeping the proxy endpoint itself locally resolvable and reachable, and note that the dangerous private-network flag does not fix missing DNS.
• Node 22 defaults to automatic address family selection except on WSL2, the DNS result order follows the Telegram environment override, then the channel network key, then the process default, falling back to IPv4-first on Node 22 when none applies, and the channel network key can turn family selection off; the RFC 2544 benchmark range is already allowed for media downloads, and only when a trusted fake-IP or transparent proxy rewrites the API host to some other private or special-use address do you opt into the Telegram-only private-network bypass, at the channel or per account, which weakens the media SSRF protections and belongs only to operator-controlled proxy environments such as Clash, Mihomo or Surge; temporary environment overrides exist for family selection and result order, and two dig commands validate the A and AAAA answers.

OpenClaw on Telegram is the channel post these symptoms belong to, and OpenClaw Telegram access control the allowlists behind most silent groups.

Reading the symptom first

Almost every fix here starts with a command that already knows the answer: the status command warns about privacy mode and stale polling, the doctor warns about missing probes, and the logs list skip reasons. OpenClaw Telegram message behaviour explains the polling model those warnings watch, and OpenClaw bot loop protection the guard that stops two bots from answering each other once yours finally speaks.

On Diali

On Diali the Telegram channel is connected from the dashboard and the runtime config is generated and replaced at each release, so most of this list is ours to watch on the hosted side, while the token, the privacy-mode setting in BotFather and the group membership stay on yours. Telegram on Diali is the channel on Diali and Diali security the boundary that applies to every connected channel.

• No mention, no reply: disable privacy mode and re-add the bot.
• A 401 at startup means the token, not the webhook.
• Stalls restart after 120 seconds; proxies need DNS for media.