hermes-gateway-troubleshooting

What problem does it solve?

This Skill provides a systematic checklist and remediation steps to diagnose and fix Hermes gateway issues such as scoped lock conflicts, stale PIDs, Telegram 401 polling errors caused by token collisions, configuration overrides, and multi-instance gateway coexistence problems.

Core Features & Use Cases

• Lock conflict diagnosis: Identify stale or conflicting gateway lock files and determine which processes hold them.
• Environment and systemd resolution: Detect and remove TELEGRAM_BOT_TOKEN overrides coming from systemd Environment entries or agent env files.
• Safe recovery actions: Guidance to stop conflicting gateways, remove stale state and lock files, verify unique tokens per agent, and restart systemd-managed gateways to restore normal polling.
• Use Case: Recover a production Hermes deployment where multiple agent instances accidentally share a Telegram token and cause polling failures and messaging spam.

Quick Start

Use the hermes-gateway-troubleshooting skill to detect which agent holds the Telegram lock, remove stale lock files and environment overrides, and restart the correct systemd-managed gateway to restore service.