How to Set Up an OpenClaw Telegram Bot (Complete Guide 2026)

Telegram is the most popular way to use OpenClaw. Instead of opening a terminal every time you want to talk to your AI agent, you message it on Telegram — from your phone, tablet, or desktop. It responds in seconds, runs tasks in the background, and remembers everything between conversations.

But getting from "I installed OpenClaw" to "my Telegram bot actually works" involves more steps than most guides let on. This article walks you through the entire process — from creating a Telegram bot to debugging connection issues. And at the end, we'll show you how LobsterLair does the same thing in about 60 seconds.

Why Telegram Is the Best Channel for OpenClaw

Before diving into setup, here's why most OpenClaw users choose Telegram over Discord, Slack, or the web interface:

• Always with you — Telegram runs on your phone, desktop, tablet, and web browser. Your AI agent is wherever you are.
• Push notifications — Get notified when your bot finishes a task, even if you sent the request hours ago.
• Rich media — Send and receive images, files, voice messages, and formatted text.
• No server exposure — Telegram bots connect outbound to Telegram's API. You don't need to open any ports or set up webhooks. Your server stays invisible to the internet.
• Privacy — With dmPolicy: "allowlist", only you can talk to your bot. Nobody else can find or message it, even if they discover the username.
• Free — Telegram's Bot API is completely free, no matter how many messages you send.

This outbound-only architecture is a big deal. Unlike building a traditional chatbot that needs a public URL, SSL certificates, and webhook endpoints, OpenClaw's Telegram integration just connects out and listens. Your firewall can block all incoming traffic and it still works.

What You Need Before Starting

To connect OpenClaw to Telegram, you need:

1. A working OpenClaw installation — Either via npm, Docker, or managed hosting. If you haven't installed OpenClaw yet, check our installation guide.
2. OpenClaw running in gateway mode — The gateway is the persistent daemon that maintains channel connections. Without it, Telegram won't work.
3. A Telegram account — The free app, available on all platforms.
4. 10-20 minutes — For the manual setup. (Or 60 seconds on LobsterLair, but we'll get to that.)

Step 1: Create a Telegram Bot

Every Telegram bot starts with @BotFather — Telegram's official bot for creating and managing bots.

Talk to BotFather

1. Open Telegram and search for @BotFather, or click the link above
2. Start a conversation and send /newbot
3. BotFather asks for a display name — this is what users see in the chat (e.g., "My AI Assistant")
4. BotFather asks for a username — must end in bot (e.g., my_ai_assistant_bot)
5. BotFather replies with your bot token

The token looks something like this:

7123456789:AAHfG3k9xN2vB8mQ1pL7wR4tY6uI0oP5aS

Keep this token secret. Anyone with it can control your bot. If it leaks, go back to BotFather and send /revoke to generate a new one.

Optional: Customize Your Bot

While you're talking to BotFather, you can also:

• /setdescription — Set what users see before starting a conversation
• /setabouttext — Short bio that appears on the bot's profile
• /setuserpic — Upload a profile picture for your bot
• /setcommands — Define slash commands (though OpenClaw handles messages directly)

These are cosmetic but make your bot feel polished.

Step 2: Get Your Telegram User ID

OpenClaw uses an allowlist to control who can talk to your bot. You need your numeric Telegram user ID (not your username).

Find Your User ID

1. Open Telegram and search for @userinfobot
2. Start a conversation — it immediately replies with your user ID

Your user ID is a number like 123456789. Save it.

Why the Allowlist Matters

Without an allowlist, anyone who finds your bot's username could send it messages — and your AI would respond, using your API credits. The allowFrom setting ensures only specific Telegram user IDs can interact with the bot. Everyone else gets ignored silently.

You can add multiple user IDs if you want family members or teammates to use the bot too:

"allowFrom": ["123456789", "987654321"]

Step 3: Configure OpenClaw

Now you need to tell OpenClaw about your Telegram bot. This means editing openclaw.json.

Find Your Config File

• npm/local install: ~/.openclaw/openclaw.json
• Docker: The file is inside the container volume. If you mounted it, it's at your mount path. Otherwise, you need to exec into the container:

docker exec -it openclaw cat /home/node/.openclaw/openclaw.json

Add the Telegram Channel

Edit openclaw.json and add the channels and plugins sections. Here's a complete example:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6"
      }
    }
  },
  "gateway": {
    "port": 18789,
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "your-gateway-token"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "7123456789:AAHfG3k9xN2vB8mQ1pL7wR4tY6uI0oP5aS",
      "dmPolicy": "allowlist",
      "allowFrom": ["123456789"],
      "groupPolicy": "disabled",
      "streaming": "partial"
    }
  },
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true
      }
    }
  }
}

Understanding the Configuration

The plugins.entries Gotcha

This is the most common reason Telegram doesn't connect. OpenClaw has a built-in "doctor" that runs on startup and normalizes your config. If plugins.entries.telegram.enabled isn't explicitly set to true, the doctor sets it to false — which silently disables Telegram even though channels.telegram.enabled is true.

You'll see no error message. The gateway starts fine. But the bot never connects to Telegram. If your bot isn't responding, this is the first thing to check.

Step 4: Restart the Gateway

After editing the config, restart OpenClaw's gateway to pick up the changes.

npm/Local Install

# If running in terminal, Ctrl+C to stop, then:
openclaw gateway

# If using systemd:
sudo systemctl restart openclaw

Docker

docker restart openclaw

Verify the Connection

Check the gateway logs to confirm Telegram connected:

# systemd
sudo journalctl -u openclaw -f

# Docker
docker logs openclaw --tail 100

You should see a log line indicating the Telegram channel connected successfully. If you see errors about invalid tokens or plugin not found, double-check your config.

Step 5: Test Your Bot

Open Telegram, find your bot by username, and send a message. Something simple like "Hello, are you there?"

If everything is configured correctly, your bot responds within a few seconds.

What to Try

Once it's working, test some capabilities:

• "What time is it?" — Checks basic responsiveness
• "Remember that my favorite color is blue" — Tests memory persistence
• "Set a reminder for tomorrow at 9 AM to check email" — Tests cron jobs (if the cron skill is installed)
• Send a photo — Tests image understanding (if your AI model supports vision)
• Send a voice message — Tests speech-to-text (if Whisper is installed)

Troubleshooting

Bot Not Responding at All

1. Check if the gateway is running:

   # systemd
   sudo systemctl status openclaw
   
   # Docker
   docker ps | grep openclaw
   

2. Check the logs for Telegram errors:

   docker logs openclaw --tail 200 | grep -i telegram
   

3. Verify plugins.entries.telegram.enabled is true — The number one cause of silent failures.

4. Verify your bot token — Go to BotFather, send /mytoken, and compare it with what's in your config.

5. Check the allowlist — If your user ID isn't in allowFrom, the bot ignores your messages silently.

Bot Responds Slowly

• First message after restart — OpenClaw indexes files and compiles skills on startup. The first response can take 30-60 seconds. Subsequent messages are fast.
• Long responses — If the AI model is generating a lengthy response, it takes time. With streaming: "partial", you'll see the response build up in real-time.
• Server resources — On a small VPS (1 CPU, 1GB RAM), response times increase under load. Monitor your server's CPU and memory.

"Unauthorized" or "Forbidden" Errors

Your bot token is invalid or expired. Get a new one from BotFather (/revoke then /newbot or re-copy the existing token).

Bot Works but Disconnects Randomly

• Server reboots — Make sure you have a restart policy (systemd Restart=unless-stopped or Docker --restart unless-stopped)
• Network issues — Telegram's API occasionally drops connections. OpenClaw reconnects automatically, but check your server's internet connectivity if it happens often.
• Memory pressure — Long-running Node.js processes can leak memory. If your server is swapping, the gateway may crash. Restart it and consider more RAM.

Bot Responds to Strangers

Your dmPolicy isn't set to "allowlist", or the allowFrom array is empty. With dmPolicy: "open", anyone can message your bot. Fix:

"dmPolicy": "allowlist",
"allowFrom": ["YOUR_USER_ID"]

Advanced Configuration

Group Chat Support

By default, we recommend groupPolicy: "disabled" for security. But if you want your bot in group chats:

"groupPolicy": "allowlist",
"allowGroups": ["-1001234567890"]

Get your group's ID by adding @userinfobot to the group — it posts the group's numeric ID (negative number).

Warning: In groups, the bot responds to every message unless you configure mention-only mode. This can get expensive with a paid AI provider.

Multiple Channels

OpenClaw supports Telegram, Discord, Slack, and more simultaneously. Each channel gets its own section in channels:

"channels": {
  "telegram": { "enabled": true, "botToken": "...", ... },
  "discord": { "enabled": true, "token": "...", ... }
}

Don't forget to add plugins.entries for each channel.

Custom System Prompt

Shape your bot's personality by creating SOUL.md in the OpenClaw workspace directory:

You are Luna, a friendly AI assistant.
You're concise and use clear language.
You respond in the same language as the user's message.
When asked about your capabilities, mention that you can browse the web,
manage files, set reminders, and remember context between conversations.

The bot picks this up automatically after a restart.

The Manual Setup Checklist

Here's everything you need to do to get an OpenClaw Telegram bot running from scratch:

That's assuming everything works on the first try. In practice, debugging config issues, waiting for gateway restarts, and troubleshooting token problems adds another 30-60 minutes for most people.

How LobsterLair Does It in 60 Seconds

All of the above — the server, Docker, OpenClaw, the AI model, the gateway, monitoring, backups — is exactly what LobsterLair automates away.

Here's the entire Telegram setup on LobsterLair:

1. Sign Up (20 seconds)

Go to lobsterlair.xyz, create an account with email or Google. No credit card needed.

2. Name Your Bot (10 seconds)

Pick a name during onboarding. Your OpenClaw instance starts deploying immediately.

3. Connect Telegram (30 seconds)

Paste your bot token from BotFather and your user ID. That's it. LobsterLair validates your token in real-time, saves the config, and connects to Telegram automatically.

Done

Your bot is live on Telegram. Send it a message and it responds.

No openclaw.json to edit. No plugins.entries to remember. No gateway to restart. No systemd service to write. No API key to manage — LobsterLair includes AI (MiniMax M2.5 with a 200K context window).

What You Get

• AI included — No need to get your own API key from Anthropic, OpenAI, or anyone else. LobsterLair provides the AI model.
• Always online — Isolated Docker container with automatic restarts and 24/7 monitoring.
• Automatic updates — New OpenClaw versions rolled out with zero downtime.
• Daily backups — Your bot's memory, personality, and config backed up offsite every day.
• 500+ tools pre-installed — Chromium for web browsing, ffmpeg for media, whisper for voice messages, yt-dlp for YouTube, and more.
• Web chat — Talk to your bot from the LobsterLair dashboard too, not just Telegram.
• Cancel anytime — Simple $19/month billing, no contracts.

Skip Telegram Entirely

Don't have a Telegram account? No problem. LobsterLair includes a built-in web chat — just message your bot from the dashboard. You can always connect Telegram later with a single click.

Self-Hosted vs. Managed: Telegram Setup Compared

Final Thoughts

Connecting OpenClaw to Telegram turns your AI agent from a terminal tool into a personal assistant that's always in your pocket. The setup isn't difficult for developers — but it has enough moving parts (tokens, user IDs, plugins.entries, gateway restarts, config doctor) that something usually goes wrong on the first attempt.

If you enjoy the process of configuring and running your own infrastructure, the manual route gives you full control. The OpenClaw community is active and the docs are solid.

If you'd rather skip straight to messaging your AI on Telegram, get started on LobsterLair for $19/month. Your bot will be live before you'd finish reading BotFather's instructions.