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

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

/newbot

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

5. 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

6. 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.

⚠️ 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.

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

openclaw --version

If you need to update:

openclaw update

3. Run the configuration command:

openclaw configure

4. Select "Local" when prompted for environment

5. Navigate to "Channels" → "Configure"

6. Select "Telegram"

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

8. 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)

9. Select "Finished" when done

10. Select "Continue" to save configuration

Step 3: Restart OpenClaw Gateway

Apply the configuration changes:

openclaw gateway restart

Wait for confirmation that the gateway has restarted successfully.

Step 4: Pair Your Telegram Account

1. Open Telegram and find your bot:

   • Search for your bot's username
   • Or click the link provided by BotFather (t.me/your_bot_name)

2. Click "Start" to begin conversation

3. Send a message:

hi

4. The bot will respond with a pairing code:

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

5. In your terminal, run:

openclaw tui

6. Paste the pairing code when prompted

7. The bot will confirm pairing:

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

Step 5: Test the Integration

Send a test message to your bot:

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)

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

Use case: Personal agent access from mobile device

Team Use

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

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

Or manually configure:

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

Advanced Features

Pairing Management

View Paired Users

openclaw tui
# Select "View paired users"

Unpair a User

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

Generate New Pairing Code

openclaw tui
# Select "Generate pairing code"

Allowlist Management

Add User to Allowlist

Via agent:

@YourBot add @username to Telegram allowlist

Via configuration:

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

Remove User from Allowlist

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

Streaming Configuration

Enable Full Streaming

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

Partial Streaming (Default)

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

Disable Streaming

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

Security Best Practices

✅ DO:

• Store bot token in .env file (see Security Guide)
• 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:

1. Revoke the old token:

   • Message @BotFather
   • Send /revoke
   • Select your bot
   • Confirm revocation

2. Generate new token:

   • Message @BotFather
   • Send /token
   • Select your bot
   • Copy new token

3. Update OpenClaw:

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

4. Restart gateway:

   openclaw gateway restart
   

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

1. Check OpenClaw status:

   openclaw status
   

2. Verify pairing:

   openclaw tui
   # Check if your Telegram account is paired
   

3. Check configuration:

   openclaw configure
   # Verify Telegram bot token is correct
   

4. Restart gateway:

   openclaw gateway restart
   

5. Check logs:

   openclaw logs | grep telegram
   

Issue 2: Pairing Code Not Working

Symptoms:

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

Solutions:

1. Request new pairing code:

   • Send hi to bot again
   • Use the new code provided

2. Check for typos:

   • Pairing codes are case-sensitive
   • Copy-paste instead of typing

3. Verify OpenClaw is running:

   openclaw status
   

4. Clear old pairing attempts:

   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:

1. Enable streaming:

   Hey, change Telegram streaming to "on"
   

2. Check model:

   • Some models (like Minimax) may have chunkier streaming
   • Try with Opus or Sonnet for smoother streaming

3. Test with long response:

   Write me a 40-line haiku
   

   or

   Tell me a short story
   

4. Configure streaming mode:

   openclaw configure
   # Channels → Telegram → Streaming → On
   

Issue 4: Bot Token Invalid

Symptoms:

• "Invalid bot token" error
• Gateway fails to start

Solutions:

1. Verify token format:

   • Should be: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
   • Check for extra spaces or line breaks

2. Get fresh token from BotFather:

   • Message @BotFather
   • Send /token
   • Select your bot
   • Copy new token

3. Update .env file:

   nano ~/.openclaw/.env
   TELEGRAM_BOT_TOKEN=your_correct_token_here
   

4. Restart gateway:

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

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:

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

Custom Commands

Configure custom bot commands with @BotFather:

1. Message @BotFather
2. Send /setcommands
3. Select your bot
4. Add commands:

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

Bot Description

Set a description for your bot:

1. Message @BotFather
2. Send /setdescription
3. Select your bot
4. Enter description (shown when users first start the bot)

Bot Profile Picture

Add a profile picture:

1. Message @BotFather
2. Send /setuserpic
3. Select your bot
4. 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.

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?

Check if the tests passed

For Code Snippets

Telegram formats code nicely:

Show me the implementation of the authentication function

The bot will respond with properly formatted code blocks.

Related Guides

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

Additional Resources

• Telegram Bot API Documentation
• BotFather Commands
• OpenClaw Telegram Integration Docs

---

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.