🦞OpenClaw Guide
Telegram

Telegram Bot Setup — Complete OpenClaw Guide

Complete guide to setting up, configuring, and troubleshooting your Telegram bot with OpenClaw. Covers pairing codes, authorization errors, token issues, plugin configuration, and streaming setup.

⚠️ The Problem

Users encounter various issues when setting up Telegram as a channel for OpenClaw, including: pairing codes that seem to go nowhere, 'You are not authorized to use this command' errors, HTTP 401 authentication errors, 'plugin not found: telegram' config errors, reasoning/streaming not displaying correctly, and general connectivity issues after updates or migrations.

🔍 Why This Happens

These issues stem from several root causes:

  1. Pairing not approved: Telegram DMs require explicit approval before users can interact with the bot
  2. Incorrect token configuration: Bot tokens may be malformed, expired, or incorrectly placed in config
  3. Wrong config location: Telegram is a built-in CHANNEL, not a plugin — configuring it under plugins.entries.telegram instead of channels.telegram causes 'plugin not found' errors
  4. Missing Message Content Intent: Bot cannot receive message content without proper permissions
  5. Version mismatches: After updates (especially the Moltbot → OpenClaw rename), old gateway instances may conflict
  6. Streaming limitations: Telegram draft streaming requires Topics mode (forum-style private chats) and Bot API 9.3+

✅ The Fix

Step 1: Create Your Telegram Bot

First, create a bot with BotFather if you haven't already:

  1. Open Telegram and search for @BotFather
  1. Send /newbot and follow the prompts
  1. Copy the bot token (looks like 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ)
  1. Important: Save this token securely — you'll need it for configuration

Step 2: Configure Telegram in OpenClaw

Telegram is a built-in channel, NOT a plugin. Configure it correctly:

json5
// ~/.openclaw/config.json5 (or clawdbot.json){  channels: {    telegram: {      enabled: true,      botToken: "YOUR_BOT_TOKEN_HERE",      dmPolicy: "pairing"  // or "allowlist" or "open"    }  }}

⚠️ Common Mistake: Do NOT put Telegram under plugins.entries:

json5
// ❌ WRONG - causes 'plugin not found: telegram' error{  plugins: {    entries: {      telegram: { ... }  // This is incorrect!    }  }}

Step 3: Approve Pairing (For DM Access)

When someone DMs your bot for the first time with dmPolicy: "pairing", they receive a pairing code. You must approve it:

bash
# List pending pairing requestsopenclaw pairing list telegram# Approve a specific codeopenclaw pairing approve telegram <code># Or approve all pendingopenclaw pairing approve telegram

Alternative: Use allowlist mode to pre-authorize users:

json5
channels: {  telegram: {    dmPolicy: "allowlist",    allowFrom: ["123456789", "@yourusername"]  }}

To find your Telegram user ID:

  • DM @userinfobot on Telegram, or
  • Check logs: openclaw logs --follow | grep from.id

Step 4: Fix HTTP 401 Authentication Errors

If you see HTTP 401: authentication_error: Invalid bearer token:

bash
# 1. Get fresh token from BotFather# Chat with @BotFather → /mybots → select bot → API Token# 2. Update your config with the exact token (no extra spaces)# Edit ~/.openclaw/config.json5# 3. Restart the gatewayopenclaw gateway restart

Common causes of 401 errors:

  • Token has extra spaces or characters
  • Token was regenerated via /revoke on BotFather (old tokens become invalid)
  • Wrong token (from a different bot)

Step 5: Configure Streaming & Reasoning Display

For reasoning to stream in separate blocks (not appended to final message):

json5
channels: {  telegram: {    streamMode: "partial",  // or "block"    blockStreaming: true  }}

Important limitation: Telegram draft streaming (showing reasoning in real-time) requires:

  • Topics enabled in the private chat (forum-topic mode)
  • Bot API 9.3+ (if self-hosting the Bot API server)

For regular DMs without Topics, use block streaming instead:

json5
channels: {  telegram: {    streamMode: "off",    blockStreaming: true  }}

Control reasoning per-chat with /reasoning command:

  • /reasoning on — Show reasoning in final message
  • /reasoning off — Hide reasoning entirely
  • /reasoning stream — Stream reasoning (requires Topics mode)

Step 6: Verify Everything is Working

bash
# Check gateway statusopenclaw gateway status# Check Telegram channel specificallyopenclaw channels status# Should show:# - Telegram default: enabled, configured, running, mode:polling# Watch live logs for issuesopenclaw logs --follow

Troubleshooting Migration Issues (Moltbot → OpenClaw)

If you updated from Moltbot/Clawdbot and Telegram stopped working:

bash
# Check for duplicate gateway processesps aux | grep -E '(moltbot|clawdbot|openclaw).*gateway'# Stop old instancesclawdbot gateway stop 2>/dev/nullmoltbot gateway stop 2>/dev/null# Ensure only OpenClaw gateway is runningopenclaw gateway restart# Verify single instanceopenclaw status --deep

Migration data path:

bash
# Copy data from old locationcp -r ~/.clawdbot/* ~/.openclaw/# orcp -r ~/.moltbot/* ~/.openclaw/# Then restartopenclaw gateway restart

🔥 Your AI should run your business, not just answer questions.

We'll show you how.Free to join.

Join Vibe Combinator →

📋 Quick Commands

CommandDescription
openclaw pairing list telegramList pending Telegram pairing requests awaiting approval
openclaw pairing approve telegramApprove pending Telegram pairing requests
openclaw channels statusCheck status of all channels including Telegram
openclaw gateway restartRestart the gateway to apply config changes
openclaw logs --followWatch live logs for Telegram-related errors
/reasoning streamEnable reasoning streaming in Telegram chat (requires Topics mode)

Related Issues

📚 You Might Also Like

Integration

Telegram Integration

Blog

OpenClaw Telegram Allowlist: How to Make Your Bot Ignore Everyone Except You

If your OpenClaw bot is connected to Telegram without an allowlist, anyone who knows your bot's handle can try to send it commands. They could ask it to list...

Guide

How to Connect OpenClaw to Google Calendar (2026 Guide)

Connect OpenClaw to Google Calendar: create events, check schedule, get reminders via WhatsApp or Telegram. Setup takes 10 minutes with the gog CLI.

Feature

Voice-Controlled AI Assistant — Talk Instead of Type

Control your AI assistant with your voice through WhatsApp or Telegram. Send voice notes, get spoken responses. Hands-free AI that works while you multitask.

🐙 Your AI should run your business.

Weekly live builds + template vault. We'll show you how to make AI actually work.Free to join.

Join Vibe Combinator →