@xfxstudio/claworld 0.1.0

package/src/openclaw/installer/doctor.js

@@ -0,0 +1,690 @@
+import os from 'os';
+import path from 'path';
+import { inspectClaworldChannelAccount } from '../plugin/config-schema.js';
+import {
+  DEFAULT_CLAWORLD_ACCOUNT_ID,
+  DEFAULT_CLAWORLD_SERVER_URL,
+  expandUserPath,
+  normalizeText,
+} 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;
+}
+
+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}`;
+}
+
+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_ACCOUNT_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 rawManagedAccount = config?.channels?.claworld?.accounts?.[configuredAccount.accountId] || null;
+  const configuredApiKey = normalizeText(rawManagedAccount?.apiKey, 'local-test');
+  const resolvedAgentId = normalizeText(agentId, normalizeText(configuredAccount.accountId, DEFAULT_CLAWORLD_ACCOUNT_ID));
+  const resolvedWorkspace = normalizeText(
+    workspace,
+    normalizeText(findManagedAgentEntry(config, resolvedAgentId)?.workspace, `~/.openclaw/workspace-${resolvedAgentId}`),
+  );
+  const effectiveServerUrl = normalizeText(
+    serverUrl,
+    normalizeText(configuredAccount.serverUrl, DEFAULT_CLAWORLD_SERVER_URL),
+  );
+  const workspaceInspection = await inspectManagedWorkspaceContract({
+    agentId: resolvedAgentId,
+    accountId: normalizeText(accountId, configuredAccount.accountId || DEFAULT_CLAWORLD_ACCOUNT_ID),
+    workspace: resolvedWorkspace,
+    serverUrl: effectiveServerUrl,
+    appToken: configuredAccount.appToken,
+    registrationAgentCode: configuredAccount.registration?.agentCode || null,
+    defaultToAddress: configuredAccount.relay?.defaultToAddress || null,
+  });
+
+  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 },
+      }));
+    } 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 },
+      }));
+    }
+  } 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: 'Managed local agent entry',
+    status: agentEntry && agentWorkspace === resolvedWorkspace ? 'pass' : 'fail',
+    summary: 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.`,
+    action: `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` to reconcile the managed agent entry.`,
+    details: { expectedWorkspace: resolvedWorkspace, actualWorkspace: agentWorkspace },
+  }));
+
+  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 },
+  }));
+
+  checks.push(createCheck({
+    id: 'app-token',
+    category: 'Credentials and runtime',
+    label: 'Managed appToken',
+    status: configuredAccount.tokenStatus === 'available' ? 'pass' : 'fail',
+    summary: configuredAccount.tokenStatus === 'available'
+      ? 'Managed account has an available appToken.'
+      : `Managed account token status is ${configuredAccount.tokenStatus}.`,
+    action: `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` to refresh activation and persist a healthy appToken.`,
+    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: 'fail',
+      summary: `Unable to read the Claworld install contract from ${effectiveServerUrl}.`,
+      action: 'Confirm the backend URL is correct and reachable, 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: `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` to refresh the managed credential and 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: 'fail',
+      summary: 'Doctor could not verify the managed relay binding because no reusable appToken is configured.',
+      action: `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` to finish activation and persist an appToken.`,
+    }));
+  } else {
+    checks.push(createCheck({
+      id: 'stable-agent-binding',
+      category: 'Credentials and runtime',
+      label: 'Stable relay binding',
+      status: 'fail',
+      summary: 'Doctor could not verify the managed relay binding because the backend install contract 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'
+    );
+    checks.push(createCheck({
+      id: 'channel-runtime',
+      category: 'Credentials and runtime',
+      label: 'Claworld channel runtime account',
+      status: channelHealthy ? 'pass' : 'fail',
+      summary: channelHealthy
+        ? `channels status reports managed account \`${configuredAccount.accountId}\` as configured with an available token.`
+        : `channels status does not report a healthy managed account for \`${configuredAccount.accountId}\`.`,
+      action: `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 gatewayBaseUrl = normalizeGatewayBaseUrl(facts.gatewayStatus);
+    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 (!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,
+    }));
+  } 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: workspaceWorstStatus,
+    summary: workspaceInspection.ok
+      ? `Managed workspace is present with ${formatWorkspaceState(workspaceInspection)}.`
+      : `Managed workspace needs repair: ${workspaceInspection.issues.map((issue) => issue.code).join(', ')}.`,
+    action: workspaceInspection.ok ? null : `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` to repair the managed workspace bootstrap.`,
+    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,
+    },
+  }));
+
+  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)'}`,
+    `Managed agent: ${result.agentId || '(unknown)'}`,
+    `Managed workspace: ${result.workspacePath || '(unknown)'}`,
+    '',
+  ];
+
+  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`;
+}