OpenClaw Telegram Channel Setup Guide

Integrating OpenClaw with Telegram turns your favorite messaging app into a powerful control center for your AI agent. Send commands, trigger automations, and receive notifications directly through Telegram. This guide covers everything from creating your bot to troubleshooting common issues.

Prerequisites

Before you begin, ensure you have:

• A Telegram account
• OpenClaw deployed and configured (version 2026.2.3 or higher recommended)
• Node.js (version 24 recommended, 22.14+ supported)
• An API key from a model provider (Anthropic, OpenAI, or Google)

Step 1: Create a Telegram Bot

Every Telegram integration starts with a bot. Here is how to create one:

1. Open Telegram and search for @BotFather
2. Select the official account with the blue verified checkmark
3. Start a chat and send /newbot
4. Follow the prompts to choose a display name for your bot
5. Choose a unique username that must end in 'bot' (e.g., MyAssistantBot)
6. Copy the HTTP API token provided by BotFather. This is essential for connecting OpenClaw to your bot.

Step 2: Configure OpenClaw with the Bot Token

Now add the token to your OpenClaw configuration:

1. Access your OpenClaw configuration via the CLI (openclaw onboard), the web interface, or by editing ~/.openclaw/openclaw.json
2. Navigate to the Telegram channel settings
3. Add your bot token to the botToken field

"channels": {
  "telegram": {
    "enabled": true,
    "dmPolicy": "pairing",
    "botToken": "YOUR_TELEGRAM_BOT_TOKEN",
    "groupPolicy": "allowlist",
    "streamMode": "partial"
  }
}

Key Configuration Options

• dmPolicy: 'pairing' (requires approval), 'allowlist' (pre-approved users), or 'open'
• groupPolicy: Controls group chat access
• streamMode: 'partial' for incremental responses, 'full' for complete messages

Set dmPolicy to "pairing" for secure access, at least initially.

Step 3: Pair Your Telegram Account

The pairing process ensures only authorized users can control your OpenClaw instance:

1. Restart OpenClaw or the gateway for changes to take effect
2. Open Telegram and search for your newly created bot
3. Send /start or any message to your bot
4. Your OpenClaw bot will reply with your Telegram user ID and a pairing code
5. Copy this pairing code
6. Approve the pairing in OpenClaw: openclaw pairing approve telegram <CODE>
7. Your Telegram account is now permanently allowlisted

Step 4: Verify and Test

Confirm everything is working:

1. Check Telegram channel status: openclaw channels status --probe
2. You should see: Telegram enabled, configured, running, and working
3. Send a test message to your bot (e.g., "Hello")
4. Your OpenClaw agent should respond

Step 5: Configure for Group Chats (Optional)

If you want to use your bot in Telegram groups:

1. In BotFather, send /setjoingroup, select your bot, and choose "Enable"
2. By default, bots only see messages that mention them
3. To see all messages, send /setprivacy to BotFather, select your bot, and choose "Disable"
4. Alternatively, make your bot a group administrator
5. After changing privacy settings, you may need to remove and re-add the bot to existing groups

In your OpenClaw configuration, set groupPolicy and channels.telegram.groups to match your desired access model.

Security Best Practices

• Never expose your bot token publicly. If compromised, regenerate it immediately via @BotFather
• Use "dmPolicy": "allowlist" and add your Telegram user ID to allowFrom for permanent access
• Always restart OpenClaw after configuration changes
• One bot token should connect to one OpenClaw instance. Create separate bots for multiple agents.

Troubleshooting Common Issues

Pairing Required Loop

If Telegram repeatedly sends new pairing codes without completing:

• Restart the OpenClaw container via your VPS panel or: docker compose -p openclaw restart
• Send a fresh message to generate a new code and approve it immediately

Silent Bot (Connected but No Replies)

Most silent bot problems relate to dmPolicy, allowFrom, or groupPolicy settings:

• Verify your numeric Telegram user ID (not @username) is in allowFrom
• Check health indicator in the dashboard (should be "Health OK")
• Verify "Running: Yes" and "Probe ok" in Channels section

Network and Firewall Issues

If the bot fails silently, especially during initial polling:

• Check if your firewall is blocking connections to api.telegram.org
• Temporarily use a mobile hotspot to diagnose network restrictions
• Ensure DNS/IPv6/proxy routing to api.telegram.org is correctly configured

"Unsupported type" Error

If you see "Unsupported type: … Use Raw mode":

• Install or upgrade the oxylabs-ai-studio-openclaw plugin to version 1.0.2 or newer
• Restart the OpenClaw container