How to connect Telegram Bot to OpenClaw
Connect Telegram Bot to OpenClaw with ClawLink: paste your Telegram Bot key once and 18 tools work from chat. No MCP server to run, nothing stored on your machine.
Telegram BotAPI KEYMCPAutomate Telegram chats and channels through a Telegram Bot. Requires a bot token from @BotFather.. Once connected, OpenClaw can read and act on Telegram Bot from chat — pairing, token refresh, and tool wiring handled for you.
The usual route to Telegram Bot access for OpenClaw is an MCP server you configure and keep running, plus your own OAuth app or API keys. ClawLink gives OpenClaw a more practical Telegram Bot setup: install one ClawHub skill, connect Telegram Bot in the browser, and OpenClaw can call real Telegram Bot actions from any chat surface with no auth, token refresh, or tool wiring to build yourself.
Copy this prompt into OpenClaw, or open the Telegram Bot skill on ClawHub.
Before installing anything, inspect the ClawHub skill metadata and setup requirements.
If the skill asks you to install a third-party package or CLI, verify its source, maintainer, and package contents before running the install command.
Install the skill "Telegram Bot" (hith3sh/telegram-messaging) from ClawHub only after those checks pass.
Skill page: https://clawhub.ai/hith3sh/telegram-messaging
Keep the work scoped to this skill only.
After install, help me finish setup from verified skill metadata.
Use only the metadata you can verify from ClawHub; do not invent missing requirements.
Ask before making any broader environment changes.Setup
It takes three steps to connect OpenClaw to Telegram Bot.
1Install the plugin
Paste the setup prompt into OpenClaw, or install from the terminal and ask OpenClaw to pair:
openclaw plugins install clawhub:clawlink-plugin- 2
Connect Telegram Bot
Paste your API key in the dashboard.
- 3
Use it from chat
Ask OpenClaw: "What can you do with Telegram Bot?"
Install by command
The setup prompt above does all of this in one paste. By hand, it is one install command plus a browser approval:
openclaw plugins install clawhub:clawlink-pluginThen ask OpenClaw to set up ClawLink. It starts browser pairing and prints an approval link — open it, approve the device, return to the chat, and say done. Finally, connect Telegram Bot in the ClawLink dashboard — paste your Telegram Bot API key once.
Verify the connection by asking OpenClaw:
Use telegram_get_chat to confirm the bot can see the chat I name, then telegram_send_message the text I paste to it. Confirm the message id before you finish.
Using a different agent?
The OpenClaw plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI:
npx -y @useclawlink/cli loginlogin opens the same browser approval and stores a credential locally. Once Telegram Bot is connected in the dashboard, that agent calls the same 18 Telegram Bot tools over MCP. Full setup for MCP clients and shell agents: connect apps to any AI agent.
Telegram Bot MCP for OpenClaw
Looking for a Telegram Bot MCP server for OpenClaw? ClawLink connects Telegram Bot to OpenClaw and exposes 18 Telegram Bot tools your agent can call over MCP, with hosted auth and nothing to run or maintain yourself. Using Hermes instead? The Hermes Telegram Bot integration works the same way.
The AI Overview's answer for "connect Telegram to OpenClaw" is a config-file walkthrough: create the bot with @BotFather, paste the token into channels.telegram.botToken in ~/.openclaw/openclaw.json, restart the gateway, and approve pairing with openclaw pairing approve telegram \<CODE>. ClawLink keeps the BotFather step, because Telegram's Bot API requires a bot token and the AIO is right that you will always need one. What it removes is the file: you paste the token into ClawLink once, it is stored server-side, and the 18 tools below work from chat with no edit to openclaw.json, no gateway restart, and no config file to keep in sync.
The other ways OpenClaw gets Telegram
Every route below pairs the same OpenClaw runtime; what differs is where the token lives and what you keep running.
- The openclaw.json route the AI Overview teaches: BotFather bot, token pasted into channels.telegram.botToken in ~/.openclaw/openclaw.json, gateway restart,
openclaw pairing approve telegram \<CODE>. You maintain a config file and restart the gateway on every change. - Self-hosted Telegram MCP servers: Telethon/MTProto servers such as Better Telegram MCP or chigwell/telegram-mcp that you run yourself and point OpenClaw at. The bot-token ones need your token; the user-account ones use a different access model entirely.
- n8n / Make / no-code templates: Telegram nodes and bot flows in a workflow tool, still needing a BotFather token and somewhere to run.
- ClawLink (this page): all 18 tools over the official Bot API, token stored server-side, no config file, nothing running on your machine.
Using Hermes too? The Hermes Telegram Bot integration is the same bot-token connection and the same tools, with Hermes' pairing flow instead of the ClawHub skill.
What the OpenClaw Telegram Bot integration can do
18 Telegram Bot tools are ready for OpenClaw once the account is connected. The 17 below are the ones people reach for most; your agent can call all 18.
17 of 18 Telegram Bot tools for OpenClaw
| Tool | What it does |
|---|---|
Answer callback query telegram_answer_callback_query | Use this method to send answers to callback queries sent from inline keyboards. The answer will be displayed to the user as a notification at the top of the chat screen or as an alert. |
Create chat invite link telegram_create_chat_invite_link | Generate a new primary invite link for a chat; any previously generated primary link is revoked. |
Edit message telegram_edit_message | Edit text messages sent by the bot. Only bot-authored messages can be edited; editing messages from other users will fail. In groups, the bot must have edit permissions. |
Forward message telegram_forward_message | Forward messages of any kind. Service messages can't be forwarded. |
Get chat telegram_get_chat | Get up to date information about the chat (current name of the user for one-on-one conversations, current username of a user, group or channel, etc.). |
Get chat administrators telegram_get_chat_administrators | Get a list of administrators in a chat. On success, returns an Array of ChatMember objects containing information about all chat administrators except other bots. |
Get chat history telegram_get_chat_history | Get chat history messages via the getUpdates polling method, filtered by chat_id. Returns only updates from the specified chat. |
Get chat member telegram_get_chat_member | Get a chat member's status/role (including the bot itself) to preflight permissions and troubleshoot 403/empty-history issues. Use before sending messages to verify bot membership and permissions. |
Get chat members count telegram_get_chat_members_count | Get the number of members in a chat. The bot must be an administrator in the chat for this to work. Insufficient admin permissions surface as authorization errors, not as a zero or empty count. |
Get me telegram_get_me | Get basic information about the bot using the Bot API getMe method. Returns fields like id, username, first_name, and capabilities. |
Get updates telegram_get_updates | Use this method to receive incoming updates using long polling. An Array of Update objects is returned. IMPORTANT: This method will not work if an outgoing webhook is set up. |
Send document telegram_send_document | Send general files (documents) to a Telegram chat using the Bot API |
Send location telegram_send_location | Send point on the map location to a Telegram chat using the Bot API |
Send message telegram_send_message | Send a text message to a Telegram chat using the Bot API |
Send photo telegram_send_photo | Send photos to a Telegram chat using the Bot API |
Send poll telegram_send_poll | Send a native poll to a Telegram chat using the Bot API |
Set my commands telegram_set_my_commands | Use this method to change the list of the bot's commands |
Try it: find the Telegram Bot tool you need
Browse the 17 Telegram Bot tools
Click any tool to see exactly what OpenClaw can do and copy a ready-to-use prompt.
Example prompts
Use telegram_get_chat to confirm the bot can see the chat I name, then telegram_send_message the text I paste to it. Confirm the message id before you finish.
Use telegram_get_chat_history on the chat I name and summarize the last 15 messages. If the bot joined after some of them, tell me where the history starts.
Use telegram_create_chat_invite_link for the group I name and give me the link. Then run telegram_get_chat_administrators and tell me who moderates it.
Use telegram_send_poll in the chat I name with the question and options I paste next. Keep it non-anonymous and tell me the poll id.
Telegram tool behaviour worth knowing
The 18 tools wrap the Bot API; these are the constraints built into their schemas.
telegram_get_updatesandtelegram_get_chat_historyuse long polling, not webhooks. The schema warns that get_updates will not work if an outgoing webhook is set up; the two are mutually exclusive, and an active webhook produces a 409 conflict. A bot with a webhook configured elsewhere must have it removed before these tools can read.telegram_get_chat_historyonly sees what the bot could see after joining. The schema states that the bot can only retrieve messages sent after it joined the chat; missing older messages is expected, and an empty ok=true result means no accessible messages, not a failure.telegram_get_meis the token health check. Its schema states that ok=false means the bot token is invalid or revoked and must be replaced before any other API call works.telegram_get_chat_members_countrequires an administrator. The schema is explicit that the bot must be an admin in the chat, and that insufficient admin permissions surface as authorization errors, not as a zero count.telegram_delete_messagehas a 48-hour limit in groups. The schema lists it: messages older than 48 hours in groups, forwarded messages, and protected-chat content cannot be deleted, returning a 400.
ClawLink vs. building it yourself
The alternative to ClawLink is usually manual API key setup plus your own token handling, permission troubleshooting, and tool plumbing for OpenClaw. That is fine if you want to build and maintain the integration yourself. Most teams just want Telegram Bot working from chat.
| Manual | ClawLink | |
|---|---|---|
| Credential handling | Collect, validate, store, and rotate the Telegram Bot API key yourself, then make sure every tool call uses the right account. | Users complete the hosted ClawLink setup once and the connected Telegram Bot account becomes available to the agent without you building credential management. |
| Ongoing maintenance | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for Telegram Bot. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. |
| Agent usability | You still need to expose the right Telegram Bot actions to the runtime in a format your agent can reliably use. | 18 tools for Telegram Bot are already exposed through ClawLink, so the agent can read and act from chat immediately. |
ClawLink vs. Composio
Composio also exposes Telegram Bot to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for OpenClaw users instead. You install the plugin once, connect Telegram Bot in the browser, and the 18 tools above work from chat. There is no SDK and no config file, and the Telegram Bot key you paste at setup is stored server-side rather than kept in your environment. Choosing between them? Read the full Composio alternatives comparison.
Troubleshooting
OpenClaw installed the Telegram Bot skill but can't call the tools
The ClawHub skill teaches OpenClaw about Telegram Bot, but the calls run through the ClawLink plugin and your connected account. Make sure Telegram Bot is connected in the dashboard, then start a fresh chat so OpenClaw reloads the tool catalog. If OpenClaw runs as a persistent gateway, restart it so the new tools register.
Connection succeeds but no tools appear
Reconnect Telegram Bot from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.
"Tool schema not loaded yet" error when calling Telegram Bot tools
Telegram Bot tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Telegram Bot call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.
Telegram Bot returns 403 or "permission denied" on one action while others work
Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.
telegram bot api 401 unauthorized
The search results answer this with token mechanics from the manual flow: a malformed token in openclaw.json, a revoked token, a test-environment mismatch, and the OpenClaw-specific writeups (stack-junkie's fix post, github.com/openclaw issue #24506) debug exactly that. In the hosted flow there is no token in a config file to inspect; a 401 means the stored token was revoked or regenerated at @BotFather. The fix is to reconnect Telegram from the ClawLink dashboard and paste the current token. Distinguish the two before following any guide: a fix that edits openclaw.json does not apply here.
Ask the agent to diagnose it:
Call telegram_get_me and report exactly what it returns. If it returns ok=false, the stored token is invalid; tell me to reconnect with a fresh token from @BotFather.telegram api 429 too many requests
The cited OpenClaw 429 reports (github.com/openclaw issue #32017) happen at gateway restart, when the gateway re-registers the bot's commands. The hosted flow has no gateway and no restart step, so that trigger does not exist here. When a 429 does appear, the response carries retry_after and honoring it is the fix. Telegram's published numbers (one message per second, twenty per minute in groups) describe direct Bot API usage and are not claimed here as this connection's limits, because the hosted toolkit's rate posture belongs to the backend, not to anything on this page. Pacing bursty sends prevents most occurrences.
Ask the agent to diagnose it:
Report the exact status and any retry_after value from the failed Telegram call. Do not retry until that interval has passed.telegram bot token invalid
The manual-flow fix is curl https://api.telegram.org/bot\<TOKEN>/getMe to test the token, then regenerate it. This integration has the same check built in: telegram_get_me returns ok=false when the token is invalid or revoked, and the tool's schema says the token must be replaced before any other API call works. In the manual flow you edit openclaw.json; here you reconnect from the ClawLink dashboard with a fresh token from @BotFather (/token to issue one, /revoke to kill the old).
Ask the agent to diagnose it:
Call telegram_get_me. If it returns ok=false, tell me the token is invalid and that I should reconnect with a fresh one from @BotFather.telegram mcp tool not found
The SERP for this phrase is full of MCP server registries and self-hosted configs, because everyone running Telegram over MCP runs a server with a config file. In the hosted flow there is no local MCP server and no config file, so the tool-not-found fixes about paths and env vars do not apply. Here the error means the tool name was wrong or the schema catalog had not loaded; schemas load on demand, so one retry clears the second case, and the error message names the nearest real tools for the first.
Ask the agent to diagnose it:
List the Telegram tools you have access to and use the exact name for what I asked.API key setup works but results look incomplete
Double-check that the API key for Telegram Bot has the right scopes or account access. A valid key can still be too limited for some reads or writes.
FAQ
Is there a OpenClaw Telegram Bot integration?
Yes. ClawLink is the fastest way to connect OpenClaw to Telegram Bot: link your Telegram Bot account once in the browser and OpenClaw can call the Telegram Bot API through 18 ready-made tools — no custom code or token handling.
How do I add Telegram Bot to OpenClaw with ClawLink?
Paste the setup prompt from this page into OpenClaw. It installs the ClawLink Telegram Bot skill from ClawHub, then you click Connect in the dashboard to authorize Telegram Bot. OpenClaw calls the tools from the next message — no config files, and the Telegram Bot key you paste is stored server-side instead of in your environment.
How long does it take to connect Telegram Bot to OpenClaw?
About two minutes. Sign in, click Connect next to Telegram Bot in the dashboard, authenticate, and OpenClaw can use it from the next chat message.
Why use ClawLink instead of wiring Telegram Bot up myself?
The alternative to ClawLink is usually manual API key setup plus your own token handling, permission troubleshooting, and tool plumbing for OpenClaw. That is fine if you want to build and maintain the integration yourself. Most teams just want Telegram Bot working from chat.
Do I need a bot token from @BotFather?
Yes, and any page claiming otherwise is not describing Telegram. The Bot API requires a bot token, which means a bot created with @BotFather; the AI Overview's "you will always need a Telegram Bot Token" is correct as far as it goes. What the hosted flow removes is the rest of the manual path: no token pasted into ~/.openclaw/openclaw.json, no gateway restart, no env vars. The token you paste into ClawLink is stored server-side instead of in a config file on your machine, and @BotFather's /revoke kills the bot, and with it the connection, at any time.
What is the difference between this and the config-file flow the guides teach?
The guides edit channels.telegram.botToken in ~/.openclaw/openclaw.json, restart the gateway so the change takes effect, and approve pairing with openclaw pairing approve telegram \<CODE>. ClawLink replaces the config-file half of that: you paste the token once in the browser flow, and the agent calls the 18 tools from chat without a file edit or a restart. The openclaw pairing approve step still exists in the ClawHub skill flow, but it approves the ClawLink connection, not a token in a config file.
Is this the same as the Hermes Agent Telegram integration?
No, and the distinction matters because Telegram error threads get mixed up across the two runtimes. OpenClaw loads the Telegram Bot skill from ClawHub into a running gateway; Hermes (the Nous Research hermes-agent runtime) pairs through a hermes clawlink begin / finish CLI handshake. The two use the same ClawLink bot-token connection and the same 18 tools, but their setup commands and config files are different. If you are following a fix written for hermes gateway setup or hermes env files, you are in the wrong flow; the OpenClaw flow has no gateway setup command.
Is it safe to connect Telegram to OpenClaw?
Two halves again. Token hygiene: the token is stored server-side, and /revoke at @BotFather ends the bot and the connection immediately. Behaviour: an agent reading group messages is reading text written by other people, and that text can carry prompt-injection attempts aimed at the agent. Restrict the bot to the chats you name for it, keep it out of groups it does not need, and require manual approval before high-risk actions such as sending to a large group or acting on instructions found inside a message.
OpenClaw installed the Telegram Bot skill but can't call the tools
The ClawHub skill teaches OpenClaw about Telegram Bot, but the calls run through the ClawLink plugin and your connected account. Make sure Telegram Bot is connected in the dashboard, then start a fresh chat so OpenClaw reloads the tool catalog. If OpenClaw runs as a persistent gateway, restart it so the new tools register.
