Hermes Plugin

yoooclaw-hermes-plugin is the Python plugin boundary between Hermes Agent and YoooClaw. It ships two entry-point plugins:

• yoooclaw — the general Hermes plugin: tools, hooks, slash commands, CLI subcommands, skills.
• yoooclaw_app — the APP platform adapter: brings phone APP messages into Hermes, and forwards Hermes replies back to the APP.

Production plugin artifacts bundle the platform-specific yoooclaw executable — users don't need a preinstalled CLI, and the plugin doesn't download it on first run. The embedded executable is verified and installed into a plugin-managed path before use. Plugin 0.8.2 bundles CLI 0.8.2.

Daemonless plugin mode

In plugin mode no CLI daemon is started. The plugin process holds the profile's storage writer lock and writes notifications / recordings / images / captured web pages directly, while also owning the openclaw-service tunnel — the phone notification Relay and the APP conversation Relay are merged onto that one connection. The CLI's read-only commands (notification *, recording list/status/events, image *, synced-web-page *) work normally against the very same files; yoooclaw daemon start is refused while the plugin holds the lock, returning YOOOCLAW_DAEMON_DISABLED_BY_PLUGIN. Disabling the plugin releases the lock and returns you to standalone CLI mode with no data migration. See Usage & Lifecycle.

One-command install

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

Windows (PowerShell):

& ([scriptblock]::Create((irm https://artifact.yoooclaw.com/hermes-plugin/install.ps1))) --api-key ock_...

Re-run the same command to update (no --force needed — it runs pip install --upgrade). You can also have the plugin self-update from a conversation; see Updating & Upgrading. The PowerShell installer resolves the matching win_amd64 wheel, locates the Hermes Agent virtualenv under the standard Windows install locations, bootstraps pip with ensurepip when needed, and installs with pip install --upgrade.

Version requirement

The installer requires Hermes Agent >= 0.14.0. Older Hermes builds don't provide the plugin platform API (PluginContext.register_platform) the APP adapter depends on, so the installer stops with an upgrade message instead of leaving a half-enabled plugin behind.

What the installer does:

• writes the shared api-key to ~/.yoooclaw/credentials.json;
• removes stale API-key and legacy local APP authorization environment overrides from ~/.hermes/.env;
• ensures both yoooclaw and yoooclaw_app are present in plugins.enabled in ~/.hermes/config.yaml;
• installs the bundled yoooclaw/yc CLI artifact into ~/.yoooclaw/hermes-plugin/bin, maintains managed shims, and links those commands next to the detected hermes executable when that directory is writable;
• if a newer standalone CLI (0.9+) has already registered OS-level autostart, disables it before installing, so the CLI can't reclaim storage ownership after a login/reboot — if it can't be disabled (the installed CLI is too old to support daemon autostart), the takeover is refused outright;
• after restarting the gateway, runs a tiered activation check: package installed (PACKAGE_INSTALLED) → the current Hermes profile's plugins.enabled has it checked (PLUGIN_CONFIGURED) → the runtime actually holds the storage writer lock and the Relay connection (PLUGIN_ACTIVE). If any tier fails, the script now exits non-zero and prints Package installed, activation failed. (previously it always printed "installation complete" regardless of the outcome). In daemonless mode the lock must be held by the long-lived gateway process, so the installer can only verify it — a short-lived Python process would release the OS lock the moment it exits.

Common options:

Option / env var	Description
--enable-app / --no-enable-app	Deprecated no-ops: the yoooclaw_app adapter is now always enabled; these flags remain only so older command lines don't error out.
--version <VERSION> / --oss-channel <NAME>	Install a specific version / choose which version marker to read (defaults to latest). See Updating & Upgrading.
--hermes-profile <name> / HERMES_PROFILE	Pass this when Hermes runs a named profile (hermes --profile <name>), so the installer patches that profile's config.yaml and the gateway restart command carries --profile too; without it, the installer targets the global config used when no named profile is in play.
YOOOCLAW_HERMES_CLI_LINK_DIR	Choose a different CLI command link directory.
YOOOCLAW_HERMES_INSTALL_CLI=0	Skip shell command links.
--no-start-daemon	Skip the post-install activation check (legacy name; there is no daemon to start in daemonless mode).

Additional local-development options (--skip-install, --package, --version, --python, --no-restart, --no-start-daemon, and more) are available via the installer's --help. Stable releases are distributed via PyPI (see Manual install below).

Manual install

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

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 don't 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). 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.
• Embedded CLI: ships the target platform's yoooclaw executable in the plugin artifact and uses PATH lookup only as a local development fallback.
• APP transport: keeps a single hosted WebSocket family open in the plugin process — the openclaw-service*.yoooclaw.com tunnels (one per apiKey). They carry Hermes APP chat RPC frames and phone notification / recording / image relay frames on the same connection; the APP protocol layer claims its whitelisted frames first and everything else goes to the in-process local ingest.
• Direct local storage writes: notifications, recordings (transcripts / summaries pushed down by the App, optionally downloading ossUrl audio in the background), images, and captured web pages (delivered over Relay by a browser extension) are all persisted by the plugin process following the CLI's directory contract, with status events forwarded to the tunnel over an in-process event bus.
• Local relay server and browser chat UI for end-to-end APP conversation tests.

APP authentication

APP user authentication is enforced by the Relay service — the Hermes plugin no longer keeps a separate local APP user allowlist.

The APP adapter resolves its Relay key from ~/.yoooclaw/credentials.json by default — the same source the yoooclaw CLI reads, so the plugin and the CLI stay on the same key. Stale YOOOCLAW_APP_API_KEY / YOOOCLAW_API_KEY values in the Hermes environment are ignored and stripped by the installer.

APP chat rides the openclaw-service Relay tunnel, so the endpoint follows PHONE_NOTIFICATIONS_ENV / the active profile:

PHONE_NOTIFICATIONS_ENV	Relay host
production (default)	openclaw-service.yoooclaw.com
development / test	the corresponding internal staging host (internal use only)

Unset or unknown values fall back to the active profile's environment, then production. YOOOCLAW_OPENCLAW_RELAY_URL overrides the tunnel URL for local or staging verification; the retired YOOOCLAW_APP_RELAY_URL variable is dead and is stripped from .env by the installer.

Next steps

• Usage & Lifecycle — environment switching, the daemonless storage model, lifecycle, common commands.
• Debugging & Troubleshooting — log locations, lifecycle diagnostics, common failures.