OpenClaw Telegram Bot Tutorial: From Zero to Working Bot in 20 Minutes

# OpenClaw Telegram Bot Tutorial: From Zero to Working Bot in 20 Minutes

You can have a working OpenClaw Telegram bot in 20 minutes. This tutorial covers every step: creating the bot token in BotFather, configuring OpenClaw, approving your first pairing, setting up group access, and keeping the bot online 24/7.

No prior bot experience required. The Telegram integration is the most stable and easiest channel in OpenClaw — which is why most people start here.

---

What You're Building

A Telegram bot powered by your own AI model. You message the bot, it thinks, it responds. The bot can:

• Answer questions using your AI model (Claude, GPT-4, Gemini — your choice)
• Remember context across conversations via the workspace memory system
• Execute commands on your server if you configure tool access
• Join Telegram groups and respond to @mentions
• Run proactive scheduled check-ins (heartbeats) where the bot messages you first

Everything runs on your own VPS or local machine. The bot token is yours. The conversation logs are yours.

---

Prerequisites

Before starting, make sure you have:

• OpenClaw installed — if not, run npm install -g openclaw then openclaw onboard
• OpenClaw gateway not yet running (we'll start it with Telegram configured)
• A Telegram account — your personal one is fine for this tutorial
• 5 minutes for the BotFather flow

---

Part 1: Create Your Bot Token

Telegram bots authenticate with a unique token issued by @BotFather. This takes 3–4 minutes.

Step 1: Open @BotFather

In Telegram, search for @BotFather. Make sure the account has a verified checkmark. The real BotFather is the only one — there are fake copies with similar names.

Step 2: Create a New Bot

Send this message to BotFather:

/newbot

BotFather asks for a display name (what users see) and a username (must end in "bot").

Example:

• Display name: My AI Assistant
• Username: myaiassistant_bot

Step 3: Save Your Token

BotFather gives you a token like this:

7291847362:AAG3kK_example_token_here_XYZ123abc

Copy it. You'll paste it into your OpenClaw config in a moment. This token is sensitive — don't commit it to a public repo.

BotFather Settings to Configure Now

While you're in BotFather, run these two commands to optimize your bot:

Allow the bot to join groups:

/setjoingroups

Select your bot → Enable

Optionally disable privacy mode (required if you want the bot to see all group messages, not just @mentions):

/setprivacy

Select your bot → Disable

You can change privacy mode later, but setting it before adding the bot to groups is cleaner.

---

Part 2: Configure OpenClaw for Telegram

Step 1: Open Your Config File

nano ~/.openclaw/openclaw.json

Or use whatever editor you prefer.

Step 2: Add the Telegram Channel Config

Your config file should look like this after adding Telegram:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "7291847362:AAG3kK_YOUR_ACTUAL_TOKEN_HERE",
      dmPolicy: "pairing",
      groups: {
        "*": {
          requireMention: true
        }
      }
    }
  }
}

Config options explained:

• enabled: true — turns on the Telegram channel
• botToken — the token from BotFather
• dmPolicy: "pairing" — requires approval before anyone can DM the bot (recommended for security)
• groups["*"] — settings for all groups
• requireMention: true — bot only responds in groups when @mentioned (prevents noise)

Understanding dmPolicy Options

The dmPolicy setting controls who can send DMs to your bot:

• pairing (recommended) — anyone who messages the bot gets a pairing code. You approve or reject them. Best for personal use.
• allowlist — only Telegram user IDs you explicitly list can interact with the bot. Best for locked-down setups.
• open — anyone can chat with the bot. Don't use this unless the bot is intentionally public.

For a personal assistant, pairing is the right choice. It takes 30 seconds to approve yourself, and you won't accidentally expose your bot to strangers.

---

Part 3: Start the Gateway and Approve Pairing

Step 1: Start the Gateway

openclaw gateway

You'll see output including:

OpenClaw gateway started
Telegram: polling active (long polling mode)

"Long polling" means OpenClaw repeatedly asks Telegram's servers for new messages. It's reliable and doesn't require a public-facing URL. Webhook mode (faster, requires a domain) is covered later.

Step 2: Send Your First Message

Go to Telegram. Find your bot by username. Send it any message:

Hello, are you there?

The bot won't respond yet — it needs approval.

Step 3: Check for Pairing Requests

Back in your terminal, run:

openclaw pairing list telegram

You'll see output like:

Pending pairing requests:
1. Code: ABC123 | User: Bart (@bart_user) | Expires: 58 minutes

Step 4: Approve the Pairing

openclaw pairing approve telegram ABC123

Now go back to Telegram and send another message. The bot should respond within 2–5 seconds.

---

Part 4: Test Your Bot

Send these test messages to verify everything works:

Basic response test:

What is 2 + 2?

Expected: a simple answer, fast.

Context memory test:

My name is Bart. Remember that.

Then send:

What's my name?

The bot should remember "Bart" within the same conversation.

Tool use test (if you have tools enabled):

Search the web for today's Bitcoin price.

If this works, your bot has web access through OpenClaw's built-in browser tools.

---

Part 5: Add the Bot to a Telegram Group

The bot can participate in group chats. Here's how to configure it properly.

Step 1: Add the Bot to Your Group

In Telegram, open your group → Members → Add Member → search for your bot's username.

Step 2: Update Group Config (Optional)

If you want specific behavior per group, update your config:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "YOUR_TOKEN",
      dmPolicy: "pairing",
      groups: {
        "-1001234567890": {
          requireMention: true,
          policy: "allowlist",
          allowFrom: ["@bart_user", "@teammate"]
        }
      }
    }
  }
}

Replace -1001234567890 with your actual group ID. To find a group ID, add @userinfobot to your group and send any message.

Step 3: Test Group Behavior

In the group, send:

@your_bot_username What's the weather in New York?

The bot should respond to the @mention. Without requireMention: false, it ignores messages that don't tag it — which is the right behavior for most groups.

---

Part 6: Run the Bot 24/7

A bot that stops when you close your laptop isn't useful. Here's how to keep it running permanently.

Option A: Systemd (Linux VPS — Recommended)

Create a service file:

sudo nano /etc/systemd/system/openclaw.service

Paste this:

[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
ExecStart=/usr/local/bin/openclaw gateway
Restart=always
RestartSec=10
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable openclaw
sudo systemctl start openclaw
sudo systemctl status openclaw

The bot now starts automatically on server boot and restarts if it crashes.

Option B: PM2 (Cross-Platform)

If you prefer PM2:

npm install -g pm2
pm2 start "openclaw gateway" --name openclaw
pm2 startup
pm2 save

PM2 handles restarts and has a nice status dashboard via pm2 status.

Option C: macOS Launch Agent

On macOS:

openclaw gateway install

OpenClaw automatically registers as a launchd agent that starts on login.

---

Part 7: Webhook Mode (Optional — Faster Responses)

Long polling works fine, but webhook mode cuts response latency from 2–5 seconds to under 1 second. You need a public HTTPS URL for this.

If you're on a VPS with a domain:

Add to your config:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "YOUR_TOKEN",
      webhook: {
        enabled: true,
        url: "https://yourdomain.com/webhook/telegram",
        port: 3000
      }
    }
  }
}

OpenClaw registers the webhook with Telegram automatically on gateway start.

If you're on a local machine (no public URL):

Use ngrok during development:

ngrok http 3000

Use the ngrok HTTPS URL as your webhook URL. Note: free ngrok URLs change on restart. For production, use a VPS with a real domain.

---

Troubleshooting Common Issues

Bot doesn't respond after approval

Check the gateway is still running:

openclaw gateway status

Check gateway logs for errors:

openclaw gateway logs --tail 50

"Unauthorized" error in logs

Your bot token is wrong. Double-check for extra spaces or line breaks when you pasted it.

Bot responds in DMs but not groups

Two possible causes:

• 1. Privacy mode is enabled — disable it via BotFather: /setprivacy → your bot → Disable
• 2. Bot isn't an admin and requireMention is false — the bot needs to see all messages. Either make it admin or require @mentions.

Pairing code expired

Codes expire after 1 hour. Just message the bot again to generate a new code.

Bot responds once, then stops

Usually a rate limit or API quota issue. Check your AI provider dashboard for usage limits. OpenAI and Anthropic both have rate limits on free tier accounts.

---

Next Steps

Your Telegram bot is live. Here's what to do next:

Install skills for extended capabilities:

openclaw skills search weather
openclaw skills install weather

After installing a skill, the bot can answer weather questions using real data.

Set up heartbeats:

In your workspace's HEARTBEAT.md, add tasks for the bot to check proactively:

# HEARTBEAT.md
- Check for unread emails
- Review today's calendar
- Monitor server uptime

The bot will check these on a schedule and message you when something needs attention.

Connect additional channels:

Once Telegram is stable, adding Discord or Slack takes another 10 minutes. Both use the same OpenClaw config pattern.

---

Want this entire setup handled for you? MrDelegate deploys OpenClaw with Telegram pre-configured — bot token, channel config, systemd service, and initial SOUL.md setup included.

Questions about specific Telegram features? The OpenClaw Telegram docs have advanced configuration for webhook mode, group policies, and multi-account setups.

Ready to add Discord next? Read the OpenClaw Discord bot hosting guide for the complete walkthrough.