Writing
Blog
Guide

OpenClaw on Telegram

Your OpenClaw assistant lives on a server. Telegram puts it in your pocket. Five steps to connect them: a bot, a token, a pairing code, and you're done.

5 min readFebruary 2026
01

Prerequisites

Three things need to be in place before you start. If any one of them is missing, the pairing step will silently fail.

01
Shell access
SSH or terminal access to the machine or container running OpenClaw.
02
openclaw CLI
The openclaw command must be reachable. Run openclaw gateway status to confirm.
03
Telegram account
A personal Telegram account you can message from.
02

Create a Telegram bot

Telegram bots are provisioned through @BotFather. Telegram's official bot management account. Open Telegram and start a chat with it.

/newbot

BotFather will ask for two things: a display name (anything you like) and a username that ends in bot and is globally unique. Once confirmed, you'll receive a token:

123456789:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Treat this token like a password. Anyone who has it can fully control your bot: intercept messages, send replies, impersonate your assistant. Never paste it into a public chat or commit it to a repository.
03

Configure the token

OpenClaw needs the token before the gateway starts. The exact method depends on your deployment: bare CLI, Docker Compose, or systemd. In all cases, the goal is the same: make the token available as an environment variable.

A · Environment variable (typical)

export TELEGRAM_BOT_TOKEN="123456789:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
openclaw gateway restart

B · Docker Compose

Add the token to the environment block for your gateway service, then redeploy:

docker-compose.yml
services:
  gateway:
    image: openclaw/gateway
    environment:
      - TELEGRAM_BOT_TOKEN=123456789:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
docker compose up -d --force-recreate
The variable name may differ depending on your OpenClaw version. If your deployment ships with a config file, check that file for the exact key name.
04

Restart & verify

After adding the token, restart the gateway so it picks up the new configuration. Then verify that the Telegram provider shows as healthy.

openclaw gateway restart
openclaw gateway status

The status output should indicate the Telegram integration is enabled. If it shows as missing or errored, the token isn't being picked up. Double-check the variable name and restart again.

05

Pair your account

OpenClaw uses an approval step so random Telegram users can't connect to your assistant. You trigger a pairing request from Telegram, then approve it from the server.

5.1 · Trigger a pairing request

Open the bot you just created in Telegram and send any message. hi is enough. OpenClaw will respond with three pieces of information:

Status
access not configured
Your Telegram ID
e.g. 987654321
Pairing code
e.g. KZ2WLBGW

5.2 · Approve from the server

Back on the server, optionally list pending requests first, then approve by code:

# Optional: see all pending pairings
openclaw pairing pending

# Approve your pairing code
openclaw pairing approve telegram KZ2WLBGW
The pairing code changes every time the bot restarts or a new request is triggered. If you see access not configured again after approving, list pending requests and approve the new code.
06

Confirm it works

Go back to Telegram and send another message to the bot. If the token and pairing are both correct, OpenClaw will relay your message to the assistant and stream the response back, directly in Telegram.

That's it. Your assistant is now reachable from any device with Telegram installed (phone, desktop, or web) without opening a terminal or a browser.
07

Troubleshooting

Three failure modes cover almost every case.

01
"access not configured" persists
Pairing approval didn't persist, or the gateway restarted and generated a new code. List pending pairings and approve the latest one.
openclaw pairing pending
openclaw pairing approve telegram <NEW_CODE>
02
Bot doesn't respond at all
Token not configured, wrong token, or gateway not running. Check gateway status.
openclaw gateway status
03
Multiple environments / bots
Make sure you're messaging the right bot and restarted the correct gateway instance, the one holding that bot's token.
08

Security notes

A Telegram bot connected to your AI assistant has access to everything the assistant can do. A few practices worth keeping in mind.

01
Token = password
Rotate it in BotFather (/revoke) if it leaks, then update the env var and restart the gateway.
02
Keep pairing enabled
Don't run an open public bot. The approval step is what prevents random Telegram users from accessing your assistant.
03
Use env vars, not config files
Secrets in plain-text config files get committed to repositories. Prefer environment variables or a secrets manager.

You're connected

One bot, one token, one pairing approval. OpenClaw is now available in your Telegram, wherever you are, on any device, with no VPN or open port required.

OpenClaw DocsBotFather