Telegram

After onboarding succeeds, configure the Telegram bot.

1. Create the Bot

In Telegram:

1. Open @BotFather.
2. Run /newbot.
3. Pick a display name and username.
4. Copy the bot token.

Treat the bot token like a password.

2. Add the Telegram Config

For a DM-first sandbox test, use pairing for DMs and disable groups at first:

openclaw config set channels.telegram.enabled true --json
openclaw config set channels.telegram.botToken '"<TELEGRAM_BOT_TOKEN>"' --json
openclaw config set channels.telegram.dmPolicy '"pairing"' --json
openclaw config set channels.telegram.groupPolicy '"disabled"' --json
openclaw config set channels.telegram.streaming '"off"' --json

Why this shape:

• dmPolicy: "pairing" gives you the shortest first test path
• groupPolicy: "disabled" removes the noisy doctor warning about empty group allowlists
• streaming: "off" keeps Telegram replies simple and final-only during setup

3. Start the Gateway

In the sandbox container, you do not need to fix background service mode first.

This warning is expected:

Gateway service disabled.
Start with: openclaw gateway

That just means no systemd user service is installed in the container.

Recommended first-run path:

openclaw gateway

Leave that running in one terminal.

If you want the gateway to keep running while you get your shell prompt back, use this detached form:

mkdir -p ~/.openclaw/logs
nohup openclaw gateway > ~/.openclaw/logs/gateway-sandbox.log 2>&1 & echo $! > ~/.openclaw/gateway-sandbox.pid
sleep 4

That means:

• the gateway keeps running in the background
• you can keep using the same terminal for the next setup commands
• logs are written to ~/.openclaw/logs/gateway-sandbox.log

Verify the gateway:

openclaw gateway status
tail -n 60 ~/.openclaw/logs/gateway-sandbox.log

What you want to see:

• RPC probe: ok
• a log line showing Telegram started successfully

4. Pair the First DM

Telegram bots cannot message you first.

Open the bot chat:

https://t.me/<bot_username>

Then:

1. Tap Start
2. Send hello

Approve the pairing in the sandbox.

If you started the gateway with plain openclaw gateway, leave that running and open a second terminal for the pairing commands.

If you started the gateway with the detached nohup ... & command above, you can run the pairing commands in the same terminal:

openclaw pairing list telegram
openclaw pairing approve telegram <PAIRING_CODE>

Then send another DM to the bot.

5. Safer Owner-Only DM Setup

After the first test works, you can switch from pairing to an explicit allowlist.

Find your Telegram user ID:

1. DM the bot
2. Run openclaw logs --follow
3. Read from.id

Or use the official Bot API:

curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getUpdates"

Then update config:

openclaw config set channels.telegram.dmPolicy '"allowlist"' --json
openclaw config set channels.telegram.allowFrom '["<YOUR_TELEGRAM_USER_ID>"]' --strict-json

6. Group Setup Later

Only do this after DMs work.

If you want group support:

openclaw config set channels.telegram.groupPolicy '"allowlist"' --json
openclaw config set channels.telegram.groupAllowFrom '["<YOUR_TELEGRAM_USER_ID>"]' --strict-json
openclaw config set channels.telegram.groups '{"*":{"requireMention":true}}' --strict-json

Also check Telegram-side settings in BotFather:

• /setjoingroups
• /setprivacy

If the bot must see all group messages, disable privacy mode or make the bot a group admin.

Troubleshooting

• openclaw gateway restart says the gateway service is disabled: That is expected in the sandbox container. Use openclaw gateway in the foreground instead.
• Telegram config is saved but no replies arrive: Make sure the gateway process is actually running and that you approved the pairing code.
• Group warnings mention empty allowlists: For DM-first setup, set channels.telegram.groupPolicy to "disabled".
• The bot exists but you cannot message it: Open the direct https://t.me/<bot_username> link and tap Start.

Next: continue to /openclaw/setup/auth.