OpenClaw Telegram Setup: Complete Guide

Telegram is the primary way most people interact with their OpenClaw agent. It turns your AI assistant into a mobile-friendly chat interface — you can send it tasks, receive proactive updates, and control your agent from anywhere using just your phone. This guide covers everything from creating your bot to advanced configuration.

Why Telegram?

OpenClaw supports multiple communication channels, but Telegram is the most popular for good reasons:

• Free: Telegram is completely free with no ads
• Fast: Messages are delivered almost instantly
• Cross-platform: Works on iPhone, Android, Windows, Mac, and browser
• Bot API: Telegram has an excellent, well-documented bot system
• Secure: End-to-end encryption available
• No phone number required for bots: Your bot communicates privately without exposing personal info

Prerequisites

Before starting, make sure you have:

• OpenClaw installed and configured (see our Setup Guide if not)
• A Telegram account (download at telegram.org or your app store)
• Your Anthropic API key already configured in OpenClaw

Step 1: Create Your Telegram Bot

Every OpenClaw agent needs its own Telegram bot. Creating one is free and takes about 2 minutes:

1. Open Telegram and search for @BotFather (the official bot creation service from Telegram)
2. Start a conversation and send: /newbot
3. BotFather will ask for a name — this is the display name (e.g., “My Assistant”)
4. Then it will ask for a username — must end in “bot” (e.g., “myassistant_bot” or “john_agent_bot”)
5. BotFather will send you a bot token — a long string that looks like 1234567890:ABCdefGHIjklMNOpqrSTUvwxyz
6. Copy and save this token somewhere safe — treat it like a password

Important: Keep your bot token private. Anyone with the token can control your bot.

Step 2: Install the Telegram Plugin

In your terminal, install the OpenClaw Telegram plugin:

openclaw plugin install telegram

The installer will prompt you for your bot token. Paste it in and press Enter.

Step 3: Configure Your Chat ID

For security, you’ll want to restrict your bot to only respond to messages from you (or your team). This requires your Telegram user ID.

To find your user ID:

1. Search for @userinfobot on Telegram
2. Send it any message
3. It will reply with your numeric user ID (e.g., 123456789)

Add this to your OpenClaw Telegram plugin configuration so the bot ignores messages from anyone else.

Step 4: Start OpenClaw and Test

Start your OpenClaw agent:

openclaw start

Now go to Telegram, find your bot (search by username), and start a conversation. Send a simple message like:

Hello, are you there?

Your agent should respond within a few seconds. If it does — you’re set up correctly!

Understanding Your Bot’s Behavior

Once connected, you can interact with your OpenClaw agent just like you would with any Telegram chat:

• Send messages asking it to do things: “Search for the weather in New York”
• Give it tasks: “Create a new file called meeting-notes.md with today’s date”
• Ask questions: “What did we talk about last Tuesday?”
• Use slash commands: /status, /reset, /reasoning

Setting Up Proactive Notifications

One of OpenClaw’s best features is that it can message you — without you asking first. This is called a heartbeat or proactive notification.

To configure this, edit your HEARTBEAT.md file in your workspace:

• List things you want the agent to check periodically (emails, calendar, weather)
• Set quiet hours so it doesn’t disturb you at night
• Define when it should reach out vs. stay silent

Example heartbeat checklist:

- Check email for urgent messages
- Check calendar for events in the next 2 hours
- Check weather if it's morning (6-10am)
- Stay quiet between 11pm and 8am

Using OpenClaw in Telegram Groups

You can add your OpenClaw bot to Telegram group chats — useful if you want to share your agent with a small team or family.

To add your bot to a group:

1. Open the group in Telegram
2. Tap the group name → Edit → Add Members
3. Search for your bot’s username and add it
4. Make the bot an admin if you want it to read all messages (required for some features)

Privacy tip: In groups, OpenClaw will see all messages. Configure it to only respond when directly mentioned (@yourbotname) to avoid it replying to every conversation.

Telegram Commands Reference

These commands work when sent to your OpenClaw bot in Telegram:

• /start — Initiate conversation with the bot
• /help — List available commands
• /status — See agent status and active settings
• /reset — Clear conversation context
• /reasoning — Toggle extended thinking mode
• /stop — Stop a running task
• /approve allow-once — Approve a pending action
• /approve deny — Deny a pending action

Troubleshooting Common Issues

Bot Doesn’t Respond

• Check that OpenClaw is still running (openclaw status)
• Verify the bot token is correct in your configuration
• Make sure you’re messaging the right bot (search by exact username)
• Check that your user ID is whitelisted if you set up restrictions

Bot Responds Slowly

• Normal response time is 3–15 seconds depending on task complexity
• Very slow responses (30+ seconds) may indicate API issues on Anthropic’s end
• Check your internet connection or VPS connectivity

“Unauthorized” Errors

• Your bot token may be invalid or revoked — generate a new one from BotFather
• Make sure you copied the full token with no extra spaces

Bot Works But Stops After a Few Hours

• OpenClaw likely crashed or your session ended — use PM2 to keep it running persistently
• On a VPS: pm2 start openclaw -- start && pm2 save && pm2 startup

Pro Tips for Daily Use

• Pin your bot chat: In Telegram, long-press the bot chat and pin it for quick access
• Create a shortcut: Add the bot to your phone’s home screen for one-tap access
• Use voice messages: Many versions of OpenClaw support voice message transcription — speak your tasks instead of typing
• Send files directly: You can send documents, images, and files to the bot for processing
• Set custom notifications: Configure Telegram to give your bot a distinctive notification tone so you notice proactive messages

Next Steps

With Telegram connected, your OpenClaw agent is fully operational. Explore what it can do:

• Install Skills to add new capabilities
• Master all available commands
• Ideas for using OpenClaw productively