If you only skim one sentence: wiring Telegram into OpenClaw takes about five minutes, gives you a fully mobile interface for your agent, and avoids most of the auth gymnastics you’ll hit with Slack or WhatsApp. Below is the exact setup I run in production and the pitfalls the community keeps tripping over.

Why engineers pick Telegram for OpenClaw

Telegram’s API is friendly to bots. No review queues, no app stores, no account whitelisting. The only gate is @BotFather. That matters because OpenClaw’s super-power is quick iteration. You can add a tool, push the daemon, and test on your phone in seconds. With Slack I routinely wait an hour for permissions to propagate; with Telegram the round-trip is a single /start message.

Other pragmatic upsides:

  • No gateway fees. Telegram’s bot API is free and rate limits are generous (30 msg/s per bot, 20 msg/s per group).
  • HTTPS optional in dev. You can run polling on localhost without a tunnel.
  • Inline commands & keyboards. Much richer UX than plain SMS.
  • Cross-platform. Same bot works on iOS, Android, macOS, Linux, web.

If you later need WhatsApp or iMessage, nothing in this guide blocks you. Telegram is just the lowest friction place to start.

Creating your Telegram bot token with BotFather

1. Chat with @BotFather

Open Telegram, search for @BotFather, hit Start.

2. Issue the create command

Send /newbot. BotFather asks for two things:

  • Display name – e.g. MyOpenClaw.
  • Username – must end with bot, e.g. my_openclaw_bot.

Immediately after, BotFather spits out a long token string:

123456789:AAE-f9FJ0mC1E2wUqF-rL8mPzZQZdKNdAbc

Copy that; you will not see it again.

3. Lock down privacy mode (optional)

By default, privacy mode prevents your bot from receiving all messages in a group. If you need full message access (for example, you want the agent to respond whenever someone mentions “deploy”), disable it:

  1. Send /setprivacy to BotFather.
  2. Select your bot.
  3. Choose Disable.

That’s it. Token in hand, move to OpenClaw.

Local development: polling mode in gateway.yaml

I recommend starting locally with long polling. No SSL, no public URL, no NAT headaches.

1. Install OpenClaw (or update)

# Node 22+ is required nvm install 22 npm i -g openclaw@latest

Running openclaw --version should print something like 0.33.4 (anything >=0.32 has the Telegram channel fixes).

2. Create a new project

mkdir claw-telegram-test && cd $_ openclaw init

The wizard walks you through naming the agent and enabling integrations. Choose Telegram when prompted. If you miss that step, just edit gateway.yaml manually:

channels: telegram: enabled: true token: "${TELEGRAM_BOT_TOKEN}" mode: polling pollingInterval: 1000 # milliseconds

Never hard-code the token. I keep secrets in .env and load with dotenv or export at shell:

export TELEGRAM_BOT_TOKEN="123456789:AAE..." openclaw dev

With the daemon running, DM your bot on Telegram and send /start. You should see connection logs in the terminal and a welcome reply from OpenClaw. If nothing happens, double-check:

  • Node version >=22
  • Token typo (copy again from BotFather)
  • Privacy mode disabled if in a group

Polling is good enough for tinkering, but production wants webhooks.

Production webhooks on ClawCloud (and bare metal)

Polling hits latency (messages arrive up to the pollingInterval) and burns CPU when idle. Webhooks push updates instantly and are what I run on ClawCloud. Two paths:

1. Hosted on ClawCloud (60 seconds)

  1. Sign in at claw.cloud.
  2. Click New Agent, pick a name, choose the Telegram channel.
  3. Paste your token.
  4. Hit Create.

ClawCloud auto-generates a public HTTPS endpoint and sets it with Telegram’s setWebhook API behind the scenes. You are live – open Telegram and try /ping.

2. Self-hosted behind nginx

If you roll your own VPS you need three things:

  • A public HTTPS URL (Telegram rejects plain HTTP).
  • A reverse proxy that forwards /telegram/webhook to the gateway port.
  • A one-time setWebhook call.

Example nginx snippet:

server { listen 443 ssl; server_name bot.example.com; ssl_certificate /etc/letsencrypt/live/bot.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/bot.example.com/privkey.pem; location /telegram/webhook { proxy_pass http://127.0.0.1:3210; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }

Then add to gateway.yaml:

channels: telegram: enabled: true token: "${TELEGRAM_BOT_TOKEN}" mode: webhook webhookPath: "/telegram/webhook"

Restart OpenClaw and run:

curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \ -d url="https://bot.example.com/telegram/webhook"

If Telegram returns {"ok":true}, you’re wired. Messages arrive in <100 ms in my experience.

Troubleshooting 502 errors: Telegram only supports a handful of ciphers. Make sure your nginx or Caddy TLS config includes TLSv1.2. Also keep body size <1 MB; larger uploads require the Bot API’s file endpoints anyway.

Group chats, inline commands, and other Telegram power-features

Most folks stop at DM, but Telegram gets interesting in group contexts. Here’s what I found useful:

1. Adding the bot to a group

  1. Open the group → Add Members → search your bot → add.
  2. If privacy mode is ON, prepend every command with / and the bot’s username: /run@my_openclaw_bot.
  3. To listen to all messages (recommended for /auto agents), disable privacy as described earlier.

2. Inline queries

Enable inline mode by sending /setinline to BotFather → Enable. Now in any chat type @my_openclaw_bot keyword... and Telegram sends an inline_query update. In OpenClaw that arrives like:

{ "type": "inline_query", "query": "deploy status prod", "from": { "username": "alice" } }

You can respond with rich articles, images, or buttons. I expose a “Quick Actions” inline menu that lets teammates trigger CI, fetch logs, or create Jira tickets without leaving Telegram.

3. Custom keyboards

For repeat commands (On-call?, Cluster healthy?) Telegram keyboards beat remembering slash syntax. Sample snippet inside an OpenClaw skill:

await ctx.reply("Pick one", { reply_markup: { keyboard: [["CPU"], ["Memory"], ["Disk"]], one_time_keyboard: true } });

4. File uploads

Telegram lets users drop files up to 20 MB via bots. The Bot API gives a file_id; OpenClaw’s telegram.downloadFile helper pulls it locally. I’ve wired that to an AWS Textract tool for on-demand OCR.

Operational playbook: secrets, logging, and zero-downtime rollouts

Secrets

  • Never commit TELEGRAM_BOT_TOKEN. GitHub’s secret scanner will catch it and Telegram will revoke it.
  • On ClawCloud, tokens live in the encrypted Environment tab. Rotate via the UI; the gateway restarts automatically.

Logging

Telegram errors are notoriously silent. I add this to openclaw.config.mjs:

export const hooks = { onChannelError: (ctx, error) => { console.error("Telegram error", error.response?.data || error); } };

With ClawCloud, logs stream into the web console and can be tailed via clawctl logs -f.

Rate limits

Individual chat messages are limited to ~20/second. If your agent blasts multi-line debug traces, batch them:

await ctx.replyChunks(longString, { delay: 40 });

The helper throttles messages to stay under Telegram’s 30 msg/s cap.

Zero-downtime deploys

Telegram webhooks are tied to a URL, not an IP, so blue/green deploys are easy. Point setWebhook at a version-specific path (/v2/telegram/webhook), verify traffic, then switch DNS or an nginx map. ClawCloud handles this for you: every push spins a new pod, warms it, then drains the old one.

Security checklist

  • Validate update_id monotonicity to prevent replay (OpenClaw does this by default).
  • If you run webhooks on bare metal, restrict inbound IPs to Telegram’s list (149.154.160.0/20, 91.108.4.0/22).
  • Strip markdown links users send if you pipe messages into the shell.

Next step: wire a real tool and ship

With Telegram plugged in you can now call any of OpenClaw’s 800+ Composio integrations. My recommendation: start with GitHub. Add the token, expose /merge and /deploy inline actions, and you have a pocket DevOps assistant. From there, explore scheduled jobs (cron: "*/15 * * * *") or browser automation for status checks. Telegram keeps the UX fast, and if something breaks you can roll back in under a minute. Happy building.