OpenClaw in Telegram in five minutes: setup, pairing, hosted or self-hosted

I work on Aplite, a managed OpenClaw host. The self-hosted path below is the upstream one, run on OpenClaw 2026.9.8 and linked to the docs at every step; the hosted path is ours, with the trade-off stated.

Search for openclaw telegram setup and you get a dozen walkthroughs by hosting companies,
each ending at their own control panel, and the upstream documentation, which is correct but
spread over four pages: setup, pairing, access control, troubleshooting. The actual job is
short. A Telegram bot is a token from @botfather; OpenClaw needs that token and then an
approval for every chat that may talk to it. That is the whole thing, and it takes about
five minutes whether the gateway runs on your machine or on someone else's.

Below, both paths on OpenClaw 2026.9.8: the self-hosted one with every command, checked
against the upstream docs and run in a
fresh container of that version, then the hosted one,
where the commands become two buttons.

What you need

• A bot token. Free, from @BotFather inside Telegram. Check the handle is exactly @BotFather; there are impostors.
• A gateway that stays up. The Telegram channel long-polls Telegram's API from the gateway, so a bot only answers while the gateway runs. A laptop that sleeps stops it.
• A model. The bot token is not a model key. Self-hosted, you still need a provider or a local model (the ways without an API key); hosted, the models are included.

Self-hosted: six steps

1. Create the bot. In Telegram, open @botfather, send /newbot, answer with a display
   name and a username ending in bot. BotFather replies with the token, shaped like
   123456789:AAF…. Keep it private: whoever has it can run your bot until you regenerate
   it with /revoke.

2. Install OpenClaw if it is not there yet. On macOS, Linux or WSL2:
   

   curl -fsSL https://openclaw.ai/install.sh | bash
   openclaw onboard
   

   Onboarding picks the model provider and starts the gateway; the longer version is in
   OpenClaw hosting for free.

3. Give OpenClaw the token. One command:
   

   openclaw channels add --channel telegram --token 123456789:AAF…
   

   It prints Added Telegram account "default". and writes the channel into
   ~/.openclaw/openclaw.json:
   

   "channels": {
     "telegram": {
       "enabled": true,
       "botToken": "123456789:AAF…"
     }
   }
   

   The same block typed by hand works too, as does the TELEGRAM_BOT_TOKEN environment
   variable for the default account; a tokenFile beats botToken, which beats the env.
   There is no openclaw channels login telegram step: unlike WhatsApp with its QR
   login, Telegram needs nothing but the token
   (setup docs).

4. Make sure the gateway is running. A running gateway hot-reloads the new channel. If
   it is not running, start it in the foreground with openclaw gateway, or as the service
   that openclaw gateway install set up (gateway docs):
   

   openclaw gateway start
   

   Then check the channel:
   

   openclaw channels status --probe
   

   The Telegram line reads Telegram default: enabled, configured, mode:polling,
token:***; with --probe the gateway also calls Telegram with the token. A wrong
   token fails at gateway startup as getMe returned 401.

5. Send /start to your bot. A Telegram bot cannot write to you first. On the first
   message from an unknown chat, OpenClaw's default DM policy, pairing, does not answer
   the question; it replies with a pairing code instead: eight characters, uppercase, no
   0, O, 1 or I, valid for one hour, at most three pending per bot
   (pairing docs).

6. Approve the chat. On the server:
   

   openclaw pairing list telegram
   openclaw pairing approve telegram K7QX2MPB
   

   Add --notify and the bot tells the requester they are in. From now on that chat talks
   to the agent; the approval lives in ~/.openclaw/state/openclaw.sqlite, and the first
   approved sender becomes the command owner if none was set
   (CLI reference). Anyone else who finds the bot
   gets a code and silence until you approve them, which is the point.

Two things people do next, both optional. Lock it to yourself: set dmPolicy to
allowlist and put your numeric Telegram user ID in allowFrom. The ID is in the bot's
pairing reply, in openclaw logs --follow as senderUserId, or at
https://api.telegram.org/bot<token>/getUpdates; @username entries are not accepted
(access control). Add it to a
group: groups default to groupPolicy: "allowlist", so a group is silent until its chat ID
(a -100… number for supergroups) is listed under channels.telegram.groups; the bot then
answers only when mentioned unless requireMention is off, and reading unmentioned messages
needs Privacy Mode disabled in BotFather (/setprivacy) or admin rights, then a remove and
re-add. /whoami@your_bot in the group confirms both IDs.

Hosted: the same bot in three steps

Aplite runs a standard OpenClaw instance for you, so the gateway is already
up and the config is a form. Same bot, same pairing rule, no server:

1. Create a workspace. Email or Google, no card on the Free plan. Pick an agent, press
   Deploy, and about a minute later the workspace opens with its own OpenClaw 2026.9.8 in
   its own container.

2. Connect the bot. Open Skills → Channels → Telegram and press Connect. Paste
   the token from @botfather, press Validate: Aplite calls Telegram's getMe and shows
   Connected to @your_bot. Press Connect again; the workspace restarts to pick up the
   bot, about a minute. Under Show advanced sit the same knobs the config file has: DM
   policy (pairing by default), group policy (allowlist), chat IDs, require @-mention.

Skills → Channels → Telegram: the card is one Connect button away from a bot.

Paste the token, Validate, Connect: the dialog does what channels add does.

1. Say /start, then Approve. Send /start to the bot from your phone. A pairing request appears on the same Telegram card within seconds, with the sender's name and the code; press Approve. Codes expire after one hour, so if you were slow, send /start again. Only chats you approve can talk to your agent.

The advanced block: pairing, allowlist, open or disabled for DMs; allowlist for groups; the mention rule.

That is the setup. The bot answers in Telegram with the same agent that answers in the
browser, routines can deliver to it, and the toggle on the
Telegram card pauses the channel without dropping the token. One honest line about the Free
plan: the workspace sleeps after 6 hours idle and wakes on your next visit, and while it
sleeps the bot does not answer, so a bot that answers at any hour needs
Pro or Power. Aplite is an independent service and is not affiliated with the
OpenClaw project.

If the bot stays silent

• Nothing at all after /start. It is waiting for approval. Run openclaw pairing list telegram, approve the code, or approve on the Telegram card. A code older than an hour is gone; send /start again (channel troubleshooting).
• getMe returned 401 or deleteWebhook 401 Unauthorized at startup. The token is wrong or revoked. Copy it again from BotFather and update botToken, tokenFile or TELEGRAM_BOT_TOKEN (Telegram troubleshooting).
• Answers in DMs, silent in a group. The group is not in channels.telegram.groups, or Privacy Mode is on while you expect unmentioned messages: /setprivacy → Disable, then remove and re-add the bot. Hosted, the same two settings are in the advanced block.
• Worked yesterday, silent today. Self-hosted: openclaw gateway status should say Runtime: running; a laptop that slept or a VPS that rebooted without openclaw gateway install stops polling. Hosted on Free: the workspace is asleep; open it once.

FAQ

Does OpenClaw need a server to work in Telegram?

Yes. The gateway polls Telegram for new messages, so something has to keep running: your
machine while it is awake, a VPS, or a managed instance. A message sent while the gateway
is down is not answered until it is back.

Can more than one person use the bot?

Yes. Each person sends /start, gets their own pairing code, and you approve each one; an
unapproved sender never reaches the agent. For a shared group, list its chat ID under
groups or switch the group policy to open.

Do I need an API key for the Telegram bot?

Not for Telegram: the bot token from @botfather is free. The model behind the bot is the
usual question. Self-hosted, that is a provider key, a subscription login or a local model
(every option); on Aplite the models are metered and
included.

Why does the bot answer my question with a code?

That is pairing, OpenClaw's default DM policy: the first message from an unknown chat gets
a code, not an answer, until the operator approves it with
openclaw pairing approve telegram <CODE> or the Approve button. Set dmPolicy to open
only if you want anyone who finds the bot to command your agent.