OpenClaw Telegram Setup Guide

TL;DR: Connecting OpenClaw to Telegram gives you a conversational interface to your AI agent from any device. You can ask it questions, give it tasks, and receive proactive updates right in your Telegram chat. Setup has three steps: create a Telegram bot through BotFather (Telegram's official bot management tool), configure the OpenClaw Telegram client with your bot token, and set up message routing so your agent knows which conversations to listen to and respond in. The process takes 30-60 minutes if your OpenClaw instance is already running. Common issues include webhook configuration errors (OpenClaw needs a publicly accessible HTTPS endpoint for Telegram to send messages to), message rate limits (Telegram caps bots at 30 messages per second), and permission scoping for deciding whether the bot responds in group chats or only in private messages. This guide covers the full setup plus configuration choices that affect how your agent interacts through Telegram.

Why is Telegram the best messaging option for OpenClaw?

Telegram is the most popular messaging interface for OpenClaw agents because of its open bot API, end-to-end encryption option, cross-platform availability, and lack of the approval process that Slack and WhatsApp require for bot integrations. Over 60% of OpenClaw deployments use Telegram as their primary interaction channel, according to community surveys.

The appeal is practical: once connected, you interact with your AI agent exactly like texting a coworker. Send a message, get a response. Ask it to check your email. Tell it to research a topic. Receive proactive alerts about calendar conflicts or important incoming messages. All from your phone, tablet, or desktop.

If you haven't set up OpenClaw yet, start with our installation guide. This guide assumes you have a running OpenClaw instance.

How do you create a Telegram bot with BotFather?

BotFather is Telegram's official bot for creating and managing other bots. Every Telegram bot starts here. The process takes about five minutes and gives you the API token you'll need for the OpenClaw configuration.

Open BotFather

1. Open Telegram on any device
2. Search for @BotFather (look for the verified checkmark)
3. Start a conversation and send /newbot

Name your bot

BotFather will ask two questions:

1. Display name: What users see in the chat header. Choose something descriptive: "My OpenClaw Agent" or "Acme AI Assistant" or whatever fits your use case. This can be changed later.

2. Username: Must end in "bot" and be globally unique on Telegram. Examples: my_openclaw_bot, acme_assistant_bot. This cannot be changed later, so choose carefully.

Save your bot token

After creating the bot, BotFather returns an API token, a long string that looks like:

1234567890:ABCDefGHIjklMNOpqrSTUvwxYZ

This token is a secret. Anyone with this token can control your bot. Store it securely, not in a public repository, not in an unencrypted file. You'll add it to your OpenClaw .env configuration in the next step.

Configure bot settings

While still in BotFather, configure these settings:

/setdescription — Set a description shown when users first open the bot
/setabouttext — Set the "about" text in the bot's profile
/setprivacy — Disable privacy mode if your bot needs to read group messages

Privacy mode is important: when enabled (the default), your bot only sees messages that start with a / command or directly mention the bot in group chats. For an OpenClaw agent that should respond to natural conversation in a group, disable privacy mode. For a bot that only responds to direct messages, leave privacy mode enabled.

How do you configure the OpenClaw Telegram client?

Add your Telegram bot token to your OpenClaw environment configuration. This step connects your bot identity to your running OpenClaw instance so the agent can send and receive messages.

Environment variables

Add these to your .env file:

# Telegram bot configuration
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_ENABLED=true

# Optional: Restrict to specific Telegram user IDs
TELEGRAM_ALLOWED_USERS=123456789,987654321

# Optional: Enable group chat support
TELEGRAM_ALLOW_GROUPS=false

# Webhook configuration (recommended for production)
TELEGRAM_WEBHOOK_URL=https://yourdomain.com/telegram/webhook
TELEGRAM_WEBHOOK_SECRET=a_random_secret_string

User ID restriction

This is a critical security setting. Without TELEGRAM_ALLOWED_USERS, anyone who discovers your bot's username can interact with your agent and, through it, access your email, calendar, and other connected services.

To find your Telegram user ID:

1. Search for @userinfobot on Telegram
2. Send it any message
3. It replies with your user ID (a number like 123456789)

Add every authorized user's ID to the TELEGRAM_ALLOWED_USERS list, separated by commas. The bot will ignore messages from anyone not on this list.

Polling vs. webhooks

OpenClaw supports two methods for receiving Telegram messages.

Polling (simpler, works anywhere):

TELEGRAM_MODE=polling
TELEGRAM_POLL_INTERVAL=2  # seconds between checks

Your OpenClaw instance repeatedly asks Telegram "any new messages?" This works behind firewalls and NATs but adds latency equal to the poll interval.

Webhooks (recommended for production):

TELEGRAM_MODE=webhook
TELEGRAM_WEBHOOK_URL=https://yourdomain.com/telegram/webhook

Telegram pushes new messages to your server instantly. Requires a publicly accessible HTTPS endpoint, which you should already have if you followed the VPS setup guide with a reverse proxy.

Webhooks are faster (instant delivery vs. polling delay) and more efficient (no repeated API calls). Use polling for testing; use webhooks for production.

How do you set up the webhook endpoint?

If you're using webhooks (recommended), configure your reverse proxy to route Telegram's messages to OpenClaw. This ensures incoming messages reach your agent and responses go back to Telegram.

Caddy configuration

If you're using Caddy as your reverse proxy:

yourdomain.com {
    handle /telegram/webhook {
        reverse_proxy localhost:3000
    }

    handle {
        # Your existing OpenClaw gateway config
        reverse_proxy localhost:3000
    }
}

Register the webhook with Telegram

After your endpoint is accessible, register it:

curl -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
  -H "Content-Type: application/json" \
  -d "{
    \"url\": \"https://yourdomain.com/telegram/webhook\",
    \"secret_token\": \"your_webhook_secret\"
  }"

Verify it's working:

curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo"

You should see your URL listed with "has_custom_certificate": false (if using Let's Encrypt) and no pending errors.

How do you test the connection?

Once the webhook is registered, restart your OpenClaw instance to pick up the new configuration and verify that messages flow correctly in both directions.

Restart your OpenClaw instance (if you need help with Docker commands, see our OpenClaw Docker setup guide):

docker compose restart

Open Telegram and send a message to your bot. Try something simple:

What time is it?

If everything is configured correctly, your agent will respond. If it doesn't:

1. Check OpenClaw logs: docker compose logs openclaw-core --tail 50
2. Check webhook status: Run the getWebhookInfo curl command above and look for error descriptions
3. Verify bot token: Make sure the token in .env matches what BotFather gave you
4. Check user ID restriction: If you set TELEGRAM_ALLOWED_USERS, confirm your user ID is in the list

How do you configure your agent's Telegram behavior?

Beyond basic messaging, Telegram integration supports proactive notifications, message formatting, group chats, and rate limit management. These settings control how your agent communicates with you day to day.

Proactive notifications

The real power of Telegram integration isn't just responding to your messages. It's your agent reaching out to you when something matters.

Configure notification triggers in your OpenClaw workflow settings:

notifications:
  telegram:
    # Notify when important emails arrive
    email_priority_alert: true
    # Morning briefing at 7 AM
    daily_briefing: "07:00"
    # Calendar conflict detection
    calendar_conflicts: true
    # Task completion reports
    task_completion: true

Your agent might message you at 6:55 AM with: "You have 3 meetings today. The 10 AM with Acme has a conflict with your dentist appointment. Two urgent emails overnight, one from your investor about the Q1 report and one from a client requesting a proposal. Want me to draft responses?"

That's the difference between a chatbot and an agent. The agent didn't wait for you to ask. You can extend these notification capabilities further using OpenClaw skills.

Message formatting

Telegram supports Markdown formatting in bot messages, and OpenClaw's Telegram client uses it automatically. Agent responses include bold text for emphasis, code blocks for technical content, bullet lists for structured information, and inline links for references. You can adjust the formatting style in the Telegram client settings if responses are too verbose or too sparse.

Group chat configuration

If you want your agent available in a team Telegram group:

1. Disable privacy mode in BotFather (/setprivacy → Disable)
2. Set TELEGRAM_ALLOW_GROUPS=true in .env
3. Add the bot to your group
4. Configure how the agent responds in groups: all messages, only when mentioned, or only commands

Security note: In a group chat, every member can interact with your agent. Make sure the agent's permissions are appropriate for the group context. A shared research agent is fine. An agent with access to your personal email should only be in private chats.

Rate limits and throttling

Telegram limits bot messages to 30 per second globally and 1 message per second per chat. OpenClaw's Telegram client handles this automatically, but be aware that agents generating long, multi-part responses may hit per-chat limits, proactive notifications should be batched rather than sent as separate messages, and group chats with multiple users interacting simultaneously can approach global limits.

How does Telegram compare to other messaging platforms?

Each messaging platform has tradeoffs for OpenClaw integration. Telegram is the path of least resistance for personal and small-team use, while Slack is better for enterprise teams already living in that tool.

| Platform | Pros for OpenClaw | Cons | |----------|-------------------|------| | Telegram | Open bot API, no approval process, end-to-end encryption available, rich formatting | Less common in US corporate environments | | Slack | Ubiquitous in business, channel-based organization | Requires Slack app approval, workspace admin permission | | WhatsApp | Most widely used globally, familiar to everyone | Business API requires Meta approval, costs per message | | Discord | Great for communities, rich bot ecosystem | Perceived as gaming/social, not business |

Most agents can be connected to multiple platforms simultaneously. Configure Telegram first for testing, then add Slack or WhatsApp as needed. Once your messaging is connected, our guide to your first 90 days with an AI agent covers how to get the most out of it.

Related guides

• What Is OpenClaw? A Guide for Business Leaders -- the complete overview of what OpenClaw does and why it matters
• How to Install OpenClaw: Complete 2026 Guide -- get your OpenClaw instance running before connecting Telegram
• OpenClaw Skills: How They Work and How to Vet Them -- extend your agent's capabilities through the Telegram interface
• Best VPS for OpenClaw in 2026 -- choose hosting that supports webhook delivery and always-on availability

Key takeaways

• Telegram is the most popular OpenClaw messaging interface because of its open bot API and zero approval process.
• Setup takes 30-60 minutes if your OpenClaw instance is already running: create a bot, configure the client, set up webhooks.
• Always set TELEGRAM_ALLOWED_USERS to restrict who can interact with your agent through Telegram.
• Use polling for testing and webhooks for production; webhooks deliver messages instantly and reduce API calls.
• Proactive notifications (morning briefings, email alerts, calendar conflicts) are what make Telegram integration valuable beyond basic chat.
• Group chat support is available but requires careful permission scoping so shared agents don't expose private data.

Frequently Asked Questions

Is my Telegram conversation with the agent encrypted?

Standard Telegram chats (including bot conversations) use client-server encryption, meaning messages are encrypted between your device and Telegram's servers, but Telegram can technically read them. For more private agent conversations, Telegram offers "Secret Chat," though bots currently have limited support for it. The most sensitive data (email content, credentials) is processed on your OpenClaw server, not passed through Telegram messages.

Can multiple people use the same Telegram bot?

Yes. Add multiple user IDs to TELEGRAM_ALLOWED_USERS. Each user's conversation with the bot is separate, and the agent maintains different context for each person. In group chats, the agent sees all messages but maintains a shared conversation context for the group.

How do I update the bot's name or username later?

The display name can be changed anytime in BotFather with /setname. The username (the one ending in "bot") cannot be changed. You'd need to create a new bot. Choose your username carefully during initial setup.

What happens if my OpenClaw server goes down?

Telegram queues messages sent to your bot for up to 24 hours. When your server comes back online and the webhook reconnects, it receives the queued messages. Your conversations aren't lost, but responses are delayed until the server recovers. This is another reason reliable hosting with restart policies matters. See our VPS hosting guide.

Do I need a domain name for Telegram webhooks?

For production webhook mode, yes. Telegram requires an HTTPS URL to send messages to, which means you need a domain pointing to your server with a valid TLS certificate. If you're using Caddy as your reverse proxy, it handles certificate provisioning automatically. For testing, polling mode works without a domain.

Telegram is how most people interact with their OpenClaw agent day-to-day. If you want a fully configured agent — Telegram connected, workflows running, security hardened — without touching a terminal, we set up the whole stack. You open Telegram, your agent is ready.