yoooclaw-hermes-plugin 0.3.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 pipeline 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 build job emits the wheels, cli-wheel-index.json, and SHA256SUMS once, then promotes that exact dist/ bundle through the release flow: test OSS first, production OSS after approval, and finally PyPI / GitHub Release for stable versions. Installers and channel markers remain environment-specific and are regenerated at deploy time. This keeps the Git repository small while guaranteeing that QA verifies the same bytes we later ship.

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.

Release flow

This repository now uses artifact promotion instead of rebuilding at each environment boundary:

1. Push to release/** runs test-oss.yml and uploads a cache-busted build to the test OSS bucket. A second upload refreshes the stable test update channel without replacing the unique install URL. Pure pyproject.toml version bumps are ignored so a release commit does not double-publish.
2. Push tag v* runs release.yml: build creates the wheels once, writes SHA256SUMS, and stores the bundle as a GitHub Actions artifact. deploy-test promotes that bundle to the stable test OSS prefix and sends an "RC pending manual promotion" notification with the exact version number to pass into the next step.
3. After QA signs off, run promote-prod.yml manually (workflow_dispatch) from GitHub Actions. It auto-discovers the successful release.yml run for v{version}, downloads that exact artifact, re-verifies SHA256SUMS, then promotes it to production OSS. Stable releases continue on to PyPI through the existing pypi environment and then publish the GitHub Release.
4. rollback.yml is a manual workflow_dispatch rollback. It repoints the latest or beta marker to a previous version and restores the archived installer from v{version}/installer/install.sh when that archive exists.

Repository settings still matter:

• test / production environment secrets hold the OSS credentials used by the deploy and rollback workflows; OPENCLAW_RELEASE_TOKEN stays build-only.
• The manual approval fallback is the promote-prod.yml dispatch itself, so it works even when private-repository required reviewers are unavailable on the current GitHub plan.
• The pypi environment remains the OIDC boundary for trusted publishing.

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, chat.abort, and sessions.* RPC frames into Hermes messages and APP-owned session state.

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 resolves its Relay key from ~/.yoooclaw/credentials.json by default — the same source the yoooclaw cli / base daemon reads, so the plugin and the cli stay on the same key. Set YOOOCLAW_APP_API_KEY to override it with a dedicated key for local or staging verification; YOOOCLAW_API_KEY is only a fallback used when credentials.json is absent. YOOOCLAW_APP_RELAY_URL overrides the Relay URL for local or staging verification.

The APP Relay endpoint follows PHONE_NOTIFICATIONS_ENV, matching the CLI's environment switch:

PHONE_NOTIFICATIONS_ENV	Relay host
development	broker-test.yoooclaw.com
test	broker-test.yoooclaw.com
production (default)	broker.yoooclaw.com

development and test share broker-test for now. Unset or unknown values fall back to production. YOOOCLAW_APP_RELAY_URL still wins over the env-based selection when set.

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 the running daemon's already-loaded Relay tunnel 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 yc env test             # equivalent short alias
hermes yoooclaw env default    # switch back to the `default` (prod) profile

/yoooclaw env <profile> and /yc env <profile> do the same from a chat session. Built-in default, test, and development profiles are initialized on first use with the matching Relay endpoint. 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.

On each Hermes gateway startup the plugin asks the running CLI daemon to reconnect its Relay tunnel (yoooclaw tunnel reconnect) so stale Relay-side plugin sockets are replaced. Set YOOOCLAW_HERMES_RECONNECT_RELAY_ON_START=0 to disable this startup reconnect.

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