clawdentity 0.0.18 → 0.0.19

package/dist/bin.js

@@ -21090,7 +21090,6 @@ var HOOK_PATH_SEND_TO_PEER = "send-to-peer";
 var OPENCLAW_SEND_TO_PEER_HOOK_PATH = "hooks/send-to-peer";
 var DEFAULT_OPENCLAW_BASE_URL2 = "http://127.0.0.1:18789";
 var DEFAULT_OPENCLAW_MAIN_SESSION_KEY = "main";
-var DEFAULT_OPENCLAW_AGENT_ID = "main";
 var DEFAULT_CONNECTOR_PORT = 19400;
 var DEFAULT_CONNECTOR_OUTBOUND_PATH3 = "/v1/outbound";
 var DEFAULT_CONNECTOR_STATUS_PATH2 = "/v1/status";
@@ -21107,6 +21106,7 @@ var OPENCLAW_SETUP_COMMAND_HINT = "Run: clawdentity openclaw setup <agentName>";
 var OPENCLAW_SETUP_RESTART_COMMAND_HINT = `${OPENCLAW_SETUP_COMMAND_HINT} and restart OpenClaw`;
 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_COMMAND_HINT = "Run: openclaw devices list and openclaw devices approve <requestId>";
 var textEncoder2 = new TextEncoder();
 var textDecoder = new TextDecoder();
 function isRecord8(value) {
@@ -21773,9 +21773,11 @@ function parseRelayRuntimeConfig(value, relayRuntimeConfigPath) {
   }
   const updatedAt = typeof value.updatedAt === "string" && value.updatedAt.trim().length > 0 ? value.updatedAt.trim() : void 0;
   const openclawHookToken = typeof value.openclawHookToken === "string" && value.openclawHookToken.trim().length > 0 ? value.openclawHookToken.trim() : void 0;
+  const relayTransformPeersPath = typeof value.relayTransformPeersPath === "string" && value.relayTransformPeersPath.trim().length > 0 ? value.relayTransformPeersPath.trim() : void 0;
   return {
     openclawBaseUrl: parseOpenclawBaseUrl(value.openclawBaseUrl),
     openclawHookToken,
+    relayTransformPeersPath,
     updatedAt
   };
 }
@@ -21791,10 +21793,11 @@ async function loadRelayRuntimeConfig(relayRuntimeConfigPath) {
   }
   return parseRelayRuntimeConfig(parsed, relayRuntimeConfigPath);
 }
-async function saveRelayRuntimeConfig(relayRuntimeConfigPath, openclawBaseUrl, openclawHookToken) {
+async function saveRelayRuntimeConfig(relayRuntimeConfigPath, openclawBaseUrl, openclawHookToken, relayTransformPeersPath) {
   const config2 = {
     openclawBaseUrl,
     ...openclawHookToken ? { openclawHookToken } : {},
+    ...relayTransformPeersPath ? { relayTransformPeersPath } : {},
     updatedAt: nowIso()
   };
   await writeSecureFile3(
@@ -21841,33 +21844,40 @@ function normalizeStringArrayWithValues(value, requiredValues) {
   return Array.from(normalized);
 }
 function resolveHookDefaultSessionKey(config2, hooks) {
-  if (typeof hooks.defaultSessionKey === "string" && hooks.defaultSessionKey.trim().length > 0) {
-    return hooks.defaultSessionKey.trim();
-  }
   const session = isRecord8(config2.session) ? config2.session : {};
   const scope = typeof session.scope === "string" ? session.scope.trim().toLowerCase() : "";
+  const configuredMainSessionKey = resolveConfiguredOpenclawMainSessionKey(session);
+  if (typeof hooks.defaultSessionKey === "string" && hooks.defaultSessionKey.trim().length > 0) {
+    return normalizeLegacyHookDefaultSessionKey(
+      hooks.defaultSessionKey,
+      configuredMainSessionKey
+    );
+  }
   if (scope === "global") {
     return "global";
   }
-  const agents = isRecord8(config2.agents) ? config2.agents : {};
-  const agentList = Array.isArray(agents.list) ? agents.list : [];
-  const defaultAgentId = resolveDefaultOpenclawAgentId(agentList);
-  return `agent:${defaultAgentId}:${DEFAULT_OPENCLAW_MAIN_SESSION_KEY}`;
+  return configuredMainSessionKey;
 }
-function resolveDefaultOpenclawAgentId(agentList) {
-  const preferred = agentList.find(
-    (agent) => isRecord8(agent) && agent.default === true && typeof agent.id === "string" && agent.id.trim().length > 0
-  ) ?? agentList.find(
-    (agent) => isRecord8(agent) && typeof agent.id === "string" && agent.id.trim().length > 0
-  );
-  if (isRecord8(preferred) && typeof preferred.id === "string" && preferred.id.trim().length > 0) {
-    return normalizeOpenclawIdToken(preferred.id, DEFAULT_OPENCLAW_AGENT_ID);
+function resolveConfiguredOpenclawMainSessionKey(session) {
+  if (typeof session.mainKey === "string" && session.mainKey.trim().length > 0) {
+    return session.mainKey.trim();
   }
-  return DEFAULT_OPENCLAW_AGENT_ID;
+  return DEFAULT_OPENCLAW_MAIN_SESSION_KEY;
 }
-function normalizeOpenclawIdToken(value, fallback) {
-  const normalized = value.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+/g, "").replace(/-+$/g, "").slice(0, 64);
-  return normalized.length > 0 ? normalized : fallback;
+function normalizeLegacyHookDefaultSessionKey(value, fallbackSessionKey) {
+  const trimmed = value.trim();
+  const legacyMatch = /^agent:[^:]+:(.+)$/i.exec(trimmed);
+  if (!legacyMatch) {
+    return trimmed;
+  }
+  const routedSessionKey = legacyMatch[1]?.trim();
+  if (typeof routedSessionKey === "string" && routedSessionKey.length > 0) {
+    return routedSessionKey;
+  }
+  return fallbackSessionKey;
+}
+function isCanonicalAgentSessionKey(value) {
+  return /^agent:[^:]+:.+/i.test(value.trim());
 }
 function generateOpenclawHookToken() {
   return randomBytes3(OPENCLAW_HOOK_TOKEN_BYTES).toString("hex");
@@ -22051,103 +22061,105 @@ async function runOpenclawDoctor(options = {}) {
   const openclawDir = resolveOpenclawDir(options.openclawDir, homeDir);
   const peerAlias = parseDoctorPeerAlias(options.peerAlias);
   const checks = [];
-  const resolveConfigImpl = options.resolveConfigImpl ?? resolveConfig;
-  try {
-    const resolvedConfig = await resolveConfigImpl();
-    const envProxyUrl = typeof process.env.CLAWDENTITY_PROXY_URL === "string" ? process.env.CLAWDENTITY_PROXY_URL.trim() : "";
-    if (typeof resolvedConfig.registryUrl !== "string" || resolvedConfig.registryUrl.trim().length === 0) {
-      checks.push(
-        toDoctorCheck({
-          id: "config.registry",
-          label: "CLI config",
-          status: "fail",
-          message: "registryUrl is missing",
-          remediationHint: "Run: clawdentity config set registryUrl <REGISTRY_URL>"
-        })
-      );
-    } else if (typeof resolvedConfig.apiKey !== "string" || resolvedConfig.apiKey.trim().length === 0) {
-      checks.push(
-        toDoctorCheck({
-          id: "config.registry",
-          label: "CLI config",
-          status: "fail",
-          message: "apiKey is missing",
-          remediationHint: "Run: clawdentity config set apiKey <API_KEY>"
-        })
-      );
-    } else if (envProxyUrl.length > 0) {
-      let hasValidEnvProxyUrl = true;
-      try {
-        parseProxyUrl(envProxyUrl);
-      } catch {
-        hasValidEnvProxyUrl = false;
+  if (options.includeConfigCheck !== false) {
+    const resolveConfigImpl = options.resolveConfigImpl ?? resolveConfig;
+    try {
+      const resolvedConfig = await resolveConfigImpl();
+      const envProxyUrl = typeof process.env.CLAWDENTITY_PROXY_URL === "string" ? process.env.CLAWDENTITY_PROXY_URL.trim() : "";
+      if (typeof resolvedConfig.registryUrl !== "string" || resolvedConfig.registryUrl.trim().length === 0) {
         checks.push(
           toDoctorCheck({
             id: "config.registry",
             label: "CLI config",
             status: "fail",
-            message: "CLAWDENTITY_PROXY_URL is invalid",
-            remediationHint: "Set CLAWDENTITY_PROXY_URL to a valid http(s) URL or unset it"
+            message: "registryUrl is missing",
+            remediationHint: "Run: clawdentity config set registryUrl <REGISTRY_URL>"
           })
         );
-      }
-      if (hasValidEnvProxyUrl) {
+      } else if (typeof resolvedConfig.apiKey !== "string" || resolvedConfig.apiKey.trim().length === 0) {
         checks.push(
           toDoctorCheck({
             id: "config.registry",
             label: "CLI config",
-            status: "pass",
-            message: "registryUrl and apiKey are configured (proxy URL override is active via CLAWDENTITY_PROXY_URL)"
+            status: "fail",
+            message: "apiKey is missing",
+            remediationHint: "Run: clawdentity config set apiKey <API_KEY>"
           })
         );
-      }
-    } else if (typeof resolvedConfig.proxyUrl !== "string" || resolvedConfig.proxyUrl.trim().length === 0) {
-      checks.push(
-        toDoctorCheck({
-          id: "config.registry",
-          label: "CLI config",
-          status: "fail",
-          message: "proxyUrl is missing",
-          remediationHint: "Run: clawdentity invite redeem <clw_inv_...> or clawdentity config init"
-        })
-      );
-    } else {
-      let hasValidConfigProxyUrl = true;
-      try {
-        parseProxyUrl(resolvedConfig.proxyUrl);
-      } catch {
-        hasValidConfigProxyUrl = false;
+      } else if (envProxyUrl.length > 0) {
+        let hasValidEnvProxyUrl = true;
+        try {
+          parseProxyUrl(envProxyUrl);
+        } catch {
+          hasValidEnvProxyUrl = false;
+          checks.push(
+            toDoctorCheck({
+              id: "config.registry",
+              label: "CLI config",
+              status: "fail",
+              message: "CLAWDENTITY_PROXY_URL is invalid",
+              remediationHint: "Set CLAWDENTITY_PROXY_URL to a valid http(s) URL or unset it"
+            })
+          );
+        }
+        if (hasValidEnvProxyUrl) {
+          checks.push(
+            toDoctorCheck({
+              id: "config.registry",
+              label: "CLI config",
+              status: "pass",
+              message: "registryUrl and apiKey are configured (proxy URL override is active via CLAWDENTITY_PROXY_URL)"
+            })
+          );
+        }
+      } else if (typeof resolvedConfig.proxyUrl !== "string" || resolvedConfig.proxyUrl.trim().length === 0) {
         checks.push(
           toDoctorCheck({
             id: "config.registry",
             label: "CLI config",
             status: "fail",
-            message: "proxyUrl is invalid",
+            message: "proxyUrl is missing",
             remediationHint: "Run: clawdentity invite redeem <clw_inv_...> or clawdentity config init"
           })
         );
+      } else {
+        let hasValidConfigProxyUrl = true;
+        try {
+          parseProxyUrl(resolvedConfig.proxyUrl);
+        } catch {
+          hasValidConfigProxyUrl = false;
+          checks.push(
+            toDoctorCheck({
+              id: "config.registry",
+              label: "CLI config",
+              status: "fail",
+              message: "proxyUrl is invalid",
+              remediationHint: "Run: clawdentity invite redeem <clw_inv_...> or clawdentity config init"
+            })
+          );
+        }
+        if (hasValidConfigProxyUrl) {
+          checks.push(
+            toDoctorCheck({
+              id: "config.registry",
+              label: "CLI config",
+              status: "pass",
+              message: "registryUrl, apiKey, and proxyUrl are configured"
+            })
+          );
+        }
       }
-      if (hasValidConfigProxyUrl) {
-        checks.push(
-          toDoctorCheck({
-            id: "config.registry",
-            label: "CLI config",
-            status: "pass",
-            message: "registryUrl, apiKey, and proxyUrl are configured"
-          })
-        );
-      }
+    } catch {
+      checks.push(
+        toDoctorCheck({
+          id: "config.registry",
+          label: "CLI config",
+          status: "fail",
+          message: "unable to resolve CLI config",
+          remediationHint: "Fix ~/.clawdentity/config.json or rerun: clawdentity config init"
+        })
+      );
     }
-  } catch {
-    checks.push(
-      toDoctorCheck({
-        id: "config.registry",
-        label: "CLI config",
-        status: "fail",
-        message: "unable to resolve CLI config",
-        remediationHint: "Fix ~/.clawdentity/config.json or rerun: clawdentity config init"
-      })
-    );
   }
   const selectedAgentPath = resolveOpenclawAgentNamePath(homeDir);
   let selectedAgentName;
@@ -22336,6 +22348,15 @@ async function runOpenclawDoctor(options = {}) {
     const hooks = isRecord8(openclawConfig.hooks) ? openclawConfig.hooks : {};
     const hooksEnabled = hooks.enabled === true;
     const hookToken = typeof hooks.token === "string" && hooks.token.trim().length > 0 ? hooks.token.trim() : void 0;
+    const defaultSessionKey = typeof hooks.defaultSessionKey === "string" && hooks.defaultSessionKey.trim().length > 0 ? hooks.defaultSessionKey.trim() : void 0;
+    const allowRequestSessionKey = hooks.allowRequestSessionKey === false;
+    const allowedSessionKeyPrefixes = normalizeStringArrayWithValues(
+      hooks.allowedSessionKeyPrefixes,
+      []
+    );
+    const missingRequiredSessionPrefixes = defaultSessionKey === void 0 ? ["hook:"] : ["hook:", defaultSessionKey].filter(
+      (prefix) => !allowedSessionKeyPrefixes.includes(prefix)
+    );
     const mappings = Array.isArray(hooks.mappings) ? hooks.mappings.filter(isRecord8) : [];
     const relayMapping = mappings.find(
       (mapping) => isRelayHookMapping(mapping)
@@ -22395,6 +22416,45 @@ async function runOpenclawDoctor(options = {}) {
         })
       );
     }
+    const sessionRoutingIssues = [];
+    if (defaultSessionKey === void 0) {
+      sessionRoutingIssues.push("hooks.defaultSessionKey is missing");
+    }
+    if (!allowRequestSessionKey) {
+      sessionRoutingIssues.push("hooks.allowRequestSessionKey is not false");
+    }
+    if (missingRequiredSessionPrefixes.length > 0) {
+      sessionRoutingIssues.push(
+        `hooks.allowedSessionKeyPrefixes is missing: ${missingRequiredSessionPrefixes.join(", ")}`
+      );
+    }
+    if (defaultSessionKey !== void 0 && isCanonicalAgentSessionKey(defaultSessionKey)) {
+      sessionRoutingIssues.push(
+        "hooks.defaultSessionKey uses canonical agent format (agent:<id>:...); use OpenClaw request session keys like main, global, or subagent:*"
+      );
+    }
+    if (sessionRoutingIssues.length > 0) {
+      checks.push(
+        toDoctorCheck({
+          id: "state.hookSessionRouting",
+          label: "OpenClaw hook session routing",
+          status: "fail",
+          message: sessionRoutingIssues.join("; "),
+          remediationHint: OPENCLAW_SETUP_RESTART_COMMAND_HINT,
+          details: { openclawConfigPath }
+        })
+      );
+    } else {
+      checks.push(
+        toDoctorCheck({
+          id: "state.hookSessionRouting",
+          label: "OpenClaw hook session routing",
+          status: "pass",
+          message: "hooks default session and allowed session prefixes are configured",
+          details: { openclawConfigPath }
+        })
+      );
+    }
   } catch {
     checks.push(
       toDoctorCheck({
@@ -22416,6 +22476,16 @@ async function runOpenclawDoctor(options = {}) {
         details: { openclawConfigPath }
       })
     );
+    checks.push(
+      toDoctorCheck({
+        id: "state.hookSessionRouting",
+        label: "OpenClaw hook session routing",
+        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 {
@@ -22441,6 +22511,72 @@ async function runOpenclawDoctor(options = {}) {
       })
     );
   }
+  const gatewayDevicePendingPath = join6(openclawDir, "devices", "pending.json");
+  try {
+    const pendingPayload = await readJsonFile(gatewayDevicePendingPath);
+    if (!isRecord8(pendingPayload)) {
+      checks.push(
+        toDoctorCheck({
+          id: "state.gatewayDevicePairing",
+          label: "OpenClaw gateway device pairing",
+          status: "fail",
+          message: `invalid pending device approvals file: ${gatewayDevicePendingPath}`,
+          remediationHint: OPENCLAW_DEVICE_APPROVAL_COMMAND_HINT,
+          details: { gatewayDevicePendingPath }
+        })
+      );
+    } else {
+      const pendingRequestIds = Object.keys(pendingPayload);
+      if (pendingRequestIds.length === 0) {
+        checks.push(
+          toDoctorCheck({
+            id: "state.gatewayDevicePairing",
+            label: "OpenClaw gateway device pairing",
+            status: "pass",
+            message: "no pending gateway device approvals",
+            details: { gatewayDevicePendingPath }
+          })
+        );
+      } else {
+        checks.push(
+          toDoctorCheck({
+            id: "state.gatewayDevicePairing",
+            label: "OpenClaw gateway device pairing",
+            status: "fail",
+            message: `pending gateway device approvals: ${pendingRequestIds.length}`,
+            remediationHint: OPENCLAW_DEVICE_APPROVAL_COMMAND_HINT,
+            details: {
+              gatewayDevicePendingPath,
+              pendingRequestIds
+            }
+          })
+        );
+      }
+    }
+  } catch (error48) {
+    if (getErrorCode2(error48) === "ENOENT") {
+      checks.push(
+        toDoctorCheck({
+          id: "state.gatewayDevicePairing",
+          label: "OpenClaw gateway device pairing",
+          status: "pass",
+          message: "no pending gateway device approvals file was found",
+          details: { gatewayDevicePendingPath }
+        })
+      );
+    } else {
+      checks.push(
+        toDoctorCheck({
+          id: "state.gatewayDevicePairing",
+          label: "OpenClaw gateway device pairing",
+          status: "fail",
+          message: `unable to read pending device approvals at ${gatewayDevicePendingPath}`,
+          remediationHint: OPENCLAW_DEVICE_APPROVAL_COMMAND_HINT,
+          details: { gatewayDevicePendingPath }
+        })
+      );
+    }
+  }
   if (options.includeConnectorRuntimeCheck !== false) {
     if (selectedAgentName === void 0) {
       checks.push(
@@ -22803,7 +22939,8 @@ async function setupOpenclawRelay(agentName, options) {
   await saveRelayRuntimeConfig(
     relayRuntimeConfigPath,
     openclawBaseUrl,
-    patchedOpenclawConfig.hookToken
+    patchedOpenclawConfig.hookToken,
+    relayTransformPeersPath
   );
   logger8.info("cli.openclaw_setup_completed", {
     agentName: normalizedAgentName,
@@ -22825,9 +22962,45 @@ async function setupOpenclawRelay(agentName, options) {
     relayRuntimeConfigPath
   };
 }
+async function assertSetupChecklistHealthy(input) {
+  const checklist = await runOpenclawDoctor({
+    homeDir: input.homeDir,
+    openclawDir: input.openclawDir,
+    includeConfigCheck: false,
+    includeConnectorRuntimeCheck: input.includeConnectorRuntimeCheck
+  });
+  if (checklist.status === "healthy") {
+    return;
+  }
+  const firstFailure = checklist.checks.find((check2) => check2.status === "fail");
+  throw createCliError6(
+    "CLI_OPENCLAW_SETUP_CHECKLIST_FAILED",
+    "OpenClaw setup checklist failed",
+    {
+      firstFailedCheckId: firstFailure?.id,
+      firstFailedCheckMessage: firstFailure?.message,
+      remediationHint: firstFailure?.remediationHint,
+      checks: checklist.checks
+    }
+  );
+}
 async function setupOpenclawSelfReady(agentName, options) {
-  const setup = await setupOpenclawRelay(agentName, options);
+  const resolvedHomeDir = resolveHomeDir(options.homeDir);
+  const resolvedOpenclawDir = resolveOpenclawDir(
+    options.openclawDir,
+    resolvedHomeDir
+  );
+  const setup = await setupOpenclawRelay(agentName, {
+    ...options,
+    homeDir: resolvedHomeDir,
+    openclawDir: resolvedOpenclawDir
+  });
   if (options.noRuntimeStart === true) {
+    await assertSetupChecklistHealthy({
+      homeDir: resolvedHomeDir,
+      openclawDir: resolvedOpenclawDir,
+      includeConnectorRuntimeCheck: false
+    });
     return {
       ...setup,
       runtimeMode: "none",
@@ -22846,7 +23019,6 @@ async function setupOpenclawSelfReady(agentName, options) {
   const waitTimeoutSeconds = parseWaitTimeoutSeconds(
     options.waitTimeoutSeconds
   );
-  const resolvedHomeDir = resolveHomeDir(options.homeDir);
   const runtime = await startSetupConnectorRuntime({
     agentName: assertValidAgentName(agentName),
     homeDir: resolvedHomeDir,
@@ -22856,6 +23028,11 @@ async function setupOpenclawSelfReady(agentName, options) {
     waitTimeoutSeconds,
     fetchImpl
   });
+  await assertSetupChecklistHealthy({
+    homeDir: resolvedHomeDir,
+    openclawDir: resolvedOpenclawDir,
+    includeConnectorRuntimeCheck: true
+  });
   return {
     ...setup,
     ...runtime
@@ -23001,6 +23178,7 @@ var AIT_FILE_NAME4 = "ait.jwt";
 var SECRET_KEY_FILE_NAME3 = "secret.key";
 var PAIRING_QR_DIR_NAME = "pairing";
 var PEERS_FILE_NAME2 = "peers.json";
+var OPENCLAW_RELAY_RUNTIME_FILE_NAME3 = "openclaw-relay.json";
 var PAIR_START_PATH = "/pair/start";
 var PAIR_CONFIRM_PATH = "/pair/confirm";
 var PAIR_STATUS_PATH = "/pair/status";
@@ -23303,6 +23481,86 @@ async function savePeersConfig2(input) {
   );
   await input.chmodImpl(peersPath, FILE_MODE4);
 }
+function resolveRelayRuntimeConfigPath2(getConfigDirImpl) {
+  return join7(getConfigDirImpl(), OPENCLAW_RELAY_RUNTIME_FILE_NAME3);
+}
+async function loadRelayTransformPeersPath(input) {
+  const relayRuntimeConfigPath = resolveRelayRuntimeConfigPath2(
+    input.getConfigDirImpl
+  );
+  let raw;
+  try {
+    raw = await input.readFileImpl(relayRuntimeConfigPath, "utf8");
+  } catch (error48) {
+    const nodeError = error48;
+    if (nodeError.code === "ENOENT") {
+      return void 0;
+    }
+    logger9.warn("cli.pair.relay_runtime_read_failed", {
+      relayRuntimeConfigPath,
+      reason: error48 instanceof Error && error48.message.length > 0 ? error48.message : "unknown"
+    });
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    logger9.warn("cli.pair.relay_runtime_invalid_json", {
+      relayRuntimeConfigPath
+    });
+    return void 0;
+  }
+  if (!isRecord9(parsed)) {
+    return void 0;
+  }
+  const relayTransformPeersPath = parseNonEmptyString9(
+    parsed.relayTransformPeersPath
+  );
+  if (relayTransformPeersPath.length === 0) {
+    return void 0;
+  }
+  return resolve(relayTransformPeersPath);
+}
+async function syncOpenclawRelayPeersSnapshot(input) {
+  const relayTransformPeersPath = await loadRelayTransformPeersPath({
+    getConfigDirImpl: input.getConfigDirImpl,
+    readFileImpl: input.readFileImpl
+  });
+  if (relayTransformPeersPath === void 0) {
+    return;
+  }
+  try {
+    await input.readFileImpl(relayTransformPeersPath, "utf8");
+  } catch (error48) {
+    const nodeError = error48;
+    if (nodeError.code === "ENOENT") {
+      return;
+    }
+    logger9.warn("cli.pair.relay_peers_snapshot_probe_failed", {
+      relayTransformPeersPath,
+      reason: error48 instanceof Error && error48.message.length > 0 ? error48.message : "unknown"
+    });
+    return;
+  }
+  try {
+    await input.mkdirImpl(dirname5(relayTransformPeersPath), {
+      recursive: true
+    });
+    await input.writeFileImpl(
+      relayTransformPeersPath,
+      `${JSON.stringify(input.config, null, 2)}
+`,
+      "utf8"
+    );
+    await input.chmodImpl(relayTransformPeersPath, FILE_MODE4);
+  } catch (error48) {
+    logger9.warn("cli.pair.relay_peers_snapshot_write_failed", {
+      relayTransformPeersPath,
+      reason: error48 instanceof Error && error48.message.length > 0 ? error48.message : "unknown"
+    });
+  }
+}
 function parseTtlSeconds(value) {
   const raw = parseNonEmptyString9(value);
   if (raw.length === 0) {
@@ -23828,6 +24086,14 @@ async function persistPairedPeer(input) {
     writeFileImpl,
     chmodImpl
   });
+  await syncOpenclawRelayPeersSnapshot({
+    config: peersConfig,
+    getConfigDirImpl,
+    readFileImpl,
+    mkdirImpl,
+    writeFileImpl,
+    chmodImpl
+  });
   return alias;
 }
 async function startPairing(agentName, options, dependencies = {}) {

package/dist/index.js

@@ -21090,7 +21090,6 @@ var HOOK_PATH_SEND_TO_PEER = "send-to-peer";
 var OPENCLAW_SEND_TO_PEER_HOOK_PATH = "hooks/send-to-peer";
 var DEFAULT_OPENCLAW_BASE_URL2 = "http://127.0.0.1:18789";
 var DEFAULT_OPENCLAW_MAIN_SESSION_KEY = "main";
-var DEFAULT_OPENCLAW_AGENT_ID = "main";
 var DEFAULT_CONNECTOR_PORT = 19400;
 var DEFAULT_CONNECTOR_OUTBOUND_PATH3 = "/v1/outbound";
 var DEFAULT_CONNECTOR_STATUS_PATH2 = "/v1/status";
@@ -21107,6 +21106,7 @@ var OPENCLAW_SETUP_COMMAND_HINT = "Run: clawdentity openclaw setup <agentName>";
 var OPENCLAW_SETUP_RESTART_COMMAND_HINT = `${OPENCLAW_SETUP_COMMAND_HINT} and restart OpenClaw`;
 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_COMMAND_HINT = "Run: openclaw devices list and openclaw devices approve <requestId>";
 var textEncoder2 = new TextEncoder();
 var textDecoder = new TextDecoder();
 function isRecord8(value) {
@@ -21773,9 +21773,11 @@ function parseRelayRuntimeConfig(value, relayRuntimeConfigPath) {
   }
   const updatedAt = typeof value.updatedAt === "string" && value.updatedAt.trim().length > 0 ? value.updatedAt.trim() : void 0;
   const openclawHookToken = typeof value.openclawHookToken === "string" && value.openclawHookToken.trim().length > 0 ? value.openclawHookToken.trim() : void 0;
+  const relayTransformPeersPath = typeof value.relayTransformPeersPath === "string" && value.relayTransformPeersPath.trim().length > 0 ? value.relayTransformPeersPath.trim() : void 0;
   return {
     openclawBaseUrl: parseOpenclawBaseUrl(value.openclawBaseUrl),
     openclawHookToken,
+    relayTransformPeersPath,
     updatedAt
   };
 }
@@ -21791,10 +21793,11 @@ async function loadRelayRuntimeConfig(relayRuntimeConfigPath) {
   }
   return parseRelayRuntimeConfig(parsed, relayRuntimeConfigPath);
 }
-async function saveRelayRuntimeConfig(relayRuntimeConfigPath, openclawBaseUrl, openclawHookToken) {
+async function saveRelayRuntimeConfig(relayRuntimeConfigPath, openclawBaseUrl, openclawHookToken, relayTransformPeersPath) {
   const config2 = {
     openclawBaseUrl,
     ...openclawHookToken ? { openclawHookToken } : {},
+    ...relayTransformPeersPath ? { relayTransformPeersPath } : {},
     updatedAt: nowIso()
   };
   await writeSecureFile3(
@@ -21841,33 +21844,40 @@ function normalizeStringArrayWithValues(value, requiredValues) {
   return Array.from(normalized);
 }
 function resolveHookDefaultSessionKey(config2, hooks) {
-  if (typeof hooks.defaultSessionKey === "string" && hooks.defaultSessionKey.trim().length > 0) {
-    return hooks.defaultSessionKey.trim();
-  }
   const session = isRecord8(config2.session) ? config2.session : {};
   const scope = typeof session.scope === "string" ? session.scope.trim().toLowerCase() : "";
+  const configuredMainSessionKey = resolveConfiguredOpenclawMainSessionKey(session);
+  if (typeof hooks.defaultSessionKey === "string" && hooks.defaultSessionKey.trim().length > 0) {
+    return normalizeLegacyHookDefaultSessionKey(
+      hooks.defaultSessionKey,
+      configuredMainSessionKey
+    );
+  }
   if (scope === "global") {
     return "global";
   }
-  const agents = isRecord8(config2.agents) ? config2.agents : {};
-  const agentList = Array.isArray(agents.list) ? agents.list : [];
-  const defaultAgentId = resolveDefaultOpenclawAgentId(agentList);
-  return `agent:${defaultAgentId}:${DEFAULT_OPENCLAW_MAIN_SESSION_KEY}`;
+  return configuredMainSessionKey;
 }
-function resolveDefaultOpenclawAgentId(agentList) {
-  const preferred = agentList.find(
-    (agent) => isRecord8(agent) && agent.default === true && typeof agent.id === "string" && agent.id.trim().length > 0
-  ) ?? agentList.find(
-    (agent) => isRecord8(agent) && typeof agent.id === "string" && agent.id.trim().length > 0
-  );
-  if (isRecord8(preferred) && typeof preferred.id === "string" && preferred.id.trim().length > 0) {
-    return normalizeOpenclawIdToken(preferred.id, DEFAULT_OPENCLAW_AGENT_ID);
+function resolveConfiguredOpenclawMainSessionKey(session) {
+  if (typeof session.mainKey === "string" && session.mainKey.trim().length > 0) {
+    return session.mainKey.trim();
   }
-  return DEFAULT_OPENCLAW_AGENT_ID;
+  return DEFAULT_OPENCLAW_MAIN_SESSION_KEY;
 }
-function normalizeOpenclawIdToken(value, fallback) {
-  const normalized = value.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+/g, "").replace(/-+$/g, "").slice(0, 64);
-  return normalized.length > 0 ? normalized : fallback;
+function normalizeLegacyHookDefaultSessionKey(value, fallbackSessionKey) {
+  const trimmed = value.trim();
+  const legacyMatch = /^agent:[^:]+:(.+)$/i.exec(trimmed);
+  if (!legacyMatch) {
+    return trimmed;
+  }
+  const routedSessionKey = legacyMatch[1]?.trim();
+  if (typeof routedSessionKey === "string" && routedSessionKey.length > 0) {
+    return routedSessionKey;
+  }
+  return fallbackSessionKey;
+}
+function isCanonicalAgentSessionKey(value) {
+  return /^agent:[^:]+:.+/i.test(value.trim());
 }
 function generateOpenclawHookToken() {
   return randomBytes3(OPENCLAW_HOOK_TOKEN_BYTES).toString("hex");
@@ -22051,103 +22061,105 @@ async function runOpenclawDoctor(options = {}) {
   const openclawDir = resolveOpenclawDir(options.openclawDir, homeDir);
   const peerAlias = parseDoctorPeerAlias(options.peerAlias);
   const checks = [];
-  const resolveConfigImpl = options.resolveConfigImpl ?? resolveConfig;
-  try {
-    const resolvedConfig = await resolveConfigImpl();
-    const envProxyUrl = typeof process.env.CLAWDENTITY_PROXY_URL === "string" ? process.env.CLAWDENTITY_PROXY_URL.trim() : "";
-    if (typeof resolvedConfig.registryUrl !== "string" || resolvedConfig.registryUrl.trim().length === 0) {
-      checks.push(
-        toDoctorCheck({
-          id: "config.registry",
-          label: "CLI config",
-          status: "fail",
-          message: "registryUrl is missing",
-          remediationHint: "Run: clawdentity config set registryUrl <REGISTRY_URL>"
-        })
-      );
-    } else if (typeof resolvedConfig.apiKey !== "string" || resolvedConfig.apiKey.trim().length === 0) {
-      checks.push(
-        toDoctorCheck({
-          id: "config.registry",
-          label: "CLI config",
-          status: "fail",
-          message: "apiKey is missing",
-          remediationHint: "Run: clawdentity config set apiKey <API_KEY>"
-        })
-      );
-    } else if (envProxyUrl.length > 0) {
-      let hasValidEnvProxyUrl = true;
-      try {
-        parseProxyUrl(envProxyUrl);
-      } catch {
-        hasValidEnvProxyUrl = false;
+  if (options.includeConfigCheck !== false) {
+    const resolveConfigImpl = options.resolveConfigImpl ?? resolveConfig;
+    try {
+      const resolvedConfig = await resolveConfigImpl();
+      const envProxyUrl = typeof process.env.CLAWDENTITY_PROXY_URL === "string" ? process.env.CLAWDENTITY_PROXY_URL.trim() : "";
+      if (typeof resolvedConfig.registryUrl !== "string" || resolvedConfig.registryUrl.trim().length === 0) {
         checks.push(
           toDoctorCheck({
             id: "config.registry",
             label: "CLI config",
             status: "fail",
-            message: "CLAWDENTITY_PROXY_URL is invalid",
-            remediationHint: "Set CLAWDENTITY_PROXY_URL to a valid http(s) URL or unset it"
+            message: "registryUrl is missing",
+            remediationHint: "Run: clawdentity config set registryUrl <REGISTRY_URL>"
           })
         );
-      }
-      if (hasValidEnvProxyUrl) {
+      } else if (typeof resolvedConfig.apiKey !== "string" || resolvedConfig.apiKey.trim().length === 0) {
         checks.push(
           toDoctorCheck({
             id: "config.registry",
             label: "CLI config",
-            status: "pass",
-            message: "registryUrl and apiKey are configured (proxy URL override is active via CLAWDENTITY_PROXY_URL)"
+            status: "fail",
+            message: "apiKey is missing",
+            remediationHint: "Run: clawdentity config set apiKey <API_KEY>"
           })
         );
-      }
-    } else if (typeof resolvedConfig.proxyUrl !== "string" || resolvedConfig.proxyUrl.trim().length === 0) {
-      checks.push(
-        toDoctorCheck({
-          id: "config.registry",
-          label: "CLI config",
-          status: "fail",
-          message: "proxyUrl is missing",
-          remediationHint: "Run: clawdentity invite redeem <clw_inv_...> or clawdentity config init"
-        })
-      );
-    } else {
-      let hasValidConfigProxyUrl = true;
-      try {
-        parseProxyUrl(resolvedConfig.proxyUrl);
-      } catch {
-        hasValidConfigProxyUrl = false;
+      } else if (envProxyUrl.length > 0) {
+        let hasValidEnvProxyUrl = true;
+        try {
+          parseProxyUrl(envProxyUrl);
+        } catch {
+          hasValidEnvProxyUrl = false;
+          checks.push(
+            toDoctorCheck({
+              id: "config.registry",
+              label: "CLI config",
+              status: "fail",
+              message: "CLAWDENTITY_PROXY_URL is invalid",
+              remediationHint: "Set CLAWDENTITY_PROXY_URL to a valid http(s) URL or unset it"
+            })
+          );
+        }
+        if (hasValidEnvProxyUrl) {
+          checks.push(
+            toDoctorCheck({
+              id: "config.registry",
+              label: "CLI config",
+              status: "pass",
+              message: "registryUrl and apiKey are configured (proxy URL override is active via CLAWDENTITY_PROXY_URL)"
+            })
+          );
+        }
+      } else if (typeof resolvedConfig.proxyUrl !== "string" || resolvedConfig.proxyUrl.trim().length === 0) {
         checks.push(
           toDoctorCheck({
             id: "config.registry",
             label: "CLI config",
             status: "fail",
-            message: "proxyUrl is invalid",
+            message: "proxyUrl is missing",
             remediationHint: "Run: clawdentity invite redeem <clw_inv_...> or clawdentity config init"
           })
         );
+      } else {
+        let hasValidConfigProxyUrl = true;
+        try {
+          parseProxyUrl(resolvedConfig.proxyUrl);
+        } catch {
+          hasValidConfigProxyUrl = false;
+          checks.push(
+            toDoctorCheck({
+              id: "config.registry",
+              label: "CLI config",
+              status: "fail",
+              message: "proxyUrl is invalid",
+              remediationHint: "Run: clawdentity invite redeem <clw_inv_...> or clawdentity config init"
+            })
+          );
+        }
+        if (hasValidConfigProxyUrl) {
+          checks.push(
+            toDoctorCheck({
+              id: "config.registry",
+              label: "CLI config",
+              status: "pass",
+              message: "registryUrl, apiKey, and proxyUrl are configured"
+            })
+          );
+        }
       }
-      if (hasValidConfigProxyUrl) {
-        checks.push(
-          toDoctorCheck({
-            id: "config.registry",
-            label: "CLI config",
-            status: "pass",
-            message: "registryUrl, apiKey, and proxyUrl are configured"
-          })
-        );
-      }
+    } catch {
+      checks.push(
+        toDoctorCheck({
+          id: "config.registry",
+          label: "CLI config",
+          status: "fail",
+          message: "unable to resolve CLI config",
+          remediationHint: "Fix ~/.clawdentity/config.json or rerun: clawdentity config init"
+        })
+      );
     }
-  } catch {
-    checks.push(
-      toDoctorCheck({
-        id: "config.registry",
-        label: "CLI config",
-        status: "fail",
-        message: "unable to resolve CLI config",
-        remediationHint: "Fix ~/.clawdentity/config.json or rerun: clawdentity config init"
-      })
-    );
   }
   const selectedAgentPath = resolveOpenclawAgentNamePath(homeDir);
   let selectedAgentName;
@@ -22336,6 +22348,15 @@ async function runOpenclawDoctor(options = {}) {
     const hooks = isRecord8(openclawConfig.hooks) ? openclawConfig.hooks : {};
     const hooksEnabled = hooks.enabled === true;
     const hookToken = typeof hooks.token === "string" && hooks.token.trim().length > 0 ? hooks.token.trim() : void 0;
+    const defaultSessionKey = typeof hooks.defaultSessionKey === "string" && hooks.defaultSessionKey.trim().length > 0 ? hooks.defaultSessionKey.trim() : void 0;
+    const allowRequestSessionKey = hooks.allowRequestSessionKey === false;
+    const allowedSessionKeyPrefixes = normalizeStringArrayWithValues(
+      hooks.allowedSessionKeyPrefixes,
+      []
+    );
+    const missingRequiredSessionPrefixes = defaultSessionKey === void 0 ? ["hook:"] : ["hook:", defaultSessionKey].filter(
+      (prefix) => !allowedSessionKeyPrefixes.includes(prefix)
+    );
     const mappings = Array.isArray(hooks.mappings) ? hooks.mappings.filter(isRecord8) : [];
     const relayMapping = mappings.find(
       (mapping) => isRelayHookMapping(mapping)
@@ -22395,6 +22416,45 @@ async function runOpenclawDoctor(options = {}) {
         })
       );
     }
+    const sessionRoutingIssues = [];
+    if (defaultSessionKey === void 0) {
+      sessionRoutingIssues.push("hooks.defaultSessionKey is missing");
+    }
+    if (!allowRequestSessionKey) {
+      sessionRoutingIssues.push("hooks.allowRequestSessionKey is not false");
+    }
+    if (missingRequiredSessionPrefixes.length > 0) {
+      sessionRoutingIssues.push(
+        `hooks.allowedSessionKeyPrefixes is missing: ${missingRequiredSessionPrefixes.join(", ")}`
+      );
+    }
+    if (defaultSessionKey !== void 0 && isCanonicalAgentSessionKey(defaultSessionKey)) {
+      sessionRoutingIssues.push(
+        "hooks.defaultSessionKey uses canonical agent format (agent:<id>:...); use OpenClaw request session keys like main, global, or subagent:*"
+      );
+    }
+    if (sessionRoutingIssues.length > 0) {
+      checks.push(
+        toDoctorCheck({
+          id: "state.hookSessionRouting",
+          label: "OpenClaw hook session routing",
+          status: "fail",
+          message: sessionRoutingIssues.join("; "),
+          remediationHint: OPENCLAW_SETUP_RESTART_COMMAND_HINT,
+          details: { openclawConfigPath }
+        })
+      );
+    } else {
+      checks.push(
+        toDoctorCheck({
+          id: "state.hookSessionRouting",
+          label: "OpenClaw hook session routing",
+          status: "pass",
+          message: "hooks default session and allowed session prefixes are configured",
+          details: { openclawConfigPath }
+        })
+      );
+    }
   } catch {
     checks.push(
       toDoctorCheck({
@@ -22416,6 +22476,16 @@ async function runOpenclawDoctor(options = {}) {
         details: { openclawConfigPath }
       })
     );
+    checks.push(
+      toDoctorCheck({
+        id: "state.hookSessionRouting",
+        label: "OpenClaw hook session routing",
+        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 {
@@ -22441,6 +22511,72 @@ async function runOpenclawDoctor(options = {}) {
       })
     );
   }
+  const gatewayDevicePendingPath = join6(openclawDir, "devices", "pending.json");
+  try {
+    const pendingPayload = await readJsonFile(gatewayDevicePendingPath);
+    if (!isRecord8(pendingPayload)) {
+      checks.push(
+        toDoctorCheck({
+          id: "state.gatewayDevicePairing",
+          label: "OpenClaw gateway device pairing",
+          status: "fail",
+          message: `invalid pending device approvals file: ${gatewayDevicePendingPath}`,
+          remediationHint: OPENCLAW_DEVICE_APPROVAL_COMMAND_HINT,
+          details: { gatewayDevicePendingPath }
+        })
+      );
+    } else {
+      const pendingRequestIds = Object.keys(pendingPayload);
+      if (pendingRequestIds.length === 0) {
+        checks.push(
+          toDoctorCheck({
+            id: "state.gatewayDevicePairing",
+            label: "OpenClaw gateway device pairing",
+            status: "pass",
+            message: "no pending gateway device approvals",
+            details: { gatewayDevicePendingPath }
+          })
+        );
+      } else {
+        checks.push(
+          toDoctorCheck({
+            id: "state.gatewayDevicePairing",
+            label: "OpenClaw gateway device pairing",
+            status: "fail",
+            message: `pending gateway device approvals: ${pendingRequestIds.length}`,
+            remediationHint: OPENCLAW_DEVICE_APPROVAL_COMMAND_HINT,
+            details: {
+              gatewayDevicePendingPath,
+              pendingRequestIds
+            }
+          })
+        );
+      }
+    }
+  } catch (error48) {
+    if (getErrorCode2(error48) === "ENOENT") {
+      checks.push(
+        toDoctorCheck({
+          id: "state.gatewayDevicePairing",
+          label: "OpenClaw gateway device pairing",
+          status: "pass",
+          message: "no pending gateway device approvals file was found",
+          details: { gatewayDevicePendingPath }
+        })
+      );
+    } else {
+      checks.push(
+        toDoctorCheck({
+          id: "state.gatewayDevicePairing",
+          label: "OpenClaw gateway device pairing",
+          status: "fail",
+          message: `unable to read pending device approvals at ${gatewayDevicePendingPath}`,
+          remediationHint: OPENCLAW_DEVICE_APPROVAL_COMMAND_HINT,
+          details: { gatewayDevicePendingPath }
+        })
+      );
+    }
+  }
   if (options.includeConnectorRuntimeCheck !== false) {
     if (selectedAgentName === void 0) {
       checks.push(
@@ -22803,7 +22939,8 @@ async function setupOpenclawRelay(agentName, options) {
   await saveRelayRuntimeConfig(
     relayRuntimeConfigPath,
     openclawBaseUrl,
-    patchedOpenclawConfig.hookToken
+    patchedOpenclawConfig.hookToken,
+    relayTransformPeersPath
   );
   logger8.info("cli.openclaw_setup_completed", {
     agentName: normalizedAgentName,
@@ -22825,9 +22962,45 @@ async function setupOpenclawRelay(agentName, options) {
     relayRuntimeConfigPath
   };
 }
+async function assertSetupChecklistHealthy(input) {
+  const checklist = await runOpenclawDoctor({
+    homeDir: input.homeDir,
+    openclawDir: input.openclawDir,
+    includeConfigCheck: false,
+    includeConnectorRuntimeCheck: input.includeConnectorRuntimeCheck
+  });
+  if (checklist.status === "healthy") {
+    return;
+  }
+  const firstFailure = checklist.checks.find((check2) => check2.status === "fail");
+  throw createCliError6(
+    "CLI_OPENCLAW_SETUP_CHECKLIST_FAILED",
+    "OpenClaw setup checklist failed",
+    {
+      firstFailedCheckId: firstFailure?.id,
+      firstFailedCheckMessage: firstFailure?.message,
+      remediationHint: firstFailure?.remediationHint,
+      checks: checklist.checks
+    }
+  );
+}
 async function setupOpenclawSelfReady(agentName, options) {
-  const setup = await setupOpenclawRelay(agentName, options);
+  const resolvedHomeDir = resolveHomeDir(options.homeDir);
+  const resolvedOpenclawDir = resolveOpenclawDir(
+    options.openclawDir,
+    resolvedHomeDir
+  );
+  const setup = await setupOpenclawRelay(agentName, {
+    ...options,
+    homeDir: resolvedHomeDir,
+    openclawDir: resolvedOpenclawDir
+  });
   if (options.noRuntimeStart === true) {
+    await assertSetupChecklistHealthy({
+      homeDir: resolvedHomeDir,
+      openclawDir: resolvedOpenclawDir,
+      includeConnectorRuntimeCheck: false
+    });
     return {
       ...setup,
       runtimeMode: "none",
@@ -22846,7 +23019,6 @@ async function setupOpenclawSelfReady(agentName, options) {
   const waitTimeoutSeconds = parseWaitTimeoutSeconds(
     options.waitTimeoutSeconds
   );
-  const resolvedHomeDir = resolveHomeDir(options.homeDir);
   const runtime = await startSetupConnectorRuntime({
     agentName: assertValidAgentName(agentName),
     homeDir: resolvedHomeDir,
@@ -22856,6 +23028,11 @@ async function setupOpenclawSelfReady(agentName, options) {
     waitTimeoutSeconds,
     fetchImpl
   });
+  await assertSetupChecklistHealthy({
+    homeDir: resolvedHomeDir,
+    openclawDir: resolvedOpenclawDir,
+    includeConnectorRuntimeCheck: true
+  });
   return {
     ...setup,
     ...runtime
@@ -23001,6 +23178,7 @@ var AIT_FILE_NAME4 = "ait.jwt";
 var SECRET_KEY_FILE_NAME3 = "secret.key";
 var PAIRING_QR_DIR_NAME = "pairing";
 var PEERS_FILE_NAME2 = "peers.json";
+var OPENCLAW_RELAY_RUNTIME_FILE_NAME3 = "openclaw-relay.json";
 var PAIR_START_PATH = "/pair/start";
 var PAIR_CONFIRM_PATH = "/pair/confirm";
 var PAIR_STATUS_PATH = "/pair/status";
@@ -23303,6 +23481,86 @@ async function savePeersConfig2(input) {
   );
   await input.chmodImpl(peersPath, FILE_MODE4);
 }
+function resolveRelayRuntimeConfigPath2(getConfigDirImpl) {
+  return join7(getConfigDirImpl(), OPENCLAW_RELAY_RUNTIME_FILE_NAME3);
+}
+async function loadRelayTransformPeersPath(input) {
+  const relayRuntimeConfigPath = resolveRelayRuntimeConfigPath2(
+    input.getConfigDirImpl
+  );
+  let raw;
+  try {
+    raw = await input.readFileImpl(relayRuntimeConfigPath, "utf8");
+  } catch (error48) {
+    const nodeError = error48;
+    if (nodeError.code === "ENOENT") {
+      return void 0;
+    }
+    logger9.warn("cli.pair.relay_runtime_read_failed", {
+      relayRuntimeConfigPath,
+      reason: error48 instanceof Error && error48.message.length > 0 ? error48.message : "unknown"
+    });
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    logger9.warn("cli.pair.relay_runtime_invalid_json", {
+      relayRuntimeConfigPath
+    });
+    return void 0;
+  }
+  if (!isRecord9(parsed)) {
+    return void 0;
+  }
+  const relayTransformPeersPath = parseNonEmptyString9(
+    parsed.relayTransformPeersPath
+  );
+  if (relayTransformPeersPath.length === 0) {
+    return void 0;
+  }
+  return resolve(relayTransformPeersPath);
+}
+async function syncOpenclawRelayPeersSnapshot(input) {
+  const relayTransformPeersPath = await loadRelayTransformPeersPath({
+    getConfigDirImpl: input.getConfigDirImpl,
+    readFileImpl: input.readFileImpl
+  });
+  if (relayTransformPeersPath === void 0) {
+    return;
+  }
+  try {
+    await input.readFileImpl(relayTransformPeersPath, "utf8");
+  } catch (error48) {
+    const nodeError = error48;
+    if (nodeError.code === "ENOENT") {
+      return;
+    }
+    logger9.warn("cli.pair.relay_peers_snapshot_probe_failed", {
+      relayTransformPeersPath,
+      reason: error48 instanceof Error && error48.message.length > 0 ? error48.message : "unknown"
+    });
+    return;
+  }
+  try {
+    await input.mkdirImpl(dirname5(relayTransformPeersPath), {
+      recursive: true
+    });
+    await input.writeFileImpl(
+      relayTransformPeersPath,
+      `${JSON.stringify(input.config, null, 2)}
+`,
+      "utf8"
+    );
+    await input.chmodImpl(relayTransformPeersPath, FILE_MODE4);
+  } catch (error48) {
+    logger9.warn("cli.pair.relay_peers_snapshot_write_failed", {
+      relayTransformPeersPath,
+      reason: error48 instanceof Error && error48.message.length > 0 ? error48.message : "unknown"
+    });
+  }
+}
 function parseTtlSeconds(value) {
   const raw = parseNonEmptyString9(value);
   if (raw.length === 0) {
@@ -23828,6 +24086,14 @@ async function persistPairedPeer(input) {
     writeFileImpl,
     chmodImpl
   });
+  await syncOpenclawRelayPeersSnapshot({
+    config: peersConfig,
+    getConfigDirImpl,
+    readFileImpl,
+    mkdirImpl,
+    writeFileImpl,
+    chmodImpl
+  });
   return alias;
 }
 async function startPairing(agentName, options, dependencies = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawdentity",
-  "version": "0.0.18",
+  "version": "0.0.19",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -21,6 +21,17 @@
     "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",
@@ -29,21 +40,11 @@
     "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",
-    "@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"
+    "@types/qrcode": "^1.5.6"
   }
-}
+}

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

@@ -196,6 +196,7 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
   - OpenClaw config path and relay runtime path
   - runtime mode/status
   - websocket status `connected`
+  - setup checklist is healthy (fails fast when hook/device/runtime prerequisites drift)
 
 7. Validate readiness.
 - Run `clawdentity openclaw doctor`.
@@ -212,6 +213,8 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
 | `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) | `openclaw devices list` then `openclaw devices approve <requestId>` |
 | `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>` |