OpenClaw Telegram Bot Setup

Introduction

Connect OpenClaw to Telegram to bring AI-powered conversations to your groups and private chats. This guide covers the complete setup process.

Prerequisites

• OpenClaw installed on your VPS
• Telegram account
• Basic familiarity with Telegram

Step 1: Create a Telegram Bot

Talk to BotFather

1. Open Telegram and search for @BotFather
2. Start a chat and send /newbot
3. Follow the prompts:
   • Enter a name for your bot (display name)
   • Enter a username (must end in bot, e.g., MyChatAssistant_bot)

Get Your Bot Token

BotFather will respond with your bot token:

Use this token to access the HTTP API:
123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Copy this token - you'll need it for configuration.

Step 2: Configure Bot Settings

While still chatting with BotFather, configure your bot:

Set Description

/setdescription

Add a brief description of what your bot does.

Set About Text

/setabouttext

This appears in the bot's profile.

Set Commands (Optional)

/setcommands

Define available commands:

start - Start the bot
help - Get help
clear - Clear conversation history

Step 3: Configure OpenClaw

SSH into your VPS and update the environment file:

cd /opt/openclaw
nano .env

Add Telegram configuration:

# Telegram Configuration
TELEGRAM_ENABLED=true
TELEGRAM_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

# Optional settings
TELEGRAM_ALLOWED_USERS=user_id1,user_id2
TELEGRAM_ALLOWED_GROUPS=-100123456789

Step 4: Start the Bot

Restart OpenClaw to apply changes:

pm2 restart openclaw
pm2 logs openclaw

Look for: Telegram bot connected successfully

Step 5: Test Your Bot

Private Chat

1. Search for your bot by username
2. Click "Start"
3. Send a message

Group Chat

1. Add your bot to a group
2. Make it admin (for best experience)
3. Mention the bot or use commands

Configuration Options

Restrict Access

Limit who can use the bot:

# Only allow specific users (get ID from @userinfobot)
TELEGRAM_ALLOWED_USERS=123456789,987654321

# Only allow specific groups
TELEGRAM_ALLOWED_GROUPS=-100123456789,-100987654321

Group Behavior

# Respond only when mentioned in groups
TELEGRAM_MENTION_ONLY=true

# Bot username for mention detection
TELEGRAM_BOT_USERNAME=MyChatAssistant_bot

Message Handling

# Maximum message length
TELEGRAM_MAX_MESSAGE_LENGTH=4096

# Enable markdown formatting
TELEGRAM_PARSE_MODE=Markdown

# Reply to messages (vs sending new)
TELEGRAM_REPLY_TO_MESSAGE=true

Telegram-Specific Features

Inline Mode

Enable inline queries:

1. Tell BotFather: /setinline
2. Set a placeholder text
3. Configure in .env:

TELEGRAM_INLINE_ENABLED=true

Users can then type @yourbot query in any chat.

Keyboards

Add custom reply keyboards:

TELEGRAM_SHOW_KEYBOARD=true
TELEGRAM_KEYBOARD_OPTIONS=Help,Settings,Clear History

Webhooks vs Polling

Polling (default): Bot regularly checks for updates

TELEGRAM_USE_POLLING=true

Webhooks (advanced): Telegram pushes updates to your server

TELEGRAM_USE_WEBHOOK=true
TELEGRAM_WEBHOOK_URL=https://yourdomain.com/webhook
TELEGRAM_WEBHOOK_PORT=8443

Webhooks require SSL certificate and domain.

Per-Group Configuration

Different settings per group:

// config/groups.js
module.exports = {
  "-100123456789": {
    name: "Support Group",
    systemPrompt: "You are a support assistant...",
    mentionOnly: true
  },
  "-100987654321": {
    name: "Casual Chat",
    systemPrompt: "You are a friendly chat companion...",
    mentionOnly: false
  }
};

Troubleshooting

Bot not responding

1. Check token is correct
2. Verify bot is started: pm2 status
3. Check logs: pm2 logs openclaw

"Unauthorized" errors

• Regenerate token with BotFather (/revoke)
• Update .env with new token
• Restart bot

Bot works in private but not groups

• Make bot admin in the group
• Disable privacy mode with BotFather: /setprivacy > Disable
• Check TELEGRAM_ALLOWED_GROUPS setting

Rate limiting

Telegram limits: 30 messages/second to same chat

TELEGRAM_RATE_LIMIT=20
TELEGRAM_RATE_LIMIT_WINDOW=60000

Security Best Practices

1. Restrict users - Don't leave bot open to everyone
2. Validate input - Bot handles this, but be aware
3. Monitor usage - Check logs for abuse
4. Rotate token if compromised

Related Guides

• Install OpenClaw
• System prompts
• Discord setup
• Get Telegram token

Need Help?

Telegram setup can be tricky. Our professional setup includes full Telegram integration with ongoing support.