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

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.

3. 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.

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.