Telegram Bot Setup — Complete OpenClaw Guide

## Step 1: Create Your Telegram Bot

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

1. Open Telegram and search for @BotFather

2. Send /newbot and follow the prompts

3. Copy the bot token (looks like 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ)

4. 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:

// ~/.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:

// ❌ 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:

# 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:

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:

# 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):

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:

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

# 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:

# 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:

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