Hermes Proxy — AI 代理管理插件 / AI Proxy Manager for Hermes

A beautiful, self-contained proxy manager plugin for the Hermes Agent desktop app. It runs an independent mihomo core (bundled as mihomo.exe inside the plugin data dir — no Clash Verge needed), fetches your subscription, and gives you a full visual panel: node switching, latency/speed tests, traffic graphs, IP info, network mode switching (port / system proxy / TUN), subscription management, and a smart node picker that actually probes AI APIs instead of just measuring ping.

为 Hermes 桌面端开发的可视化代理管理插件：独立运行 mihomo 内核（内嵌 mihomo.exe，无需安装 Clash Verge）， 面板内置节点切换、测速、流量图、IP 信息、网络模式、订阅管理，以及实测 AI API 连通性的智能节点推荐。

---

Features

Feature	Description
🧭 Node management	Grouped by country with colored region badges (JP/SG/US…), one-click switch, per-node & batch latency test
⚡ Smart node picker	Probes opencode.ai + Google per node (real HTTP status, not just ping) — finds nodes whose IP actually works, scoring top candidates
📊 Speed test	Cloudflare-based download/upload (curl, bypasses WAF) + latency + connectivity to AI APIs & blocked sites, each testable independently
📈 Live traffic graph	Real-time up/down curve + persistent daily/session traffic stats
🌍 IP info	Local IP vs proxy exit IP + geo location
🖧 Network modes	Port-only / System proxy / TUN (persistent core — closing Hermes won't kill your network)
📡 Subscription manager	Remaining quota / reset / expiry parsing, multi-subscription add/switch/remove
🔌 Route Hermes via proxy	One-click toggle writes HTTPS_PROXY to registry and the current process — takes effect immediately, no restart (refused unless the core is actually running)
🛡 Self-healing	On startup, if the system proxy or a leftover HTTPS_PROXY env var points at a dead core, Hermes Proxy auto-clears it so you're never left offline

Requirements

• Windows 10/11
• Hermes Agent desktop app (v0.20+)
• No Clash Verge required — the mihomo core is self-contained (see Embedded core below)
• A Clash/Mihomo subscription URL (added in the panel)
• python with yaml, psutil (fastapi/uvicorn ship with the Hermes dashboard)

Install

git clone https://github.com/TurkeyGuoba/hermes-proxy
cd hermes-proxy
install.bat

Or manually copy:

• plugin/plugin.js → <hermes-home>/desktop-plugins/hermes-proxy/plugin.js
• dashboard/* → <hermes-home>/plugins/hermes-proxy/dashboard/
• hermes-home is %LOCALAPPDATA%\hermes on Windows (or ~/.hermes)

Then restart the Hermes desktop app. Open the panel with Ctrl+Alt+P (rebindable in Settings → Keybinds), or search "Hermes Proxy" in the ⌘K palette.

First run

1. Open Hermes Proxy → 订阅信息 → paste your subscription URL → 添加
2. Make sure the embedded core is in place (see below), then click 启动 — the core starts, fetches the subscription, and shows nodes
3. Optionally flip Hermes 走代理 to route all Hermes API calls through the proxy (immediate, no restart)

Embedded mihomo core

The plugin expects its own mihomo.exe at <plugin-data>/mihomo.exe — on Windows that's %LOCALAPPDATA%\hermes\proxy\mihomo.exe (overridable via the HERMES_MIHOMO_EXE env var).

Get the core (one-time):

:: Option A — latest stable from the official repo
curl -L -o mihomo.zip ^
  https://github.com/MetaCubeX/mihomo/releases/download/v1.19.30/mihomo-windows-amd64-compatible-v1.19.30.zip
tar -xf mihomo.zip
move mihomo-windows-amd64-compatible.exe "%LOCALAPPDATA%\hermes\proxy\mihomo.exe"

:: Option B — if you already have Clash Verge installed, you can point HERMES_MIHOMO_EXE
:: at its core instead of downloading:
::   setx HERMES_MIHOMO_EXE "C:\Program Files\Clash Verge\verge-mihomo.exe"

The core is launched with mihomo.exe -d <data-dir> -f config.yaml. Geodata (Country.mmdb / geoip.dat / geosite.dat) lives in the same data dir; if missing, copy them from a Clash Verge install, or download the latest files from the mihomo release assets.

How it works

┌──────────────────────────── Hermes desktop ────────────────────────────┐
│  plugin.js (UI panel)  ──ctx.rest──▶  plugin_api.py (backend router)   │
│      │                                    │                            │
│      │ fetch (mihomo REST API)            ▼ proxy_core.py              │
│      └──────────────────────▶ 127.0.0.1:9096 ◀── manages ── mihomo.exe │
│                                 (external controller)      (core, port 7896)
└─────────────────────────────────────────────────────────────────────────┘

• The plugin spawns its own detached mihomo core on port 7896 (controller 9096) — fully independent of any other proxy client.
• Geodata (Country.mmdb / geoip.dat / geosite.dat) lives in the plugin data dir so the core runs offline-capable.
• All plugin API calls use GET + query params to stay compatible with the Electron bridge.

Development

hermes-proxy/
├── plugin/plugin.js        # Desktop UI (i18n zh/en, zero-build ESM)
├── dashboard/plugin_api.py # FastAPI router mounted at /api/plugins/hermes-proxy/
├── dashboard/proxy_core.py # Core logic: subscription, mihomo lifecycle, probes, stats
└── dashboard/manifest.json # Plugin manifest (api: plugin_api.py)

License

MIT

Changelog

2026-08-17 - Embedded core, no Clash Verge dependency (v1.1.0)

• Core is now self-contained: the default core path is <data-dir>/mihomo.exe instead of borrowing C:\Program Files\Clash Verge\verge-mihomo.exe. The plugin no longer requires Clash Verge to be installed at all — a uninstalled/cleaned Clash Verge used to silently kill the proxy ("内核不存在").
• Added Embedded mihomo core section to the README with download instructions (official MetaCubeX mihomo release) and the HERMES_MIHOMO_EXE override.
• Geodata note updated: files live in the plugin data dir, independent from any Clash Verge install.

2026-08-16 - Crash fix and self-heal hardening (v1.0.1)

• Fixed fatal plugin load crash: plugin.js called tr() inside the STR translation literal before let T was initialized (JS temporal dead zone), killing the whole plugin UI. Strings are now hardcoded; a comment warns against regressions.
• Fixed offline incident root cause: a leftover HTTPS_PROXY=127.0.0.1:7896 registry value (persisted by the "Route Hermes via proxy" toggle) broke all Hermes model requests with ECONNREFUSED when the core was dead. Startup self-heal now also clears the env var (it previously only disabled the Windows system proxy).
• Safety valve: enabling "Route Hermes via proxy" is now refused unless the mihomo core is actually running, so a dead-end proxy can never be created.
• Self-heal only touches values pointing at this plugin own port (7896); Clash Verge system proxy settings (7897) are left untouched.