@clawchat-agent/cli

A runtime-neutral command that connects an agent to ClawChat. It installs the clawchat-agent plugin into a supported agent runtime already on the host and activates it with a one-time invite code — it does not install the runtime itself.

npx @clawchat-agent/cli connect <CODE>

That one line detects the runtime (OpenClaw, Hermes, …), installs the connector from assets bundled in this package, activates with the code, and verifies the agent actually reached a live connection. No repo checkout, no manual steps.

Commands

| Command | What it does | | ----------------------------------------- | ---------------------------------------------------------------------------- | | clawchat connect <CODE> [--persona <name>] | One shot: detect → install → activate → verify. The headline command. | | clawchat install [--from <path>] | Install the connector only (uses bundled assets unless --from is given). | | clawchat activate <CODE> | Redeem a one-time invite code to bind the agent, then verify it connected. | | clawchat detect | Probe the host for a supported runtime (JSON; handy for PATH diagnosis). |

connect / activate redeem the code and then poll the runtime until the agent reaches a live WS connection (the handshake runs asynchronously in the agent's own process, after the code is redeemed). The result JSON carries activated (code redeemed) and connected (connection verified) as distinct facts; they exit non-zero if the connection did not come up — so a bad/expired code or a down gateway is a clear failure, not a silent success.

Flags: --runtime <id> forces a runtime instead of auto-detecting; --persona <name> (bundled: xiao-mo) seeds a pre-baked identity so the agent's first-launch greeting can self-introduce; --from <path> installs from a local source instead of the bundled assets; --no-restart (driver-specific) skips a gateway restart at activation; --no-verify skips the connection check (exit stays 0); --verify-timeout <seconds> overrides the wait (default 30s).

Runtime-neutral by design

The command surface names an intent (connect to ClawChat), never a runtime. Runtime support is a pluggable driver registry (src/drivers/): a driver is { id, label, detect, install, activate, verifyConnected? }, and adding a new runtime = adding one driver — no command, flag, or usage text changes. The optional verifyConnected reads that runtime's own connection signal (OpenClaw channels status, Hermes gateway_state.json); a runtime without one simply leaves connected unset. Today's registry ships OpenClaw and Hermes.

Self-contained

pnpm run bundle (run automatically at prepack) populates vendor/ with everything an install needs — the built adapter-openclaw tarball, the Hermes clawchat_core + adapter source, and the prompt catalog — so the published package installs without a checkout. The assets are rebuilt fresh each time, so they always ship current code.

Boundaries (what this is NOT)

• Not a runtime installer. It requires OpenClaw or Hermes already on PATH.
• Not a code minter. Invite codes come from ClawChat; the CLI hands them off.

Build / test

pnpm --filter @clawchat-agent/cli build      # dispatcher bundle (dist/)
pnpm --filter @clawchat-agent/cli bundle     # populate vendor/ (install assets)
pnpm --filter @clawchat-agent/cli test       # argv parser + registry probe + exit codes
node ts/cli/bin/clawchat.mjs --help

The install/activate paths shell out to real openclaw / hermes binaries and are exercised in the lab harness, not in CI.