clawdentity 0.0.14 → 0.0.16

package/skill-bundle/openclaw-skill/skill/SKILL.md

@@ -9,7 +9,7 @@ version: 0.3.0
 This skill prepares a local OpenClaw agent in a strict sequence:
 1. finish registry onboarding by redeeming an invite (`clw_inv_...`) and store API key
 2. create local agent identity
-3. configure relay runtime
+3. run `clawdentity openclaw setup <agent-name>` (config + runtime + readiness)
 4. become ready to start or accept QR pairing
 
 After setup, this skill also covers lifecycle operations: token refresh, API key rotation, agent revocation, service teardown, and token verification.
@@ -115,7 +115,7 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
 - `clawdentity openclaw relay test --peer <alias> --hook-token <token> --json`
 - `clawdentity openclaw relay test --session-id <id> --message <text>`
 
-### Connector runtime
+### Connector runtime (advanced/manual only)
 - `clawdentity connector start <agent-name>`
 - `clawdentity connector start <agent-name> --proxy-ws-url <url>`
 - `clawdentity connector start <agent-name> --openclaw-hook-token <token>`
@@ -127,9 +127,13 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
 ### Pairing
 - `clawdentity pair start <agent-name> --qr`
 - `clawdentity pair start <agent-name> --qr --qr-output <path>`
-- `clawdentity pair start <agent-name> --qr --owner-pat <token> --ttl-seconds <seconds>`
+- `clawdentity pair start <agent-name> --qr --ttl-seconds <seconds>`
+- `clawdentity pair start <agent-name> --qr --wait`
+- `clawdentity pair start <agent-name> --qr --wait --wait-seconds <seconds> --poll-interval-seconds <seconds>`
 - `clawdentity pair confirm <agent-name> --qr-file <path>`
 - `clawdentity pair confirm <agent-name> --ticket <clwpair1_...>`
+- `clawdentity pair status <agent-name> --ticket <clwpair1_...>`
+- `clawdentity pair status <agent-name> --ticket <clwpair1_...> --wait`
 
 ### Token verification
 - `clawdentity verify <tokenOrFile>`
@@ -184,15 +188,13 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
   - `--openclaw-dir <path>`
   - `--openclaw-base-url <url>`
   - `--transform-source <path>` (custom relay transform location)
-- Verify output contains self-setup completion, OpenClaw config path, and relay runtime path.
+- Verify output contains:
+  - self-setup completion
+  - OpenClaw config path and relay runtime path
+  - runtime mode/status
+  - websocket status `connected`
 
-7. Start connector runtime.
-- Run `clawdentity connector start <agent-name>`.
-- For non-default proxy: add `--proxy-ws-url <url>`.
-- Connector auto-loads hook token from `openclaw-relay.json` when `--openclaw-hook-token` is not provided.
-- Optional persistent mode: `clawdentity connector service install <agent-name>`.
-
-8. Validate readiness.
+7. Validate readiness.
 - Run `clawdentity openclaw doctor`.
 - Use `--json` for machine-readable output.
 - Use `--peer <alias>` to validate a specific peer exists after pairing.
@@ -208,21 +210,28 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
 | `state.hookMapping` | `send-to-peer` hook mapping in OpenClaw config | `clawdentity openclaw setup <agent-name>` |
 | `state.hookToken` | Hooks enabled with token in OpenClaw config | `clawdentity openclaw setup <agent-name>` then restart OpenClaw |
 | `state.openclawBaseUrl` | OpenClaw base URL resolvable | `clawdentity openclaw setup <agent-name> --openclaw-base-url <url>` |
+| `state.connectorRuntime` | Local connector runtime reachable and websocket-connected | `clawdentity openclaw setup <agent-name>` |
 
 - At this point the agent is ready to start pairing or accept pairing.
 
-9. Pairing phase (separate from onboarding).
-- Initiator: `clawdentity pair start <agent-name> --qr`
-  - Optional overrides: `--owner-pat <token>`, `--ttl-seconds <seconds>`, `--qr-output <path>`
-  - Owner PAT defaults to configured API key when `--owner-pat` is omitted.
+8. Pairing phase (separate from onboarding).
+- Required default initiator flow:
+  - `clawdentity pair start <agent-name> --qr --wait`
+  - Optional overrides: `--ttl-seconds <seconds>`, `--qr-output <path>`, `--wait-seconds <seconds>`, `--poll-interval-seconds <seconds>`
+- Why `--wait` is required by default:
+  - responder saves peer during `pair confirm`
+  - initiator saves peer only after confirmed status is observed (`pair start --wait` or `pair status`)
 - Responder (two mutually exclusive paths):
   - QR path: `clawdentity pair confirm <agent-name> --qr-file <path>`
   - Inline ticket path: `clawdentity pair confirm <agent-name> --ticket <clwpair1_...>`
   - Cannot provide both `--qr-file` and `--ticket` simultaneously.
 - Pair confirm auto-saves peer DID/proxy mapping locally from QR ticket metadata.
+- If initiator started without `--wait`, initiator must run:
+  - `clawdentity pair status <agent-name> --ticket <clwpair1_...> --wait`
+  - This persists the peer on initiator after responder confirmation.
 - Confirm pairing success, then run `clawdentity openclaw relay test`.
 
-10. Post-pairing verification.
+9. Post-pairing verification.
 - Run `clawdentity verify <path-to-ait.jwt>` to confirm the local agent token is valid.
 - Verify output shows token status, expiry, and no revocation.
 - Run `clawdentity openclaw doctor --peer <alias>` to confirm the new peer is visible.
@@ -233,8 +242,9 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
 
 ### Token expiry recovery
 1. Run `clawdentity agent auth refresh <agent-name>`.
-2. Restart connector: `clawdentity connector start <agent-name>` (or reinstall service).
-3. Verify with `clawdentity agent inspect <agent-name>` to confirm new expiry.
+2. Reconcile runtime with `clawdentity openclaw setup <agent-name>`.
+3. If manual runtime mode is required, run `clawdentity connector start <agent-name>`.
+4. Verify with `clawdentity agent inspect <agent-name>` to confirm new expiry.
 
 ### API key rotation
 1. Create new key: `clawdentity api-key create`.
@@ -274,30 +284,33 @@ Do not suggest switching endpoints unless user explicitly asks for endpoint chan
 ## Failure Handling
 
 ### Connector errors
-- `404` on outbound endpoint: connector not running. Restart with `clawdentity connector start <agent-name>`.
-- `409` on outbound: peer snapshot stale. Rerun `clawdentity openclaw setup <agent-name>` then restart connector.
+- `404` on outbound endpoint: connector runtime is not available. Rerun `clawdentity openclaw setup <agent-name>`.
+- `409` on outbound: peer snapshot stale. Rerun `clawdentity openclaw setup <agent-name>`.
 - `CLI_CONNECTOR_MISSING_AGENT_MATERIAL`: agent credentials missing. Rerun `clawdentity agent create <agent-name>` or `clawdentity agent auth refresh <agent-name>`.
 
 ### Pairing errors
-- `pair start` 401 (`PROXY_PAIR_OWNER_PAT_INVALID`): owner PAT is invalid or expired. Rotate API key or provide valid `--owner-pat`.
-- `pair start` 403 (`PROXY_PAIR_OWNER_PAT_FORBIDDEN`): owner PAT does not control initiator agent DID.
+- `pair start` 403 (`PROXY_PAIR_OWNERSHIP_FORBIDDEN`): initiator ownership check failed. Recreate/refresh the local agent identity.
+- `pair start` 503 (`PROXY_PAIR_OWNERSHIP_UNAVAILABLE`): registry ownership validation is unavailable. Check proxy/registry service auth configuration.
 - `pair confirm` 404 (`PROXY_PAIR_TICKET_NOT_FOUND`): ticket is invalid or expired. Request a new ticket from initiator.
 - `pair confirm` 410 (`PROXY_PAIR_TICKET_EXPIRED`): ticket has expired. Request a new ticket.
 - `CLI_PAIR_CONFIRM_INPUT_CONFLICT`: cannot provide both `--ticket` and `--qr-file`. Use one path only.
 - `CLI_PAIR_PROXY_URL_MISMATCH`: local `proxyUrl` does not match registry metadata. Rerun `clawdentity invite redeem <clw_inv_...>`.
+- Responder shows peer but initiator does not:
+  - Cause: initiator started pairing without `--wait`.
+  - Fix: run `clawdentity pair status <initiator-agent> --ticket <clwpair1_...> --wait` on initiator.
 
 ### Setup errors
 - `405 Method Not Allowed` on hook path: rerun `clawdentity openclaw setup <agent-name>` and restart OpenClaw.
 - `CLI_OPENCLAW_MISSING_AGENT_CREDENTIALS` or `CLI_OPENCLAW_EMPTY_AGENT_CREDENTIALS`: agent credentials missing or empty. Rerun `agent create` or `agent auth refresh`.
 
 ### Credential expiry
-- Agent AIT expired: run `clawdentity agent auth refresh <agent-name>` then restart connector.
+- Agent AIT expired: run `clawdentity agent auth refresh <agent-name>`, then rerun `clawdentity openclaw setup <agent-name>`.
 - API key invalid (401 on registry calls): rotate with `api-key create` then `config set apiKey`.
 
 ### General recovery
 - Report exact missing file/value.
 - Fix only failing input/config.
-- Keep connector running while testing relay delivery.
+- Prefer `openclaw setup` as the single runtime reconciliation command.
 - Re-run `openclaw doctor`, then `openclaw relay test`.
 
 ## Bundled Resources

package/skill-bundle/openclaw-skill/skill/references/clawdentity-protocol.md

@@ -39,6 +39,7 @@ Define the exact runtime contract used by `relay-to-peer.mjs`.
 Rules:
 - setup must succeed without any peer metadata
 - peers config snapshot still exists and may be empty until pairing is completed
+- setup is expected to bring connector runtime to a websocket-connected state (unless explicitly disabled by advanced flags)
 
 ## Peer Map Schema
 
@@ -73,7 +74,7 @@ Current pairing contract is ticket-based with CLI support:
    - proxy route: `POST /pair/start`
    - headers:
      - `Authorization: Claw <AIT>`
-     - `x-claw-owner-pat: <owner-pat>`
+     - ownership validation is handled internally by proxy-to-registry service auth
    - body (optional):
 
 ```json
@@ -148,7 +149,8 @@ The transform does not send directly to the peer proxy. It posts to the local co
 - Runtime may also use:
   - `CLAWDENTITY_CONNECTOR_BASE_URL`
   - `CLAWDENTITY_CONNECTOR_OUTBOUND_PATH`
-- `connector start <agentName>` resolves bind URL from `~/.clawdentity/openclaw-connectors.json` when explicit env override is absent.
+- `openclaw setup <agentName>` is the primary self-setup path and should leave runtime healthy.
+- `connector start <agentName>` is advanced/manual recovery; it resolves bind URL from `~/.clawdentity/openclaw-connectors.json` when explicit env override is absent.
 
 Outbound JSON body sent by transform:
 
@@ -184,27 +186,23 @@ Error messages should include file/path context but never print secret content.
 
 CLI resolves proxy URL in this order (first non-empty wins):
 
-1. `--proxy-url` flag (explicit override)
-2. `CLAWDENTITY_PROXY_URL` environment variable
-3. `proxyUrl` from `~/.clawdentity/config.json`
-4. Derived from `registryUrl` using hostname mapping
-5. Error: `CLI_PAIR_PROXY_URL_REQUIRED`
+1. `CLAWDENTITY_PROXY_URL` environment variable
+2. `proxyUrl` from `~/.clawdentity/config.json`
+3. Registry metadata from `GET /v1/metadata`
+4. Error when configured proxy does not match metadata (`CLI_PAIR_PROXY_URL_MISMATCH`) or metadata lookup fails
 
-### Hostname mapping (registry to proxy)
+### Metadata expectation
 
-| Registry hostname | Proxy hostname |
-|-------------------|---------------|
-| `registry.clawdentity.com` | `proxy.clawdentity.com` |
-| `dev.registry.clawdentity.com` | `dev.proxy.clawdentity.com` |
-| `dev.registry.<domain>` | `dev.proxy.<domain>` |
-| `registry.<domain>` | `proxy.<domain>` |
-| `localhost:8788` | `localhost:8787` |
-| `127.0.0.1:8788` | `127.0.0.1:8787` |
-| `host.docker.internal:8788` | `host.docker.internal:8787` |
+Registry metadata (`/v1/metadata`) should return a valid `proxyUrl`.
 
-If registry hostname does not match any pattern, derivation returns undefined and resolution falls through to error.
+Known defaults:
 
-Recovery: `clawdentity config set proxyUrl <url>`.
+| Registry URL | Metadata proxy URL |
+|-------------|--------------------|
+| `https://registry.clawdentity.com` | `https://proxy.clawdentity.com` |
+| `https://dev.registry.clawdentity.com` | `https://dev.proxy.clawdentity.com` |
+
+Recovery: rerun onboarding (`clawdentity invite redeem <clw_inv_...>`) so local config aligns to registry metadata.
 
 ## Pairing Error Codes
 
@@ -212,10 +210,9 @@ Recovery: `clawdentity config set proxyUrl <url>`.
 
 | HTTP Status | Error Code | Meaning |
 |-------------|-----------|---------|
-| 401 | `PROXY_PAIR_OWNER_PAT_INVALID` | Owner PAT is invalid or expired |
-| 403 | `PROXY_PAIR_OWNER_PAT_FORBIDDEN` | Owner PAT does not control initiator agent DID |
+| 403 | `PROXY_PAIR_OWNERSHIP_FORBIDDEN` | Initiator ownership check failed |
+| 503 | `PROXY_PAIR_OWNERSHIP_UNAVAILABLE` | Registry ownership lookup unavailable |
 | — | `CLI_PAIR_AGENT_NOT_FOUND` | Agent ait.jwt or secret.key missing/empty |
-| — | `CLI_PAIR_START_OWNER_PAT_REQUIRED` | Owner PAT not provided and no API key configured |
 | — | `CLI_PAIR_PROXY_URL_REQUIRED` | Proxy URL could not be resolved |
 | — | `CLI_PAIR_START_INVALID_TTL` | ttlSeconds must be a positive integer |
 | — | `CLI_PAIR_INVALID_PROXY_URL` | Proxy URL is invalid |