@earzbook/openclaw

Sidecar daemon that bridges the Earzbook mobile app to a locally-running OpenClaw agent via a WebSocket relay.

Long-running Node process, installed once on the user's machine by the Earzbook pair flow. Registered as a per-user service (launchd LaunchAgent on macOS, systemd --user unit on Linux) so it auto-starts on login and survives crashes.

Install (user-facing — runs from the Earzbook pair script)

npm install -g @earzbook/openclaw

The Earzbook app's "Connect OpenClaw" flow prints a curl … | bash one-liner that runs the npm install above, writes ~/.earzbook/sidecar.json, drops the launchd plist / systemd unit, and starts the service. No manual setup required.

Usage

earzbook-openclaw --config ~/.earzbook/sidecar.json

Config file shape:

{
  "relayUrl": "wss://api.earzbook.app/openclaw/relay",
  "deviceToken": "<JWT issued by Earzbook backend at pair time>",
  "userId": "<Earzbook user id>",
  "agentId": "main",
  "versionEndpoint": "https://api.earzbook.app/openclaw/sidecar/version"
}

What it does

1. Opens a WebSocket to the Earzbook relay with role: "plugin" and authenticates with the deviceToken JWT.
2. On each inbound user_message, spawns openclaw agent --agent <agentId> --message <text> --json to get the local OpenClaw agent's reply.
3. Sends the reply back as an agent_reply frame.
4. Pings every 30s, reconnects with exponential backoff (3s → 5min cap), checks for updates on startup + every 24h.

See the architecture plan in /Users/earzbook/.claude/plans/users-earzbook-documents-github-recall-rippling-sphinx.md for the full design.

Why not the OpenClaw channel plugin?

We started with a channel plugin at ../earzbook-plugin/. OpenClaw 2026.5.22 doesn't import external channel plugin entry modules in its gateway daemon — the plugin's lifecycle.start and registerFull hooks only fire in CLI invocations. The plugin code stays in the repo for when OpenClaw fixes that, or when we fork them.

The sidecar lives alongside as a self-contained workaround. Same wire protocol as the plugin would have used.