openclaw-lighthouse

Telegram setup workflow after installing OpenClaw (with root VPS notes)

Problem

After a fresh OpenClaw install, Telegram setup may fail or behave inconsistently:

On root VPS hosts, this often combines with gateway lifecycle issues.

Why this happens

Most failures come from one of these:

  1. Telegram plugin is not effectively enabled (or blocked by plugins.allow).
  2. Gateway was not restarted after config/plugin changes.
  3. Channel token was added before plugin/channel runtime was active.
  4. Pairing flow was expected, but no pending request existed yet.
  5. On root VPS, systemctl --user may be unavailable, so service-mode restart fails.
  6. Bot token mapping is wrong (for example, multiple bots/tokens used on the same VPS and the active token points to another bot).

Step-by-step fix

Follow this exact order.

1) Ensure Telegram plugin is allowed and enabled

If you use plugin allowlist, include telegram.

openclaw config set plugins.allow '["telegram"]'
openclaw config set plugins.entries.telegram.enabled true

If you also use Feishu on the same host, allow both:

openclaw config set plugins.allow '["feishu","telegram"]'

2) Start gateway with the correct mode for your host

Root VPS / no working systemctl --user (recommended)

tmux kill-session -t openclaw 2>/dev/null || true
tmux new -d -s openclaw 'openclaw gateway run --port 18789'

Standard user-service mode (when systemd user bus works)

openclaw gateway install --force
systemctl --user enable --now openclaw-gateway.service

3) Add Telegram bot token

openclaw channels add --channel telegram --token "<BOTFATHER_TOKEN>"

4) Verify channel runtime

openclaw gateway status
openclaw channels status --probe

Expected Telegram state: enabled, configured, running.

5) Pairing flow (if DM policy is pairing)

Set pairing policy (safe default):

openclaw config set channels.telegram.dmPolicy pairing

Now send one DM to the bot from Telegram, then check pending requests:

openclaw pairing list telegram --json

Approve code:

openclaw pairing approve telegram <CODE> --notify

Optional checks if it still fails

A) Unknown channel: telegram

Usually means telegram plugin runtime not active yet.

It can also happen when CLI commands run in a different OpenClaw profile than the running gateway.

Check:

openclaw plugins list | grep -i telegram
openclaw config get plugins.allow
openclaw config get plugins.entries.telegram.enabled

If you use named profiles, run all commands with the same profile:

openclaw --profile <profile_name> channels status --probe
openclaw --profile <profile_name> channels add --channel telegram --token "<BOTFATHER_TOKEN>"
openclaw --profile <profile_name> plugins list | grep -i telegram

B) requests: [] and no pairing code

Possible reasons:

Check:

openclaw channels status --probe
cat ~/.openclaw/credentials/telegram-allowFrom.json 2>/dev/null || echo "no approved senders file"

C) Gateway unreachable (1006)

Use root VPS quick recovery command:

tmux kill-session -t openclaw 2>/dev/null || true
tmux new -d -s openclaw 'openclaw gateway run --port 18789'

D) Outbound message comes from the wrong bot

This means the VPS is using a different Telegram token than expected.

1) Send an outbound test to yourself:

openclaw message send --channel telegram --target <telegram-user-id> --message "vps outbound test" --json

2) If the message comes from another bot, set the correct bot token for this VPS:

openclaw channels add --channel telegram --token "<BOT_TOKEN_FOR_THIS_VPS>"

3) Restart gateway (tmux mode) and verify:

tmux kill-session -t openclaw 2>/dev/null || true
tmux new -d -s openclaw 'openclaw gateway run --port 18789'
openclaw channels status --probe

Check that status shows the expected bot:@<your_bot_username>.

Validation

Security notes

Upstream status

References

Credits