# 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)

```bash
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

```bash
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:

```bash
# 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
```bash
hermes gateway restart
# ⚠️ Cannot restart from inside the gateway — instruct user to run from separate shell
```

## Verification
```bash
# 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")`