Haven't installed OpenClaw yet? Click here for one-line install commands
curl -fsSL https://openclaw.ai/install.sh | bashiwr -useb https://openclaw.ai/install.ps1 | iexcurl -fsSL https://openclaw.ai/install.cmd -o install.cmd && install.cmd && del install.cmd- Telegram is one of OpenClaw's most popular messaging channels, allowing users to issue commands to AI agents, receive reports, and control their computers from their phone anytime, anywhere[1]
- The integration process involves three steps: (1) Create a Telegram Bot via BotFather, (2) Write the Bot Token into OpenClaw's configuration, (3) Complete the Pairing verification[2]
- The Pairing mechanism is the security core of OpenClaw — only Telegram accounts that have completed pairing verification can control your agent, preventing others from accessing your computer through your Bot[5]
- DM Policy and group settings let you precisely control who can interact with the agent and in what contexts, preventing unauthorized access[1]
1. Why Choose Telegram?
OpenClaw supports multiple messaging channels, including WhatsApp, Discord, LINE, and Slack. So why is Telegram the top choice for many users?
- Fully open Bot API: Telegram's Bot API is free, unrestricted, and well-documented — no business account or approval process required[3]
- Code formatting support: Telegram natively supports Markdown and code blocks, so the agent's responses stay well-formatted
- Uncompressed file transfers: You can send raw files directly to the agent for processing without compression or conversion
- Cross-platform sync: Mobile, desktop, and web versions sync in real time — switch devices at any time
- Group functionality: You can create groups so team members share the same AI agent
2. Step-by-Step Setup Tutorial
Step 1: Create a Telegram Bot
In Telegram, search for @BotFather (Telegram's official Bot management tool) and send the following message:[3]
/newbotBotFather will ask you in sequence:
- Bot name (display name): e.g., "My AI Agent"
- Bot username (unique identifier, must end with
bot): e.g., "my_openclaw_agent_bot"
Once complete, BotFather will reply with a Bot Token in a format like:
7123456789:AAHx1234567890abcdefghijklmnopqrstuvKeep this Token safe — anyone who has it can control your Bot.
Step 2: Write the Bot Token to OpenClaw
Return to your terminal and run the following command to save the Token to OpenClaw's configuration:[1]
openclaw config set channels.telegram.botToken "YOUR_BOT_TOKEN"Then restart the Gateway for the settings to take effect:
openclaw gateway restartStep 3: Pairing Verification
At this point, your Bot is live on Telegram, but it cannot yet control the agent. You need to complete Pairing — OpenClaw's security mechanism that ensures only you can control the agent.[2]
- Send any message to your Bot in Telegram
- The Bot will reply with "Pairing Required" and display a pairing code
- In your terminal, run:
# View pending pairing requests
openclaw pairing list
# Approve pairing
openclaw pairing approveOnce pairing is complete, you can chat normally with the AI agent in Telegram.
3. DM Policies and Group Management
3.1 DM Policy
OpenClaw provides fine-grained access control to determine who can interact with the agent via direct messages:[1]
- owner_only (default): Only the paired owner can use it
- allowlist: Only Telegram users on the allowlist can use it
- anyone: Anyone can use it (suitable for testing only — never use in production)
openclaw config set channels.telegram.dmPolicy "owner_only"3.2 Group Settings
You can add the Bot to a Telegram group so that team members can share the AI agent. Access control within the group is managed via groupPolicy:
openclaw config set channels.telegram.groupPolicy "allowlist"Security note: In group mode, every action the agent takes can affect your entire computer. Make sure all group members are trusted individuals.[5]
4. Common Use Cases
4.1 Remote Development
Away from your desk but need to modify code on the server? Send a command to the agent via Telegram:
"Change the API_URL in config.js from staging to production, then run the deployment script"The agent will make the changes on your server, run the deployment, and report the results back to Telegram.
4.2 Scheduled Reports
Combined with OpenClaw's Cron functionality, set the agent to send a system status report via Telegram every morning:
"Every day at 9 AM, check the server's CPU, memory, and disk usage, and send a summary to Telegram"4.3 File Processing
Send files directly to the agent in Telegram for processing — for example, drop a CSV file and ask the agent to analyze the data and generate charts.[6]
5. Troubleshooting
| Problem | Cause | Solution |
|---|---|---|
| Bot has no response at all | Gateway is not running or Bot Token is incorrect | Confirm the Gateway is running (openclaw gateway status); verify the Token is correct |
| "Pairing Required" keeps appearing | Pairing was not completed or has expired | Run openclaw pairing approve again |
| Bot does not respond in group | Bot is not set as a group admin or groupPolicy restricts access | Set the Bot as a group administrator; check groupPolicy settings |
| Message delay exceeds 30 seconds | Slow LLM response or network latency | Switch to a faster model (Haiku); check the Gateway server's network |
| Chinese replies show garbled characters | Model is not configured for Chinese preference | Add language preference settings in the agent's System Prompt |
6. Security Best Practices
Controlling an AI agent via Telegram essentially extends your computer's control authority over the network. The following security principles must be observed:[5][8]
- Always use owner_only or allowlist: Unless you have a clear reason, never set the DM Policy to anyone
- Regularly check paired devices: Use
openclaw pairing listto view all paired devices and remove those no longer in use - Do not use in public groups: Only interact with the agent in private groups or direct messages
- Rotate Bot Tokens: If you suspect the Token has been compromised, immediately regenerate it in BotFather (
/revoke) and update the OpenClaw configuration - Limit agent Skill permissions: If the agent only needs to query data, do not install Skills with file modification permissions
Conclusion
The Telegram and OpenClaw integration turns the AI agent into your true "remote assistant" — no need to open your computer; a single Telegram message lets AI complete tasks for you.[6] The entire setup process takes just three steps and less than ten minutes.
If you haven't installed OpenClaw yet, we recommend reading the Architecture Deep Dive and Deployment Guide to complete the basic setup first. To learn about configuring other channels like WhatsApp and Discord, check out the Messaging Integration Guide.
