Telegram + Hermes Agent: Known Pitfalls and Fixes

The two most common Telegram pitfalls: Telegram's 100 slash-command limit (disable unneeded skills via skills.platform_disabled) and gateway disconnects under WSL (use hermes gateway run or tmux).

Who this is for：Anyone whose Telegram bot loses commands or keeps disconnecting.

Steps

  1. Pitfall 1: over 100 slash commands

    Telegram caps commands at 100. Official fix: disable unused skills per platform in config.yaml, then restart the gateway.

    skills:
  platform_disabled:
    telegram: [skill-a, skill-b]

  2. Pitfall 2: gateway disconnects under WSL

    Official FAQ: systemd is unreliable in WSL; run in the foreground or under tmux.

    hermes gateway run
# or
tmux new -s hermes 'hermes gateway run'

  3. Multiple users need authorization

    The messaging gateway supports allowlists and DM pairing; configure the authorization mode under gateway settings in config.yaml.

How to verify

FAQ

Migrating from OpenClaw: do I redo the Telegram allowlist?

The official migration moves compatible settings like TELEGRAM_ALLOWED_USERS; with --migrate-secrets it also moves TELEGRAM_BOT_TOKEN. See the OpenClaw migration guide.

Related pages