Connect a Telegram bot to your OpenClaw agent

Telegram is the fastest way to put an OpenClaw agent in front of a human. It's also the integration we've spent the most time hardening, because it has the gnarliest gotchas — public bot usernames, multi-agent webhooks, idle timeouts, and the auto-lock.

Prerequisites

• A ShipClaw account with at least one agent created
• Telegram installed (mobile or desktop)

1. Create the bot with @BotFather

In Telegram, search for @BotFather — the verified, blue-check bot. Send:

/newbot

BotFather will prompt for:

1. A display name ("Polymarket Pete")
2. A username that ends in _bot (e.g. @my_pmpete_bot)

The username has to be globally unique across Telegram. Once accepted, BotFather returns the bot's API token.

2. Copy the bot token

The token looks like:

1234567890:AAH-redacted-redacted-redacted

This is a secret. Anyone with this token can read and send messages as the bot.

3. Paste the token into ShipClaw

On the agent's settings page in the ShipClaw dashboard, paste the token into the Telegram bot token field. Save.

Behind the scenes, the save triggers a 10-second debounced sync to your pool node. The debounce prevents a rapid kill-respawn cycle if you save twice in quick succession (it caught us in the wild).

4. ShipClaw registers the webhook

Each agent gets its own webhook path: /telegram-webhook/{agentId}. OpenClaw on your pool node calls Telegram's setWebhook for you, pointing at the routed URL /{userId}/telegram/webhook/{agentId}.

You don't need a public URL, you don't need to port-forward, and you don't need a tunnel like ngrok. The pool node already has a public hostname and routes to your specific OpenClaw process by user-id prefix.

5. Send the first message — agent auto-locks

Open the bot in Telegram and send any message.

This is the auto-lock: the first Telegram user to message the bot becomes its locked operator. Subsequent messages from other Telegram users are silently ignored. This protects you from a stranger discovering your bot's @_bot username and hijacking it before you do.

The lock state is stored in three places (in-memory cache, the pool node's pool-settings.json, and the agent's openclaw.json) so it survives a restart.

If you need to reset the lock (e.g. you locked it from your test account and want a friend to use it instead), the dashboard exposes a Reset operator button on the agent settings page.

6. Chat with the agent

Send messages. The first message after a long idle period wakes the OpenClaw process — usually under a second. After the last message, the agent stays warm for 1 hour before suspending (vs. 15 minutes for non-Telegram agents).

Multiple Telegram accounts on one agent

You can connect more than one bot to the same agent. Each bot is keyed by agentId, not "default", and gets its own webhook path. The pool node multiplexes them through a single webhook port.

(Caveat: as of April 2026 we have not stress-tested this with five-plus bots on one agent. It works, we just can't promise nothing weird happens at scale.)

Disconnecting

Clear the bot token field and save. The pool node calls Telegram's deleteWebhook, the agent stops processing Telegram traffic, and the auto-lock resets.