OpenClaw Telegram not working? Every fix, explained

Your OpenClaw bot is silent on Telegram while the gateway looks healthy. That combination is common and usually maps to a short checklist: token, channel config, pairing, group privacy, duplicate polling, or network transport. The Telegram channel docs are the reference; this page walks symptoms in the order that wastes the least time.

Triage commands

Run these on the gateway host before you edit config:

openclaw gateway status
openclaw channels status --probe
openclaw logs --follow
openclaw doctor

channels status --probe hits live Telegram checks when the gateway is reachable. Recent builds warn when polling never completes a successful getUpdates or when webhook registration never finished, even if a coarse status line still says ok (openclaw/openclaw#74299).

getMe returned 401

Startup logs with getMe returned 401 mean Telegram rejected the bot token before polling starts. OpenClaw stops there; webhook cleanup errors on a bad token are the same root cause per the channel docs.

Open BotFather, copy the token again or /revoke to mint a new one, then update config:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456789:AAExampLEtoKEN",
    },
  },
}

Or set TELEGRAM_BOT_TOKEN in the environment the gateway inherits. Avoid trailing spaces when you paste. Confirm with the getMe method or:

curl -sS "https://api.telegram.org/bot<TOKEN>/getMe"

That command puts the token in your shell history and the process list, so on a shared machine clear it afterward, or run openclaw channels status --probe instead, which checks the same getMe call without printing the raw token. Restart the gateway after changing the token. Run openclaw doctor to catch a wrong channels.telegram.apiRoot (it must be the API root, not a URL that already includes /bot).

access not configured

access not configured means OpenClaw has no usable Telegram channel configuration: missing channels.telegram, enabled: false, or no token source.

Minimum block:

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

Restart after edits. Long polling is the default; webhook mode needs channels.telegram.webhookUrl and a reachable listener, documented in the same Telegram page.

Pairing codes

Default DM policy is pairing. The first DM returns a short code and does not run your message. There is no paste box inside Telegram.

On the gateway host:

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Message the bot again. Codes expire after about an hour; send a new DM for a fresh code.

For a single owner bot, dmPolicy: "allowlist" with your numeric Telegram user ID in allowFrom avoids depending on pairing store files. openclaw doctor --fix can migrate recovered IDs when you switch policies.

dmPolicy: "open" with allowFrom: ["*"] lets anyone who finds the username talk to the bot, so reach for it only when you actually mean to run a public one. If you do, pare its tools back before you open it, since every stranger who messages it is then talking to an agent that can use whatever you left connected.

Silent in a group

DMs work but groups stay quiet when privacy mode filters updates. Bots normally see commands, @mentions, and replies to the bot. OpenClaw also expects a mention in groups unless you change activation.

In BotFather run /setprivacy, choose Disable, remove the bot from the group, and add it back so Telegram applies the setting. Group admin rights can behave similarly. Worth remembering while you do this: with privacy off the bot reads every message in the group rather than only the ones aimed at it, so save that for a group you run yourself and leave it on where other people are talking.

Test with an explicit @mention or /activation always in that chat before you loosen mention requirements globally.

Group sender authorization does not inherit DM pairing approvals. Set groupAllowFrom or config allowFrom when you restrict who can trigger the bot in groups.

Silent in DMs

Past token and pairing checks, dmPolicy: "allowlist" with an empty or wrong allowFrom blocks everyone. Add your numeric user ID:

{
  channels: {
    telegram: {
      dmPolicy: "allowlist",
      allowFrom: ["123456789"],
    },
  },
}

Find your ID in openclaw logs --follow on the next DM (from.id), or inspect getUpdates output. Confirm the gateway is actually running with openclaw gateway status, not only that Telegram printed ok once at boot.

Webhook still set

Long polling conflicts with an active webhook. Clear it:

curl -sS "https://api.telegram.org/bot<TOKEN>/deleteWebhook"

The deleteWebhook API documents parameters. OpenClaw normally calls this during polling startup; transient failures on current builds continue into getUpdates, while an active webhook surfaces as a conflict there.

If you intentionally use webhooks, set channels.telegram.webhookUrl and expose the local listener or reverse proxy per the channel docs instead of running a second poller elsewhere. Telegram only posts to a public HTTPS URL with a valid certificate, and the webhook secret token it echoes back on each request lets the gateway drop anything that did not come from Telegram, which is what stops a stranger who finds the endpoint from feeding it fake updates.

getUpdates 409

Logs with getUpdates 409 or "terminated by other getUpdates request" mean two consumers share one bot token. Causes include a second OpenClaw gateway, a dev script, or another host still polling.

Stop every duplicate process. Only one gateway per token should run getUpdates. openclaw gateway status --deep helps find extra gateway services on the same machine.

Network stalls

Intermittent fetch failed, long gaps with no inbound messages, or status ok while nothing arrives often trace to egress to api.telegram.org. Broken IPv6 paths are a frequent VPS pattern. Check DNS:

dig +short api.telegram.org A
dig +short api.telegram.org AAAA

The Telegram docs describe channels.telegram.network.dnsResultOrder, OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, and NODE_OPTIONS=--dns-result-order=ipv4first for Node 22+. WSL2 defaults differ from bare metal; see channel troubleshooting for proxy and timeout settings.

Raising channels.telegram.timeoutSeconds can help when the HTTP client hangs before OpenClaw's stall watchdog fires. Polling stall loops on some 2026.3.x builds were addressed upstream (openclaw/openclaw#47458); upgrade before you chase socket leaks by hand. High RTT hosts saw startup gates block polling on certain 2026.5.x builds (openclaw/openclaw#76388); current main continues to refine webhook cleanup versus getUpdates startup.

If logs stop after starting provider with no further Telegram lines on WSL2 after a version bump, verify grammY related dependencies installed with the global package (openclaw/openclaw#59833).

Setup guide

For first time wiring from scratch, the dashboard flow and BotFather steps live in How to set up OpenClaw on Telegram. This troubleshooting page assumes the bot already existed and stopped answering.

The managed option

Each cause above has a concrete fix once you match the log line. Telegram stacks token validity, gateway reachability, sender policy, group visibility, and a single poller per token, so several independent checks must pass.

Operator.io runs OpenClaw with Telegram connected on the hosted gateway: token storage, pairing, polling, and upgrades sit outside your VPS. You sign in and message the bot without maintaining channels.telegram on a box you reboot yourself. See pricing to try that path, or keep your own bot and use the triage commands at the top of this page.