yoooclaw

English

简体中文

English

简体中文

Appearance

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.

The shared notification / recording / image / credential / light-rule data plane is still owned by the @yoooclaw/cli daemon; the Hermes plugin runs and manages that daemon as a localhost sidecar, and owns two external WebSocket transports on its own: the phone notification Relay (openclaw-service) and the APP conversation Relay, now merged onto the same tunnel.

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.

One-command install ​

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

Windows (PowerShell):

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

Re-run the same command to update. 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;
  • after restarting the gateway, ensures the YoooClaw daemon is running.

Common options:

Option / env varDescription
--no-enable-app / YOOOCLAW_HERMES_ENABLE_APP=0Install the tools plugin only, without enabling the APP adapter.
YOOOCLAW_HERMES_CLI_LINK_DIRChoose a different CLI command link directory.
YOOOCLAW_HERMES_INSTALL_CLI=0Skip shell command links.
--no-start-daemon / YOOOCLAW_HERMES_START_DAEMON=0Skip auto-starting the daemon after install.

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:

bash
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:

yaml
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 and the daemon localhost HTTP API.
  • 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 is bridged into the local CLI sidecar.
  • Local relay server and browser chat UI for end-to-end APP conversation tests.
  • Notification watcher: uses 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.

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 / base daemon 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_ENVRelay host
production (default)openclaw-service.yoooclaw.com
development / testthe 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 ​