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.10.0 bundles CLI 0.11.0-beta.0.

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: read-only queries, light control and cloud todos call the embedded CLI via yc --format json (todos pass arguments as JSON on stdin).
• 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.
• Cloud todos: five native ai_todo_* tools manage the todos in the app (new in 0.10.0).
• Voice input (dictation) history: voice_* tools query dictation history saved on this machine (new in 0.10.0).
• 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.