OpenClaw Telegram integration isn’t working and I don’t know why

The Telegram integration is one of OpenClaw’s most useful features and one of its most opaque when something goes wrong. Messages stop arriving, commands go unanswered, and the agent shows no errors. This article walks through every layer of the integration in sequence, from the Telegram bot token to the OpenClaw plugin config to the channel routing, so you can find exactly where it broke and fix it without guessing.

How the Telegram integration works

Before diagnosing a broken integration, it helps to understand what is actually happening when Telegram and OpenClaw talk to each other. There are three pieces, and any one of them can be the problem.

The Telegram bot: A Telegram bot is an account controlled by software rather than a person. Telegram’s BotFather service is where bots are created and their tokens are managed. A bot token is a long alphanumeric string that acts as a password for your bot. Anyone who has your bot token can send messages as your bot. The token is the first thing to check when the integration stops working.

The webhook or polling connection: OpenClaw receives messages from Telegram in one of two ways. In webhook mode, Telegram sends an HTTP POST request to a URL you specify whenever someone sends your bot a message. Your OpenClaw instance must be reachable at that URL from Telegram’s servers for this to work. In polling mode, OpenClaw periodically asks Telegram “do you have any new messages for me?” This approach is more forgiving on network setup because it does not require a publicly reachable URL: your agent reaches out to Telegram, not the other way around. The tradeoff is latency. With a default polling interval, there is a 1 to 3 second delay between a message being sent and your agent receiving it. Webhook mode typically delivers messages in under half a second. The OpenClaw Telegram plugin as of March 2026 defaults to polling unless a webhook URL is explicitly configured in openclaw.json.

The plugin routing: Once OpenClaw receives a Telegram message, the plugin decides which agent session handles it. If this routing is misconfigured, messages arrive at OpenClaw but are silently dropped or routed to an agent that is not responding. This is the failure mode that looks most like a Telegram problem but is actually an OpenClaw problem.

Walk me through how my Telegram integration is currently configured. Read my openclaw.json and tell me: what bot token is set, what connection mode is active (polling or webhook), what webhook URL is configured if any, which agent session receives Telegram messages, and whether the Telegram plugin appears to be active and enabled. Show me the current values for each of these.

Step 1: Confirm your agent is running

Before checking anything Telegram-specific, confirm OpenClaw itself is up. A bot that cannot reach your agent produces the same symptom as a broken Telegram config: messages go unanswered. These are different problems with different fixes.

Run a status check on my OpenClaw installation. I need to know: is the gateway service running, when did it last start, are there any error messages in the service journal from the last 30 minutes, and is the Telegram plugin listed as active? Show me the full output.

If your agent is not running, the Telegram symptoms are a side effect, not the root cause. Fix the service first. The article on OpenClaw gateway restart issues covers the common causes of a downed gateway. Come back to this article once the agent is responding to direct messages in another channel (Discord, web UI, or the local API).

Step 2: Verify the bot token

A bot token is a string that looks like 7930272159:AAF_your_token_here. The number before the colon is your bot’s numeric ID. The string after the colon is the secret key. Telegram uses this token to authenticate your bot when it makes API requests. If the token is invalid, expired, or the bot was deleted and recreated, every API call fails silently from OpenClaw’s perspective.

Tokens can become invalid in several ways: you regenerated the token in BotFather but did not update openclaw.json, the bot was deleted and a new one created with a new token, someone revoked the token after a security incident, or the token was copied incorrectly (trailing space, missing character).

Test my Telegram bot token by making a getMe API call to Telegram. The URL is https://api.telegram.org/bot[TOKEN]/getMe where [TOKEN] is the value from my telegram config in openclaw.json. Do not show me the token value. Show me the full response from Telegram and tell me whether the token is valid. If the response contains an error, explain what it means.

A valid token returns a JSON response containing your bot’s username, first name, and ID. An invalid token returns {"ok":false,"error_code":401,"description":"Unauthorized"}. If you see a 401 error, the token needs to be replaced.

How to replace a revoked or invalid token

Token replacement in BotFather takes under two minutes. Open Telegram, find the BotFather account (search for @BotFather), send /mybots, select your bot, then select “API Token” and generate a new token. Copy the new token.

Update the Telegram bot token in my openclaw.json config to [NEW TOKEN]. Then restart the OpenClaw gateway so the change takes effect. Once restarted, test the connection by calling getMe against the new token and confirm it returns a valid bot identity.

Step 3: Confirm webhook or polling is set up correctly

A webhook URL is a web address that Telegram sends messages to. Think of it as a mailbox address. When you message your bot, Telegram delivers that message by making an HTTP request to your webhook URL. If that URL is wrong, offline, or not reachable from the internet, the delivery fails and your bot appears to do nothing.

Polling is the alternative. Instead of Telegram pushing messages to you, your OpenClaw instance repeatedly asks Telegram whether new messages have arrived. Polling does not require a publicly accessible URL, which makes it easier to set up on home networks or machines without a fixed public IP address.

Check what Telegram thinks your webhook is set to

Call the Telegram API getWebhookInfo endpoint for my bot. The URL is https://api.telegram.org/bot[TOKEN]/getWebhookInfo. Show me the full response. Tell me: is a webhook URL set, is there a pending update count, and are there any error messages in the last_error_message field. If last_error_message contains anything, explain what it means.

The response tells you exactly what Telegram has on file for your webhook. The last_error_message field is particularly valuable. Common values and what they mean:

• “Wrong response from the webhook: 403 Forbidden”: Telegram reached your server but was refused. Your reverse proxy or firewall is blocking Telegram’s IP ranges.
• “Failed to resolve host”: The domain name in your webhook URL does not resolve to a valid IP. DNS problem or the domain is wrong.
• “Connection refused”: Telegram reached your server’s IP but nothing is listening on the expected port. OpenClaw may be down or on a different port than the webhook URL specifies.
• “SSL certificate verification failed”: Telegram requires HTTPS webhooks with a valid certificate. Self-signed certificates are not accepted. As of March 2026, Telegram requires HTTPS for webhooks on port 443. Ports 80 and 88 can use HTTP, though HTTPS is strongly recommended for all ports. For HTTPS ports, the certificate must be from a recognized CA or a self-signed certificate explicitly submitted to Telegram’s setWebhook API in the certificate field.
• Empty last_error_message with a non-zero pending_update_count: Messages are queued but not being delivered. OpenClaw may be processing them slowly or the webhook endpoint is responding slowly.

Switching from webhook to polling

If your network setup cannot support a public webhook URL (home network, no fixed IP, no reverse proxy), polling is the correct mode. The tradeoff is a small delay between a message being sent and OpenClaw responding, typically 1 to 3 seconds at the default polling interval.

Check my Telegram plugin config. Is it set to polling or webhook mode? If it is set to webhook mode and I want to switch to polling: delete the current webhook registration by calling the Telegram deleteWebhook API, then update my openclaw.json to remove or blank the webhook URL so the plugin falls back to polling mode. Restart the gateway afterward and confirm the change took effect by calling getWebhookInfo again to verify no webhook is registered.

Step 4: Verify the plugin is enabled and correctly configured

The Telegram plugin must be both installed and explicitly enabled in your openclaw.json config. Installation without enablement leaves the plugin dormant. Enablement without the correct token or routing config leaves it running but not functional.

Read my openclaw.json and show me the complete Telegram plugin configuration. I need to see: whether the plugin is listed in plugins.entries, whether it has enabled:true set, what the token field contains (show the first 10 characters only for verification, not the full token), and whether there is an allowedUsers or allowedChats restriction set. Also tell me what happens to messages that arrive from users not in the allowedUsers list, if that setting is present.

The most common config issues:

• enabled: false or missing. The plugin is installed but dormant. Set enabled: true and restart.
• allowedUsers list is empty or too restrictive. If allowedUsers is set and your Telegram user ID is not in it, your messages are silently dropped. Telegram user IDs are numeric. Your ID is in your Telegram settings under Privacy and Security, or can be retrieved by messaging @userinfobot.
• allowedChats set but the chat ID is wrong. Chat IDs for group chats are negative numbers. Direct message chat IDs are positive numbers equal to your user ID. A common mistake is using a username (@yourusername) instead of the numeric chat ID.
• Token field is empty or set to a placeholder. Some OpenClaw installations ship with a template openclaw.json that has "token": "YOUR_TOKEN_HERE". If this was never replaced with a real token, the plugin will fail on every API call.

Step 5: Verify message routing

Routing is how OpenClaw decides which agent session handles a message from Telegram. If routing is misconfigured, messages arrive at your OpenClaw instance and are immediately discarded, or are sent to an agent that is not set up to respond.

The routing config lives in the plugin settings. The key field is which agent the plugin forwards messages to. In a single-agent setup this is straightforward. In a multi-agent setup, messages from specific chats or users can be routed to specific agents.

Check the routing configuration for my Telegram plugin. Tell me which agent or session name Telegram messages are forwarded to. Is that agent currently running and accepting messages? If there is a main agent and a secondary agent defined, tell me which one handles Telegram. If no routing target is explicitly configured, tell me what the default behavior is.

Check whether messages are arriving but being dropped

There is a meaningful difference between “Telegram is not delivering messages to OpenClaw” and “OpenClaw is receiving messages but not acting on them.” The gateway logs distinguish these two cases.

Check the OpenClaw gateway logs for the last 20 minutes. Look specifically for: any lines mentioning Telegram, any incoming message events, any routing errors, and any plugin errors. Show me all relevant log lines. If you do not see any Telegram activity in the logs, tell me whether the Telegram plugin is in polling or webhook mode, because that changes where to look next.

If the logs show messages arriving but no agent response, the problem is routing or agent availability. If the logs show no Telegram activity at all, the problem is earlier in the chain: either polling is not running, the webhook is not being called, or the plugin is not active.

Step 6: Send a test message and trace it

Once you have checked the token, webhook/polling config, plugin enablement, and routing, send a fresh test message and watch what happens end to end.

I am about to send a test message to my Telegram bot from my phone. Watch the gateway logs in real time for the next 60 seconds. Tell me what happens when I send the message: does it appear in the logs, does it get routed to an agent, does the agent generate a response, and does the response get sent back to Telegram? If anything in that chain breaks, tell me exactly where it stops.

This real-time trace is the fastest way to isolate the problem once the basic config checks are done. The message either arrives in the logs or it does not. If it arrives, the response either completes or it stops at a specific point. Each stopping point maps to a specific fix. You are not debugging in the dark: every layer of the integration produces a log entry when it handles a message, and a silent failure means the message never reached that layer. Work backward from the last layer that logged activity to find where the chain broke.

Specific error patterns and fixes

The bot works from some accounts but not others

If your bot responds to one Telegram account but not another, the cause is almost always the allowedUsers filter. The account that is not working is not in the allowedUsers list, or the list is using a username instead of a numeric ID.

Check whether my Telegram plugin has an allowedUsers restriction. If it does, show me the current list of allowed user IDs (not full tokens or credentials). Then help me add a new user ID to the list. The user ID I want to add is [USER ID]. Make the change in my config and restart the gateway.

The bot works in direct messages but not group chats

Group chats require two additional conditions that direct messages do not. First, the bot must have been added to the group and given message access. Bots in groups can only receive messages that either mention them directly or include a message privacy setting that allows all messages. Second, group chat IDs are negative numbers (for example, -1001234567890) and must be in the allowedChats config if that restriction is set.

I want my OpenClaw bot to respond in a Telegram group chat. The group chat ID is [CHAT ID, a negative number you can get by messaging @userinfobot in the group]. Check whether group chats are supported in my current Telegram plugin config. If there is an allowedChats restriction, add this chat ID to it. Also check whether the bot’s privacy settings in Telegram allow it to read all messages in groups, or only messages that mention it. Tell me what I need to change in BotFather if the privacy setting needs updating.

Responses are arriving with significant delay

If Telegram messages get responses but they take 10 to 60 seconds instead of 2 to 5, the issue is usually in one of three places: the model being too slow for the task, polling interval too long, or Telegram’s message queue has backed up because of prior failed deliveries.

Check three things related to Telegram response speed. First, what is the polling interval set to in my Telegram plugin config? Second, what model am I using for the main agent and what is the typical response time for that model? Third, run getWebhookInfo and check the pending_update_count field. If it is above zero, there are queued messages. Tell me what each finding means for response time and what I should change.

FAQ

Three things to check in order. First, the allowedUsers filter: if it is set and your Telegram user ID is not in it, your messages arrive at OpenClaw and are silently discarded without a response. Second, the agent session the Telegram plugin routes to: if that session is not running or is in an error state, messages arrive but produce no output. Third, the model: if the model configured for your agent is unreachable, rate-limited, or returning errors, the agent receives the message but fails to generate a response. Check all three by running the gateway log trace in Step 6 while sending a test message.

Plugin configs sometimes need to be re-enabled after an update if the update changed the plugin’s config schema. Check that your Telegram plugin entry in openclaw.json still has enabled: true and that the token field is still populated correctly. Updates occasionally reset plugin configs to defaults, which may blank out the token or disable the plugin. Also check whether the update changed the config key names for the Telegram plugin. If the plugin moved from one config path to another, your old settings are still in the file but the plugin is reading from a new location where no config exists.

No. Your bot token is the equivalent of a password for your bot. Anyone who has it can send messages as your bot, read messages sent to your bot, change your bot’s settings, and interact with any OpenClaw integration you have set up. If you have shared your token or suspect it has been exposed, revoke it immediately in BotFather using /mybots, select your bot, select API Token, and generate a new one. Then update your openclaw.json with the new token and restart the gateway.

Yes, if your OpenClaw setup has multiple agent definitions. The Telegram plugin routing config can specify different agents for different chat IDs. Ask your agent to show you the current routing config and help you add per-chat-ID routing rules. The structure varies slightly by OpenClaw version, so reading the current config first is the right starting point rather than writing rules from scratch.

The most common cause is a TLS/SSL mismatch. Telegram requires webhooks to use HTTPS with a valid certificate from a recognized Certificate Authority. Self-signed certificates are not accepted. If you are using a reverse proxy (Nginx, Caddy, or similar), verify the SSL certificate is from Let’s Encrypt or another recognized CA and that it has not expired. If you are exposing the OpenClaw port directly without a proxy, you need a valid SSL certificate on that port. Telegram does not support plain HTTP webhooks. The second common cause is a firewall that allows your traffic but blocks Telegram’s servers. Telegram uses a range of IP addresses for webhook delivery; your server’s firewall must allow inbound connections from those ranges on the webhook port.

No. Telegram only delivers messages to one destination per bot token. If two instances are both registered with the same token and one has a webhook set, Telegram delivers to that webhook only. The second instance receives nothing in polling mode. If both are in polling mode, they race for messages and each gets approximately half of them, unpredictably. Use a separate bot token for each OpenClaw instance. Tokens are free and you can create as many bots as you need via BotFather.

Four things cause spontaneous failures without any user-initiated change. First, Telegram occasionally invalidates bot tokens during security sweeps, particularly if the token appeared in a public repository, log file, or was accessed from an unusual location. Check the token by running getMe. Second, SSL certificates expire. If your webhook runs over HTTPS and the cert expired, Telegram stops delivering. Third, your server’s IP address may have changed (common on home networks with dynamic IPs or VPS providers that reassign IPs after a restart), breaking webhook delivery. Fourth, the Telegram plugin may have crashed silently inside OpenClaw. Checking the gateway logs for the time the integration stopped usually identifies the exact cause.

Step 7: Firewall and network checks

A firewall is a security layer that controls which network connections are allowed in and out of your server. Most VPS providers include a firewall by default, and many home routers have one too. If your OpenClaw instance is behind a firewall that blocks incoming connections from Telegram’s servers, webhook delivery will fail silently. The firewall refuses the connection before OpenClaw ever sees the request.

Telegram’s webhook delivery comes from two IP address ranges. Per Telegram’s official documentation, webhook requests come from 149.154.160.0/20 and 91.108.4.0/22. Telegram notes these ranges may change and recommends checking their webhook documentation if you encounter problems after restricting by IP. Your firewall needs to allow inbound connections on the webhook port from these ranges. Telegram supports webhooks on ports 443, 80, 88, and 8443. Port 443 (HTTPS) is the standard choice. If your setup uses a different port, allow that port specifically.

Check my server’s firewall rules. I am using Telegram webhooks and I need to verify that inbound HTTPS connections on port 443 are allowed. Show me the current firewall configuration. If UFW is running, show the output of the equivalent status check. If I am using a cloud provider like DigitalOcean, Hetzner, or Vultr, remind me to check their network-level firewall rules in the provider dashboard as well, since those sit in front of any OS-level firewall rules.

Cloud providers add an extra layer here. DigitalOcean, Hetzner, Vultr, AWS, and others all provide network-level firewalls (sometimes called Security Groups or Cloud Firewalls) that control traffic before it reaches your server. These are separate from the UFW or iptables rules on the server itself. Both layers must allow traffic for webhook delivery to work.

Using a reverse proxy for webhooks

A reverse proxy is a piece of software that sits between the internet and your OpenClaw instance, forwarding requests from outside to your agent. Using a reverse proxy (Nginx, Caddy, or Traefik are common choices) is the standard approach for running OpenClaw with a Telegram webhook on a VPS, because it handles TLS termination (the HTTPS part Telegram requires) and lets you keep OpenClaw itself on a non-standard internal port.

I want to set up a Caddy reverse proxy to handle my Telegram webhook. My domain is [your domain] and my OpenClaw gateway runs on port 18789. Generate a complete Caddyfile configuration that proxies HTTPS requests on port 443 to my local OpenClaw port. Also tell me whether I need to register the webhook URL with Telegram after setting this up and give me the exact API call to do that.

Step 8: Full reset and reconnect

If you have worked through every step above and the integration is still not working, a clean reset is usually faster than continued diagnosis. This involves deleting the webhook registration, confirming the token is valid, re-enabling the plugin from scratch, and re-registering the webhook.

I want to do a full reset of my Telegram integration. Walk me through this sequence: first, call deleteWebhook to clear any existing webhook registration. Second, call getMe to verify the bot token is still valid. Third, read my openclaw.json and confirm the Telegram plugin config looks correct. Fourth, restart the OpenClaw gateway. Fifth, if I am using webhook mode, call setWebhook to re-register the URL. Sixth, send a test message and watch the logs. Do each step and report the result before moving to the next one. Stop and tell me if any step fails before continuing.

This sequence eliminates the most common compounding problem: a partially broken state where one component was fixed but another is still in an error condition from before the fix. Starting fresh ensures each component is in a clean state. It also gives you a reliable baseline: if the full reset works and the integration is functional, you know the previous issue was a state problem. If it still fails after a clean reset, you have ruled out stale state and the problem is structural (config, network, or token).

Keep Reading: