Telegram Agent Setup — Connect OpenClaw to Telegram

What You Get

• ⏱️ Working bot in 15 minutes instead of 3+ hours reading scattered docs
• 🔒 Security lockdown — stop strangers from using your bot (most guides skip this)
• 👥 Group & forum support — route topics to different agents
• 🎤 Voice messages working — full STT setup with faster-whisper
• 🔧 15+ troubleshooting fixes — every problem we've hit running 5 production bots
• ✅ Production checklist — 8-point verification before going live

When to Use

• Setting up a new Telegram bot for OpenClaw
• Configuring group chats, forum topics, or private chats
• Troubleshooting connection issues (bot not responding, messages not arriving)
• Setting up voice messages (STT transcription)
• Configuring inline buttons, reactions, and media handling
• Moving from basic setup to production-ready configuration

Prerequisites

• OpenClaw installed and running (openclaw gateway status shows OK)
• Telegram account
• Access to @BotFather on Telegram

Step 1: Create a Telegram Bot

1. Open Telegram, find @BotFather
2. Send /newbot
3. Choose a display name (e.g., "My AI Assistant")
4. Choose a username (must end in bot, e.g., my_ai_assistant_bot)
5. Copy the API token (looks like 7123456789:AAH...)

Important BotFather Settings

/setprivacy → Disable (so bot sees all messages in groups)
/setjoingroups → Enable (if you want to add bot to groups)
/setcommands → Set your commands:
  start - Start the bot
  help - Show help
  status - Check status

Step 2: Connect to OpenClaw

Method A: CLI (recommended)

openclaw telegram setup

Follow the interactive prompts. Paste your bot token when asked.

Method B: Manual config

Edit ~/.openclaw/openclaw.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN_HERE",
      "allowedChatIds": []
    }
  }
}

Then restart:

openclaw gateway restart

Step 3: Verify Connection

1. Open your bot in Telegram
2. Send /start or any message
3. Bot should respond

If no response:

openclaw gateway status
openclaw gateway logs --tail 50

Step 4: Security — Restrict Access

Critical. Without this, anyone who finds your bot can use your Claude subscription.

{
  "channels": {
    "telegram": {
      "allowedChatIds": ["YOUR_TELEGRAM_USER_ID"],
      "rejectUnknown": true
    }
  }
}

Find your user ID: message @userinfobot on Telegram.

Step 5: Group Chat Setup

Regular group

1. Add bot to group
2. Get group chat ID from logs: openclaw gateway logs | grep "chat_id"
3. Add to allowedChatIds (group IDs are negative: -1001234567890)

Forum (topics) group

• Each topic gets its own topic_id
• Route different topics to different agents
• Perfect for multi-agent setups (see multi-agent-architecture skill)

Response behavior in groups

{
  "groupBehavior": {
    "respondTo": "mention"
  }
}

Options: "all" (every message), "mention" (when tagged — recommended), "command" (only /commands).

Step 6: Voice Messages

Quick STT setup with faster-whisper:

python3 -m venv ~/.openclaw/venvs/stt-tools
source ~/.openclaw/venvs/stt-tools/bin/activate
pip install faster-whisper

Model sizes: tiny (fast, ~1GB RAM), base (better, ~2GB), small (best, ~4GB).

Create scripts/transcribe_audio.py:

#!/usr/bin/env python3
import sys
from faster_whisper import WhisperModel

def transcribe(audio_path, model_size="tiny", language="ru"):
    model = WhisperModel(model_size, device="cpu", compute_type="int8")
    segments, _ = model.transcribe(audio_path, language=language)
    print(" ".join(seg.text.strip() for seg in segments))

if __name__ == "__main__":
    transcribe(sys.argv[1],
               sys.argv[2] if len(sys.argv) > 2 else "tiny",
               sys.argv[3] if len(sys.argv) > 3 else "ru")

Troubleshooting

Bot not responding

1. openclaw gateway status — is it running?
2. openclaw gateway logs --tail 100 | grep -i error — any errors?
3. Check bot token — no extra spaces?
4. Check firewall — outbound HTTPS (port 443) open?

Bot responds to strangers

→ Add allowedChatIds + rejectUnknown: true

Messages delayed

→ Check server load (htop), check for rate limits in logs

Voice not transcribed

→ Check STT venv exists and faster-whisper installed

→ Telegram sends .ogg (opus) — faster-whisper handles it natively

"Webhook" vs "Polling"

→ OpenClaw uses long polling by default (no public IP needed)

Production Checklist

• [ ] Bot token stored securely (not in git, not in chat)
• [ ] allowedChatIds configured
• [ ] rejectUnknown: true enabled
• [ ] Error policy: "silent" (no error messages to users)
• [ ] Voice transcription working (if needed)
• [ ] Group privacy mode disabled in BotFather (if using groups)
• [ ] Bot commands registered via BotFather
• [ ] Gateway auto-restarts on failure