Usage & Lifecycle

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 managed daemon/websocket service group in one step:

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. The 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), independent of profile. Switch it with:

yoooclaw auth set-default-api-key <label>

CLI profiles use openclaw-service*.yoooclaw.com for the Relay tunnel; APP chat shares the same connection. The installer repairs stale legacy URLs if an old plugin version persisted them into CLI profiles.

Lifecycle management

Hermes manages the YoooClaw CLI daemon plus the openclaw-service Relay tunnels as one service group. The CLI daemon runs as a local sidecar in --ingress proxied mode, so it exposes ingest APIs without opening its own Relay tunnel. The plugin owns the openclaw-service*.yoooclaw.com tunnel (one tunnel per apiKey), carrying Hermes APP chat / session RPC, phone notifications, recordings, images, and daemon egress events.

On startup the plugin computes a lifecycle generation from the plugin version, embedded CLI binary, active profile, Relay environment, openclaw-service URL, API-key fingerprint, proxied ingress mode, and the local egress callback. If a daemon is already running but does not advertise the same owner=hermes-plugin generation and ingressMode=proxied contract, the plugin stops it, starts the current embedded CLI daemon, waits for readiness, and then connects the openclaw-service tunnels. On shutdown it disconnects the tunnels first and then stops the owned daemon.

In proxied mode, openclaw-service Relay frames are forwarded to the daemon's localhost ingest/gateway endpoints with the same internal relay marker header the CLI dispatcher used (to distinguish internally-forwarded traffic from external direct connections) plus the api-key label. Daemon egress events such as recording.status POST back to a token-protected 127.0.0.1 callback owned by the plugin, then the plugin broadcasts them over the openclaw-service Relay websocket.

Use the lifecycle diagnostics when debugging upgrade or connection problems:

hermes yoooclaw lifecycle status
hermes yoooclaw lifecycle restart
hermes yc lifecycle status

The APP adapter also runs a watchdog while connected. If the daemon disappears or its generation changes, the adapter restarts the whole service group. If the Relay websocket remains disconnected past YOOOCLAW_HERMES_WS_RESTART_AFTER (default 30 seconds), it also restarts the group. Set YOOOCLAW_HERMES_LIFECYCLE_WATCH_INTERVAL to tune the watchdog interval (default 5 seconds). Failed recoveries use exponential backoff capped by YOOOCLAW_HERMES_LIFECYCLE_MAX_BACKOFF (default 60 seconds). If a Relay connection still fails, the watchdog restores the local daemon independently and keeps retrying the remote connections, so a transient network outage cannot leave the daemon stopped.

Surface area

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.

Common lifecycle-related environment variables

Most setups never need to touch these — they matter when you're adjusting timeouts, disabling an automatic behavior, or doing local development:

Variable	Default	Effect
YOOOCLAW_HERMES_AUTO_START_DAEMON	on	Set to 0 to disable auto-starting the daemon on session start.
YOOOCLAW_HERMES_RECONNECT_RELAY_ON_START	on	Set to 0 to disable auto-reconnecting Relay when the supervisor starts.
YOOOCLAW_HERMES_WS_RESTART_AFTER	30 (seconds)	How long the Relay websocket must stay disconnected before the whole group restarts.
YOOOCLAW_HERMES_LIFECYCLE_WATCH_INTERVAL	5 (seconds)	Watchdog poll interval.
YOOOCLAW_HERMES_LIFECYCLE_MAX_BACKOFF	60 (seconds)	Cap on exponential backoff after failed recoveries.
YOOOCLAW_HERMES_LIFECYCLE_MISMATCH_STREAK	2	How many consecutive mismatch readings are required before a restart (avoids over-reacting to probe noise).
YOOOCLAW_CLI_PATH	unset	Explicitly points at a CLI binary, entirely bypassing the embedded CLI's PATH injection — only meant for local development against a non-embedded CLI build.
YOOOCLAW_HERMES_INSTALL_CLI	on	Set to 0 to disable PATH injection (shim install) at plugin load.
YOOOCLAW_HERMES_INSTALL_SKILLS	on	Set to 0 to disable the bundled-skills copy step.

Next steps

• Debugging & Troubleshooting — log locations, common failures.
• Standalone CLI — the daemon that the Hermes plugin manages internally is this same CLI.