@xfxstudio/claworld 0.2.9 → 0.2.10-beta.1

package/src/openclaw/installer/core.js

@@ -11,8 +11,11 @@ import {
   applyClaworldManagedRuntimeConfig,
   ensureObject,
   expandUserPath,
+  findClaworldManagedRuntimeBackup,
   normalizeText,
   resolveClaworldManagedRuntimeOptions,
+  setClaworldManagedRuntimeBackupState,
+  stripClaworldManagedRuntimeConfig,
 } from '../plugin/managed-config.js';
 import {
   defaultClaworldAccountId,
@@ -23,6 +26,7 @@ import {
   CLAWORLD_INSTALLER_COMMAND,
   CLAWORLD_INSTALLER_PACKAGE_NAME,
   CLAWORLD_OPENCLAW_MIN_HOST_VERSION,
+  CLAWORLD_UNINSTALL_COMMAND,
   CLAWORLD_UPDATE_COMMAND,
 } from './constants.js';
 import { seedManagedWorkspaceContract } from './workspace-contract.js';
@@ -139,13 +143,7 @@ export function isManagedToolAllowlistReady(config = {}, options = {}) {
 export function isRelayBootstrapReady(account = {}) {
   return Boolean(
     account?.configured
-    && (
-      normalizeText(account?.appToken, null)
-      || (
-        account?.registration?.enabled === true
-        && normalizeText(account?.registration?.agentCode, null)
-      )
-    ),
+    && normalizeText(account?.appToken, null),
   );
 }
 
@@ -658,6 +656,23 @@ export async function loadConfigFromDisk(configPath) {
   }
 }
 
+export function resolveClaworldInstallerStatePath(configPath) {
+  const resolvedConfigPath = path.resolve(String(configPath || DEFAULT_OPENCLAW_CONFIG_PATH));
+  return path.join(path.dirname(resolvedConfigPath), '.claworld-installer-state.json');
+}
+
+export async function loadInstallerStateFromDisk(installerStatePath) {
+  try {
+    const raw = await fs.readFile(installerStatePath, 'utf8');
+    return { existed: true, state: parseConfigObject(raw, installerStatePath) };
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return { existed: false, state: {} };
+    }
+    throw error;
+  }
+}
+
 export async function backupConfigIfPresent(configPath, existed, dryRun = false) {
   if (!existed) return null;
   const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..+$/, '').replace('T', '-');
@@ -675,6 +690,20 @@ export async function writeConfig(configPath, config, dryRun = false) {
   return rendered;
 }
 
+export async function writeInstallerState(installerStatePath, installerState, dryRun = false) {
+  const renderedState = ensureObject(installerState);
+  if (Object.keys(renderedState).length === 0) {
+    if (dryRun) return '';
+    await fs.rm(installerStatePath, { force: true });
+    return '';
+  }
+  const rendered = `${JSON.stringify(renderedState, null, 2)}\n`;
+  if (dryRun) return rendered;
+  await fs.mkdir(path.dirname(installerStatePath), { recursive: true });
+  await fs.writeFile(installerStatePath, rendered, 'utf8');
+  return rendered;
+}
+
 export function buildOpenclawCommandEnv({ configPath, stateDir = null, env = process.env } = {}) {
   return {
     ...env,
@@ -688,6 +717,7 @@ export function inspectManagedClaworldInstall({
   accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
   input = {},
   overrides = {},
+  installerState = {},
 } = {}) {
   const configuredAccountIds = listClaworldAccountIds(cfg);
   const hasAnyConfig = configuredAccountIds.length > 0 || cfg?.channels?.claworld != null;
@@ -696,6 +726,7 @@ export function inspectManagedClaworldInstall({
     accountId,
     input,
     overrides,
+    installerState,
   });
   const managedAgentPresent = Boolean(findAgentEntry(cfg, managedOptions.agentId));
   const managedBindingPresent = hasManagedBinding(cfg, managedOptions);
@@ -719,8 +750,8 @@ export function inspectManagedClaworldInstall({
     statusLabel = managedReady ? 'configured' : 'configured (managed refresh recommended)';
     selectionHint = managedReady ? 'configured · managed runtime' : 'configured · managed refresh';
   } else if (hasAnyConfig) {
-    statusLabel = 'needs refresh';
-    selectionHint = 'needs refresh · remote relay';
+    statusLabel = 'configured (activation pending)';
+    selectionHint = 'configured · activation pending';
   }
 
   return {
@@ -735,7 +766,10 @@ export function inspectManagedClaworldInstall({
     accountStatus,
     managedRuntimeReady,
     managedReady,
-    reusableAppToken: normalizeText(accountStatus?.appToken, null),
+    reusableAppToken: normalizeText(
+      managedOptions.appToken,
+      normalizeText(accountStatus?.appToken, null),
+    ),
     statusLabel,
     selectionHint,
     quickstartScore: managedRuntimeReady ? 2 : 5,
@@ -879,7 +913,7 @@ export async function ensureClaworldPluginInstalled({
       });
     }
 
-    const args = ['plugins', 'install'];
+    const args = ['plugins', 'install', '--dangerously-force-unsafe-install'];
     if (installMode === 'link') args.push('--link');
     args.push(installSource);
     await executeCommand({
@@ -1248,6 +1282,7 @@ export async function verifyClaworldInstall({
   attempts = DEFAULT_VERIFICATION_ATTEMPTS,
   delayMs = DEFAULT_VERIFICATION_DELAY_MS,
   requireGatewayRunning = resolveRequireGatewayRunning(env),
+  requireChannelToken = true,
 } = {}) {
   let lastResult = null;
 
@@ -1301,7 +1336,10 @@ export async function verifyClaworldInstall({
       channelAccount
       && channelAccount.configured === true
       && channelAccount.enabled !== false
-      && channelAccount.tokenStatus === 'available'
+      && (
+        requireChannelToken !== true
+        || channelAccount.tokenStatus === 'available'
+      )
     );
     const pluginReady = Boolean(plugin.installed);
     const bindingReady = Boolean(bindingLine);
@@ -1318,6 +1356,7 @@ export async function verifyClaworldInstall({
       channelReady,
       bindingReady,
       requireGatewayRunning,
+      requireChannelToken,
     };
 
     if (lastResult.ok) {
@@ -1337,8 +1376,10 @@ export async function verifyClaworldInstall({
 async function reconcileManagedClaworldRuntime({
   openclawBin = DEFAULT_OPENCLAW_BIN,
   configPath = DEFAULT_OPENCLAW_CONFIG_PATH,
+  installerStatePath = null,
   stateDir = DEFAULT_OPENCLAW_STATE_DIR,
   currentConfigState = { existed: false, config: {} },
+  currentInstallerState = {},
   currentConfig = {},
   host = null,
   serverUrl = null,
@@ -1361,6 +1402,7 @@ async function reconcileManagedClaworldRuntime({
   const existingInstall = inspectManagedClaworldInstall({
     cfg: currentConfig,
     accountId,
+    installerState: currentInstallerState,
     overrides: {
       agentId,
       workspace,
@@ -1376,35 +1418,19 @@ async function reconcileManagedClaworldRuntime({
     normalizeText(existingInstall.accountStatus?.serverUrl, DEFAULT_CLAWORLD_SERVER_URL),
   );
 
-  const manifest = await fetchInstallManifest({
-    serverUrl: effectiveServerUrl,
-    apiKey,
-    fetchImpl,
-  });
-  const manifestMinHostVersion = normalizeText(
-    manifest?.installer?.minHostVersion,
-    normalizeText(manifest?.plugin?.minHostVersion, CLAWORLD_OPENCLAW_MIN_HOST_VERSION),
-  );
-  if (host && compareVersionParts(host.version, manifestMinHostVersion) < 0) {
-    throw createInstallerError(
-      'openclaw_version_too_old',
-      `OpenClaw ${host.version} is below the required minimum ${manifestMinHostVersion}.`,
-      { hostVersion: host.version, minHostVersion: manifestMinHostVersion },
-    );
-  }
-
   const installAccountId = normalizeText(
     accountId,
-    normalizeText(manifest?.setup?.defaultAccountId, DEFAULT_CLAWORLD_ACCOUNT_ID),
+    DEFAULT_CLAWORLD_ACCOUNT_ID,
   );
   const installAgentId = normalizeText(
     agentId,
-    normalizeText(manifest?.setup?.defaultLocalAgentId, installAccountId),
+    installAccountId,
   );
 
   const preflight = inspectManagedClaworldInstall({
     cfg: currentConfig,
     accountId: installAccountId,
+    installerState: currentInstallerState,
     overrides: {
       agentId: installAgentId,
       workspace,
@@ -1421,50 +1447,15 @@ async function reconcileManagedClaworldRuntime({
     normalizeText(preflight.managedOptions.displayName, null),
   );
 
-  let activation = null;
-  let activationMode = 'new_activation';
-  const existingAppToken = normalizeText(preflight.reusableAppToken, null);
-  if (existingAppToken) {
-    try {
-      activation = await activateInstall({
-        serverUrl: effectiveServerUrl,
-        apiKey,
-        appToken: existingAppToken,
-        displayName: desiredDisplayName,
-        fetchImpl,
-      });
-      activationMode = 'reused_existing_token';
-    } catch (error) {
-      const status = error?.context?.response?.status;
-      if (status !== 401 && status !== 403) {
-        throw error;
-      }
-    }
-  }
-  if (!activation) {
-    activation = await activateInstall({
-      serverUrl: effectiveServerUrl,
-      apiKey,
-      displayName: desiredDisplayName,
-      fetchImpl,
-    });
-    activationMode = 'created_new_activation';
-  }
-
   const managedOptions = resolveClaworldManagedRuntimeOptions({
     cfg: currentConfig,
+    installerState: currentInstallerState,
     accountId: installAccountId,
-    input: {
-      name: desiredDisplayName,
-      appToken: activation.appToken,
-      toolProfile,
-    },
     overrides: {
       agentId: installAgentId,
       workspace,
       serverUrl: effectiveServerUrl,
       apiKey,
-      appToken: activation.appToken,
       displayName: desiredDisplayName,
       toolProfile,
       approvalMode,
@@ -1517,29 +1508,40 @@ async function reconcileManagedClaworldRuntime({
     env,
     dryRun,
     delayMs: Math.min(timeoutMs, DEFAULT_VERIFICATION_DELAY_MS),
+    requireChannelToken: Boolean(managedOptions.appToken),
   });
   if (!verification.ok) {
     throw createInstallerError(
       'claworld_install_verification_failed',
-      'Claworld install verification did not confirm the managed account binding.',
+      'Claworld install verification did not confirm the managed channel runtime shape.',
       { verification },
     );
   }
 
+  let installerStateChanged = false;
+  if (installerStatePath && installAccountId) {
+    const nextInstallerState = JSON.parse(JSON.stringify(ensureObject(currentInstallerState)));
+    setClaworldManagedRuntimeBackupState(nextInstallerState, installAccountId, null);
+    installerStateChanged = JSON.stringify(currentInstallerState) !== JSON.stringify(nextInstallerState);
+    if (installerStateChanged) {
+      await writeInstallerState(installerStatePath, nextInstallerState, dryRun);
+    }
+  }
+
   return {
     backupPath,
     existingInstall,
     effectiveServerUrl,
-    manifest,
     preflight,
-    activationMode,
-    activation,
+    activationStatus: managedOptions.appToken ? 'ready' : 'pending',
     managedOptions,
     transformed,
     configChanged,
     workspaceActions,
     runtimeRefresh,
     verification,
+    installerStatePath,
+    installerStateChanged,
   };
 }
 
@@ -1567,6 +1569,7 @@ export async function runClaworldInstallerInstall({
   timeoutMs = DEFAULT_INSTALL_TIMEOUT_MS,
 } = {}) {
   const resolvedConfigPath = path.resolve(expandUserPath(configPath, os.homedir()));
+  const installerStatePath = resolveClaworldInstallerStatePath(resolvedConfigPath);
   const resolvedStateDir = stateDir ? path.resolve(expandUserPath(stateDir, os.homedir())) : null;
   const commandEnv = buildOpenclawCommandEnv({
     configPath: resolvedConfigPath,
@@ -1574,6 +1577,7 @@ export async function runClaworldInstallerInstall({
     env,
   });
   const currentConfigState = await loadConfigFromDisk(resolvedConfigPath);
+  const currentInstallerState = (await loadInstallerStateFromDisk(installerStatePath)).state;
   const currentConfigBeforePluginInstall = currentConfigState.config;
   const host = await detectOpenclawHost({
     openclawBin,
@@ -1620,8 +1624,10 @@ export async function runClaworldInstallerInstall({
   const lifecycle = await reconcileManagedClaworldRuntime({
     openclawBin,
     configPath: resolvedConfigPath,
+    installerStatePath,
     stateDir: resolvedStateDir,
     currentConfigState,
+    currentInstallerState,
     currentConfig,
     host,
     serverUrl,
@@ -1646,6 +1652,7 @@ export async function runClaworldInstallerInstall({
     ok: true,
     command: CLAWORLD_INSTALLER_COMMAND,
     configPath: resolvedConfigPath,
+    installerStatePath,
     stateDir: resolvedStateDir,
     host,
     plugin,
@@ -1674,6 +1681,7 @@ export async function runClaworldInstallerUpdate({
   timeoutMs = DEFAULT_INSTALL_TIMEOUT_MS,
 } = {}) {
   const resolvedConfigPath = path.resolve(expandUserPath(configPath, os.homedir()));
+  const installerStatePath = resolveClaworldInstallerStatePath(resolvedConfigPath);
   const resolvedStateDir = stateDir ? path.resolve(expandUserPath(stateDir, os.homedir())) : null;
   const commandEnv = buildOpenclawCommandEnv({
     configPath: resolvedConfigPath,
@@ -1681,6 +1689,7 @@ export async function runClaworldInstallerUpdate({
     env,
   });
   const currentConfigState = await loadConfigFromDisk(resolvedConfigPath);
+  const currentInstallerState = (await loadInstallerStateFromDisk(installerStatePath)).state;
   const host = await detectOpenclawHost({
     openclawBin,
     commandRunner,
@@ -1712,8 +1721,10 @@ export async function runClaworldInstallerUpdate({
   const lifecycle = await reconcileManagedClaworldRuntime({
     openclawBin,
     configPath: resolvedConfigPath,
+    installerStatePath,
     stateDir: resolvedStateDir,
     currentConfigState: refreshedConfigState,
+    currentInstallerState,
     currentConfig,
     host,
     serverUrl,
@@ -1737,6 +1748,7 @@ export async function runClaworldInstallerUpdate({
     ok: true,
     command: CLAWORLD_UPDATE_COMMAND,
     configPath: resolvedConfigPath,
+    installerStatePath,
     stateDir: resolvedStateDir,
     host,
     plugin,
@@ -1744,6 +1756,170 @@ export async function runClaworldInstallerUpdate({
   };
 }
 
+export async function runClaworldInstallerUninstall({
+  openclawBin = DEFAULT_OPENCLAW_BIN,
+  configPath = DEFAULT_OPENCLAW_CONFIG_PATH,
+  stateDir = DEFAULT_OPENCLAW_STATE_DIR,
+  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
+  agentId = DEFAULT_CLAWORLD_AGENT_ID,
+  commandRunner = defaultCommandRunner,
+  cwd = process.cwd(),
+  env = process.env,
+  dryRun = false,
+} = {}) {
+  const resolvedConfigPath = path.resolve(expandUserPath(configPath, os.homedir()));
+  const installerStatePath = resolveClaworldInstallerStatePath(resolvedConfigPath);
+  const resolvedStateDir = stateDir ? path.resolve(expandUserPath(stateDir, os.homedir())) : null;
+  const commandEnv = buildOpenclawCommandEnv({
+    configPath: resolvedConfigPath,
+    stateDir: resolvedStateDir,
+    env,
+  });
+  const currentConfigState = await loadConfigFromDisk(resolvedConfigPath);
+  const currentInstallerState = (await loadInstallerStateFromDisk(installerStatePath)).state;
+  const currentConfig = currentConfigState.config;
+  const host = await detectOpenclawHost({
+    openclawBin,
+    commandRunner,
+    cwd,
+    env: commandEnv,
+    dryRun,
+  });
+  if (compareVersionParts(host.version, CLAWORLD_OPENCLAW_MIN_HOST_VERSION) < 0) {
+    throw createInstallerError(
+      'openclaw_version_too_old',
+      `OpenClaw ${host.version} is below the required minimum ${CLAWORLD_OPENCLAW_MIN_HOST_VERSION}.`,
+      { hostVersion: host.version, minHostVersion: CLAWORLD_OPENCLAW_MIN_HOST_VERSION },
+    );
+  }
+
+  const pluginBefore = await inspectClaworldPluginInstall({
+    openclawBin,
+    configPath: resolvedConfigPath,
+    stateDir: resolvedStateDir,
+    commandRunner,
+    cwd,
+    env,
+    dryRun,
+  });
+  const transformed = stripClaworldManagedRuntimeConfig(currentConfig, {
+    accountId,
+    agentId,
+    preserveBackup: true,
+  });
+  const configChanged = JSON.stringify(currentConfig) !== JSON.stringify(transformed.config);
+  const backupPath = configChanged
+    ? await backupConfigIfPresent(resolvedConfigPath, currentConfigState.existed, dryRun)
+    : null;
+  if (configChanged) {
+    await writeConfig(resolvedConfigPath, transformed.config, dryRun);
+  }
+  const nextInstallerState = JSON.parse(JSON.stringify(ensureObject(currentInstallerState)));
+  setClaworldManagedRuntimeBackupState(nextInstallerState, accountId, transformed.backup);
+  const installerStateChanged = JSON.stringify(currentInstallerState) !== JSON.stringify(nextInstallerState);
+  if (installerStateChanged) {
+    await writeInstallerState(installerStatePath, nextInstallerState, dryRun);
+  }
+
+  await validateOpenclawConfig({
+    openclawBin,
+    configPath: resolvedConfigPath,
+    stateDir: resolvedStateDir,
+    commandRunner,
+    cwd,
+    env,
+    dryRun,
+  });
+
+  const uninstallBootstrap = pluginBefore.installed
+    ? await preparePluginBootstrapConfig({
+        configPath: resolvedConfigPath,
+        config: currentConfig,
+        dryRun,
+      })
+    : null;
+
+  let pluginAction = 'plugin_already_absent';
+  try {
+    if (pluginBefore.installed) {
+      await executeCommand({
+        commandRunner,
+        bin: openclawBin,
+        args: ['plugins', 'uninstall', 'claworld', '--force'],
+        cwd,
+        env: buildOpenclawCommandEnv({
+          configPath: uninstallBootstrap?.configPath || resolvedConfigPath,
+          stateDir: resolvedStateDir,
+          env,
+        }),
+        dryRun,
+        capture: false,
+      });
+      pluginAction = 'uninstalled_plugin';
+    }
+  } finally {
+    if (uninstallBootstrap) {
+      await uninstallBootstrap.cleanup();
+    }
+  }
+
+  const runtimeRefresh = await refreshOpenclawRuntime({
+    openclawBin,
+    configPath: resolvedConfigPath,
+    stateDir: resolvedStateDir,
+    commandRunner,
+    cwd,
+    env,
+    dryRun,
+  });
+  const pluginAfter = await inspectClaworldPluginInstall({
+    openclawBin,
+    configPath: resolvedConfigPath,
+    stateDir: resolvedStateDir,
+    commandRunner,
+    cwd,
+    env,
+    dryRun,
+  });
+  if (pluginBefore.installed && pluginAfter.installed) {
+    throw createInstallerError(
+      'claworld_plugin_uninstall_failed',
+      'OpenClaw still reports the claworld plugin as installed after uninstall.',
+      { before: pluginBefore, after: pluginAfter },
+    );
+  }
+
+  const gatewayStatus = await readGatewayStatus({
+    openclawBin,
+    configPath: resolvedConfigPath,
+    stateDir: resolvedStateDir,
+    commandRunner,
+    cwd,
+    env,
+    dryRun,
+  });
+
+  return {
+    ok: true,
+    command: CLAWORLD_UNINSTALL_COMMAND,
+    configPath: resolvedConfigPath,
+    installerStatePath,
+    stateDir: resolvedStateDir,
+    host,
+    backupPath,
+    transformed,
+    configChanged,
+    installerStateChanged,
+    plugin: {
+      action: pluginAction,
+      before: pluginBefore,
+      after: pluginAfter,
+    },
+    runtimeRefresh,
+    gatewayStatus,
+  };
+}
+
 export {
   compareVersionParts,
   defaultCommandRunner,

package/src/openclaw/installer/doctor.js

@@ -249,8 +249,8 @@ export async function runClaworldDoctor({
       workspace: resolvedWorkspace,
       serverUrl: effectiveServerUrl,
       appToken: configuredAccount.appToken,
-      registrationAgentCode: configuredAccount.registration?.agentCode || null,
-      defaultToAddress: configuredAccount.relay?.defaultToAddress || null,
+      registrationDisplayName: configuredAccount.registration?.displayName || null,
+      defaultTargetAgentId: configuredAccount.relay?.defaultTargetAgentId || null,
     })
     : {
       ok: true,
@@ -522,11 +522,13 @@ export async function runClaworldDoctor({
     id: 'app-token',
     category: 'Credentials and runtime',
     label: 'Managed appToken',
-    status: configuredAccount.tokenStatus === 'available' ? 'pass' : 'fail',
+    status: configuredAccount.tokenStatus === 'available' ? 'pass' : 'warn',
     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.`,
+      : `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_update_public_identity` when prompted.',
     details: { tokenSource: configuredAccount.tokenSource, tokenStatus: configuredAccount.tokenStatus },
   }));
 
@@ -549,9 +551,9 @@ export async function runClaworldDoctor({
       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.',
+      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) },
     }));
   }
@@ -580,7 +582,7 @@ export async function runClaworldDoctor({
         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.`,
+        action: 'Run `claworld_pair_agent` in a live OpenClaw session to refresh the managed relay binding.',
         details: { message: error?.message || String(error) },
       }));
     }
@@ -589,17 +591,17 @@ export async function runClaworldDoctor({
       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.`,
+      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_update_public_identity` when prompted.',
     }));
   } 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.',
+      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.',
     }));
   }
@@ -655,15 +657,27 @@ export async function runClaworldDoctor({
       && 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' : 'fail',
+      status: channelHealthy ? 'pass' : channelPendingActivation ? 'warn' : '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.`,
+        : 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_update_public_identity` when prompted.'
+          : `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` or restart the gateway to recover the managed account runtime.`,
       details: { channelAccount },
     }));
   } catch (error) {

package/src/openclaw/plugin/account-identity.js

@@ -17,7 +17,6 @@ export function normalizeRuntimeRegistration(candidate = {}) {
 
   return {
     enabled: true,
-    agentCode: normalizeText(registration.agentCode, normalizeText(legacyLocalAgent.agentCode, null)),
     displayName: normalizeText(registration.displayName, normalizeText(legacyLocalAgent.displayName, null)),
   };
 }
@@ -49,7 +48,7 @@ export function applyRuntimeIdentity(runtimeConfig = {}, { agentId = null, appTo
       agentId: normalizeText(agentId, normalizeText(relay.agentId, null)),
       appToken: resolvedAppToken,
       credentialToken: resolvedAppToken,
-      defaultToAddress: normalizeText(relay.defaultToAddress, null),
+      defaultTargetAgentId: normalizeText(relay.defaultTargetAgentId, null),
     },
   };
 }