OpenClawWiki
tutorials

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

Connect OpenClaw to Telegram in 15 minutes: create the bot, add the token safely, approve device pairing, and lock it down so only you can talk to your agent.

OpenClaw Team•
telegramchannelsmessagingsetuptutorial

Introduction

Telegram is the easiest way to put OpenClaw in your pocket. It's a first-class channel in OpenClaw, the bot creation flow takes two minutes, and unlike WhatsApp you don't need a second phone or a QR dance — just a bot token. By the end of this guide your agent will answer you in Telegram, and — just as important — only you, because we'll set up pairing correctly instead of leaving the front door open.

This guide assumes OpenClaw is already installed and running. If not, start with the installation guide (or the Docker route), then come back.

Prerequisites

  • OpenClaw installed and the Gateway running (any OpenClaw 2.x version)
  • A Telegram account (yours — the one you'll actually message from)
  • Five minutes and a terminal

Step 1 — Create Your Bot with BotFather

Every Telegram bot needs a token from @BotFather, Telegram's official bot-creation bot:

  1. Open Telegram and message /newbot to BotFather
  2. Choose a display name (anything — this is what shows in your chat list)
  3. Choose a username ending in bot (e.g. chases_claw_bot) — this must be globally unique
  4. BotFather replies with an API token that looks like 123456789:AAE...aBcD

Treat that token like a password. Anyone holding it controls the bot. Don't paste it into chat with your agent, don't commit it to a repo, don't bake it into a Docker image — inject it at runtime. Our API key security guide covers why this class of credential leaks and how to cap the damage; the same rules apply to channel tokens.

Step 2 — Add the Token to Your OpenClaw Config

Open your OpenClaw configuration (the channel settings live in your main config file — see the configuration guide for the full layout) and add the Telegram channel with your token:

{
  "channels": {
    "telegram": {
      "botToken": "123456789:AAE...aBcD"
    }
  }
}

Restart the gateway so it picks up the channel:

openclaw gateway restart

If the config format has changed since you last looked (the 2.0 upgrade touched messaging internals), the channel section examples in the official docs are the source of truth — but existing channel credentials carry over from pre-2.0 installs.

Step 3 — Pair Your Account (Don't Skip This)

Here's the step people skip, and it's the step that keeps strangers out of your agent. OpenClaw treats inbound messages as untrusted input and pairs unknown senders by default — a stranger messaging your bot doesn't get an AI with shell access; they get a pairing request.

Open Telegram, send any message to your new bot, and watch the Gateway logs — you'll see a pairing code appear. Then approve your own account:

openclaw pairing approve telegram <code>

Your next message gets a real reply. Anyone else who messages the bot stays unpaired until you approve them explicitly — which is exactly the behavior you want. If you ever want a family member or teammate on the same bot, approve them deliberately rather than opening the bot to everyone.

Step 4 — Test It Properly

Run through this checklist before you consider it done:

  • Basic reply — "hello" gets a sane response from your model backend
  • History survives restart — restart the gateway, confirm the conversation context is still there (on 2.0, sessions live in SQLite)
  • Unpaired stranger test — message the bot from a second Telegram account; confirm it gets a pairing wall, not your agent
  • Tool sanity — ask it to do one real task you actually want (a summary, a lookup, a reminder) so you know tools fire from the Telegram path

Securing the Setup

A Telegram-connected agent is only as safe as the rest of the deployment:

  • Gateway stays local. Nothing in this guide requires exposing your Gateway to the internet — Telegram's bot API works over an outbound connection. If your Gateway is currently exposed, fix that first (see is OpenClaw safe?)
  • Sandbox your tools. Your agent now takes instructions from a chat app on your phone. If a prompt-injected message can reach unsandboxed shell, your Telegram account is now a root shell. Two-minute fix in the sandboxing guide
  • Cap your model spend. A bot anyone can message is a bot that can burn tokens — spending caps and alerts, per the cost guide
  • Group chats are a trust decision. Adding the bot to a group means every member can trigger it. Family group: fine after you think about it. Large public group: don't.

Daily-Driving It

Once paired, a few habits make the Telegram experience much better:

  • Talk to it like a delegate, not a search box. "Summarize this article and save the key points" works; "search the internet" just burns tokens. The operators who get the most out of channel-connected agents give them bounded tasks with clear outputs.
  • Watch the first week's usage. Your first week of Telegram-triggered agents is when you learn what a "message" costs in model terms. Check your provider dashboard after a few days and right-size your caps (see the cost breakdown).
  • Keep a second admin path. If Telegram is your only window into the agent, a Telegram outage locks you out of your own assistant. The CLI or the browser app on your server is your spare key.

Troubleshooting

Bot doesn't respond at all. Check the token is complete (they're long and easy to truncate) and the gateway restarted cleanly. The logs will show an auth error from Telegram if the token is wrong — on a VPS, check with your service manager (journalctl -u <your-openclaw-service> under systemd, or your process manager's log file); on a Mac, check the terminal you launched from.

"Pairing required" from your own account. The pairing code expires — send a fresh message to generate a new one, then approve it promptly.

Replies stopped after an upgrade. Channel credentials normally carry over, but messaging internals changed in 2.0 — check the logs for pairing or config errors before re-onboarding, per the upgrade guide.

Agent replies but can't do tasks. That's a tools/sandboxing issue, not Telegram — check the Gateway logs for tool execution errors.

Slow or doubled replies. Usually two gateways running against the same token (a stale process didn't die on restart). Stop all instances, start one.

FAQ

Does the OpenClaw Telegram bot work in groups? Yes, but be deliberate: in groups, more people can trigger your agent. Keep it to a private chat or a trusted group, and remember every participant's messages are untrusted input your agent will process.

Can I use the same bot token on two OpenClaw instances? No — one token, one polling connection. Run a second bot (another BotFather chat, 60 seconds) for a second instance.

Is Telegram more secure than WhatsApp for OpenClaw? Neither is inherently safer — the security boundary is your OpenClaw deployment (pairing, sandboxing, Gateway exposure), not the transport. Telegram's advantage is operational: no phone-number/QR ceremony and instant bot creation.

How much does running the bot cost? Telegram bots are free. Your costs are the usual OpenClaw ones — model usage and optional hosting (from $6/month, see the cost breakdown).

Related Articles

OpenClaw Security & Deployment Brief

Get the weekly OpenClaw Security & Deployment Brief — malicious skill alerts, CVE breakdowns, cost optimization tips.

Related Articles