Initial commit: Hermes Agent skills collection

- Trading skills (OKX, dividend, lottery, quantitative) - Creative skills (ASCII art, diagrams, video) - Development skills (GitHub, debugging, TDD) - Research skills (arXiv, blog monitoring) - Productivity skills (email, documents, notes) - MCP integration skills - Custom user skills
2026-07-05 02:31:15 -04:00
commit 6770bc9b9d
908 changed files with 239614 additions and 0 deletions
@@ -0,0 +1,107 @@
+# 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")`