How to Connect OpenClaw to Telegram (Without the Setup Headache)

Telegram is the most popular platform for OpenClaw bots. It's instant, cross-device, and free. But getting OpenClaw talking to Telegram requires navigating a surprisingly long chain of config: create a bot via BotFather, grab the token, configure your OpenClaw gateway, handle polling vs webhooks, deal with Node.js version errors — all before your agent says its first word.

This guide walks through every step. If you want to skip straight to a working Telegram bot without any of this, NeatClaw does the entire setup in about 90 seconds.

Step 1: Create a Telegram Bot with BotFather

Every Telegram bot starts here. Open Telegram and search for @BotFather (the official bot creation service).

1. Open Telegram → search "@BotFather"
2. Send /newbot
3. Choose a name (e.g., "My OpenClaw Agent")
4. Choose a username (must end in "bot", e.g., "myopenclaw_bot")
5. BotFather sends you a token like: 7392847261:AAHxyz...

Save that token. It's the credential that lets OpenClaw send messages as your bot. Treat it like a password — anyone with this token can control your bot.

Step 2: Install OpenClaw

If you haven't already:

# Requirements: Node.js 18.x or higher
node --version  # must be v18+

npm install -g openclaw

# Or if you prefer yarn:
yarn global add openclaw

Common failure: Node version mismatch. OpenClaw requires Node.js 18.x minimum. If you're on 16.x, you'll see:

Error: The engine "node" is incompatible with this module.
Expected version ">=18.0.0". Got "16.14.2"

Fix with nvm:

nvm install 18
nvm use 18
npm install -g openclaw

Step 3: Configure OpenClaw's Telegram Integration

OpenClaw uses a config file (typically ~/.openclaw/config.json) for platform connections. You need to add your Telegram bot token:

{
  "platforms": {
    "telegram": {
      "enabled": true,
      "token": "7392847261:AAHxyz...",
      "mode": "polling",
      "allowedUsers": ["your_telegram_username"]
    }
  },
  "llm": {
    "provider": "anthropic",
    "apiKey": "sk-ant-..."
  }
}

Important security note: The allowedUsers field restricts who can send commands to your bot. Without it, anyone who finds your bot can use it — burning your API credits and potentially running shell commands on your server.

Step 4: Choose Polling vs Webhooks

OpenClaw supports two ways to receive messages from Telegram:

Polling (simpler, works anywhere):

OpenClaw continuously asks Telegram "any new messages?" every few seconds
Works behind firewalls and NAT
Slight latency (up to the polling interval)
Uses more API calls

Webhooks (faster, production-grade):

Telegram sends messages to your server as they arrive
Requires a public HTTPS endpoint
Near-instant message delivery
Requires a domain + SSL certificate

For a home server or simple VPS: use polling. For production: use webhooks.

To configure webhooks, you need a public URL and HTTPS. Set it in config:

{
  "platforms": {
    "telegram": {
      "mode": "webhook",
      "webhookUrl": "https://yourdomain.com/openclaw/webhook",
      "port": 18789
    }
  }
}

Then register the webhook with Telegram:

curl "https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook?url=https://yourdomain.com/openclaw/webhook"

Step 5: Start OpenClaw

openclaw start

# Or as a background service:
openclaw start --daemon

# Check if it's running:
openclaw status

Open Telegram, find your bot by username, and send it a message. If everything is configured correctly, it should respond.

Common Errors and Fixes

"ETELEGRAM: 401 Unauthorized"
Your bot token is wrong. Copy it directly from BotFather without extra spaces.

"ECONNREFUSED: connection refused"
OpenClaw isn't running, or it crashed on startup. Check logs:

openclaw logs --tail 50

Bot receives messages but doesn't respond
Your LLM API key may be invalid or have no credits. Test with:

openclaw test --platform telegram --message "hello"

"Cannot find module 'openclaw'"
The global npm install didn't add it to your PATH. Try:

export PATH="$(npm prefix -g)/bin:$PATH"

Rate limit errors from Telegram
Telegram limits bots to 30 messages/second to any group, and 1 message/second to the same user. OpenClaw's default rate limiting is aggressive enough for personal use, but if you're in many groups, configure rateLimitMs in your config.

Keeping OpenClaw Running 24/7

A bot that stops when you close your laptop isn't useful. To keep OpenClaw running persistently, you need a server and a process manager:

# Using systemd (Linux):
sudo nano /etc/systemd/system/openclaw.service

[Unit]
Description=OpenClaw Agent
After=network.target

[Service]
User=openclaw
ExecStart=/usr/local/bin/openclaw start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl enable openclaw
sudo systemctl start openclaw

Or with PM2:

npm install -g pm2
pm2 start openclaw -- start
pm2 save
pm2 startup

The Managed Alternative

If this feels like a lot of steps between "I want a Telegram AI bot" and "I have a Telegram AI bot" — you're not wrong. It's about 45-90 minutes of work if everything goes smoothly. With permission errors, Node version mismatches, and webhook config, it can take all day.

NeatClaw's Telegram integration is a checkbox. You sign up, paste your bot token, check "Telegram," and your bot is live — running on cloud infrastructure, available 24/7, no server required.

Start your Telegram bot on NeatClaw — free, 2 minutes →

This guide covers OpenClaw v2.x Telegram integration as of March 2026.