원클릭으로
hermes-gateway-troubleshooting
Diagnose and fix Hermes messaging gateway connectivity issues (Telegram/Discord down, stale locks, PM2 problems)
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
메뉴
Diagnose and fix Hermes messaging gateway connectivity issues (Telegram/Discord down, stale locks, PM2 problems)
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Backup Hermes agent to GitHub and restore on a new VPS. Covers what to include/exclude, GitHub token requirements, and restore steps. Includes automated scripts.
GitHub auth setup: HTTPS tokens, SSH keys, gh CLI login.
Clone, create, fork, configure, and manage GitHub repositories. Manage remotes, secrets, releases, and workflows. Works with gh CLI or falls back to git + GitHub REST API via curl.
Fetch YouTube video transcripts and transform them into structured content (chapters, summaries, threads, blog posts). Use when the user shares a YouTube URL or video link, asks to summarize a video, requests a transcript, or wants to extract and reformat content from any YouTube video.
Manage Linear issues, projects, and teams via the GraphQL API. Create, update, search, and organize issues. Uses API key auth (no OAuth needed). All operations via curl — no dependencies.
Give Hermes phone capabilities without core tool changes. Provision and persist a Twilio number, send and receive SMS/MMS, make direct calls, and place AI-driven outbound calls through Bland.ai or Vapi.
| name | hermes-gateway-troubleshooting |
| description | Diagnose and fix Hermes messaging gateway connectivity issues (Telegram/Discord down, stale locks, PM2 problems) |
| triggers | ["telegram gateway not working","discord gateway not working","hermes gateway down","Another local Hermes gateway is already using","gateway connection error","pm2 gateway stopped","telegram bot token lock","hermes gateway locked"] |
Common connectivity issues and solutions for Hermes messaging gateway.
Check gateway status:
~/.hermes/node/bin/pm2 status
View recent logs:
~/.hermes/node/bin/pm2 logs hermes-gateway --lines 50
tail -50 /root/.pm2/logs/hermes-gateway-error-0.log
tail -50 /root/.pm2/logs/hermes-gateway-out-0.log
Symptoms:
ERROR gateway.platforms.telegram: [Telegram] Another local Hermes gateway is already using this Telegram bot token (PID XXXXX)Root Cause:
Stale lock files in ~/.local/state/hermes/gateway-locks/ from a dead process that didn't clean up.
Solution:
~/.hermes/node/bin/pm2 stop hermes-gateway
# Check what lock files exist
ls -la ~/.local/state/hermes/gateway-locks/
# Remove Telegram lock
rm -f ~/.local/state/hermes/gateway-locks/telegram-bot-token-*.lock
# Remove all locks if needed (nuclear option)
rm -f ~/.local/state/hermes/gateway-locks/*.lock
~/.hermes/node/bin/pm2 start hermes-gateway
~/.hermes/node/bin/pm2 save
~/.hermes/node/bin/pm2 status
sleep 3 && tail -20 /root/.pm2/logs/hermes-gateway-error-0.log
Look for: Telegram fallback IPs active (normal warning) without ERROR lines.
Solution:
~/.hermes/node/bin/pm2 start hermes-gateway
~/.hermes/node/bin/pm2 save
Check for fatal errors in logs, common causes:
# Check last errors
tail -100 /root/.pm2/logs/hermes-gateway-error-0.log | grep -E "(ERROR|FATAL)"
# Full restart with cleanup
~/.hermes/node/bin/pm2 delete hermes-gateway
~/.hermes/node/bin/pm2 start ~/.hermes/hermes-agent/gateway/ecosystem.config.js
~/.hermes/node/bin/pm2 save
Symptoms:
pm2 status shows "online" but Telegram/Discord not respondingDiagnosis:
# Compare current time vs last log entry
date '+%H:%M'
tail -1 /root/.pm2/logs/hermes-gateway-error-0.log | grep -oE '[0-9]{2}:[0-9]{2}'
# Check for stale lock files even if process seems running
cat ~/.local/state/hermes/gateway-locks/*.lock | grep pid
# Count actual gateway processes (should be 1)
ps aux | grep -E "hermes.*gateway" | grep -v grep | wc -l
Solution:
# Stop PM2-managed gateway
~/.hermes/node/bin/pm2 stop hermes-gateway
# Kill ALL orphaned gateway processes by pattern
pkill -f "hermes.*gateway"
# Remove ALL lock files
rm -f ~/.local/state/hermes/gateway-locks/*.lock
# Verify no processes remain
ps aux | grep -E "hermes.*gateway" | grep -v grep
# Restart clean
~/.hermes/node/bin/pm2 start hermes-gateway
~/.hermes/node/bin/pm2 save
# Verify single process
ps aux | grep -E "hermes.*gateway" | grep -v grep | wc -l # Should show: 1
Symptoms:
ps auxRoot Cause: Manually targeting specific PIDs can leave other gateway instances running. The gateway auto-restarts on failure, creating new processes. Discord token can be held by orphaned processes.
Solution:
# Don't target specific PIDs - kill ALL by pattern
pkill -f "hermes.*gateway"
# Or use stronger sigkill if needed
pkill -9 -f "hermes.*gateway"
# Remove locks and restart
rm -f ~/.local/state/hermes/gateway-locks/*.lock
~/.hermes/node/bin/pm2 restart hermes-gateway
Key Lesson: Always use pattern-based killing (pkill -f) rather than targeting specific PIDs that may have been restarted/replaced. For Discord token conflicts specifically:
ps aux | grep -E "hermes.*gateway.*discord"systemctl stop hermes-gateway firstSymptoms:
tail -20 /root/.pm2/logs/hermes-gateway-error-0.log shows old logs, nothing recentpm2 status shows online but Telegram/Discord not respondingRoot Cause: PM2 may write to different log files:
hermes-gateway-error-0.log (numbered, from older PM2 instance)hermes-gateway-error.log (current, non-numbered)This happens when PM2 process is deleted and recreated with same name.
Solution:
# List ALL log files to see which is actually being written
ls -lah ~/.pm2/logs/hermes-gateway*
# Check the most recently modified file
ls -lt ~/.pm2/logs/hermes-gateway*.log | head -5
# Or check both
for f in ~/.pm2/logs/hermes-gateway-error*.log; do
echo "=== $f ==="
tail -5 "$f"
done
Key Lesson: When troubleshooting, always verify you're reading the active log file by checking modification timestamps.
Symptoms:
pm2 status shows status "errored" immediately after startModuleNotFoundError: No module named 'hermes_cli'Root Cause:
Started PM2 with direct path to hermes binary: pm2 start /root/.local/bin/hermes -- hermes gateway run. This bypasses the Python virtualenv that contains hermes_cli dependencies.
Solution:
~/.hermes/node/bin/pm2 delete hermes-gateway
~/.hermes/gateway-both.sh):#!/bin/bash
export HOME=/root
export HERMES_HOME="/root/.hermes"
export PATH="$HERMES_HOME/node/bin:$HOME/.local/bin:${PATH}"
# CRITICAL: Load virtualenv BEFORE calling hermes
source "$HERMES_HOME/hermes-agent/venv/bin/activate"
# Load environment
if [ -f "$HERMES_HOME/.env" ]; then
set -a
source "$HERMES_HOME/.env"
set +a
fi
# Run gateway
exec "$HOME/.local/bin/hermes" gateway run
chmod +x ~/.hermes/gateway-both.sh
~/.hermes/node/bin/pm2 start ~/.hermes/gateway-both.sh --name hermes-gateway
~/.hermes/node/bin/pm2 save
Key Lesson: Never start hermes directly in PM2 — always use a bash wrapper that activates the virtualenv first.
After restart, check if platforms connected:
# Should show "Telegram fallback IPs active" for Telegram
grep -E "(telegram|discord)" /root/.pm2/logs/hermes-gateway-error-0.log | tail -10
Symptoms:
last_status: ok but user never receives messages on Discordjournalctl -u hermes-gateway.service shows: ERROR cron.scheduler: Job 'xxx': delivery error: Discord API error (404): {"message": "Unknown Channel", "code": 10003}Root Cause:
The DISCORD_HOME_CHANNEL ID in ~/.hermes/config.yaml points to a channel that doesn't exist or the bot doesn't have access to. This happens when channels are deleted, IDs change, or the bot was removed from the channel.
Solution:
Get the correct channel ID:
Update the config:
grep DISCORD_HOME_CHANNEL ~/.hermes/config.yaml
pkill -9 -f hermes_gateway
sleep 3
systemctl start hermes-gateway.service
journalctl -u hermes-gateway.service --since "1 minute ago" | grep -i delivery
Key Lesson: Always verify Discord channel IDs periodically. When setting up cron delivery to Discord, test immediately after creation.
Symptoms:
systemctl status hermes-gateway.service shows failed (Result: exit-code) or Status 200/CHDIRRoot Cause:
The systemd service was configured with User=hermes and Group=hermes, but the hermes-agent directory (/root/.hermes/hermes-agent/) and config files are owned by root with restrictive permissions (700/600). The hermes user cannot access WorkingDirectory or read the config.
Solution:
cat /etc/systemd/system/hermes-gateway.service
ls -la /root/.hermes/
ls -la /root/.hermes/config.yaml
su -c "cd /root/.hermes/hermes-agent && pwd" hermes # Should fail with "Permission denied" if this is the issue
# Edit the service file, change these lines:
# User=root
# Group=root
# Remove all Environment= lines that override HOME/USER/PATH
# OR (alternative) fix permissions:
chown -R hermes:hermes /root/.hermes/
chmod -R 755 /root/.hermes/hermes-agent/
[Unit]
Description=Hermes Agent Gateway
After=network-online.target
[Service]
Type=simple
User=root
Group=root
ExecStart=/root/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main gateway run --replace
WorkingDirectory=/root/.hermes/hermes-agent
Restart=on-failure
RestartSec=30
[Install]
WantedBy=multi-user.target
pkill -9 -f hermes_gateway
sleep 3
systemctl daemon-reload
systemctl start hermes-gateway.service
sleep 3
systemctl status hermes-gateway.service
ps aux | grep hermes_cli | grep -v grep
# Should show "active (running)" and a running python process
journalctl -u hermes-gateway.service --since "1 minute ago" | tail -20
Key Lesson: When gateway runs via systemd (not PM2), the User/Group in the service unit MUST match file ownership. On a personal VPS, running as root avoids all permission headaches.
Symptoms:
Root Cause:
This is expected behavior — the gateway has DISCORD_REQUIRE_MENTION=true by default.
Key environment variables (all checked in gateway/platforms/discord.py:592-603,2041-2052):
DISCORD_REQUIRE_MENTION (default: true) — If true, bot only responds to @mentions in server channels unless channel is in free-response list or session is in a bot-initiated thread.DISCORD_FREE_RESPONSE_CHANNELS — Comma-separated channel IDs where bot responds without mention.DISCORD_IGNORE_NO_MENTION (default: true) — If message @mentions other users but NOT the bot, stay silent. Set to false to ignore this check.Solution — Read all messages without mention:
Set in ~/.hermes/config.yaml (under discord:):
discord:
require_mention: false
Or in .env:
DISCORD_REQUIRE_MENTION=false
Restart gateway after change.
⚠️ Warning: With require_mention: false, the bot will attempt to process ALL your messages in ALL channels. Avoid in shared servers with multiple users.
Lock files prevent multiple gateways from polling the same Telegram bot (which would cause conflicts):
~/.local/state/hermes/gateway-locks/{scope}-{hash}.lock (e.g., telegram-bot-token-caad7d40317c2c76.lock)ps aux | grep {pid} shows nothing)Use --replace flag when manually restarting gateway to auto-clean locks:
hermes gateway run --replace
Note: PM2-managed gateway should auto-restart on crashes, but may leave stale locks if killed with SIGKILL or on system hard reboot.