yoooclaw-hermes-plugin 0.2.3

YoooClaw tools and APP messaging platform adapter for Hermes Agent

hermes-plugin

YoooClaw integration for Hermes Agent.

This repository is the Python plugin boundary between Hermes and YoooClaw. The existing @yoooclaw/cli daemon remains responsible for the shared data plane: phone notification ingest, recordings, images, Relay tunnels, credentials, light-rule storage, and one-shot light control. The Hermes plugin owns the APP conversation transport and the host-side light-rule trigger runtime.

Production plugin artifacts bundle the platform-specific yoooclaw executable itself. Users do not need a preinstalled CLI, and the plugin does not download the CLI on first run. The embedded executable is verified and installed into a plugin-managed path before use.

The release workflow downloads the four verified native assets from the pinned cli-v* release in YoooClaw/cli, then creates one Python wheel per platform. Each wheel carries only its own executable and a SHA-256 manifest:

darwin-arm64
darwin-x64
linux-arm64
linux-x64

The wheels and cli-wheel-index.json are attached to the matching YoooClaw/hermes-plugin GitHub Release. On release tags, CI also uploads the installer plus the same dist/ artifacts to OSS under ${OSS_PUBLIC_URL}/${OSS_PREFIX:-hermes-plugin} and updates latest / beta channel markers. This keeps the Git repository small while giving Hermes a package artifact that already contains the CLI.

One-command install

Install the plugin, store the YoooClaw API key, enable both Hermes plugins, and restart the gateway:

curl -fsSL https://artifact.yoooclaw.com/hermes-plugin/install.sh | bash -s -- --api-key "ock_..."

For APP chat, authorize the users that may talk to Hermes:

curl -fsSL https://artifact.yoooclaw.com/hermes-plugin/install.sh | bash -s -- \
  --api-key "ock_..." \
  --allowed-users "u_123,u_456"

Use --allow-all-users only for a trusted single-user account. The installer writes the shared key to ~/.yoooclaw/credentials.json, mirrors it into ~/.hermes/.env as YOOOCLAW_API_KEY / YOOOCLAW_APP_API_KEY, and ensures yoooclaw plus yoooclaw_app are present in plugins.enabled in ~/.hermes/config.yaml.

Run scripts/install.sh --help for local development options such as --skip-install, --package, --oss-base-url, --version, --python, and --no-restart. The source-tree installer defaults to PyPI; the installer uploaded by CI is rendered with the OSS base URL from .env / GitHub Secrets and installs the matching platform wheel directly from OSS.

Manual install

Stable plugin releases also publish the platform wheels to PyPI. Hermes discovers both entry-point plugins after a normal package install into the same Python environment Hermes uses:

pip install yoooclaw-hermes-plugin

Enabling pip-installed plugins on Hermes 0.15.1 (and earlier). The hermes plugins enable <name> / disable / list commands only recognize directory-based (~/.hermes/plugins/) and bundled plugins — they do not scan Python entry points, so hermes plugins enable yoooclaw fails with "Plugin 'yoooclaw' is not installed or bundled." The runtime loader does load entry-point plugins, but only when their names appear in the plugins.enabled allow-list. For a pip install, enable them by editing ~/.hermes/config.yaml directly:

plugins:
  enabled: [yoooclaw, yoooclaw_app]

Then restart the gateway (hermes gateway restart). If a future Hermes release teaches hermes plugins enable to recognize entry-point plugins, the CLI commands below will work as written. The one-command installer above applies this config-file enablement automatically.

Features

• General Hermes plugin: tools, hooks, slash commands, CLI subcommands, skills.
• yoooclaw_app platform adapter: APP messages into Hermes and Hermes replies back to the APP.
• Tool bridge: call yc --format json and the daemon localhost HTTP API.
• Embedded CLI: ship the target platform's yoooclaw executable in the plugin artifact and use PATH lookup only as a local development fallback.
• APP transport: connect the Hermes platform adapter directly to the existing APP conversation channel without routing messages through the CLI daemon.
• Local relay server and browser chat UI for end-to-end APP conversation tests.
• Notification watcher: use OS file notifications on the active CLI profile's notifications/ directory to feed newly persisted items into the host-side light-rule runtime without adding a daemon event API.

The tool plugin exposes notification, recording, image, Relay, light-control, light-rule CRUD, daemon status, and doctor tools. The APP platform adapter connects directly to Relay and translates the existing OpenClaw-compatible chat.send, chat.history, and chat.abort RPC frames into Hermes messages.

APP Authorization

APP chat fails closed. Configure an explicit user allowlist or opt into all users before enabling yoooclaw_app:

export YOOOCLAW_APP_ALLOWED_USERS="u_123,u_456"
# or, only for a trusted account:
export YOOOCLAW_APP_ALLOW_ALL_USERS=1

The APP adapter reuses YOOOCLAW_API_KEY or ~/.yoooclaw/credentials.json by default. Set YOOOCLAW_APP_API_KEY when the APP conversation connection should use a dedicated Relay key. YOOOCLAW_APP_RELAY_URL overrides the Relay URL for local or staging verification.

Switching environments

The base daemon's Relay endpoint is per yoooclaw profile (relay.url in each profile's config.json). Use env to switch the active profile and restart the daemon in one step — hermes gateway restart alone reconnects to the running daemon and would not pick up the new relay.url:

hermes yoooclaw env            # show the active environment + Relay status
hermes yoooclaw env test       # switch to the `test` profile and restart the daemon
hermes yoooclaw env default    # switch back to the `default` (prod) profile

/yoooclaw env <profile> does the same from a chat session. The switch stops the previous profile's daemon before starting the target's, so exactly one daemon runs; an unknown profile name fails without disturbing the running daemon. The Relay apiKey stays account-global (~/.yoooclaw/credentials.json); switch it with yoooclaw auth set-default-api-key <label> when an environment needs a different key.

Logging

The plugin uses an OpenClaw-style file logger in addition to Hermes' normal logging pipeline. Logs are written daily under:

~/.yoooclaw/plugins/yoooclaw-hermes/logs/YYYY-MM-DD.log

Set YOOOCLAW_HERMES_LOG_DIR to override the log directory. Stable releases redact common secrets, user text, user URLs, emails, phone numbers, bearer tokens, JWTs, and long hex tokens before writing files or passing records to Hermes' upstream logging handlers. Versions containing beta keep raw logs for debugging, matching the OpenClaw plugin behavior. Log files older than 30 days are pruned automatically; override with YOOOCLAW_HERMES_LOG_RETENTION_DAYS.

Search recent plugin logs through the Hermes plugin CLI:

hermes yoooclaw logs --keyword relay --from 2026-06-01 --to 2026-06-04 --limit 50

The Hermes-owned foreground daemon still writes its child-process stdout/stderr to ~/.yoooclaw/hermes-plugin/daemon-fg.log.

Local Relay And Web UI

For local end-to-end testing, run the Bun/Hono relay server instead of the production Relay, then start the Vite/React web UI:

bun install
bun run relay:dev
bun run web:dev

Configure Hermes to point the APP adapter at it:

export YOOOCLAW_APP_RELAY_URL="ws://127.0.0.1:8799/message/messages/ws/plugin"
export YOOOCLAW_APP_API_KEY="ock-local-dev"
export YOOOCLAW_APP_ALLOW_ALL_USERS=1
hermes gateway restart

Ensure yoooclaw_app is in the plugins.enabled list in ~/.hermes/config.yaml (see the install note above; for a linked development checkout under ~/.hermes/plugins/ you can instead run hermes plugins enable yoooclaw_app).

Open http://127.0.0.1:5173/ to chat through the browser UI. GET /healthz on http://127.0.0.1:8799 returns pluginConnected: true after the Hermes platform adapter connects.

The local relay keeps the current OpenClaw-compatible plugin path /message/messages/ws/plugin, and also exposes /app plus /v1/app/ws for browser-style clients. POST /v1/messages is available for simple scripted message injection. The web UI renders Hermes events, RPC responses, typing state, and app.message.update / hermes.message.update streaming frames in a structured event panel powered by Vercel Labs json-render (@json-render/core and @json-render/react).

Layout

yoooclaw_hermes/   # General Hermes plugin
yoooclaw_app/      # Hermes platform adapter for YoooClaw APP chat
apps/relay-server/ # Bun + Hono local Relay-compatible server
apps/web/          # Vite + React + Tailwind CSS web chat UI
tests/

Development

Install uv first, then:

uv sync --dev
uv run pytest
uv build

For local Hermes discovery, link the plugin directories into ~/.hermes/plugins/ and enable them:

ln -s "$PWD/yoooclaw_hermes" ~/.hermes/plugins/yoooclaw
ln -s "$PWD/yoooclaw_app" ~/.hermes/plugins/yoooclaw_app
hermes plugins enable yoooclaw
hermes plugins enable yoooclaw_app
hermes plugins list

References

• Build a Hermes Plugin
• Adding a Platform Adapter