OpenClaw Telegram Setup and Pairing Guide

Before you pair Telegram with OpenClaw

• OpenClaw installed via installer or npm.
• Telegram account (for creating bot and getting user ID).
• LLM provider credentials already configured.
• Gateway running: openclaw gateway status.
• Access to the machine or managed instance where OpenClaw runs, because Telegram replies depend on the gateway staying online.

Step 1: Create your Telegram bot

1. Open Telegram and search for @BotFather.

2. Send /newbot to create a new bot.

3. Follow the prompts to name your bot (e.g., "My OpenClaw Assistant").

4. Copy the bot token — you'll need it for configuration.

BotFather token checklist

• Use the token from the final BotFather message, not the bot username.
• Store it as a secret and never paste it into a shared chat or public issue.
• Use one active OpenClaw runtime per bot token to avoid duplicate polling.
• Rotate the token in BotFather if it was exposed or used by an old machine.

Step 2: Allowed users and chat IDs

1. Search for @userinfobot on Telegram.

2. Send any message to get your user ID.

Alternatively, use @myidbot — send /getid to get your ID.

For groups, add the bot to the group, send a test message, then capture the group chat ID from your OpenClaw logs or Telegram tooling. Keep personal user IDs and group chat IDs explicit; broad access is convenient but makes it easier for the wrong chat to control your agent.

Step 3: Configure Telegram channel in OpenClaw

Run the configuration wizard:

openclaw configure

Select "Add channel" → "Telegram" and enter:

• Bot token from Step 1.
• Your user ID from Step 2 (for allowlist).

Or add manually via config:

openclaw config set telegram.bot_token "YOUR_BOT_TOKEN"
openclaw config set telegram.allowed_users "YOUR_USER_ID"

Step 4: Verify Telegram connection

Check gateway status:

openclaw gateway status

You should see Telegram as an active channel.

Open your bot in Telegram and send /start — you should receive a greeting from OpenClaw.

If the bot remains silent, work through the checks below before changing unrelated OpenClaw settings.

Step 5: Test your setup

Send a message to your bot:

OpenClaw should respond using your configured LLM provider.

Common errors and quick fixes

"Bot token invalid"

Copy the token exactly as provided by BotFather — it should be in the format 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz.

"User not authorized"

Your user ID must be in the allowlist:

openclaw config set telegram.allowed_users "YOUR_USER_ID"
openclaw gateway restart

Fix: Telegram bot sends no reply

Verify the gateway sees Telegram:

openclaw gateway status

Check logs:

openclaw doctor

Then confirm the token has not been rotated, your user ID is allowlisted, and your runtime has outbound network access to Telegram. For a deeper version of this failure mode, see Telegram typing/no reply.

Fix: duplicate Telegram messages

Duplicate replies usually mean two OpenClaw processes are polling the same BotFather token. Stop old local gateways, check for a stale service or scheduled task, and make sure only one managed or local instance owns the bot. Use the duplicate progress messages guide if duplicates happen during long-running tasks.

Fix: pairing required loop

A pairing loop usually means OpenClaw is running, but the Telegram channel is attached to the wrong scope, user, or instance. Re-run configuration, confirm the allowed user or chat ID, restart the gateway, and send /start from the same Telegram account you allowlisted. If direct messages route into the wrong main session, use the Telegram DM scope fix.

"Channel not found" during config

Ensure OpenClaw is updated:

npm install -g openclaw@latest

Managed option: use Lobsterland for always-on Telegram agents

Telegram works best when the OpenClaw gateway stays online. Laptops sleep, local networks change, and old service files can keep polling after you thought the bot was stopped. Lobsterland gives you always-on Telegram agent hosting with managed runtime operations, isolated instances, and dashboard controls.

If you are comparing local hosting against managed operations, start with managed OpenClaw hosting.

Next steps