How to Set Up OpenClaw on Telegram (Step-by-Step)

Telegram is the easiest and most capable channel for OpenClaw. Once connected, you can message your AI agent from anywhere, get proactive alerts, use voice messages, and even add it to group chats. This guide walks through the full setup from zero to working bot in under 20 minutes.

What You’ll Need

• OpenClaw installed (see the official install guide)
• A Telegram account
• 5-10 minutes

Step 1: Create a Telegram Bot

Every OpenClaw Telegram connection uses a bot that Telegram provides for free. Creating one takes two minutes:

1. Open Telegram and search for @BotFather (official Telegram bot, blue checkmark)
2. Send the message: /newbot
3. Follow the prompts: choose a name (e.g. “My Assistant”) and username (must end in “bot”, e.g. “myassistant_bot”)
4. BotFather will send you a bot token – a long string like 1234567890:ABCdefGHIjklmNOPqrsTUVwxyz
5. Copy this token – you’ll need it in a moment

Keep your bot token private. Anyone with it can control your bot.

Step 2: Add the Bot Token to OpenClaw

Open your OpenClaw config file at ~/.openclaw/openclaw.json and add the Telegram channel config:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN_HERE",
      "dmPolicy": "open",
      "allowFrom": ["YOUR_TELEGRAM_USER_ID"]
    }
  }
}

To find your Telegram user ID: message @userinfobot on Telegram and it will reply with your numeric ID.

Important: Set allowFrom to your user ID for security. Using ["*"] allows anyone who finds your bot to message it.

Step 3: Restart the Gateway

openclaw gateway restart

OpenClaw will connect to Telegram automatically on startup.

Step 4: Message Your Bot

1. Search for your bot by the username you created (e.g. @myassistant_bot)
2. Tap Start
3. Send any message

You should get a response within a few seconds. If you get no response, check that your gateway is running (openclaw gateway status) and that your bot token is correct.

Useful Telegram-Specific Features

Voice Messages

OpenClaw supports voice message transcription – hold the microphone button in Telegram, record your message, and it gets transcribed and processed as text. Useful when you’re driving or want to dictate rather than type.

Streaming Responses

Enable partial streaming so responses appear word-by-word rather than waiting for the full reply:

{
  "channels": {
    "telegram": {
      "streaming": "partial"
    }
  }
}

Group Chats

Add your bot to a Telegram group and configure it to respond only when mentioned (to avoid it responding to every message):

{
  "channels": {
    "telegram": {
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

In a group, tag your bot: “@myassistant_bot what’s the status of the Johnson project?” and it will respond in the group.

Heartbeat Alerts

Configure OpenClaw to send proactive messages to your Telegram when something needs attention:

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "2h",
        "target": "last"
      }
    }
  }
}

With target: "last", heartbeat alerts go to whoever last messaged the bot – typically you.

Troubleshooting Common Issues

Bot doesn’t respond

• Check gateway is running: openclaw gateway status
• Verify bot token in config has no extra spaces
• Make sure you’ve started the chat by pressing Start in Telegram
• Check your allowFrom list includes your user ID

Messages deliver but no reply

• Check your AI API key is configured and valid
• Run openclaw logs --follow to see real-time gateway logs
• Verify the model you configured exists (common issue: typos in model names)

Slow responses

• Normal response time is 5-20 seconds depending on the model and task
• If consistently slow, try switching to a faster model like google/gemini-3-flash-preview
• Check your VPS or machine isn’t resource-constrained

Next Steps

Once your Telegram bot is working, the useful next steps are:

• Set up a second channel (WhatsApp, Discord) for redundancy
• Configure heartbeats so the agent proactively monitors and works in the background
• Explore the workspace files – edit SOUL.md to customize the agent’s personality, USER.md to tell it about yourself

See our full OpenClaw guide for more on what the agent can do once it’s running.

Recommended on Amazon: AI Book 2024 | Prompt Engineering Guide