wishee-hermes-connector

Connect a Hermes agent to the Wishee bridge (openclaw-bridge) over a reverse WebSocket — the Hermes counterpart of @wishee-ai/openclaw-connector. The bridge drives the agent (chat.send / chat.history / sessions.reset) and receives its replies (task-result).

Requires no changes to the bridge or to hermes-agent core.

Requires Hermes >= 0.14.0. The connector checks this in register() and refuses to load below it — Hermes surfaces the error in the gateway log and in hermes plugins list. See version_gate.py for how that floor was derived (the binding constraint is PlatformEntry.is_connected, 2026-04-20).

How it works

The connector is a Hermes platform adapter (runs inside the hermes gateway process). It dials the bridge, does the hello/welcome handshake, then:

• chat.send → mints a runId, answers immediately, runs the agent turn, and emits a task-result event when the turn finishes (the bridge's device-push path).
• chat.history / sessions.reset → reads / clears the Hermes session store.

From the bridge's perspective a Hermes agent is indistinguishable from an OpenClaw instance: same /api/bind, same hello, same RPCs, same event frames.

Activity (usage duration)

The connector installs a Hermes hook at ~/.hermes/hooks/wishee-activity/ that listens for agent:start / agent:end — the two events that bracket one _run_agent call, i.e. the real boundary of a turn, for every platform. So turns the user starts locally count too, not just the ones the bridge dispatches.

The hook handler only appends one self-contained interval per finished run to a local journal (~/.hermes/wishee-connector/wishee-activity-YYYYMMDD.jsonl); it never imports the connector, touches the network, or starts a timer. The connector reads that journal by byte watermark and ships batches as agent-activity frames, advancing the watermark only after a successful send — the journal is what makes this survive a disconnect or a restart (unlike an in-memory queue).

On first run it also seeds the journal once from state.db, deriving past turns from message timestamps, so history predating the hook isn't lost.

The hook is picked up by discover_and_load() at gateway startup, so a freshly installed hook takes effect on the next gateway restart.

The transport auto-reconnects: an unexpected socket close (bridge restart, network drop) re-dials with capped exponential backoff and re-runs the hello/welcome handshake. A deliberate shutdown never reconnects.

Install

pip install wishee-hermes-connector   # into your Hermes environment

Enable

1. Add wishee to plugins.enabled in your Hermes config.yaml (entry-point plugins are opt-in).
2. Optionally set WISHEE_BRIDGE_URL to override the default (wss://ai-bridge.wishee.com.cn/ws).
3. Run hermes gateway. On first run it prints a QR code — scan it to bind this instance to the bridge (via the bridge's /api/bind). Identity is stored at ~/.hermes/wishee-connector/binding.json.

Scope

v1 emits task-result on each completed turn (the bridge's device-push path). Live streaming (agent progress events) is out of scope for v1.

Development

uv venv --python 3.13 .venv
uv pip install --python .venv/bin/python -e /path/to/hermes-agent
uv pip install --python .venv/bin/python -e ".[dev]"
.venv/bin/python -m pytest -q