Connecting OpenClaw to Telegram gives you a reliable, mobile-accessible channel to your agent from anywhere with a network connection. The setup is straightforward, but the most common mistake operators make is storing the openclaw telegram bot token in a way that exposes it to other processes, other users on the server, or version control history. This article covers how to configure the Telegram channel correctly and keep the token secure from day one.
TL;DR
- Create the bot via BotFather on Telegram and copy the token.
- Store the token in OpenClaw config using
openclaw config set, not by hand-editing the JSON. - Lock down access with dmPolicy “allowlist” and your Telegram chat ID in allowFrom before the bot goes live.
- Rotate the token if it is ever exposed. BotFather revocation takes under two minutes.
Throughout this article you will see indented blocks like the ones below. Each one is a command you can paste directly into your OpenClaw chat. Your agent will run it and report back. You do not need to open a terminal or edit any files manually.
Step 1: Create the Telegram bot via BotFather
Every Telegram bot, including the one you will use for your OpenClaw agent, is created and managed through BotFather, Telegram’s official bot management system. Open Telegram and search for @BotFather. Start a conversation and send /newbot. BotFather will ask for a display name and a username. The username must end in “bot” (for example, myagentbot or my_agent_bot). Once you confirm both, BotFather generates a bot token.
The token looks like this: 7654321098:AAFabcdefghijklmnopqrstuvwxyz1234567. The portion before the colon is the bot’s numeric user ID on Telegram. The portion after is the authentication secret.
Copy the token immediately after BotFather displays it. While you can retrieve it again from BotFather by sending /mybots, getting into the habit of copying it straight to the config command prevents you from accidentally pasting it somewhere insecure in the process. Do not paste it into any chat, document, note, or file other than the OpenClaw config input command. The openclaw telegram bot token is a live secret credential. Treat it with the same care you would give any API key that grants control over a running service.
Never paste the token into Discord or Telegram chat
Even in a private DM with your own agent, pasting the token in plaintext creates a record that persists in chat history, logs, and potentially LCM summaries. Always use the gateway config patch command to pass the token directly to the config file. Never type or paste it into any chat message, including messages to your own agent.
Step 2: Add the token to OpenClaw config
With the openclaw telegram bot token copied from BotFather, add it to the OpenClaw Telegram channel config. The correct config path is channels.telegram.token. Use the gateway config patch command so the token goes directly into the config file without passing through any chat interface as plaintext.
Apply a config patch to set channels.telegram.token to [YOUR_TOKEN_HERE] and channels.telegram.enabled to true. Show me the Telegram channel config section (with the token redacted) before applying so I can confirm the structure is correct.
If you are configuring OpenClaw for the first time via a terminal session rather than through an existing active channel, you can run the equivalent config command directly from the command line. The key principle is the same regardless of method: the openclaw telegram bot token must enter the config file through a controlled write operation, never through an unencrypted chat message or plaintext input.
After adding the token, verify the config was written correctly and completely before triggering any restart:
Read my openclaw.json and show me the channels.telegram section. Show the token as redacted (just confirm it is present and non-empty). Is enabled set to true?
Step 3: Set access controls before the gateway restarts
The most critical step that operators consistently skip: configure access controls on the Telegram channel before the bot goes live. Once the gateway restarts with the openclaw telegram bot token configured, the bot is immediately active and any Telegram user who searches for it by username can message it. If dmPolicy is not set to “allowlist” before that restart, the bot comes up fully open from its very first second online.
Before restarting the gateway: set channels.telegram.dmPolicy to “allowlist”. I will add my chat ID to allowFrom in the next step. Confirm this setting is applied to the config file now, before any restart.
The reason for setting this before restart: once the openclaw telegram bot is online with dmPolicy “all”, it is fully open. Any message from any user is processed. Setting dmPolicy to “allowlist” first means the bot comes up in a restricted state rather than an open one. You can always relax restrictions after the setup is verified and working correctly. You cannot undo access that already happened.
Step 4: Find your Telegram chat ID
allowFrom requires your numeric Telegram user ID (chat ID), not your username or display name. Before the openclaw telegram bot is live, the easiest way to get your numeric chat ID is through a Telegram helper bot. The @userinfobot account on Telegram will reply with your numeric user ID immediately when you send it any message. Send it any message and it returns your numeric ID.
Alternatively, after the gateway restarts with the bot active, send any message to your new bot and ask the agent to report the sender ID. Your agent has access to the message metadata including the sender ID on every inbound message.
I just sent you a message from Telegram. What is the sender ID (chat ID) of the message I just sent? I need this numeric ID to add to channels.telegram.allowFrom.
Once you have the numeric ID, add it to allowFrom:
Update channels.telegram.allowFrom to include [YOUR_CHAT_ID]. Confirm the full Telegram access control config: token present (redacted), enabled true, dmPolicy “allowlist”, allowFrom contains my chat ID.
Step 5: Restart the gateway and test
With the token in config, dmPolicy set to “allowlist”, and your chat ID in allowFrom, restart the gateway. The Telegram plugin will initialize, connect to Telegram’s API, and register the bot’s webhook or start polling.
Restart the gateway to activate the Telegram channel. After restart, confirm: is the Telegram channel plugin showing as connected? Are there any errors in the startup log related to Telegram?
Once the gateway is back up, open Telegram and find your bot by username. Send it a message. The agent should respond within a few seconds. If it does not respond, work through the troubleshooting section below before assuming the setup is correct.
I just sent a test message to my Telegram bot. Did you receive it? If yes, confirm receipt and the sender ID you observed. If no, check the gateway logs for any Telegram plugin errors.
Keeping the token secure after setup
The token is now in your openclaw.json. A few things to verify to keep it there and only there:
File permissions on openclaw.json. The config file should be readable only by the user running OpenClaw. Other users on the same server should not be able to read it.
Run: ls -la ~/.openclaw/openclaw.json and report the file permissions. If the permissions are not 600 (owner read/write only), show me the command to fix them and apply it.
Version control exclusion. If your workspace is a git repo, make sure openclaw.json is in .gitignore. The config file contains your Telegram bot token, API keys for every model provider, and any other secrets you have configured. None of that should ever be committed.
Check if ~/.openclaw/openclaw.json appears in any git repository’s tracking. Run: git -C ~/.openclaw ls-files openclaw.json 2>/dev/null and git -C /home/node/.openclaw/workspace ls-files ../.openclaw/openclaw.json 2>/dev/null. If any output is returned, the file is tracked and needs to be removed from tracking immediately.
No token in environment variables in plain text. Some setups pass the token through environment variables. This is generally acceptable but environment variables can be visible to other processes running as the same user. If you use environment variables for secrets, be aware of this exposure.
How to rotate the token if it is exposed
If you suspect the Telegram bot token has been exposed, rotate it immediately. Token rotation for an openclaw telegram bot is fast: the old token becomes invalid the moment the new one is generated in BotFather.
Rotating the token:
- Open BotFather on Telegram and send
/mybots - Select your bot from the list
- Choose API Token, then Revoke current token
- BotFather generates a new token immediately
- Copy the new token and update OpenClaw config
I have rotated my Telegram bot token via BotFather. Update channels.telegram.token to [NEW_TOKEN]. Confirm the config is updated and restart the gateway so the new token takes effect.
After rotating: check any places the old token may have been pasted or stored (chat logs, documents, notes) and remove it. The old token is already invalid, but removing it prevents confusion about which token is current.
The bot continues working during rotation
Token rotation does not delete the bot or remove it from servers and conversations. The bot username, all Telegram conversation history, and any group memberships all remain intact. Only the authentication credential changes. After updating the openclaw config with the new token and restarting the gateway, the bot resumes functioning normally with no other changes needed on the Telegram side.
Troubleshooting: bot not responding on Telegram
If the bot is online (gateway is running, Telegram channel shows no errors) but not responding to your messages, work through these checks in order:
Check dmPolicy and allowFrom. If dmPolicy is “allowlist” but your chat ID is not in allowFrom, the bot silently ignores your messages. This is the most common cause of a new setup that appears to work but produces no responses.
Show me channels.telegram.dmPolicy and channels.telegram.allowFrom. Is the numeric value in allowFrom exactly matching my Telegram user ID? Are there any formatting issues (extra spaces, quotes, wrong numeric format)?
Check whether the Telegram plugin is actually connected. The gateway may have restarted successfully but the Telegram plugin may have failed to initialize due to a token error or network issue.
Check the gateway logs for any errors from the Telegram channel plugin. Look for: invalid token errors, webhook registration failures, connection timeouts, or any other Telegram plugin startup errors. Show me the relevant log lines.
Verify the token is correct. A single wrong character in the token causes all Telegram API requests to fail with an “Unauthorized” error. If the token was typed rather than pasted, typos are likely.
Read channels.telegram.token from openclaw.json (show me the token length and first/last 4 characters only, not the full token). Then run: curl -s “https://api.telegram.org/bot[TOKEN]/getMe” and report whether the response shows ok:true or an error. Replace [TOKEN] with the actual token value.
Check for Telegram API rate limits or service issues. Telegram occasionally has API outages that affect bot connectivity. If the token is valid but the bot is still not responding, check Telegram’s status page or the official Telegram developer group for known issues.
Using the bot in Telegram groups
If you add the OpenClaw bot to a Telegram group, all group members can message it unless allowFrom restricts access. For personal agents, adding the bot to groups is usually not necessary. For shared setups, it requires careful access control configuration.
Is my OpenClaw Telegram bot currently a member of any group chats? If yes, list the group IDs. Are any group members not in my allowFrom list? What happens if a group member not in allowFrom sends a message to the bot in that group?
The bot must be specifically added to a group by an admin, it does not join groups automatically. If you have not added the bot to any groups, this is not a concern. If you have, verify the access controls cover the group context correctly.
What the Telegram bot token actually is
The Telegram bot token is an authentication credential that proves to Telegram’s API that you own the bot. It is a string in the format NUMERIC_ID:ALPHANUMERIC_SECRET. The numeric part is the bot’s unique user ID on Telegram. The alphanumeric part is the secret that authenticates requests.
The openclaw telegram bot token is a complete credential. With it, anyone can:
- Send messages as your bot to any user or group it is a member of
- Read messages sent to the bot
- Change the bot’s profile picture, description, and commands
- Delete messages the bot has sent
- Receive webhooks and configure polling settings
This is exactly why openclaw telegram bot token security matters from day one. It is not just about preventing someone else from chatting with your OpenClaw agent through the bot. It is about preventing anyone from impersonating your bot, reading your conversations, or sending messages on your behalf to any user who has interacted with the bot.
Has my Telegram bot token ever appeared in a chat message, a commit, a log file, or any location other than openclaw.json? Check: git log –all –full-history — ~/.openclaw/openclaw.json 2>/dev/null for recent commits touching the config, and check if any workspace files contain a string matching a Telegram token pattern (numbers:alphanumeric).
Bot name, privacy mode, and discoverability
When you create a Telegram bot, some settings affect how visible it is and how it behaves in groups. These are worth configuring through BotFather before deploying the bot.
Privacy mode. By default, Telegram bots in group chats only receive messages that mention the bot directly or start with a command (slash prefix). This is privacy mode enabled. If privacy mode is disabled, the bot receives all messages in the group. For a personal OpenClaw agent, leave privacy mode enabled. The bot should only respond when addressed.
To check or change privacy mode: send /setprivacy to BotFather, select your bot, and choose Enable or Disable. Enable means the bot only sees messages directed at it. This is the more secure and less noisy setting for an OpenClaw agent.
What privacy mode setting should my Telegram bot use for an OpenClaw agent? Is privacy mode currently enabled or disabled? If disabled, show me how to enable it through BotFather (the steps I need to take on my end, not the API call).
Allow groups. You can prevent your bot from being added to groups at all. Send /setjoingroups to BotFather and select Disable. With groups disabled, the bot can only be used in direct messages. For a personal agent you control, this is the cleaner setup.
Inline mode. By default, inline mode is disabled. Inline mode allows users to use the bot by typing @botusername query in any chat. This is not useful for an OpenClaw agent and should remain disabled.
Long polling vs webhook: which one OpenClaw uses
Telegram bots receive messages in one of two ways. Webhook mode requires Telegram to send an HTTP POST to a public URL on your server every time a message arrives. Long polling mode has the bot repeatedly call Telegram’s API asking for new messages. OpenClaw uses long polling by default.
Long polling is the correct choice for virtually all personal OpenClaw deployments because it requires no publicly accessible URL, no SSL certificate, and no inbound firewall rules. The openclaw telegram bot works correctly with the gateway bound to loopback (127.0.0.1) and behind any NAT or firewall with no additional configuration.
Is my OpenClaw Telegram integration using long polling or webhook mode? Can you confirm by checking the Telegram plugin config and the gateway logs for any webhook registration attempts?
If you previously configured a webhook for the same bot token outside of OpenClaw, the webhook may conflict with long polling. Telegram only allows one active delivery method at a time. To clear a previously set webhook and switch to polling:
Run: curl -s “https://api.telegram.org/bot[TOKEN]/deleteWebhook” and report the response. If a webhook was previously set, this clears it and allows polling to work correctly. Replace [TOKEN] with the actual token value.
Testing the connection from multiple devices
Telegram is multi-device. Your bot conversations are visible across all your Telegram devices. When you verify the setup by sending a test message, make sure you are testing from the same Telegram account whose chat ID is in allowFrom, not from a different account or device that uses a different account.
I want to verify the Telegram bot is working correctly from my mobile device. Send a response to this message confirming you received it via Telegram and can see my chat ID in the metadata. What is my Telegram user ID from this inbound message?
If the response arrives on your phone, the end-to-end connection is confirmed: BotFather created the bot, OpenClaw received the token, the Telegram plugin is polling successfully, your chat ID is in allowFrom, and responses are routing back correctly. All five components are working.
Notification settings for a personal agent bot
Once the bot is active, Telegram will notify you of every response from the agent with a push notification by default. For a personal agent that sends frequent cron job updates, this can produce notification noise. Telegram allows you to mute specific conversations or set custom notification settings per chat.
To mute the bot chat without disabling it: open the chat with your bot in Telegram, tap the bot name at the top, select Notifications, and choose Mute for a period or permanently. Muting prevents push notifications but the messages still arrive and are readable when you open the chat.
How should I handle notification settings for my OpenClaw Telegram bot if it sends frequent automated messages? What is the best practice for distinguishing urgent alerts (that should push a notification) from routine output (that can be read on my schedule)?
A pattern that works well: mute the bot conversation on Telegram, but configure urgent cron jobs to send to a separate Telegram conversation or group where notifications are enabled. Routine output arrives silently in the muted bot chat. Alerts go to the unmuted destination and push a notification.
Setting up bot commands for quicker access
BotFather allows you to define a commands list for your bot. These appear as suggestions when a user starts typing a slash in the bot chat. For an OpenClaw agent, you can define shortcut commands for frequent requests, for example /status for a status check or /brief for a morning brief.
What commands do I use most frequently with my OpenClaw agent via Telegram? Based on my recent interactions, suggest a list of 5 to 8 Telegram bot commands I could register with BotFather that would be useful shortcuts. Format as: /command – Description.
To register the commands, send /setcommands to BotFather, select your bot, and paste the list in the format BotFather expects. The commands appear as a menu in the Telegram chat UI but are entirely cosmetic. They do not add functionality, they are just visible shortcuts that send the slash command as a message to the bot.
Token backup and migration considerations
The bot token lives in openclaw.json. If that file is lost (server failure, accidental deletion, migration without backup), you can retrieve the token from BotFather. Send /mybots, select the bot, choose API Token, and the current token is displayed. This is why rotating the token is the correct response to potential exposure, not creating a new bot. The existing bot with all its conversation history and group memberships persists. Only the token changes.
Is my openclaw.json backed up anywhere? Check: is it in a git repository, does it get copied in any cron job or backup script, is it in the workspace that gets committed to the ghost-memory repository? If the config file is not backed up, recommend a backup approach that does not commit secrets to git.
A safe backup approach: keep the config in the standard location, ensure file permissions are 600, and separately note the BotFather bot name (not the token) so you can retrieve a fresh token if needed. Do not commit openclaw.json to a repository. The token inside it is a live secret.
Advanced Telegram config options worth knowing
Beyond the basics, a few config options are worth understanding before you encounter them unexpectedly.
parseMode. OpenClaw’s Telegram plugin sends messages in a default format. Telegram supports several parse modes: plain text, Markdown, MarkdownV2, and HTML. The parse mode determines how the bot renders formatting in outgoing messages. If agent responses include markdown (bold, code blocks, lists) and they are displaying as raw asterisks and backticks rather than formatted text, the parse mode setting may need adjustment.
What is the current channels.telegram.parseMode setting? Are markdown elements in agent responses rendering correctly in Telegram, or are they appearing as raw characters? If rendering is broken, what parseMode value would fix it?
polling interval. Long polling has a configurable interval that affects how quickly the bot receives new messages. A shorter interval means faster response to messages but more API calls. The default is usually acceptable. On high-latency connections or under rate pressure, adjusting this may help.
botApiUrl. By default the Telegram plugin calls Telegram’s official API at api.telegram.org. There is an option to run a local Bot API server for higher limits and more control, but this requires running additional infrastructure and is only relevant for high-volume use cases well beyond personal agent deployments.
Managing bot conversation history on Telegram
Telegram stores conversation history between your account and the bot. Every message, every agent response, every cron job notification accumulates. After months of active use, the conversation can get long. Telegram allows you to delete messages and clear conversation history.
For the agent, conversation history in the Telegram chat is separate from OpenClaw’s own context management. The agent’s working memory is managed by OpenClaw (LCM, memory plugin) independently of what is visible in the Telegram chat window. Clearing the Telegram chat history does not affect the agent’s memory or context.
Is my OpenClaw Telegram conversation history being used as context for agent responses, or does the agent’s context come from OpenClaw’s own context management (LCM, memory)? If I clear the Telegram chat history, what effect does that have on the agent’s ability to recall past conversations?
The answer matters for privacy. If you want a clean conversation history in Telegram without affecting agent memory, you can clear the Telegram chat. The agent’s context, stored in LCM and the memory plugin, is unaffected by Telegram-side deletion.
Configuring Telegram specifically for cron job alerts
Telegram’s reliability and mobile push delivery make it well suited as the primary channel for cron job alerts and notifications. Once the channel is configured and access controls are in place, routing cron job delivery to Telegram is a matter of setting the delivery config on each cron job.
Update all my time-sensitive cron jobs (morning brief, disk check alerts, error notifications) to deliver to Telegram at my chat ID [CHAT_ID]. Update non-urgent cron jobs (weekly reports, pipeline completions) to deliver to Discord. Show me the proposed cron delivery config changes before applying anything.
This separation gives you the notification behavior most personal agents benefit from: urgent items push to your phone via Telegram, verbose operational output goes to Discord where you can scroll through it when at a keyboard. The openclaw telegram bot token configuration is what makes the Telegram delivery path possible.
What to do after the first successful message
Once you have confirmed the Telegram bot is responding correctly, a few follow-up steps complete the setup:
- Note your Telegram chat ID in TOOLS.md so you have it handy for cron delivery configs without asking the agent each time
- Set the notification settings on the Telegram chat to match your preferred alert behavior
- Configure any cron jobs that should deliver via Telegram with your chat ID as the destination
- Run a proactive delivery test to confirm the agent can send messages to you unprompted
- Verify the bot token and config are not in any git-tracked file
Run the post-setup checklist for the Telegram channel. Check: is my chat ID saved in TOOLS.md? Are there any cron jobs that should be delivering to Telegram but currently have no delivery destination? Send me a proactive test message on Telegram right now to confirm unprompted delivery works. Check that openclaw.json is not tracked by git.
After those steps complete, the Telegram integration is fully operational and the openclaw telegram bot token is properly secured. The bot is accessible only to you, delivers output reliably, and is configured to avoid token exposure.
Frequently asked questions
Can I use the same Telegram bot for multiple OpenClaw instances?
No. A Telegram bot token can only have one active webhook or polling connection at a time. Telegram does not support multiple consumers of the same token simultaneously. If you configure two OpenClaw instances with the same token, the two instances will conflict and compete to receive inbound messages. The result is unpredictable: some messages go to one instance and some to the other, with no reliable way to know which one processed a given message. If you need two separate OpenClaw instances to both have Telegram access, create two separate bots through BotFather and configure each instance with its own unique token.
Do I need a public URL or open gateway port for Telegram to work?
No, if you use long polling. OpenClaw’s Telegram plugin uses long polling by default. In long polling mode, the bot repeatedly calls Telegram’s servers asking for new messages. This is an outbound connection from your server to Telegram’s API and requires no publicly accessible URL, no SSL certificate, and no inbound firewall rules. The gateway can remain bound to 127.0.0.1 (loopback only) and still receive Telegram messages without issue. Only webhook mode requires a public URL, and OpenClaw does not default to webhook mode for this reason.
How do I set a profile picture and description for the bot?
Both are managed through BotFather. Send /setuserpic to BotFather to set a profile picture, upload an image when prompted, and the bot will use it. Send /setdescription to set the about text that appears when a user first opens the bot. Send /setabouttext to set the short bio visible on the bot’s profile page. These are cosmetic settings that do not affect functionality. For a personal OpenClaw agent, they are optional, but setting a recognizable name and profile picture makes the bot easier to identify in your Telegram conversations list.
What is the message size limit on Telegram?
Telegram has a 4,096 character limit per message. OpenClaw’s Telegram plugin automatically splits longer responses into multiple sequential messages. This works correctly for most conversational outputs and short-to-medium structured responses. Very long structured outputs, such as large code blocks, full file contents, or long formatted lists, may split at awkward points in the middle of a code block or list item. For outputs that need to stay intact and readable, the better approach is to have the agent write the full content to a file and send a short summary or notification to Telegram instead. The full content is then readable by opening the file, while Telegram receives only the summary.
Can I have both Telegram and Discord active at the same time?
Yes. OpenClaw’s Telegram and Discord channel plugins run completely independently of each other. Messages arriving from Telegram are handled by the Telegram plugin and responses route back to Telegram. Messages from Discord are handled by the Discord plugin and responses route back to Discord. Both channels can be active and receiving messages simultaneously with no conflict or interference between them. The agent processes messages from both channels sequentially, one at a time, in the order they arrive. Access controls (allowFrom, dmPolicy, groupPolicy) are configured separately per channel and do not affect each other.
My bot username is being found and messaged by strangers. What do I do?
Confirm dmPolicy is set to “allowlist” and your chat ID is the only entry in allowFrom for the Telegram channel. With both settings correctly applied, messages from any Telegram user not in allowFrom are silently ignored. No response, no error message, no indication the bot received anything. Strangers who find the openclaw telegram bot typically stop attempting contact after a short period of no response. If dmPolicy is already “allowlist” and you are still seeing responses going to users who should not have access, check whether allowFrom contains correct numeric user IDs rather than usernames. Usernames can be reused by different accounts; numeric IDs cannot.
Can I disable the Telegram channel temporarily without removing the config?
Yes. Set channels.telegram.enabled to false and restart the gateway. The openclaw telegram bot token and all other Telegram channel settings remain intact in the config file. Re-enabling requires only setting enabled back to true and restarting the gateway. No token re-entry, no BotFather changes, and no access control reconfiguration is needed. The bot simply goes offline and comes back online as if it never left. This is the recommended approach for taking the Telegram channel offline temporarily, for maintenance windows, or during periods when you want the agent accessible only through Discord.