Hermes-Skills/devops/clash-docker-workflow/references/hermes-telegram-proxy.md

Hermes Telegram Proxy Configuration

How to route Hermes Agent's Telegram gateway through a local proxy (Clash/Mihomo).

Why needed

Telegram API (api.telegram.org) is blocked in China. The Hermes gateway needs a proxy to connect.

How the Telegram Adapter Reads Proxy

The Telegram adapter reads proxy from environment variables at the network layer.

Source code:

• gateway/platforms/telegram_network.py → _resolve_proxy_url() → calls resolve_proxy_url("TELEGRAM_PROXY", ...) from gateway/platforms/base.py
• gateway/platforms/telegram.py line 2068 → same resolve_proxy_url() call

resolve_proxy_url() checks (in order):

1. TELEGRAM_PROXY env var (Telegram-specific, highest priority)
2. HTTPS_PROXY / HTTP_PROXY / ALL_PROXY env vars (and lowercase variants)
3. macOS system proxy auto-detection

Key: telegram.proxy_url in config.yaml IS bridged to TELEGRAM_PROXY env var by load_gateway_config() at startup. So both config.yaml and direct env vars work.

Configuration Options

Option A — telegram.proxy_url in config.yaml (simpler, recommended)

hermes config set telegram.proxy_url http://127.0.0.1:7890
hermes gateway restart

Verified working — load_gateway_config() reads telegram.proxy_url and sets TELEGRAM_PROXY env var.

Option B — System env vars in systemd service file

python3 -c "
import pathlib
p = pathlib.Path.home() / '.config/systemd/user/hermes-gateway.service'
lines = p.read_text().splitlines()
# Remove any existing proxy lines first
lines = [l for l in lines if 'HTTPS_PROXY' not in l and 'HTTP_PROXY' not in l]
out = []
for l in lines:
    out.append(l)
    # Insert after HERMES_HOME line
    if 'HERMES_HOME' in l and l.strip().startswith('Environment'):
        out.append('Environment=\"HTTPS_PROXY=http://127.0.0.1:7890\"')
        out.append('Environment=\"HTTP_PROXY=http://127.0.0.1:7890\"')
p.write_text('\n'.join(out) + '\n')
"

systemctl --user daemon-reload
hermes gateway restart

Or use the quick-fix script: bash ~/clash/fix-proxy.sh → option 6 → option 1.

Option C — Dual defense (recommended)

Set BOTH config.yaml bridge AND systemd env vars. This ensures proxy works whether the config bridge runs or not:

# 1. Config bridge
hermes config set telegram.proxy_url http://127.0.0.1:7890

# 2. Systemd env vars (see Option B above)

# 3. Restart
hermes gateway restart

Applying changes

hermes gateway restart
# ⚠️ Cannot restart from inside the gateway — instruct user to run from separate shell

Verification

# Check config
grep proxy_url ~/.hermes/config.yaml

# Check process env vars
PID=$(pgrep -f "hermes_cli.main gateway" | head -1)
tr '\0' '\n' < /proc/$PID/environ | grep -i proxy
# Expected: TELEGRAM_PROXY=http://127.0.0.1:7890 (from config bridge)
#           HTTPS_PROXY=http://127.0.0.1:7890 (from systemd, if set)

# Check logs
journalctl --user -u hermes-gateway -n 50 | grep -i telegram
# Good: "connected" state
# Bad: "connection failed" / "Timed out"

# Check gateway state
cat ~/.hermes/gateway_state.json | python3 -m json.tool | grep -A3 telegram

Supported proxy types

• HTTP proxy: http://127.0.0.1:7890
• SOCKS5 proxy: socks5://127.0.0.1:1080

Notes

• The proxy applies to both the main Telegram connection and the fallback IP transport.
• Mihomo/Clash mixed-port (7890) supports both HTTP and SOCKS5 on the same port.
• The bot token is configured separately under telegram.token in config.yaml.
• For full diagnostic checklist: skill_view(name="clash-docker-workflow", file_path="references/proxy-diagnostics.md")