@xfxstudio/claworld 0.2.12 → 0.2.14

package/src/openclaw/installer/doctor.js

@@ -1,876 +0,0 @@
-import os from 'os';
-import path from 'path';
-import { inspectClaworldChannelAccount } from '../plugin/config-schema.js';
-import {
-  DEFAULT_CLAWORLD_ACCOUNT_ID,
-  DEFAULT_CLAWORLD_AGENT_ID,
-  DEFAULT_CLAWORLD_SERVER_URL,
-  expandUserPath,
-  getEffectiveAgentSandboxMode,
-  MIN_MANAGED_SESSION_VISIBILITY,
-  normalizeText,
-  resolveClaworldManagedRuntimeOptions,
-  sandboxModeNeedsSessionToolsVisibility,
-} from '../plugin/managed-config.js';
-import {
-  CLAWORLD_DOCTOR_COMMAND,
-  CLAWORLD_INSTALLER_COMMAND,
-  CLAWORLD_OPENCLAW_MIN_HOST_VERSION,
-} from './constants.js';
-import {
-  activateInstall,
-  compareVersionParts,
-  DEFAULT_OPENCLAW_BIN,
-  DEFAULT_OPENCLAW_CONFIG_PATH,
-  DEFAULT_OPENCLAW_STATE_DIR,
-  detectOpenclawHost,
-  fetchInstallManifest,
-  inspectClaworldPluginInstall,
-  loadConfigFromDisk,
-  readAgentBindings,
-  readChannelStatus,
-  readGatewayStatus,
-} from './core.js';
-import { inspectManagedWorkspaceContract } from './workspace-contract.js';
-
-function createCheck({
-  id,
-  category,
-  label,
-  status,
-  summary,
-  action = null,
-  details = {},
-} = {}) {
-  return {
-    id,
-    category,
-    label,
-    status,
-    summary,
-    action,
-    details,
-  };
-}
-
-function statusRank(status) {
-  if (status === 'fail') return 3;
-  if (status === 'warn') return 2;
-  return 1;
-}
-
-function overallStatus(checks = []) {
-  if (checks.some((check) => check.status === 'fail')) return 'fail';
-  if (checks.some((check) => check.status === 'warn')) return 'warn';
-  return 'pass';
-}
-
-function formatStatus(status) {
-  return `[${String(status || 'pass').toUpperCase()}]`;
-}
-
-function findManagedAgentEntry(config = {}, agentId) {
-  const list = Array.isArray(config?.agents?.list) ? config.agents.list : [];
-  return list.find((entry) => entry?.id === agentId) || null;
-}
-
-function hasConfiguredBinding(config = {}, { agentId, accountId } = {}) {
-  const bindings = Array.isArray(config?.bindings) ? config.bindings : [];
-  return bindings.some((binding) =>
-    binding?.agentId === agentId
-    && binding?.match?.channel === 'claworld'
-    && binding?.match?.accountId === accountId,
-  );
-}
-
-function findChannelAccount(channelStatus, accountId) {
-  const entries = Array.isArray(channelStatus?.channelAccounts?.claworld)
-    ? channelStatus.channelAccounts.claworld
-    : [];
-  return entries.find((entry) => entry?.accountId === accountId) || null;
-}
-
-const SESSION_VISIBILITY_RANK = Object.freeze({
-  self: 0,
-  tree: 1,
-  agent: 2,
-  all: 3,
-});
-
-function resolveConfiguredSessionVisibility(config = {}) {
-  const visibility = normalizeText(config?.tools?.sessions?.visibility, null);
-  return Object.prototype.hasOwnProperty.call(SESSION_VISIBILITY_RANK, visibility) ? visibility : null;
-}
-
-function normalizeGatewayBaseUrl(gatewayStatus) {
-  const probeUrl = normalizeText(gatewayStatus?.gateway?.probeUrl, null);
-  if (probeUrl) {
-    const parsed = new URL(probeUrl);
-    parsed.protocol = parsed.protocol === 'wss:' ? 'https:' : 'http:';
-    parsed.pathname = '';
-    parsed.search = '';
-    parsed.hash = '';
-    return parsed.toString().replace(/\/$/, '');
-  }
-
-  const bindHost = normalizeText(gatewayStatus?.gateway?.bindHost, null);
-  const port = gatewayStatus?.gateway?.port;
-  if (!bindHost || !port) return null;
-  const host = bindHost === '0.0.0.0' ? '127.0.0.1' : bindHost;
-  return `http://${host}:${port}`;
-}
-
-function normalizeConfiguredGatewayBaseUrl(config = {}) {
-  const configuredPort = Number(config?.gateway?.port);
-  if (!Number.isFinite(configuredPort) || configuredPort <= 0) {
-    return null;
-  }
-
-  const configuredBind = normalizeText(config?.gateway?.bind, '127.0.0.1');
-  const configuredHost = (
-    configuredBind === 'loopback'
-    || configuredBind === 'localhost'
-    || configuredBind === '0.0.0.0'
-    || configuredBind === '::'
-  )
-    ? '127.0.0.1'
-    : configuredBind;
-  return `http://${configuredHost}:${configuredPort}`;
-}
-
-function describePluginStatusRouteTarget({
-  config = {},
-  gatewayStatus = {},
-} = {}) {
-  const configuredBaseUrl = normalizeConfiguredGatewayBaseUrl(config);
-  const runtimeBaseUrl = normalizeGatewayBaseUrl(gatewayStatus);
-  return {
-    configuredBaseUrl,
-    runtimeBaseUrl,
-    baseUrlMismatch: Boolean(
-      configuredBaseUrl
-      && runtimeBaseUrl
-      && configuredBaseUrl !== runtimeBaseUrl
-    ),
-    runtimePortSource: normalizeText(gatewayStatus?.gateway?.portSource, null),
-  };
-}
-
-async function fetchPluginStatusRoute({
-  gatewayBaseUrl,
-  fetchImpl = globalThis.fetch?.bind(globalThis),
-} = {}) {
-  if (!gatewayBaseUrl || typeof fetchImpl !== 'function') {
-    return {
-      ok: false,
-      status: null,
-      body: null,
-      routeUrl: gatewayBaseUrl ? `${gatewayBaseUrl}/plugins/claworld/status` : null,
-      error: gatewayBaseUrl ? 'missing_fetch' : 'missing_gateway_base_url',
-    };
-  }
-
-  const routeUrl = `${gatewayBaseUrl}/plugins/claworld/status`;
-  try {
-    const response = await fetchImpl(routeUrl, {
-      method: 'GET',
-      headers: {
-        accept: 'application/json',
-      },
-    });
-    const text = await response.text();
-    let body = null;
-    try {
-      body = text ? JSON.parse(text) : null;
-    } catch {
-      body = null;
-    }
-    return {
-      ok: response.ok,
-      status: response.status,
-      body,
-      routeUrl,
-      error: null,
-    };
-  } catch (error) {
-    return {
-      ok: false,
-      status: null,
-      body: null,
-      routeUrl,
-      error: error?.message || String(error),
-    };
-  }
-}
-
-function formatWorkspaceState(workspaceInspection) {
-  return workspaceInspection.files.map((file) => `${file.relativePath}=${file.state}`).join(', ');
-}
-
-export async function runClaworldDoctor({
-  openclawBin = DEFAULT_OPENCLAW_BIN,
-  configPath = DEFAULT_OPENCLAW_CONFIG_PATH,
-  stateDir = DEFAULT_OPENCLAW_STATE_DIR,
-  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
-  agentId = DEFAULT_CLAWORLD_AGENT_ID,
-  workspace = null,
-  serverUrl = null,
-  fetchImpl = globalThis.fetch?.bind(globalThis),
-  commandRunner,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-} = {}) {
-  const resolvedConfigPath = path.resolve(expandUserPath(configPath, os.homedir()));
-  const resolvedStateDir = stateDir ? path.resolve(expandUserPath(stateDir, os.homedir())) : null;
-  const configState = await loadConfigFromDisk(resolvedConfigPath);
-  const config = configState.config;
-  const configuredAccount = inspectClaworldChannelAccount(config, accountId);
-  const managedOptions = resolveClaworldManagedRuntimeOptions({
-    cfg: config,
-    accountId,
-    overrides: {
-      agentId,
-      workspace,
-    },
-  });
-  const rawManagedAccount = config?.channels?.claworld?.accounts?.[configuredAccount.accountId] || null;
-  const configuredApiKey = normalizeText(rawManagedAccount?.apiKey, 'local-test');
-  const resolvedAgentId = normalizeText(managedOptions.agentId, DEFAULT_CLAWORLD_AGENT_ID);
-  const resolvedWorkspace = normalizeText(managedOptions.workspace, null);
-  const effectiveServerUrl = normalizeText(
-    serverUrl,
-    normalizeText(configuredAccount.serverUrl, DEFAULT_CLAWORLD_SERVER_URL),
-  );
-  const workspaceInspection = managedOptions.manageWorkspace
-    ? await inspectManagedWorkspaceContract({
-      agentId: resolvedAgentId,
-      accountId: normalizeText(accountId, configuredAccount.accountId || DEFAULT_CLAWORLD_ACCOUNT_ID),
-      workspace: resolvedWorkspace,
-      serverUrl: effectiveServerUrl,
-      appToken: configuredAccount.appToken,
-      registrationDisplayName: configuredAccount.registration?.displayName || null,
-      defaultTargetAgentId: configuredAccount.relay?.defaultTargetAgentId || null,
-    })
-    : {
-      ok: true,
-      workspacePath: resolvedWorkspace,
-      metadataPath: null,
-      files: [],
-      issues: [],
-    };
-
-  const checks = [];
-  const facts = {
-    host: null,
-    plugin: null,
-    manifest: null,
-    activation: null,
-    gatewayStatus: null,
-    channelStatus: null,
-    bindingOutput: null,
-    pluginStatusRoute: null,
-    workspaceInspection,
-  };
-
-  try {
-    const host = await detectOpenclawHost({
-      openclawBin,
-      commandRunner,
-      cwd,
-      env,
-      dryRun,
-    });
-    facts.host = host;
-    if (compareVersionParts(host.version, CLAWORLD_OPENCLAW_MIN_HOST_VERSION) < 0) {
-      checks.push(createCheck({
-        id: 'host-version',
-        category: 'Host and plugin',
-        label: 'OpenClaw host version',
-        status: 'fail',
-        summary: `OpenClaw ${host.version} is below the required minimum ${CLAWORLD_OPENCLAW_MIN_HOST_VERSION}.`,
-        action: `Upgrade OpenClaw, then rerun \`${CLAWORLD_DOCTOR_COMMAND}\`.`,
-        details: {
-          version: host.version,
-          minimum: CLAWORLD_OPENCLAW_MIN_HOST_VERSION,
-          requestedBin: host.requestedBin || null,
-          binaryPath: host.binaryPath || null,
-          binarySource: host.binarySource || null,
-        },
-      }));
-    } else {
-      checks.push(createCheck({
-        id: 'host-version',
-        category: 'Host and plugin',
-        label: 'OpenClaw host version',
-        status: 'pass',
-        summary: `OpenClaw ${host.version} satisfies the required minimum ${CLAWORLD_OPENCLAW_MIN_HOST_VERSION}.`,
-        details: {
-          version: host.version,
-          minimum: CLAWORLD_OPENCLAW_MIN_HOST_VERSION,
-          requestedBin: host.requestedBin || null,
-          binaryPath: host.binaryPath || null,
-          binarySource: host.binarySource || null,
-          skippedLocalBinaryPaths: host.skippedLocalBinaryPaths || [],
-        },
-      }));
-    }
-  } catch (error) {
-    checks.push(createCheck({
-      id: 'host-version',
-      category: 'Host and plugin',
-      label: 'OpenClaw host version',
-      status: 'fail',
-      summary: 'Unable to determine the installed OpenClaw version.',
-      action: 'Install OpenClaw or fix the host CLI path, then rerun the doctor command.',
-      details: { message: error?.message || String(error) },
-    }));
-  }
-
-  try {
-    facts.plugin = await inspectClaworldPluginInstall({
-      openclawBin,
-      configPath: resolvedConfigPath,
-      stateDir: resolvedStateDir,
-      commandRunner,
-      cwd,
-      env,
-      dryRun,
-    });
-    if (!facts.plugin.installed) {
-      checks.push(createCheck({
-        id: 'plugin-install',
-        category: 'Host and plugin',
-        label: 'Claworld plugin install',
-        status: 'fail',
-        summary: 'The `claworld` plugin is not installed or not discoverable.',
-        action: `Run \`${CLAWORLD_INSTALLER_COMMAND}\` to install and configure the managed Claworld runtime.`,
-      }));
-    } else {
-      checks.push(createCheck({
-        id: 'plugin-install',
-        category: 'Host and plugin',
-        label: 'Claworld plugin install',
-        status: 'pass',
-        summary: `The \`claworld\` plugin is installed (${facts.plugin.install || 'install type unavailable'}).`,
-        details: { version: facts.plugin.version || null, sourcePath: facts.plugin.sourcePath || null },
-      }));
-      checks.push(createCheck({
-        id: 'plugin-load',
-        category: 'Host and plugin',
-        label: 'Claworld plugin load',
-        status: facts.plugin.loaded ? 'pass' : 'fail',
-        summary: facts.plugin.loaded
-          ? 'The `claworld` plugin reports a healthy loaded state.'
-          : `The \`claworld\` plugin is installed but reports status ${facts.plugin.status || 'unknown'}.`,
-        action: facts.plugin.loaded
-          ? null
-          : 'Inspect `openclaw plugins info claworld` and fix the plugin load error before retrying.',
-        details: { status: facts.plugin.status || null, raw: facts.plugin.raw || null },
-      }));
-    }
-  } catch (error) {
-    checks.push(createCheck({
-      id: 'plugin-install',
-      category: 'Host and plugin',
-      label: 'Claworld plugin install',
-      status: 'fail',
-      summary: 'Unable to inspect the `claworld` plugin install state.',
-      action: 'Confirm the host can run `openclaw plugins info claworld`, then rerun doctor.',
-      details: { message: error?.message || String(error) },
-    }));
-  }
-
-  const agentEntry = findManagedAgentEntry(config, resolvedAgentId);
-  const agentWorkspace = normalizeText(agentEntry?.workspace, null);
-  const bindingConfigured = hasConfiguredBinding(config, {
-    agentId: resolvedAgentId,
-    accountId: normalizeText(accountId, configuredAccount.accountId || DEFAULT_CLAWORLD_ACCOUNT_ID),
-  });
-  const defaultAccount = normalizeText(config?.channels?.claworld?.defaultAccount, null);
-
-  checks.push(createCheck({
-    id: 'managed-agent',
-    category: 'Managed config',
-    label: managedOptions.manageAgentEntry ? 'Managed local agent entry' : 'Bound local agent target',
-    status: managedOptions.manageAgentEntry
-      ? (agentEntry && agentWorkspace === resolvedWorkspace ? 'pass' : 'fail')
-      : (agentEntry ? 'pass' : 'warn'),
-    summary: managedOptions.manageAgentEntry
-      ? (
-        agentEntry && agentWorkspace === resolvedWorkspace
-          ? `Managed agent \`${resolvedAgentId}\` points at \`${resolvedWorkspace}\`.`
-          : agentEntry
-            ? `Managed agent \`${resolvedAgentId}\` exists but points at \`${agentWorkspace || 'missing workspace'}\`.`
-            : `Managed agent \`${resolvedAgentId}\` is missing from agents.list.`
-      )
-      : (
-        agentEntry
-          ? `Claworld is bound to existing local agent \`${resolvedAgentId}\` (${agentWorkspace || 'workspace unspecified'}).`
-          : `Claworld is configured to bind to local agent \`${resolvedAgentId}\`; this doctor run could not confirm an agents.list entry and will rely on runtime binding visibility instead.`
-      ),
-    action: managedOptions.manageAgentEntry
-      ? `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` to reconcile the managed agent entry.`
-      : null,
-    details: {
-      expectedWorkspace: resolvedWorkspace,
-      actualWorkspace: agentWorkspace,
-      manageAgentEntry: managedOptions.manageAgentEntry,
-    },
-  }));
-
-  checks.push(createCheck({
-    id: 'managed-account',
-    category: 'Managed config',
-    label: 'Managed claworld account',
-    status: configuredAccount.configured && configuredAccount.enabled !== false ? 'pass' : 'fail',
-    summary: configuredAccount.configured && configuredAccount.enabled !== false
-      ? `Managed account \`${configuredAccount.accountId}\` is configured and enabled.`
-      : `Managed account \`${configuredAccount.accountId}\` is missing required config or disabled.`,
-    action: `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` to repair the managed account config.`,
-    details: {
-      configuredStatus: configuredAccount.configuredStatus,
-      enabled: configuredAccount.enabled,
-      issues: configuredAccount.issues || [],
-    },
-  }));
-
-  checks.push(createCheck({
-    id: 'default-account',
-    category: 'Managed config',
-    label: 'Default claworld account',
-    status: defaultAccount === configuredAccount.accountId ? 'pass' : 'fail',
-    summary: defaultAccount === configuredAccount.accountId
-      ? `channels.claworld.defaultAccount is correctly set to \`${configuredAccount.accountId}\`.`
-      : `channels.claworld.defaultAccount is \`${defaultAccount || 'missing'}\`, expected \`${configuredAccount.accountId}\`.`,
-    action: `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` to reset the managed default account.`,
-    details: { expectedDefaultAccount: configuredAccount.accountId, actualDefaultAccount: defaultAccount },
-  }));
-
-  checks.push(createCheck({
-    id: 'managed-binding',
-    category: 'Managed config',
-    label: 'Managed claworld binding',
-    status: bindingConfigured ? 'pass' : 'fail',
-    summary: bindingConfigured
-      ? `Config includes the managed binding ${resolvedAgentId} <- claworld accountId=${configuredAccount.accountId}.`
-      : `Config is missing the managed binding ${resolvedAgentId} <- claworld accountId=${configuredAccount.accountId}.`,
-    action: `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` to restore the managed binding.`,
-  }));
-
-  checks.push(createCheck({
-    id: 'managed-config-shape',
-    category: 'Managed config',
-    label: 'Managed config shape',
-    status: configuredAccount.issues.length === 0 ? 'pass' : 'fail',
-    summary: configuredAccount.issues.length === 0
-      ? 'Managed Claworld config matches the canonical account schema.'
-      : `Managed Claworld config still has schema issues: ${configuredAccount.issues.map((issue) => issue.code).join(', ')}.`,
-    action: `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` to normalize the managed config shape.`,
-    details: { issues: configuredAccount.issues },
-  }));
-
-  const configuredSessionVisibility = resolveConfiguredSessionVisibility(config);
-  const sessionVisibilityHealthy = (
-    configuredSessionVisibility != null
-    && SESSION_VISIBILITY_RANK[configuredSessionVisibility] >= SESSION_VISIBILITY_RANK[MIN_MANAGED_SESSION_VISIBILITY]
-  );
-  checks.push(createCheck({
-    id: 'session-tools-visibility',
-    category: 'Managed config',
-    label: 'Session tool visibility',
-    status: sessionVisibilityHealthy ? 'pass' : 'warn',
-    summary: sessionVisibilityHealthy
-      ? `tools.sessions.visibility is \`${configuredSessionVisibility}\`, which satisfies the managed same-agent minimum \`${MIN_MANAGED_SESSION_VISIBILITY}\`.`
-      : `tools.sessions.visibility is \`${configuredSessionVisibility || 'missing'}\`, but the managed same-agent follow-up path needs at least \`${MIN_MANAGED_SESSION_VISIBILITY}\`.`,
-    action: sessionVisibilityHealthy
-      ? null
-      : `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` to raise session visibility for managed same-agent follow-up routing.`,
-    details: {
-      actualVisibility: configuredSessionVisibility,
-      minimumVisibility: MIN_MANAGED_SESSION_VISIBILITY,
-    },
-  }));
-
-  const effectiveSandboxMode = getEffectiveAgentSandboxMode(config, resolvedAgentId);
-  if (sandboxModeNeedsSessionToolsVisibility(effectiveSandboxMode)) {
-    const sandboxSessionToolsVisibility = normalizeText(
-      config?.agents?.defaults?.sandbox?.sessionToolsVisibility,
-      null,
-    );
-    const sandboxVisibilityHealthy = sandboxSessionToolsVisibility === 'all';
-    checks.push(createCheck({
-      id: 'sandbox-session-tools-visibility',
-      category: 'Managed config',
-      label: 'Sandbox session tool visibility',
-      status: sandboxVisibilityHealthy ? 'pass' : 'warn',
-      summary: sandboxVisibilityHealthy
-        ? `Effective sandbox mode is \`${effectiveSandboxMode}\` and agents.defaults.sandbox.sessionToolsVisibility is correctly set to \`all\`.`
-        : `Effective sandbox mode is \`${effectiveSandboxMode}\`, so agents.defaults.sandbox.sessionToolsVisibility should be \`all\` (currently \`${sandboxSessionToolsVisibility || 'missing'}\`).`,
-      action: sandboxVisibilityHealthy
-        ? null
-        : `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` to widen sandbox session-tool visibility for managed follow-up routing.`,
-      details: {
-        effectiveSandboxMode,
-        sessionToolsVisibility: sandboxSessionToolsVisibility,
-        requiredSessionToolsVisibility: 'all',
-      },
-    }));
-  }
-
-  checks.push(createCheck({
-    id: 'app-token',
-    category: 'Credentials and runtime',
-    label: 'Managed appToken',
-    status: configuredAccount.tokenStatus === 'available' ? 'pass' : 'warn',
-    summary: configuredAccount.tokenStatus === 'available'
-      ? 'Managed account has an available appToken.'
-      : `Managed account token status is ${configuredAccount.tokenStatus}; activation is still pending.`,
-    action: configuredAccount.tokenStatus === 'available'
-      ? null
-      : 'Open a live OpenClaw session, run `claworld_pair_agent`, and then complete `claworld_profile` with `action=update_identity` when prompted.',
-    details: { tokenSource: configuredAccount.tokenSource, tokenStatus: configuredAccount.tokenStatus },
-  }));
-
-  try {
-    facts.manifest = await fetchInstallManifest({
-      serverUrl: effectiveServerUrl,
-      apiKey: configuredApiKey,
-      fetchImpl,
-    });
-    checks.push(createCheck({
-      id: 'backend-reachable',
-      category: 'Credentials and runtime',
-      label: 'Claworld backend reachability',
-      status: 'pass',
-      summary: `Reached the Claworld install contract at ${effectiveServerUrl}.`,
-      details: { serverUrl: effectiveServerUrl, mode: facts.manifest.mode || null },
-    }));
-  } catch (error) {
-    checks.push(createCheck({
-      id: 'backend-reachable',
-      category: 'Credentials and runtime',
-      label: 'Claworld backend reachability',
-      status: 'warn',
-      summary: `Unable to reach the Claworld backend at ${effectiveServerUrl}.`,
-      action: 'Restore backend reachability before pairing or live Claworld use, then rerun doctor.',
-      details: { serverUrl: effectiveServerUrl, message: error?.message || String(error) },
-    }));
-  }
-
-  const backendReachable = checks.find((check) => check.id === 'backend-reachable')?.status === 'pass';
-  if (configuredAccount.appToken && backendReachable) {
-    try {
-      facts.activation = await activateInstall({
-        serverUrl: effectiveServerUrl,
-        apiKey: configuredApiKey,
-        appToken: configuredAccount.appToken,
-        fetchImpl,
-      });
-      checks.push(createCheck({
-        id: 'stable-agent-binding',
-        category: 'Credentials and runtime',
-        label: 'Stable relay binding',
-        status: 'pass',
-        summary: `Backend activation resolved a stable managed agentId: \`${facts.activation.agentId}\`.`,
-        details: { agentId: facts.activation.agentId, created: facts.activation.created === true },
-      }));
-    } catch (error) {
-      checks.push(createCheck({
-        id: 'stable-agent-binding',
-        category: 'Credentials and runtime',
-        label: 'Stable relay binding',
-        status: 'fail',
-        summary: 'Managed appToken could not be resolved into a healthy backend binding.',
-        action: 'Run `claworld_pair_agent` in a live OpenClaw session to refresh the managed relay binding.',
-        details: { message: error?.message || String(error) },
-      }));
-    }
-  } else if (!configuredAccount.appToken) {
-    checks.push(createCheck({
-      id: 'stable-agent-binding',
-      category: 'Credentials and runtime',
-      label: 'Stable relay binding',
-      status: 'warn',
-      summary: 'Doctor could not verify the managed relay binding because activation is still pending.',
-      action: 'Open a live OpenClaw session, run `claworld_pair_agent`, and then complete `claworld_profile` with `action=update_identity` when prompted.',
-    }));
-  } else {
-    checks.push(createCheck({
-      id: 'stable-agent-binding',
-      category: 'Credentials and runtime',
-      label: 'Stable relay binding',
-      status: 'warn',
-      summary: 'Doctor could not verify the managed relay binding because the backend was not reachable.',
-      action: 'Restore backend reachability, then rerun doctor to verify the managed relay binding.',
-    }));
-  }
-
-  try {
-    facts.gatewayStatus = await readGatewayStatus({
-      openclawBin,
-      configPath: resolvedConfigPath,
-      stateDir: resolvedStateDir,
-      commandRunner,
-      cwd,
-      env,
-      dryRun,
-    });
-    const gatewayRunning = facts.gatewayStatus?.service?.runtime?.status === 'running';
-    checks.push(createCheck({
-      id: 'gateway-runtime',
-      category: 'Credentials and runtime',
-      label: 'OpenClaw gateway runtime',
-      status: gatewayRunning ? 'pass' : 'fail',
-      summary: gatewayRunning
-        ? 'OpenClaw gateway runtime is running.'
-        : `OpenClaw gateway runtime reports ${facts.gatewayStatus?.service?.runtime?.status || 'unknown'}.`,
-      action: gatewayRunning ? null : 'Start or restart the OpenClaw gateway, then rerun doctor.',
-      details: { gateway: facts.gatewayStatus.gateway || null, service: facts.gatewayStatus.service || null },
-    }));
-  } catch (error) {
-    checks.push(createCheck({
-      id: 'gateway-runtime',
-      category: 'Credentials and runtime',
-      label: 'OpenClaw gateway runtime',
-      status: 'fail',
-      summary: 'Unable to read OpenClaw gateway status.',
-      action: 'Confirm the host can run `openclaw gateway status --json --no-probe`, then rerun doctor.',
-      details: { message: error?.message || String(error) },
-    }));
-  }
-
-  try {
-    facts.channelStatus = await readChannelStatus({
-      openclawBin,
-      configPath: resolvedConfigPath,
-      stateDir: resolvedStateDir,
-      commandRunner,
-      cwd,
-      env,
-      dryRun,
-    });
-    const channelAccount = findChannelAccount(facts.channelStatus, configuredAccount.accountId);
-    const channelHealthy = Boolean(
-      channelAccount
-      && channelAccount.configured === true
-      && channelAccount.enabled !== false
-      && channelAccount.tokenStatus === 'available'
-    );
-    const channelPendingActivation = Boolean(
-      channelAccount
-      && channelAccount.configured === true
-      && channelAccount.enabled !== false
-      && channelAccount.tokenStatus !== 'available'
-    );
-    checks.push(createCheck({
-      id: 'channel-runtime',
-      category: 'Credentials and runtime',
-      label: 'Claworld channel runtime account',
-      status: channelHealthy ? 'pass' : channelPendingActivation ? 'warn' : 'fail',
-      summary: channelHealthy
-        ? `channels status reports managed account \`${configuredAccount.accountId}\` as configured with an available token.`
-        : channelPendingActivation
-          ? `channels status reports managed account \`${configuredAccount.accountId}\` as configured, but activation is still pending (${channelAccount.tokenStatus}).`
-          : `channels status does not report a healthy managed account for \`${configuredAccount.accountId}\`.`,
-      action: channelHealthy
-        ? null
-        : channelPendingActivation
-          ? 'Open a live OpenClaw session, run `claworld_pair_agent`, and then complete `claworld_profile` with `action=update_identity` when prompted.'
-          : `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` or restart the gateway to recover the managed account runtime.`,
-      details: { channelAccount },
-    }));
-  } catch (error) {
-    checks.push(createCheck({
-      id: 'channel-runtime',
-      category: 'Credentials and runtime',
-      label: 'Claworld channel runtime account',
-      status: 'fail',
-      summary: 'Unable to read `openclaw channels status --json` for the Claworld account.',
-      action: 'Confirm the gateway can load channel metadata, then rerun doctor.',
-      details: { message: error?.message || String(error) },
-    }));
-  }
-
-  try {
-    facts.bindingOutput = await readAgentBindings({
-      openclawBin,
-      configPath: resolvedConfigPath,
-      stateDir: resolvedStateDir,
-      commandRunner,
-      cwd,
-      env,
-      dryRun,
-    });
-    const bindingLine = String(`${facts.bindingOutput.stdout || ''}${facts.bindingOutput.stderr || ''}`)
-      .split('\n')
-      .map((line) => line.trim())
-      .find((line) => line === `- ${resolvedAgentId} <- claworld accountId=${configuredAccount.accountId}`) || null;
-    checks.push(createCheck({
-      id: 'runtime-binding',
-      category: 'Credentials and runtime',
-      label: 'Runtime binding visibility',
-      status: bindingLine ? 'pass' : 'fail',
-      summary: bindingLine
-        ? `OpenClaw agents bindings exposes ${resolvedAgentId} <- claworld accountId=${configuredAccount.accountId}.`
-        : `OpenClaw agents bindings does not show ${resolvedAgentId} <- claworld accountId=${configuredAccount.accountId}.`,
-      action: `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` to restore the managed binding.`,
-      details: { bindingLine, output: facts.bindingOutput.stdout || facts.bindingOutput.stderr || null },
-    }));
-  } catch (error) {
-    checks.push(createCheck({
-      id: 'runtime-binding',
-      category: 'Credentials and runtime',
-      label: 'Runtime binding visibility',
-      status: 'fail',
-      summary: 'Unable to read `openclaw agents bindings`.',
-      action: 'Confirm the OpenClaw host can inspect bindings, then rerun doctor.',
-      details: { message: error?.message || String(error) },
-    }));
-  }
-
-  if (facts.gatewayStatus?.service?.runtime?.status === 'running') {
-    const routeTarget = describePluginStatusRouteTarget({
-      config,
-      gatewayStatus: facts.gatewayStatus,
-    });
-    const gatewayBaseUrl = routeTarget.runtimeBaseUrl;
-    facts.pluginStatusRoute = await fetchPluginStatusRoute({
-      gatewayBaseUrl,
-      fetchImpl,
-    });
-    const routeStatus = facts.pluginStatusRoute.status;
-    const routeReachable = facts.pluginStatusRoute.ok || routeStatus === 401 || routeStatus === 403;
-    let status = 'pass';
-    let summary = `Reached ${facts.pluginStatusRoute.routeUrl}.`;
-    let action = null;
-    if (routeTarget.baseUrlMismatch) {
-      status = 'warn';
-      const runtimeTarget = routeTarget.runtimeBaseUrl || 'the running gateway target';
-      const configuredTarget = routeTarget.configuredBaseUrl || 'the inspected config target';
-      const responseSummary = routeStatus == null
-        ? facts.pluginStatusRoute.error || 'no response'
-        : `HTTP ${routeStatus}`;
-      summary = [
-        `OpenClaw gateway status resolved ${runtimeTarget}, but the inspected config declares ${configuredTarget}.`,
-        `Treating \`${facts.pluginStatusRoute.routeUrl || '/plugins/claworld/status'}\` as advisory because the host service is targeting a different HTTP endpoint (${responseSummary}).`,
-      ].join(' ');
-      action = 'Align the host gateway service target with the inspected config if you need live plugin-route proof for this config.';
-    } else if (!routeReachable) {
-      status = 'fail';
-      summary = `Unable to reach ${facts.pluginStatusRoute.routeUrl || 'the plugin status route'}.`;
-      action = 'Confirm the local OpenClaw gateway HTTP surface is reachable, then rerun doctor.';
-    } else if (!facts.pluginStatusRoute.ok) {
-      status = 'warn';
-      summary = `${facts.pluginStatusRoute.routeUrl} responded with ${routeStatus}, which proves the route exists but still requires gateway auth.`;
-      action = 'Provide gateway auth credentials if you need the live plugin status payload.';
-    }
-    checks.push(createCheck({
-      id: 'plugin-status-route',
-      category: 'Credentials and runtime',
-      label: 'Plugin status HTTP route',
-      status,
-      summary,
-      action,
-      details: {
-        ...facts.pluginStatusRoute,
-        configuredBaseUrl: routeTarget.configuredBaseUrl,
-        runtimeBaseUrl: routeTarget.runtimeBaseUrl,
-        baseUrlMismatch: routeTarget.baseUrlMismatch,
-        runtimePortSource: routeTarget.runtimePortSource,
-      },
-    }));
-  } else {
-    checks.push(createCheck({
-      id: 'plugin-status-route',
-      category: 'Credentials and runtime',
-      label: 'Plugin status HTTP route',
-      status: 'warn',
-      summary: 'Skipped the plugin status route check because the OpenClaw gateway runtime is not running.',
-      action: 'Start the gateway, then rerun doctor to verify `/plugins/claworld/status`.',
-    }));
-  }
-
-  const workspaceWorstStatus = workspaceInspection.issues.reduce((current, issue) =>
-    statusRank(issue.severity) > statusRank(current) ? issue.severity : current, 'pass');
-  checks.push(createCheck({
-    id: 'workspace-contract',
-    category: 'Workspace',
-    label: 'Managed workspace contract',
-    status: managedOptions.manageWorkspace ? workspaceWorstStatus : 'pass',
-    summary: managedOptions.manageWorkspace
-      ? (
-        workspaceInspection.ok
-          ? `Managed workspace is present with ${formatWorkspaceState(workspaceInspection)}.`
-          : `Managed workspace needs repair: ${workspaceInspection.issues.map((issue) => issue.code).join(', ')}.`
-      )
-      : `Claworld is attached to existing local agent \`${resolvedAgentId}\`; no dedicated managed workspace is expected.`,
-    action: managedOptions.manageWorkspace && !workspaceInspection.ok
-      ? `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` to repair the managed workspace bootstrap.`
-      : null,
-    details: {
-      workspacePath: workspaceInspection.workspacePath,
-      metadataPath: workspaceInspection.metadataPath,
-      files: workspaceInspection.files.map((file) => ({
-        relativePath: file.relativePath,
-        policy: file.policy,
-        state: file.state,
-        exists: file.exists,
-      })),
-      issues: workspaceInspection.issues,
-      manageWorkspace: managedOptions.manageWorkspace,
-    },
-  }));
-
-  const status = overallStatus(checks);
-  return {
-    ok: status !== 'fail',
-    status,
-    command: CLAWORLD_DOCTOR_COMMAND,
-    configPath: resolvedConfigPath,
-    stateDir: resolvedStateDir,
-    accountId: configuredAccount.accountId || normalizeText(accountId, DEFAULT_CLAWORLD_ACCOUNT_ID),
-    agentId: resolvedAgentId,
-    workspacePath: workspaceInspection.workspacePath,
-    checks,
-    facts,
-  };
-}
-
-export function formatClaworldDoctorReport(result = {}) {
-  const checks = Array.isArray(result.checks) ? result.checks : [];
-  const categoryOrder = [
-    'Host and plugin',
-    'Managed config',
-    'Credentials and runtime',
-    'Workspace',
-  ];
-  const lines = [
-    `Claworld doctor: ${String(result.status || 'pass').toUpperCase()}`,
-    `Command: ${CLAWORLD_DOCTOR_COMMAND}`,
-    `Config: ${result.configPath || '(unknown)'}`,
-    `Managed account: ${result.accountId || '(unknown)'}`,
-    `Bound local agent: ${result.agentId || '(unknown)'}`,
-    `Managed workspace: ${result.workspacePath || '(not used)'}`,
-    '',
-  ];
-
-  for (const category of categoryOrder) {
-    const categoryChecks = checks.filter((check) => check.category === category);
-    if (categoryChecks.length === 0) continue;
-    lines.push(`${category}:`);
-    for (const check of categoryChecks) {
-      lines.push(`${formatStatus(check.status)} ${check.label}: ${check.summary}`);
-      if (check.action) {
-        lines.push(`  Fix: ${check.action}`);
-      }
-    }
-    lines.push('');
-  }
-
-  if (checks.length === 0) {
-    lines.push('No checks were collected.');
-  }
-
-  return `${lines.join('\n').trim()}\n`;
-}