OpenClaw Telegram Setup Guide

Overview

Telegram integration enables mobile access to your OpenClaw agents with real-time streaming responses. This is perfect for on-the-go interactions, quick queries, and monitoring long-running tasks from your phone.

Benefits

Mobile Access: Interact with your agent from anywhere using Telegram mobile app
Streaming Responses: See responses as they're generated (especially useful for long outputs)
Real-Time Notifications: Get updates on task completion
Secure Pairing: Control who can access your agent with pairing codes
Cross-Platform: Works on iOS, Android, Desktop, and Web
Lightweight: Fast and responsive interface

Use Cases

Mobile Monitoring: Check on long-running tasks while away from computer
Quick Queries: Ask questions and get answers on the go
Task Updates: Receive notifications when tasks complete
Remote Control: Trigger actions on your OpenClaw instance remotely

Prerequisites

OpenClaw 3.2 or later installed and running
Telegram account (free)
Terminal access to your OpenClaw installation (SSH, Termius, or local terminal)
Basic understanding of bot configuration

Step-by-Step Setup

Step 1: Create Telegram Bot with BotFather

Open Telegram and search for @BotFather (official bot with verified checkmark ✓)
Start a conversation with BotFather
Send the command:

/newbot

/newbot

BotFather will ask for a name for your bot:
- Enter a display name (e.g., "My OpenClaw Agent", "BoxMining AI Bot")
- This is what users will see
BotFather will ask for a username:
- Must end in "bot" (e.g., "boxmining_ai_bot", "my_openclaw_bot")
- Must be unique across all Telegram
- Cannot contain spaces
BotFather will respond with your bot token:

Done! Congratulations on your new bot. You will find it at t.me/your_bot_name.

Use this token to access the HTTP API:
1234567890:ABCdefGHIjklMNOpqrsTUVwxyz1234567890

Keep your token secure and store it safely, it can be used by anyone to control your bot.

Done! Congratulations on your new bot. You will find it at t.me/your_bot_name.

Use this token to access the HTTP API:
1234567890:ABCdefGHIjklMNOpqrsTUVwxyz1234567890

Keep your token secure and store it safely, it can be used by anyone to control your bot.

[Image blocked: BotFather Setup]

⚠️ IMPORTANT: Copy this token immediately and keep it secure. Never share it publicly.

Step 2: Configure OpenClaw

Recommended Method: Use the OpenClaw configuration interface for reliability.

Open your terminal and connect to your OpenClaw server
Ensure you're running OpenClaw 3.2 or later:

bash

openclaw --version

openclaw --version

If you need to update:

bash

openclaw update

openclaw update

Run the configuration command:

bash

openclaw configure

openclaw configure

Select "Local" when prompted for environment
Navigate to "Channels" → "Configure"
Select "Telegram"

[Image blocked: OpenClaw Configure]

When prompted for "Telegram bot token", paste your token from BotFather:
- Windows: Ctrl + Shift + V
- Mac: Cmd + V
- Linux: Ctrl + Shift + V or right-click → Paste
Configure pairing policy:
- Allow DM pairing: Recommended for personal use
- Pairing policy options:
  - Open: Anyone can pair (not recommended)
  - Pairing codes: Users need a code to pair (recommended)
  - Allowlist: Only pre-approved users can pair (most secure)
Select "Finished" when done
Select "Continue" to save configuration

Step 3: Restart OpenClaw Gateway

Apply the configuration changes:

bash

openclaw gateway restart

openclaw gateway restart

Wait for confirmation that the gateway has restarted successfully.

Step 4: Pair Your Telegram Account

Open Telegram and find your bot:
- Search for your bot's username
- Or click the link provided by BotFather (t.me/your_bot_name)
Click "Start" to begin conversation
Send a message:

hi

hi

The bot will respond with a pairing code:

To pair this Telegram account with OpenClaw, please run:
openclaw tui
And enter pairing code: ABC123

To pair this Telegram account with OpenClaw, please run:
openclaw tui
And enter pairing code: ABC123

[Image blocked: Pairing Code]

In your terminal, run:

bash

openclaw tui

openclaw tui

Paste the pairing code when prompted
The bot will confirm pairing:

✓ Paired successfully! You can now interact with your OpenClaw agent.

✓ Paired successfully! You can now interact with your OpenClaw agent.

[Image blocked: Successful Pairing]

Step 5: Test the Integration

Send a test message to your bot:

Hello! Can you introduce yourself?

Hello! Can you introduce yourself?

The bot should respond with streaming output (you'll see the response being typed in real-time).

Configuration Examples

Personal Use (Recommended)

bash

# OpenClaw configuration
Pairing Policy: Pairing codes
Allow DM: Yes
Streaming: Enabled

# OpenClaw configuration
Pairing Policy: Pairing codes
Allow DM: Yes
Streaming: Enabled

Use case: Personal agent access from mobile device

Team Use

bash

# OpenClaw configuration
Pairing Policy: Allowlist
Allow DM: Yes
Streaming: Enabled
Allowlist: @user1, @user2, @user3

# OpenClaw configuration
Pairing Policy: Allowlist
Allow DM: Yes
Streaming: Enabled
Allowlist: @user1, @user2, @user3

Use case: Team members need access to shared agent

Public Bot (Not Recommended for OpenClaw)

bash

# OpenClaw configuration
Pairing Policy: Open
Allow DM: Yes
Streaming: Enabled

# OpenClaw configuration
Pairing Policy: Open
Allow DM: Yes
Streaming: Enabled

⚠️ Warning: Only use for demo purposes. Anyone can access your agent.

Streaming Responses

How Streaming Works

Telegram streaming shows responses as they're generated, rather than waiting for the complete response. This is especially useful for:

Long responses (stories, articles, code)
Complex queries that take time to process
Monitoring the agent's thought process

Streaming Behavior

Expected behavior:

Responses appear in chunks as they're generated
You see progress in real-time
Useful for long-running tasks

Note: Streaming may appear "chunky" rather than smooth character-by-character typing. This is normal and depends on:

Model being used (Opus vs Sonnet vs Minimax)
Response length
Network latency

Configuring Streaming

If streaming isn't working as expected:

Hey, can you change the Telegram streaming setting from partial to on?

Hey, can you change the Telegram streaming setting from partial to on?

Or manually configure:

bash

openclaw configure
# Channels → Configure → Telegram → Streaming → On

openclaw configure
# Channels → Configure → Telegram → Streaming → On

Advanced Features

Pairing Management

View Paired Users

bash

openclaw tui
# Select "View paired users"

openclaw tui
# Select "View paired users"

Unpair a User

bash

openclaw tui
# Select "Unpair user"
# Enter username or user ID

openclaw tui
# Select "Unpair user"
# Enter username or user ID

Generate New Pairing Code

bash

openclaw tui
# Select "Generate pairing code"

openclaw tui
# Select "Generate pairing code"

Allowlist Management

Add User to Allowlist

Via agent:

@YourBot add @username to Telegram allowlist

@YourBot add @username to Telegram allowlist

Via configuration:

bash

openclaw configure
# Channels → Configure → Telegram → Allowlist → Add user

openclaw configure
# Channels → Configure → Telegram → Allowlist → Add user

Remove User from Allowlist

bash

openclaw configure
# Channels → Configure → Telegram → Allowlist → Remove user

openclaw configure
# Channels → Configure → Telegram → Allowlist → Remove user

Streaming Configuration

Enable Full Streaming

bash

openclaw configure
# Channels → Configure → Telegram → Streaming → On

openclaw configure
# Channels → Configure → Telegram → Streaming → On

Partial Streaming (Default)

bash

openclaw configure
# Channels → Configure → Telegram → Streaming → Partial

openclaw configure
# Channels → Configure → Telegram → Streaming → Partial

Disable Streaming

bash

openclaw configure
# Channels → Configure → Telegram → Streaming → Off

openclaw configure
# Channels → Configure → Telegram → Streaming → Off

Security Best Practices

✅ DO:

Store bot token in .env file (see Security Guide [blocked])
Use pairing codes or allowlist for access control
Regularly review paired users and remove inactive ones
Regenerate bot token if exposed
Use unique bot per OpenClaw instance
Enable 2FA on your Telegram account

❌ DON'T:

Never share bot token in Telegram or other platforms
Don't use open pairing policy for production
Don't pair unknown users
Don't share pairing codes publicly
Don't reuse bot tokens across multiple instances

Token Security

If your bot token is exposed:

Revoke the old token:
- Message @BotFather
- Send /revoke
- Select your bot
- Confirm revocation
Generate new token:
- Message @BotFather
- Send /token
- Select your bot
- Copy new token

Update OpenClaw:

bash

nano ~/.openclaw/.env
# Update TELEGRAM_BOT_TOKEN=new_token_here

nano ~/.openclaw/.env
# Update TELEGRAM_BOT_TOKEN=new_token_here

Restart gateway:

bash

openclaw gateway restart

openclaw gateway restart

Re-pair all users with new pairing codes

Common Issues and Solutions

Issue 1: Bot Doesn't Respond

Symptoms:

Bot shows online but doesn't reply
Messages show as delivered but no response

Solutions:

Check OpenClaw status:
bash
openclaw status
openclaw status

Verify pairing:

bash

openclaw tui
# Check if your Telegram account is paired

openclaw tui
# Check if your Telegram account is paired

Check configuration:

bash

openclaw configure
# Verify Telegram bot token is correct

openclaw configure
# Verify Telegram bot token is correct

Restart gateway:

bash

openclaw gateway restart

openclaw gateway restart

Check logs:

bash

openclaw logs | grep telegram

openclaw logs | grep telegram

Issue 2: Pairing Code Not Working

Symptoms:

"Invalid pairing code" error
Code doesn't work in openclaw tui

Solutions:

Request new pairing code:
- Send hi to bot again
- Use the new code provided
Check for typos:
- Pairing codes are case-sensitive
- Copy-paste instead of typing
Verify OpenClaw is running:
bash
openclaw status
openclaw status

Clear old pairing attempts:

bash

openclaw tui
# Clear pending pairings

openclaw tui
# Clear pending pairings

Issue 3: Streaming Not Working

Symptoms:

Responses appear all at once instead of streaming
Long wait with "typing..." indicator

Solutions:

Enable streaming:

Hey, change Telegram streaming to "on"

Hey, change Telegram streaming to "on"

Check model:
- Some models (like Minimax) may have chunkier streaming
- Try with Opus or Sonnet for smoother streaming

Test with long response:

Write me a 40-line haiku

Write me a 40-line haiku

Tell me a short story

Tell me a short story

Configure streaming mode:

bash

openclaw configure
# Channels → Telegram → Streaming → On

openclaw configure
# Channels → Telegram → Streaming → On

Issue 4: Bot Token Invalid

Symptoms:

"Invalid bot token" error
Gateway fails to start

Solutions:

Verify token format:
- Should be: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
- Check for extra spaces or line breaks
Get fresh token from BotFather:
- Message @BotFather
- Send /token
- Select your bot
- Copy new token

Update .env file:

bash

nano ~/.openclaw/.env
TELEGRAM_BOT_TOKEN=your_correct_token_here

nano ~/.openclaw/.env
TELEGRAM_BOT_TOKEN=your_correct_token_here

Restart gateway:

bash

openclaw gateway restart

openclaw gateway restart

Issue 5: Agent Configuration Fails

Symptoms:

Asking agent to set up Telegram causes errors
Agent says "I'll configure Telegram" but nothing happens
OpenClaw crashes during setup

Solutions:

Use manual configuration instead (recommended):

bash

openclaw configure
# Follow the prompts manually

openclaw configure
# Follow the prompts manually

Why manual is better:

More reliable (works 100% of the time vs ~75% with agent)
Clearer error messages
No risk of agent misconfiguration
Faster setup process

If you must use agent:

Start a fresh session (clear context)
Be very specific with instructions
Verify each step completed successfully
Be prepared to retry or switch to manual method

Troubleshooting Checklist

Before asking for help, verify:

OpenClaw version is 3.2 or later
Bot token is correct and stored in .env file
OpenClaw gateway has been restarted after configuration
Your Telegram account is paired (check with openclaw tui)
Bot is responding to @BotFather (send /mybots to verify it exists)
No firewall blocking OpenClaw's connection to Telegram
Pairing policy is configured correctly
Streaming is enabled if you want real-time responses

Advanced Configuration

Multiple Bots

Run multiple OpenClaw instances with different Telegram bots:

Create separate bots with @BotFather
Configure each OpenClaw instance with its own token
Each bot operates independently

Custom Commands

Configure custom bot commands with @BotFather:

Message @BotFather
Send /setcommands
Select your bot
Add commands:

status - Check agent status
help - Get help
clear - Clear conversation context

status - Check agent status
help - Get help
clear - Clear conversation context

Bot Description

Set a description for your bot:

Message @BotFather
Send /setdescription
Select your bot
Enter description (shown when users first start the bot)

Bot Profile Picture

Add a profile picture:

Message @BotFather
Send /setuserpic
Select your bot
Upload an image (square, at least 512x512px)

Usage Tips

For Long Tasks

Telegram is perfect for monitoring long-running tasks:

Start training the model on the dataset. I'll check back in an hour.

Start training the model on the dataset. I'll check back in an hour.

You'll receive updates as the task progresses.

For Quick Queries

Use Telegram for quick questions while away from computer:

What's the status of the deployment?

What's the status of the deployment?

Check if the tests passed

Check if the tests passed

For Code Snippets

Telegram formats code nicely:

Show me the implementation of the authentication function

Show me the implementation of the authentication function

The bot will respond with properly formatted code blocks.

Related Guides

Security Best Practices [blocked] - Secure your bot token
Discord Setup [blocked] - Alternative for team collaboration
Notion Integration [blocked] - Connect to Notion for task management
API Integration Guide [blocked] - Add more capabilities

Additional Resources

Video Tutorial: Watch the complete setup guide

Need Help? Join the OpenClaw community Discord for support.

Pro Tip: Telegram streaming works best for longer responses. For short queries, you might not notice the streaming effect, but for tasks like "write a detailed analysis" or "generate a report", you'll see responses appear in real-time as your agent thinks through the problem.