clawdentity 0.0.21 → 0.0.22

package/dist/bin.js

@@ -15719,20 +15719,56 @@ var registryConfigSchema = external_exports.object({
   REGISTRY_SIGNING_KEY: external_exports.string().min(1).optional(),
   REGISTRY_SIGNING_KEYS: registrySigningKeysEnvSchema.optional()
 });
-function parseRegistryConfig(env) {
-  const parsed = registryConfigSchema.safeParse(env);
-  if (parsed.success) {
-    return parsed.data;
-  }
+var REQUIRED_REGISTRY_RUNTIME_KEYS = [
+  "PROXY_URL",
+  "REGISTRY_ISSUER_URL",
+  "EVENT_BUS_BACKEND",
+  "BOOTSTRAP_SECRET",
+  "REGISTRY_SIGNING_KEY",
+  "REGISTRY_SIGNING_KEYS"
+];
+function throwRegistryConfigValidationError(details) {
   throw new AppError({
     code: "CONFIG_VALIDATION_FAILED",
     message: "Registry configuration is invalid",
     status: 500,
     expose: true,
-    details: {
-      fieldErrors: parsed.error.flatten().fieldErrors,
-      formErrors: parsed.error.flatten().formErrors
+    details
+  });
+}
+function assertRequiredRegistryRuntimeKeys(input) {
+  if (input.ENVIRONMENT === "test") {
+    return;
+  }
+  const fieldErrors = {};
+  for (const key of REQUIRED_REGISTRY_RUNTIME_KEYS) {
+    const value = input[key];
+    if (typeof value === "string" && value.trim().length > 0) {
+      continue;
+    }
+    if (value !== void 0 && value !== null && !(typeof value === "string" && value.trim().length === 0)) {
+      continue;
+    }
+    fieldErrors[key] = [`${key} is required`];
+  }
+  if (Object.keys(fieldErrors).length > 0) {
+    throwRegistryConfigValidationError({
+      fieldErrors,
+      formErrors: []
+    });
+  }
+}
+function parseRegistryConfig(env, options = {}) {
+  const parsed = registryConfigSchema.safeParse(env);
+  if (parsed.success) {
+    if (options.requireRuntimeKeys === true) {
+      assertRequiredRegistryRuntimeKeys(parsed.data);
     }
+    return parsed.data;
+  }
+  throwRegistryConfigValidationError({
+    fieldErrors: parsed.error.flatten().fieldErrors,
+    formErrors: parsed.error.flatten().formErrors
   });
 }
 
@@ -21760,6 +21796,7 @@ var OPENCLAW_SETUP_RESTART_COMMAND_HINT = `${OPENCLAW_SETUP_COMMAND_HINT} and re
 var OPENCLAW_SETUP_WITH_BASE_URL_HINT = `${OPENCLAW_SETUP_COMMAND_HINT} --openclaw-base-url <url>`;
 var OPENCLAW_PAIRING_COMMAND_HINT = "Run QR pairing first: clawdentity pair start <agentName> --qr and clawdentity pair confirm <agentName> --qr-file <path>";
 var OPENCLAW_DEVICE_APPROVAL_RECOVERY_HINT = "Run: clawdentity openclaw setup <agentName> (auto-recovers pending OpenClaw gateway device approvals)";
+var OPENCLAW_GATEWAY_AUTH_RECOVERY_HINT = "Run: clawdentity openclaw setup <agentName> (ensures gateway auth mode/token are configured)";
 var OPENCLAW_GATEWAY_APPROVAL_COMMAND = "openclaw";
 var OPENCLAW_GATEWAY_APPROVAL_TIMEOUT_MS = 1e4;
 var textEncoder2 = new TextEncoder();
@@ -22691,6 +22728,28 @@ function isCanonicalAgentSessionKey(value) {
 function generateOpenclawHookToken() {
   return randomBytes3(OPENCLAW_HOOK_TOKEN_BYTES).toString("hex");
 }
+function generateOpenclawGatewayToken() {
+  return randomBytes3(OPENCLAW_HOOK_TOKEN_BYTES).toString("hex");
+}
+function parseGatewayAuthMode(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "token" || normalized === "password" || normalized === "trusted-proxy") {
+    return normalized;
+  }
+  return void 0;
+}
+function resolveEnvOpenclawGatewayToken() {
+  if (typeof process.env.OPENCLAW_GATEWAY_TOKEN === "string" && process.env.OPENCLAW_GATEWAY_TOKEN.trim().length > 0) {
+    return process.env.OPENCLAW_GATEWAY_TOKEN.trim();
+  }
+  return void 0;
+}
+function resolveGatewayAuthToken(existingToken) {
+  return resolveEnvOpenclawGatewayToken() ?? existingToken ?? generateOpenclawGatewayToken();
+}
 function upsertRelayHookMapping(mappingsValue) {
   const mappings = Array.isArray(mappingsValue) ? mappingsValue.filter(isRecord9).map((mapping) => ({ ...mapping })) : [];
   const existingIndex = mappings.findIndex((mapping) => {
@@ -22757,9 +22816,22 @@ async function patchOpenclawConfig(openclawConfigPath, hookToken) {
     ["hook:", defaultSessionKey]
   );
   hooks.mappings = upsertRelayHookMapping(hooks.mappings);
+  const gateway = isRecord9(config2.gateway) ? { ...config2.gateway } : {};
+  const gatewayAuth = isRecord9(gateway.auth) ? { ...gateway.auth } : {};
+  const configuredGatewayAuthMode = parseGatewayAuthMode(gatewayAuth.mode);
+  if (configuredGatewayAuthMode === void 0) {
+    gatewayAuth.mode = "token";
+  }
+  const effectiveGatewayAuthMode = parseGatewayAuthMode(gatewayAuth.mode) ?? "token";
+  if (effectiveGatewayAuthMode === "token") {
+    const existingGatewayAuthToken = typeof gatewayAuth.token === "string" && gatewayAuth.token.trim().length > 0 ? gatewayAuth.token.trim() : void 0;
+    gatewayAuth.token = resolveGatewayAuthToken(existingGatewayAuthToken);
+  }
+  gateway.auth = gatewayAuth;
   const nextConfig = {
     ...config2,
-    hooks
+    hooks,
+    gateway
   };
   await writeFile6(
     openclawConfigPath,
@@ -23264,6 +23336,79 @@ async function runOpenclawDoctor(options = {}) {
         })
       );
     }
+    const gateway = isRecord9(openclawConfig.gateway) ? openclawConfig.gateway : {};
+    const gatewayAuth = isRecord9(gateway.auth) ? gateway.auth : {};
+    const gatewayAuthMode = parseGatewayAuthMode(gatewayAuth.mode);
+    const gatewayAuthToken = typeof gatewayAuth.token === "string" && gatewayAuth.token.trim().length > 0 ? gatewayAuth.token.trim() : void 0;
+    const gatewayAuthPassword = typeof gatewayAuth.password === "string" && gatewayAuth.password.trim().length > 0 ? gatewayAuth.password.trim() : void 0;
+    if (gatewayAuthMode === "token") {
+      if (gatewayAuthToken === void 0) {
+        checks.push(
+          toDoctorCheck({
+            id: "state.gatewayAuth",
+            label: "OpenClaw gateway auth",
+            status: "fail",
+            message: `gateway.auth.token is missing in ${openclawConfigPath}`,
+            remediationHint: OPENCLAW_GATEWAY_AUTH_RECOVERY_HINT,
+            details: { openclawConfigPath, gatewayAuthMode }
+          })
+        );
+      } else {
+        checks.push(
+          toDoctorCheck({
+            id: "state.gatewayAuth",
+            label: "OpenClaw gateway auth",
+            status: "pass",
+            message: "gateway auth is configured with token mode",
+            details: { openclawConfigPath, gatewayAuthMode }
+          })
+        );
+      }
+    } else if (gatewayAuthMode === "password") {
+      if (gatewayAuthPassword === void 0) {
+        checks.push(
+          toDoctorCheck({
+            id: "state.gatewayAuth",
+            label: "OpenClaw gateway auth",
+            status: "fail",
+            message: `gateway.auth.password is missing in ${openclawConfigPath}`,
+            remediationHint: OPENCLAW_GATEWAY_AUTH_RECOVERY_HINT,
+            details: { openclawConfigPath, gatewayAuthMode }
+          })
+        );
+      } else {
+        checks.push(
+          toDoctorCheck({
+            id: "state.gatewayAuth",
+            label: "OpenClaw gateway auth",
+            status: "pass",
+            message: "gateway auth is configured with password mode",
+            details: { openclawConfigPath, gatewayAuthMode }
+          })
+        );
+      }
+    } else if (gatewayAuthMode === "trusted-proxy") {
+      checks.push(
+        toDoctorCheck({
+          id: "state.gatewayAuth",
+          label: "OpenClaw gateway auth",
+          status: "pass",
+          message: "gateway auth is configured with trusted-proxy mode",
+          details: { openclawConfigPath, gatewayAuthMode }
+        })
+      );
+    } else {
+      checks.push(
+        toDoctorCheck({
+          id: "state.gatewayAuth",
+          label: "OpenClaw gateway auth",
+          status: "fail",
+          message: `gateway.auth.mode is missing or unsupported in ${openclawConfigPath}`,
+          remediationHint: OPENCLAW_GATEWAY_AUTH_RECOVERY_HINT,
+          details: { openclawConfigPath }
+        })
+      );
+    }
   } catch {
     checks.push(
       toDoctorCheck({
@@ -23295,6 +23440,16 @@ async function runOpenclawDoctor(options = {}) {
         details: { openclawConfigPath }
       })
     );
+    checks.push(
+      toDoctorCheck({
+        id: "state.gatewayAuth",
+        label: "OpenClaw gateway auth",
+        status: "fail",
+        message: `unable to read ${openclawConfigPath}`,
+        remediationHint: "Ensure the OpenClaw config file exists (OPENCLAW_CONFIG_PATH/CLAWDBOT_CONFIG_PATH, or state dir) and rerun openclaw setup",
+        details: { openclawConfigPath }
+      })
+    );
   }
   const relayRuntimeConfigPath = resolveRelayRuntimeConfigPath(homeDir);
   try {

package/dist/index.js

@@ -15723,20 +15723,56 @@ var registryConfigSchema = external_exports.object({
   REGISTRY_SIGNING_KEY: external_exports.string().min(1).optional(),
   REGISTRY_SIGNING_KEYS: registrySigningKeysEnvSchema.optional()
 });
-function parseRegistryConfig(env) {
-  const parsed = registryConfigSchema.safeParse(env);
-  if (parsed.success) {
-    return parsed.data;
-  }
+var REQUIRED_REGISTRY_RUNTIME_KEYS = [
+  "PROXY_URL",
+  "REGISTRY_ISSUER_URL",
+  "EVENT_BUS_BACKEND",
+  "BOOTSTRAP_SECRET",
+  "REGISTRY_SIGNING_KEY",
+  "REGISTRY_SIGNING_KEYS"
+];
+function throwRegistryConfigValidationError(details) {
   throw new AppError({
     code: "CONFIG_VALIDATION_FAILED",
     message: "Registry configuration is invalid",
     status: 500,
     expose: true,
-    details: {
-      fieldErrors: parsed.error.flatten().fieldErrors,
-      formErrors: parsed.error.flatten().formErrors
+    details
+  });
+}
+function assertRequiredRegistryRuntimeKeys(input) {
+  if (input.ENVIRONMENT === "test") {
+    return;
+  }
+  const fieldErrors = {};
+  for (const key of REQUIRED_REGISTRY_RUNTIME_KEYS) {
+    const value = input[key];
+    if (typeof value === "string" && value.trim().length > 0) {
+      continue;
+    }
+    if (value !== void 0 && value !== null && !(typeof value === "string" && value.trim().length === 0)) {
+      continue;
+    }
+    fieldErrors[key] = [`${key} is required`];
+  }
+  if (Object.keys(fieldErrors).length > 0) {
+    throwRegistryConfigValidationError({
+      fieldErrors,
+      formErrors: []
+    });
+  }
+}
+function parseRegistryConfig(env, options = {}) {
+  const parsed = registryConfigSchema.safeParse(env);
+  if (parsed.success) {
+    if (options.requireRuntimeKeys === true) {
+      assertRequiredRegistryRuntimeKeys(parsed.data);
     }
+    return parsed.data;
+  }
+  throwRegistryConfigValidationError({
+    fieldErrors: parsed.error.flatten().fieldErrors,
+    formErrors: parsed.error.flatten().formErrors
   });
 }
 
@@ -21760,6 +21796,7 @@ var OPENCLAW_SETUP_RESTART_COMMAND_HINT = `${OPENCLAW_SETUP_COMMAND_HINT} and re
 var OPENCLAW_SETUP_WITH_BASE_URL_HINT = `${OPENCLAW_SETUP_COMMAND_HINT} --openclaw-base-url <url>`;
 var OPENCLAW_PAIRING_COMMAND_HINT = "Run QR pairing first: clawdentity pair start <agentName> --qr and clawdentity pair confirm <agentName> --qr-file <path>";
 var OPENCLAW_DEVICE_APPROVAL_RECOVERY_HINT = "Run: clawdentity openclaw setup <agentName> (auto-recovers pending OpenClaw gateway device approvals)";
+var OPENCLAW_GATEWAY_AUTH_RECOVERY_HINT = "Run: clawdentity openclaw setup <agentName> (ensures gateway auth mode/token are configured)";
 var OPENCLAW_GATEWAY_APPROVAL_COMMAND = "openclaw";
 var OPENCLAW_GATEWAY_APPROVAL_TIMEOUT_MS = 1e4;
 var textEncoder2 = new TextEncoder();
@@ -22691,6 +22728,28 @@ function isCanonicalAgentSessionKey(value) {
 function generateOpenclawHookToken() {
   return randomBytes3(OPENCLAW_HOOK_TOKEN_BYTES).toString("hex");
 }
+function generateOpenclawGatewayToken() {
+  return randomBytes3(OPENCLAW_HOOK_TOKEN_BYTES).toString("hex");
+}
+function parseGatewayAuthMode(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "token" || normalized === "password" || normalized === "trusted-proxy") {
+    return normalized;
+  }
+  return void 0;
+}
+function resolveEnvOpenclawGatewayToken() {
+  if (typeof process.env.OPENCLAW_GATEWAY_TOKEN === "string" && process.env.OPENCLAW_GATEWAY_TOKEN.trim().length > 0) {
+    return process.env.OPENCLAW_GATEWAY_TOKEN.trim();
+  }
+  return void 0;
+}
+function resolveGatewayAuthToken(existingToken) {
+  return resolveEnvOpenclawGatewayToken() ?? existingToken ?? generateOpenclawGatewayToken();
+}
 function upsertRelayHookMapping(mappingsValue) {
   const mappings = Array.isArray(mappingsValue) ? mappingsValue.filter(isRecord9).map((mapping) => ({ ...mapping })) : [];
   const existingIndex = mappings.findIndex((mapping) => {
@@ -22757,9 +22816,22 @@ async function patchOpenclawConfig(openclawConfigPath, hookToken) {
     ["hook:", defaultSessionKey]
   );
   hooks.mappings = upsertRelayHookMapping(hooks.mappings);
+  const gateway = isRecord9(config2.gateway) ? { ...config2.gateway } : {};
+  const gatewayAuth = isRecord9(gateway.auth) ? { ...gateway.auth } : {};
+  const configuredGatewayAuthMode = parseGatewayAuthMode(gatewayAuth.mode);
+  if (configuredGatewayAuthMode === void 0) {
+    gatewayAuth.mode = "token";
+  }
+  const effectiveGatewayAuthMode = parseGatewayAuthMode(gatewayAuth.mode) ?? "token";
+  if (effectiveGatewayAuthMode === "token") {
+    const existingGatewayAuthToken = typeof gatewayAuth.token === "string" && gatewayAuth.token.trim().length > 0 ? gatewayAuth.token.trim() : void 0;
+    gatewayAuth.token = resolveGatewayAuthToken(existingGatewayAuthToken);
+  }
+  gateway.auth = gatewayAuth;
   const nextConfig = {
     ...config2,
-    hooks
+    hooks,
+    gateway
   };
   await writeFile6(
     openclawConfigPath,
@@ -23264,6 +23336,79 @@ async function runOpenclawDoctor(options = {}) {
         })
       );
     }
+    const gateway = isRecord9(openclawConfig.gateway) ? openclawConfig.gateway : {};
+    const gatewayAuth = isRecord9(gateway.auth) ? gateway.auth : {};
+    const gatewayAuthMode = parseGatewayAuthMode(gatewayAuth.mode);
+    const gatewayAuthToken = typeof gatewayAuth.token === "string" && gatewayAuth.token.trim().length > 0 ? gatewayAuth.token.trim() : void 0;
+    const gatewayAuthPassword = typeof gatewayAuth.password === "string" && gatewayAuth.password.trim().length > 0 ? gatewayAuth.password.trim() : void 0;
+    if (gatewayAuthMode === "token") {
+      if (gatewayAuthToken === void 0) {
+        checks.push(
+          toDoctorCheck({
+            id: "state.gatewayAuth",
+            label: "OpenClaw gateway auth",
+            status: "fail",
+            message: `gateway.auth.token is missing in ${openclawConfigPath}`,
+            remediationHint: OPENCLAW_GATEWAY_AUTH_RECOVERY_HINT,
+            details: { openclawConfigPath, gatewayAuthMode }
+          })
+        );
+      } else {
+        checks.push(
+          toDoctorCheck({
+            id: "state.gatewayAuth",
+            label: "OpenClaw gateway auth",
+            status: "pass",
+            message: "gateway auth is configured with token mode",
+            details: { openclawConfigPath, gatewayAuthMode }
+          })
+        );
+      }
+    } else if (gatewayAuthMode === "password") {
+      if (gatewayAuthPassword === void 0) {
+        checks.push(
+          toDoctorCheck({
+            id: "state.gatewayAuth",
+            label: "OpenClaw gateway auth",
+            status: "fail",
+            message: `gateway.auth.password is missing in ${openclawConfigPath}`,
+            remediationHint: OPENCLAW_GATEWAY_AUTH_RECOVERY_HINT,
+            details: { openclawConfigPath, gatewayAuthMode }
+          })
+        );
+      } else {
+        checks.push(
+          toDoctorCheck({
+            id: "state.gatewayAuth",
+            label: "OpenClaw gateway auth",
+            status: "pass",
+            message: "gateway auth is configured with password mode",
+            details: { openclawConfigPath, gatewayAuthMode }
+          })
+        );
+      }
+    } else if (gatewayAuthMode === "trusted-proxy") {
+      checks.push(
+        toDoctorCheck({
+          id: "state.gatewayAuth",
+          label: "OpenClaw gateway auth",
+          status: "pass",
+          message: "gateway auth is configured with trusted-proxy mode",
+          details: { openclawConfigPath, gatewayAuthMode }
+        })
+      );
+    } else {
+      checks.push(
+        toDoctorCheck({
+          id: "state.gatewayAuth",
+          label: "OpenClaw gateway auth",
+          status: "fail",
+          message: `gateway.auth.mode is missing or unsupported in ${openclawConfigPath}`,
+          remediationHint: OPENCLAW_GATEWAY_AUTH_RECOVERY_HINT,
+          details: { openclawConfigPath }
+        })
+      );
+    }
   } catch {
     checks.push(
       toDoctorCheck({
@@ -23295,6 +23440,16 @@ async function runOpenclawDoctor(options = {}) {
         details: { openclawConfigPath }
       })
     );
+    checks.push(
+      toDoctorCheck({
+        id: "state.gatewayAuth",
+        label: "OpenClaw gateway auth",
+        status: "fail",
+        message: `unable to read ${openclawConfigPath}`,
+        remediationHint: "Ensure the OpenClaw config file exists (OPENCLAW_CONFIG_PATH/CLAWDBOT_CONFIG_PATH, or state dir) and rerun openclaw setup",
+        details: { openclawConfigPath }
+      })
+    );
   }
   const relayRuntimeConfigPath = resolveRelayRuntimeConfigPath(homeDir);
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawdentity",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -21,17 +21,6 @@
     "postinstall.mjs",
     "skill-bundle"
   ],
-  "scripts": {
-    "build": "pnpm -F @clawdentity/openclaw-skill build && pnpm run sync:skill-bundle && pnpm run verify:skill-bundle && tsup",
-    "format": "biome format .",
-    "lint": "biome lint .",
-    "prepack": "pnpm run build",
-    "postinstall": "node ./postinstall.mjs",
-    "sync:skill-bundle": "node ./scripts/sync-skill-bundle.mjs",
-    "verify:skill-bundle": "node ./scripts/verify-skill-bundle.mjs",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  },
   "dependencies": {
     "commander": "^13.1.0",
     "jsqr": "^1.4.0",
@@ -40,11 +29,21 @@
     "ws": "^8.19.0"
   },
   "devDependencies": {
-    "@clawdentity/connector": "workspace:*",
-    "@clawdentity/protocol": "workspace:*",
-    "@clawdentity/sdk": "workspace:*",
     "@types/node": "^22.18.11",
     "@types/pngjs": "^6.0.5",
-    "@types/qrcode": "^1.5.6"
+    "@types/qrcode": "^1.5.6",
+    "@clawdentity/connector": "0.0.0",
+    "@clawdentity/protocol": "0.0.0",
+    "@clawdentity/sdk": "0.0.0"
+  },
+  "scripts": {
+    "build": "pnpm -F @clawdentity/openclaw-skill build && pnpm run sync:skill-bundle && pnpm run verify:skill-bundle && tsup",
+    "format": "biome format .",
+    "lint": "biome lint .",
+    "postinstall": "node ./postinstall.mjs",
+    "sync:skill-bundle": "node ./scripts/sync-skill-bundle.mjs",
+    "verify:skill-bundle": "node ./scripts/verify-skill-bundle.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
-}
+}

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

@@ -1,6 +1,6 @@
 ---
 name: clawdentity_openclaw_relay
-description: This skill should be used when the user asks to "set up Clawdentity relay", "pair two agents", "verify an agent token", "rotate API key", "refresh agent auth", "revoke an agent", "troubleshoot relay", "uninstall connector service", or needs OpenClaw relay onboarding, lifecycle management, or pairing workflows.
+description: This skill should be used when the user asks to "set up Clawdentity relay", "pair two agents", "verify an agent token", "rotate API key", "refresh agent auth", "revoke an agent", "troubleshoot relay", "uninstall connector service", "check relay health", "run relay doctor", "test relay connection", "send relay test", "install relay skill", "bootstrap registry", "create onboarding invite", "decommission agent", or needs OpenClaw relay onboarding, lifecycle management, or pairing workflows.
 version: 0.3.0
 ---
 
@@ -104,9 +104,17 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
 
 ### OpenClaw relay setup
 - `clawdentity skill install`
+- `clawdentity skill install --openclaw-dir <path>`
+- `clawdentity skill install --skill-package-root <path>`
+- `clawdentity skill install --json`
 - `clawdentity openclaw setup <agent-name>`
 - `clawdentity openclaw setup <agent-name> --transform-source <path>`
 - `clawdentity openclaw setup <agent-name> --openclaw-dir <path> --openclaw-base-url <url>`
+- `clawdentity openclaw setup <agent-name> --runtime-mode <auto|service|detached>`
+- `clawdentity openclaw setup <agent-name> --wait-timeout-seconds <seconds>` (default 30)
+- `clawdentity openclaw setup <agent-name> --no-runtime-start`
+
+Use `--no-runtime-start` when the connector runs as a separate container or process.
 
 ### OpenClaw diagnostics
 - `clawdentity openclaw doctor`
@@ -143,6 +151,20 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
 - `clawdentity admin bootstrap --bootstrap-secret <secret>`
 - `clawdentity admin bootstrap --bootstrap-secret <secret> --display-name <name> --api-key-name <name> --registry-url <url>`
 
+### Command idempotency
+
+| Command | Idempotent? | Note |
+|---|---|---|
+| `config init` | Yes | Safe to re-run |
+| `invite redeem` | **No** | One-time; invite consumed on success |
+| `agent create` | No | Fails if agent directory exists |
+| `openclaw setup` | Yes | Primary reconciliation re-entry point |
+| `skill install` | Yes | Reports: installed/updated/unchanged |
+| `pair start` | No | Creates new ticket each time; old ticket expires |
+| `pair confirm` | No | Ticket consumed on success |
+| `connector service install` | Yes | Idempotent |
+| `connector service uninstall` | Yes | Idempotent |
+
 ## Journey (strict order)
 
 1. Validate prerequisites.
@@ -178,11 +200,13 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
   - `API key saved to local config`
   - `Human name: <human-name>`
 - Stop and fix if this step fails. Do not proceed to pairing.
+- **Validate:** `clawdentity config get apiKey` returns a non-empty value.
 
 5. Create local OpenClaw agent identity.
 - Run `clawdentity agent create <agent-name> --framework openclaw`.
 - Optionally add `--ttl-days <days>` to control token lifetime.
 - Run `clawdentity agent inspect <agent-name>`.
+- **Validate:** `~/.clawdentity/agents/<agent-name>/ait.jwt` and `secret.key` exist and are non-empty.
 
 6. Configure relay setup.
 - Run:
@@ -197,30 +221,15 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
   - runtime mode/status
   - websocket status `connected`
   - setup checklist is healthy (fails fast when hook/device/runtime prerequisites drift)
+- **Validate:** run `clawdentity openclaw doctor --json` and confirm all check entries have `status: "pass"`. If any check has `status: "fail"`, use `checkId` to look up remediation in `references/clawdentity-protocol.md` § Doctor Check Reference.
+- If setup throws `CLI_OPENCLAW_SETUP_CHECKLIST_FAILED`, parse `details.firstFailedCheckId` for targeted remediation.
 
 7. Validate readiness.
-- `clawdentity openclaw setup` already runs an internal checklist and auto-recovers pending OpenClaw gateway device approvals when possible.
+- `clawdentity openclaw setup` already runs an internal checklist, stabilizes OpenClaw gateway auth token mode, and auto-recovers pending OpenClaw gateway device approvals when possible.
 - Run `clawdentity openclaw doctor` only for diagnostics or CI reporting.
 - Use `--json` for machine-readable output.
 - Use `--peer <alias>` to validate a specific peer exists after pairing.
-- Doctor check IDs and remediation:
-
-| Check ID | Validates | Remediation on Failure |
-|----------|-----------|----------------------|
-| `config.registry` | `registryUrl`, `apiKey`, and `proxyUrl` in config (or proxy env override) | `clawdentity config init` or `invite redeem` |
-| `state.selectedAgent` | Agent marker at `~/.clawdentity/openclaw-agent-name` | `clawdentity openclaw setup <agent-name>` |
-| `state.credentials` | `ait.jwt` and `secret.key` exist and non-empty | `clawdentity agent create <agent-name>` or `agent auth refresh <agent-name>` |
-| `state.peers` | Peers config valid; requested `--peer` alias exists | `clawdentity pair start` / `pair confirm` (optional until pairing) |
-| `state.transform` | Relay transform artifacts in OpenClaw hooks dir | Reinstall skill package or `openclaw setup <agent-name>` |
-| `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.hookSessionRouting` | `hooks.defaultSessionKey`, `hooks.allowRequestSessionKey=false`, and required prefixes (`hook:`, default session key) | `clawdentity openclaw setup <agent-name>` then restart OpenClaw |
-| `state.gatewayDevicePairing` | Pending OpenClaw device approvals (prevents `pairing required` websocket errors) | Re-run `clawdentity openclaw setup <agent-name>` so setup auto-recovers approvals |
-| `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>` |
-| `state.connectorInboundInbox` | Connector local inbound inbox backlog and replay queue state (`/v1/status`) | Re-run `clawdentity openclaw setup <agent-name>` and verify connector runtime health |
-| `state.openclawHookHealth` | Connector replay status for local OpenClaw hook delivery (`/v1/status`) | Re-run `clawdentity openclaw setup <agent-name>` and restart OpenClaw if hook replay stays failed |
-
+- Doctor check IDs and remediation are in `references/clawdentity-protocol.md` § Doctor Check Reference.
 - At this point the agent is ready to start pairing or accept pairing.
 
 8. Pairing phase (separate from onboarding).
@@ -246,7 +255,10 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
 - 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.
+- Default wait timeout is 300 seconds with 3-second polling.
+- If `CLI_PAIR_STATUS_WAIT_TIMEOUT` is thrown: the responder did not confirm in time. Recovery: re-run `clawdentity pair start <agent-name> --qr --wait` to generate a new ticket.
 - Confirm pairing success, then run `clawdentity openclaw relay test`.
+- **Validate:** `~/.clawdentity/peers.json` contains the new peer alias entry.
 
 9. Post-pairing verification.
 - Run `clawdentity verify <path-to-ait.jwt>` to confirm the local agent token is valid.
@@ -257,6 +269,35 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
 - `state=queued` is not a pairing failure. The proxy retries delivery automatically while the message is within queue TTL/retry limits.
 - Note: `relay test` runs preflight doctor checks before sending the probe.
 
+## Peer Recognition & Messaging
+
+After pairing, agents receive relayed messages from their paired peers.
+Identity injection is enabled by default (`INJECT_IDENTITY_INTO_MESSAGE=true` on proxy).
+
+### Recognizing incoming messages
+- Relayed messages contain a `[Clawdentity Identity]` block prepended to the message body.
+- Extract `agentDid` from this block to identify the sender.
+- See `references/clawdentity-protocol.md` § Identity Injection for the exact block format and field definitions.
+- The connector `deliver` frame also exposes `fromAgentDid` for programmatic access.
+
+### Looking up peer identity
+- Map sender `agentDid` to a known peer by matching against `did` in `~/.clawdentity/peers.json`.
+- Each peer entry contains:
+  - `did` — the peer's agent DID (match key)
+  - `agentName` — the peer's agent name (use for addressing)
+  - `humanName` — the human behind the peer agent (use for context)
+  - `proxyUrl` — the peer's proxy endpoint
+- Address the peer by `agentName` or `humanName` in responses for natural conversation.
+
+### Sending messages to a peer
+- Include `"peer": "<alias>"` in the webhook payload to route via relay.
+- The alias is the key in `peers.json` (e.g., `"beta"`).
+- The relay transform strips `peer` from the payload and routes to the connector.
+
+### Peer validation
+- `clawdentity openclaw doctor --peer <alias>` confirms a specific peer is reachable.
+- `clawdentity openclaw relay test --peer <alias>` sends a test probe to the peer.
+
 ## Lifecycle Management
 
 ### Token expiry recovery
@@ -287,6 +328,11 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
 - Uses cached registry keys (1h TTL) and CRL (15min TTL).
 - Exit code 1 on verification failure or revocation.
 
+### Periodic health checks
+- Run `clawdentity openclaw doctor` periodically to detect stale credentials, expired AIT, or drifted runtime.
+- Run `clawdentity agent inspect <agent-name>` to check token expiry.
+- If AIT is within 24 hours of expiry, proactively run `clawdentity agent auth refresh <agent-name>`.
+
 ## Required Question Policy
 
 Ask only when missing:
@@ -308,24 +354,33 @@ Do not suggest switching endpoints unless user explicitly asks for endpoint chan
 - `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` 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.
+- `PROXY_PAIR_TICKET_NOT_FOUND`: ticket invalid or expired. Request a new ticket from initiator.
+- `PROXY_PAIR_TICKET_EXPIRED`: ticket has expired. Request a new ticket.
+- `CLI_PAIR_STATUS_WAIT_TIMEOUT`: responder did not confirm in time. Re-run `pair start`.
 - `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.
+- For complete pairing error codes, read `references/clawdentity-protocol.md` § Pairing Error Codes.
 
 ### 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`.
+- `CLI_OPENCLAW_SETUP_CHECKLIST_FAILED`: post-setup checklist reported a failing check. Parse `details.firstFailedCheckId` and apply remediation from the doctor check table in `references/clawdentity-protocol.md`. Common failing checks:
+  - `state.connectorRuntime` → rerun `openclaw setup <agent-name>`
+  - `state.gatewayDevicePairing` → rerun `openclaw setup <agent-name>` (auto-approval)
+  - `state.gatewayAuth` → rerun `openclaw setup <agent-name>` (auto-configures gateway auth mode/token)
+  - `state.hookToken` → rerun `openclaw setup <agent-name>` then restart OpenClaw
 
 ### Credential expiry
 - 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`.
 
+### Network connectivity
+- `CLI_PAIR_REQUEST_FAILED` or `CLI_ADMIN_BOOTSTRAP_REQUEST_FAILED`: proxy/registry unreachable. Check DNS, firewall rules, and URL with `clawdentity config show`.
+- If running on an air-gapped machine, confirm proxy/registry URLs resolve to reachable endpoints.
+
 ### General recovery
 - Report exact missing file/value.
 - Fix only failing input/config.
@@ -337,7 +392,10 @@ Do not suggest switching endpoints unless user explicitly asks for endpoint chan
 
 | File | Purpose |
 |------|---------|
-| `references/clawdentity-protocol.md` | Peer-map schema, pairing contract, connector handoff envelope, proxy URL resolution, pairing error codes, cache files, peer alias derivation |
-| `references/clawdentity-registry.md` | Admin bootstrap, API key lifecycle, agent revocation, auth refresh |
+| `references/clawdentity-protocol.md` | Peer-map schema, pairing contract, connector handoff, error codes, Docker guidance, doctor checks, identity injection |
+| `references/clawdentity-registry.md` | Admin bootstrap, API key lifecycle, agent revocation, auth refresh, connector errors |
+| `references/clawdentity-environment.md` | Complete environment variable reference for all CLI overrides |
+| `examples/peers-sample.json` | Valid peers.json example with one peer entry |
+| `examples/openclaw-relay-sample.json` | Relay runtime config example |
 
 Directive: read the reference files before troubleshooting relay contract, connector handoff failures, or registry/admin operations.

package/skill-bundle/openclaw-skill/skill/examples/openclaw-relay-sample.json

@@ -0,0 +1,5 @@
+{
+  "openclawBaseUrl": "http://127.0.0.1:18789",
+  "openclawHookToken": "<auto-provisioned-token>",
+  "updatedAt": "2026-02-15T20:00:00.000Z"
+}

package/skill-bundle/openclaw-skill/skill/examples/peers-sample.json

@@ -0,0 +1,10 @@
+{
+  "peers": {
+    "beta": {
+      "did": "did:claw:agent:01HEXAMPLE",
+      "proxyUrl": "https://proxy.clawdentity.com/hooks/agent",
+      "agentName": "beta",
+      "humanName": "Ira"
+    }
+  }
+}

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

@@ -0,0 +1,40 @@
+# Clawdentity Environment Variable Reference
+
+## Purpose
+
+Complete reference for CLI environment variable overrides. When env overrides are present, config-file URL mismatches are not blockers.
+
+## CLI Environment Variables
+
+| Variable | Purpose | Used By |
+|---|---|---|
+| `CLAWDENTITY_PROXY_URL` | Override proxy URL | pair, connector |
+| `CLAWDENTITY_PROXY_WS_URL` | Override proxy WebSocket URL | connector |
+| `CLAWDENTITY_REGISTRY_URL` | Override registry URL | config |
+| `CLAWDENTITY_CONNECTOR_BASE_URL` | Override connector bind URL | connector |
+| `CLAWDENTITY_CONNECTOR_OUTBOUND_PATH` | Override outbound path | relay transform |
+| `CLAWDENTITY_AGENT_NAME` | Override agent name resolution | openclaw, transform |
+| `OPENCLAW_BASE_URL` | Override OpenClaw upstream URL | openclaw setup |
+| `OPENCLAW_HOOK_TOKEN` | Override hook auth token | openclaw setup |
+| `OPENCLAW_GATEWAY_TOKEN` | Override gateway auth token | openclaw setup |
+| `OPENCLAW_CONFIG_PATH` | Override OpenClaw config file path | openclaw |
+| `OPENCLAW_STATE_DIR` | Override OpenClaw state directory | openclaw |
+| `OPENCLAW_HOME` | Override OpenClaw home directory (used when explicit config/state overrides are unset) | openclaw |
+
+## Legacy Environment Variables
+
+| Variable | Replaced By |
+|---|---|
+| `CLAWDBOT_CONFIG_PATH` | `OPENCLAW_CONFIG_PATH` |
+| `CLAWDBOT_STATE_DIR` | `OPENCLAW_STATE_DIR` |
+
+## Proxy Server Environment Variables
+
+These variables configure the Clawdentity proxy server (operator-facing, not CLI):
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `INJECT_IDENTITY_INTO_MESSAGE` | Enable/disable identity block injection into relayed messages | `true` |
+| `RELAY_QUEUE_MAX_MESSAGES_PER_AGENT` | Max queued messages per agent | `500` |
+| `RELAY_QUEUE_TTL_SECONDS` | Queue message time-to-live | `3600` |
+| `RELAY_RETRY_INITIAL_MS` | Initial retry delay for relay delivery | `1000` |

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

@@ -6,31 +6,7 @@ Define the exact runtime contract used by `relay-to-peer.mjs`.
 
 ## Filesystem Paths
 
-### OpenClaw files
-- `<resolved-openclaw-state>/openclaw.json` (legacy filenames may exist: `clawdbot.json`, `moldbot.json`, `moltbot.json`)
-- `<resolved-openclaw-state>/hooks/transforms/relay-to-peer.mjs`
-- `<resolved-openclaw-state>/hooks/transforms/clawdentity-relay.json`
-- `<resolved-openclaw-state>/hooks/transforms/clawdentity-peers.json`
-- `<resolved-openclaw-state>/skills/clawdentity-openclaw-relay/SKILL.md`
-- env overrides:
-  - `OPENCLAW_CONFIG_PATH`, `CLAWDBOT_CONFIG_PATH`
-  - `OPENCLAW_STATE_DIR`, `CLAWDBOT_STATE_DIR`
-  - `OPENCLAW_HOME` (used when explicit config/state overrides are unset)
-
-### Clawdentity files
-- `~/.clawdentity/config.json`
-- `~/.clawdentity/agents/<agent-name>/secret.key`
-- `~/.clawdentity/agents/<agent-name>/public.key`
-- `~/.clawdentity/agents/<agent-name>/identity.json`
-- `~/.clawdentity/agents/<agent-name>/registry-auth.json`
-- `~/.clawdentity/agents/<agent-name>/ait.jwt`
-- `~/.clawdentity/peers.json`
-- `~/.clawdentity/openclaw-agent-name`
-- `~/.clawdentity/openclaw-relay.json`
-- `~/.clawdentity/openclaw-connectors.json`
-- `~/.clawdentity/pairing/` (ephemeral QR PNG storage, auto-cleaned after 900s)
-- `~/.clawdentity/cache/registry-keys.json` (1-hour TTL, used by `verify`)
-- `~/.clawdentity/cache/crl-claims.json` (15-minute TTL, used by `verify`)
+Canonical paths are defined in SKILL.md § Filesystem Truth. Refer there for all path contracts.
 
 ## Setup Input Contract
 
@@ -214,32 +190,82 @@ Known defaults:
 
 Recovery: rerun onboarding (`clawdentity invite redeem <clw_inv_...> --display-name <human-name>`) so local config aligns to registry metadata.
 
+## Identity Injection
+
+When identity injection is enabled (proxy env `INJECT_IDENTITY_INTO_MESSAGE`, default `true`), the proxy prepends an identity block to the `message` field of relayed payloads.
+
+### Block format
+
+```
+[Clawdentity Identity]
+agentDid: did:claw:agent:01H...
+ownerDid: did:claw:human:01H...
+issuer: https://registry.clawdentity.com
+aitJti: 01H...
+```
+
+The block is separated from the original message by a blank line (`\n\n`).
+
+### Field definitions
+
+| Field | Description |
+|---|---|
+| `agentDid` | Sender agent DID — use to identify the peer |
+| `ownerDid` | DID of the human who owns the sender agent |
+| `issuer` | Registry URL that issued the sender's AIT |
+| `aitJti` | Unique JTI claim from the sender's AIT |
+
+### Programmatic access
+
+The connector `deliver` frame includes `fromAgentDid` as a top-level field. Inbound inbox items (`ConnectorInboundInboxItem`) also expose `fromAgentDid` for programmatic sender identification without parsing the identity block.
+
 ## Pairing Error Codes
 
 ### `pair start` errors
 
-| HTTP Status | Error Code | Meaning |
-|-------------|-----------|---------|
-| 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_HUMAN_NAME_MISSING` | Local config is missing `humanName`; set via invite redeem or config |
-| — | `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 |
-| — | `CLI_PAIR_REQUEST_FAILED` | Unable to connect to proxy URL |
+| HTTP Status | Error Code | Meaning | Recovery |
+|---|---|---|---|
+| 403 | `PROXY_PAIR_OWNERSHIP_FORBIDDEN` | Initiator ownership check failed | Recreate/refresh the local agent identity |
+| 503 | `PROXY_PAIR_OWNERSHIP_UNAVAILABLE` | Registry ownership lookup unavailable | Check proxy/registry service auth configuration |
+| — | `CLI_PAIR_AGENT_NOT_FOUND` | Agent ait.jwt or secret.key missing/empty | Run `agent create` or `agent auth refresh` |
+| — | `CLI_PAIR_HUMAN_NAME_MISSING` | Local config is missing `humanName` | Set via `invite redeem` or config |
+| — | `CLI_PAIR_PROXY_URL_REQUIRED` | Proxy URL could not be resolved | Run `invite redeem` or set `CLAWDENTITY_PROXY_URL` |
+| — | `CLI_PAIR_START_INVALID_TTL` | ttlSeconds must be a positive integer | Use valid `--ttl-seconds` value |
+| — | `CLI_PAIR_INVALID_PROXY_URL` | Proxy URL is invalid | Fix proxy URL in config |
+| — | `CLI_PAIR_REQUEST_FAILED` | Unable to connect to proxy URL | Check DNS, firewall, proxy URL |
+| — | `CLI_PAIR_START_FAILED` | Generic pair start failure | Retry; check proxy connectivity |
+| — | `CLI_PAIR_PROFILE_INVALID` | Name too long, contains control characters, or empty | Fix agent or human name |
 
 ### `pair confirm` errors
 
-| HTTP Status | Error Code | Meaning |
-|-------------|-----------|---------|
-| 404 | `PROXY_PAIR_TICKET_NOT_FOUND` | Pairing ticket is invalid or expired |
-| 410 | `PROXY_PAIR_TICKET_EXPIRED` | Pairing ticket has expired |
-| — | `CLI_PAIR_CONFIRM_TICKET_REQUIRED` | Either --ticket or --qr-file is required |
-| — | `CLI_PAIR_CONFIRM_INPUT_CONFLICT` | Cannot provide both --ticket and --qr-file |
-| — | `CLI_PAIR_CONFIRM_TICKET_INVALID` | Pairing ticket is invalid |
-| — | `CLI_PAIR_CONFIRM_QR_FILE_NOT_FOUND` | QR file not found |
-| — | `CLI_PAIR_CONFIRM_QR_NOT_FOUND` | No pairing QR code found in image |
+| HTTP Status | Error Code | Meaning | Recovery |
+|---|---|---|---|
+| 404 | `PROXY_PAIR_TICKET_NOT_FOUND` | Pairing ticket is invalid or expired | Request new ticket from initiator |
+| 410 | `PROXY_PAIR_TICKET_EXPIRED` | Pairing ticket has expired | Request new ticket |
+| — | `CLI_PAIR_CONFIRM_TICKET_REQUIRED` | Either --ticket or --qr-file is required | Provide one input path |
+| — | `CLI_PAIR_CONFIRM_INPUT_CONFLICT` | Cannot provide both --ticket and --qr-file | Use one input path only |
+| — | `CLI_PAIR_CONFIRM_TICKET_INVALID` | Pairing ticket is invalid | Get new ticket from initiator |
+| — | `CLI_PAIR_CONFIRM_QR_FILE_NOT_FOUND` | QR file not found | Verify file path |
+| — | `CLI_PAIR_CONFIRM_QR_NOT_FOUND` | No pairing QR code found in image | Request new QR from initiator |
+| — | `CLI_PAIR_CONFIRM_FAILED` | Generic pair confirm failure | Retry with new ticket |
+| — | `CLI_PAIR_CONFIRM_QR_FILE_INVALID` | QR image file corrupt or unsupported | Request new QR from initiator |
+| — | `CLI_PAIR_CONFIRM_QR_FILE_REQUIRED` | QR path unusable | Verify file path and format |
+
+### `pair status` errors
+
+| HTTP Status | Error Code | Meaning | Recovery |
+|---|---|---|---|
+| — | `CLI_PAIR_STATUS_FAILED` | Generic pair status failure | Retry |
+| — | `CLI_PAIR_STATUS_WAIT_TIMEOUT` | Wait polling timed out | Generate new ticket via `pair start` |
+| — | `CLI_PAIR_STATUS_FORBIDDEN` | 403 on status check — ownership mismatch | Verify correct agent |
+| — | `CLI_PAIR_STATUS_TICKET_REQUIRED` | Missing ticket argument | Provide `--ticket <clwpair1_...>` |
+
+### Peer persistence errors
+
+| Error Code | Meaning | Recovery |
+|---|---|---|
+| `CLI_PAIR_PEERS_CONFIG_INVALID` | `peers.json` corrupt or invalid structure | Delete `peers.json` and re-pair |
+| `CLI_PAIR_PEER_ALIAS_INVALID` | Derived alias fails validation | Re-pair with valid agent DID |
 
 ## Cache Files
 
@@ -261,3 +287,38 @@ When `pair confirm` saves a new peer, alias is derived automatically:
 5. Fallback alias is `peer` if DID is not a valid agent DID.
 
 Alias validation: `[a-zA-Z0-9._-]`, max 128 characters.
+
+## Container Environments
+
+When running in Docker or similar container runtimes:
+
+- `openclaw setup` writes Docker-aware endpoint candidates into `clawdentity-relay.json`:
+  - `host.docker.internal`, `gateway.docker.internal`, Linux bridge (`172.17.0.1`), default gateway, and loopback.
+  - Candidates are attempted in order by the relay transform.
+- Use `--no-runtime-start` when the connector runs as a separate container or process.
+- Required env overrides for container networking:
+  - `OPENCLAW_BASE_URL` — point to OpenClaw inside/outside the container network.
+  - `CLAWDENTITY_CONNECTOR_BASE_URL` — point to the connector's bind address from the transform's perspective.
+- Port allocation: each agent gets its own connector port starting from `19400`.
+  - Port assignment is tracked in `~/.clawdentity/openclaw-connectors.json`.
+
+## Doctor Check Reference
+
+Run `clawdentity openclaw doctor --json` for machine-readable diagnostics.
+
+| Check ID | Validates | Remediation on Failure |
+|---|---|---|
+| `config.registry` | `registryUrl`, `apiKey`, and `proxyUrl` in config (or proxy env override) | `clawdentity config init` or `invite redeem` |
+| `state.selectedAgent` | Agent marker at `~/.clawdentity/openclaw-agent-name` | `clawdentity openclaw setup <agent-name>` |
+| `state.credentials` | `ait.jwt` and `secret.key` exist and non-empty | `clawdentity agent create <agent-name>` or `agent auth refresh <agent-name>` |
+| `state.peers` | Peers config valid; requested `--peer` alias exists | `clawdentity pair start` / `pair confirm` (optional until pairing) |
+| `state.transform` | Relay transform artifacts in OpenClaw hooks dir | Reinstall skill package or `openclaw setup <agent-name>` |
+| `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.hookSessionRouting` | `hooks.defaultSessionKey`, `hooks.allowRequestSessionKey=false`, and required prefixes | `clawdentity openclaw setup <agent-name>` then restart OpenClaw |
+| `state.gatewayAuth` | OpenClaw `gateway.auth` readiness (`mode` + required credential) | `clawdentity openclaw setup <agent-name>` to re-sync gateway auth |
+| `state.gatewayDevicePairing` | Pending OpenClaw device approvals | Re-run `clawdentity openclaw setup <agent-name>` so setup auto-recovers approvals |
+| `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>` |
+| `state.connectorInboundInbox` | Connector local inbound inbox backlog and replay queue state | Re-run `clawdentity openclaw setup <agent-name>` and verify connector runtime health |
+| `state.openclawHookHealth` | Connector replay status for local OpenClaw hook delivery | Re-run `clawdentity openclaw setup <agent-name>` and restart OpenClaw if hook replay stays failed |

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

@@ -173,3 +173,14 @@ Admin-only. Creates a registry invite code (`clw_inv_...`) for onboarding new us
 | 401 | Authentication failed |
 | 403 | Requires admin access |
 | 400 | Invalid request |
+
+## Connector Errors
+
+| Error Code | Meaning | Recovery |
+|---|---|---|
+| `CLI_CONNECTOR_SERVICE_PLATFORM_INVALID` | Invalid platform argument | Use `auto`, `launchd`, or `systemd` |
+| `CLI_CONNECTOR_SERVICE_PLATFORM_UNSUPPORTED` | OS unsupported for selected platform | Use a supported platform (macOS: launchd, Linux: systemd) |
+| `CLI_CONNECTOR_SERVICE_INSTALL_FAILED` | Service install failed | Check permissions, systemd/launchd status |
+| `CLI_CONNECTOR_PROXY_URL_REQUIRED` | Proxy URL unresolvable | Run `invite redeem` or set `CLAWDENTITY_PROXY_URL` / `CLAWDENTITY_PROXY_WS_URL` |
+| `CLI_CONNECTOR_INVALID_REGISTRY_AUTH` | `registry-auth.json` corrupt or invalid | Run `clawdentity agent auth refresh <agent-name>` |
+| `CLI_CONNECTOR_INVALID_AGENT_IDENTITY` | `identity.json` corrupt or invalid | Re-create agent with `clawdentity agent create <agent-name>` |