@xfxstudio/claworld 0.2.9 → 0.2.10-beta.0

package/src/openclaw/installer/cli.js

@@ -8,6 +8,7 @@ import {
   CLAWORLD_INSTALLER_BIN_NAME,
   CLAWORLD_INSTALLER_COMMAND,
   CLAWORLD_INSTALLER_PACKAGE_NAME,
+  CLAWORLD_UNINSTALL_COMMAND,
   CLAWORLD_UPDATE_COMMAND,
 } from './constants.js';
 import { formatClaworldDoctorReport, runClaworldDoctor } from './doctor.js';
@@ -15,6 +16,7 @@ import {
   DEFAULT_OPENCLAW_BIN,
   DEFAULT_OPENCLAW_CONFIG_PATH,
   runClaworldInstallerInstall,
+  runClaworldInstallerUninstall,
   runClaworldInstallerUpdate,
 } from './core.js';
 
@@ -38,6 +40,7 @@ Commands:
   install                     Run the installer-first Claworld setup flow
   doctor                      Validate the managed Claworld install health
   update                      Update the tracked Claworld plugin, refresh managed state, and run doctor
+  uninstall                   Safely remove the managed Claworld runtime and uninstall the plugin
   upgrade                     Alias for update
   help                        Show this help
 
@@ -74,6 +77,12 @@ Doctor options:
   --account-id <id>           Managed Claworld account id (default: claworld)
   --agent-id <id>             Local OpenClaw agent id bound to claworld (default: main)
   --workspace <path>          Optional dedicated workspace path override
+Uninstall options:
+  --config <path>             OpenClaw config path (default: ${DEFAULT_OPENCLAW_CONFIG_PATH})
+  --state-dir <path>          Optional OPENCLAW_STATE_DIR for OpenClaw commands
+  --openclaw-bin <path>       OpenClaw CLI binary (default: ${DEFAULT_OPENCLAW_BIN})
+  --account-id <id>           Managed Claworld account id (default: claworld)
+  --agent-id <id>             Local OpenClaw agent id bound to claworld (default: main)
   --json                      Print machine-readable result
   --help, -h                  Show this help
 
@@ -81,6 +90,7 @@ Canonical commands:
   ${CLAWORLD_INSTALLER_COMMAND}
   ${CLAWORLD_DOCTOR_COMMAND}
   ${CLAWORLD_UPDATE_COMMAND}
+  ${CLAWORLD_UNINSTALL_COMMAND}
 `);
 }
 
@@ -132,6 +142,13 @@ export function parseInstallerCliArgs(argv = process.argv.slice(2), env = proces
       agentId: 'main',
       workspace: null,
     },
+    uninstall: {
+      openclawBin: env.OPENCLAW_BIN || DEFAULT_OPENCLAW_BIN,
+      configPath: expandUserPath(env.OPENCLAW_CONFIG_PATH || DEFAULT_OPENCLAW_CONFIG_PATH, homeDir),
+      stateDir: env.OPENCLAW_STATE_DIR ? expandUserPath(env.OPENCLAW_STATE_DIR, homeDir) : null,
+      accountId: 'claworld',
+      agentId: 'main',
+    },
   };
 
   if (argv.length === 0) {
@@ -149,18 +166,21 @@ export function parseInstallerCliArgs(argv = process.argv.slice(2), env = proces
         options.install.configPath = expandUserPath(nextValue(remaining, index), homeDir);
         options.update.configPath = options.install.configPath;
         options.doctor.configPath = options.install.configPath;
+        options.uninstall.configPath = options.install.configPath;
         index += 1;
         break;
       case '--state-dir':
         options.install.stateDir = expandUserPath(nextValue(remaining, index), homeDir);
         options.update.stateDir = options.install.stateDir;
         options.doctor.stateDir = options.install.stateDir;
+        options.uninstall.stateDir = options.install.stateDir;
         index += 1;
         break;
       case '--openclaw-bin':
         options.install.openclawBin = nextValue(remaining, index);
         options.update.openclawBin = options.install.openclawBin;
         options.doctor.openclawBin = options.install.openclawBin;
+        options.uninstall.openclawBin = options.install.openclawBin;
         index += 1;
         break;
       case '--server-url':
@@ -178,12 +198,14 @@ export function parseInstallerCliArgs(argv = process.argv.slice(2), env = proces
         options.install.accountId = nextValue(remaining, index);
         options.update.accountId = options.install.accountId;
         options.doctor.accountId = options.install.accountId;
+        options.uninstall.accountId = options.install.accountId;
         index += 1;
         break;
       case '--agent-id':
         options.install.agentId = nextValue(remaining, index);
         options.update.agentId = options.install.agentId;
         options.doctor.agentId = options.install.agentId;
+        options.uninstall.agentId = options.install.agentId;
         index += 1;
         break;
       case '--workspace':
@@ -226,7 +248,7 @@ export function parseInstallerCliArgs(argv = process.argv.slice(2), env = proces
     }
   }
 
-  if (!['install', 'update', 'doctor', 'help'].includes(options.command)) {
+  if (!['install', 'update', 'uninstall', 'doctor', 'help'].includes(options.command)) {
     throw new Error(`Unknown command: ${options.command}`);
   }
   if (options.command === 'install' && !['npm', 'link', 'copy', 'skip'].includes(options.install.pluginInstallMode)) {
@@ -304,6 +326,19 @@ function printUpdateSummary(result, doctorResult) {
   console.log('');
 }
 
+function printUninstallSummary(result) {
+  console.log('');
+  console.log('Claworld uninstall complete');
+  console.log('===========================');
+  console.log(`Managed account:    ${result.transformed?.backup?.accountId || 'claworld'}`);
+  console.log(`OpenClaw version:   ${result.host?.version || '(unknown)'}`);
+  console.log(`Plugin action:      ${result.plugin?.action || 'unknown'}`);
+  console.log(`Runtime refresh:    ${result.runtimeRefresh?.action || 'unknown'}`);
+  console.log(`Config path:        ${result.configPath}`);
+  console.log(`Backup path:        ${result.backupPath || '(unchanged or new file)'}`);
+  console.log('');
+}
+
 export async function runInstallerCli(argv = process.argv.slice(2), env = process.env) {
   const parsed = parseInstallerCliArgs(argv, env);
   if (parsed.command === 'help') {
@@ -347,6 +382,16 @@ export async function runInstallerCli(argv = process.argv.slice(2), env = proces
     };
   }
 
+  if (parsed.command === 'uninstall') {
+    const result = await runClaworldInstallerUninstall(parsed.uninstall);
+    if (parsed.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      printUninstallSummary(result);
+    }
+    return result;
+  }
+
   const result = await runClaworldDoctor(parsed.doctor);
   if (parsed.json) {
     console.log(JSON.stringify(result, null, 2));

package/src/openclaw/installer/constants.js

@@ -3,4 +3,5 @@ export const CLAWORLD_INSTALLER_PACKAGE_NAME = '@xfxstudio/claworld';
 export const CLAWORLD_INSTALLER_COMMAND = 'npx -y @xfxstudio/claworld install';
 export const CLAWORLD_DOCTOR_COMMAND = 'npx -y @xfxstudio/claworld doctor';
 export const CLAWORLD_UPDATE_COMMAND = 'npx -y @xfxstudio/claworld update';
+export const CLAWORLD_UNINSTALL_COMMAND = 'npx -y @xfxstudio/claworld uninstall';
 export const CLAWORLD_OPENCLAW_MIN_HOST_VERSION = '>=2026.3.22';

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';
@@ -143,7 +147,7 @@ export function isRelayBootstrapReady(account = {}) {
       normalizeText(account?.appToken, null)
       || (
         account?.registration?.enabled === true
-        && normalizeText(account?.registration?.agentCode, null)
+        && normalizeText(account?.registration?.displayName, null)
       )
     ),
   );
@@ -658,6 +662,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 +696,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 +723,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 +732,7 @@ export function inspectManagedClaworldInstall({
     accountId,
     input,
     overrides,
+    installerState,
   });
   const managedAgentPresent = Boolean(findAgentEntry(cfg, managedOptions.agentId));
   const managedBindingPresent = hasManagedBinding(cfg, managedOptions);
@@ -735,7 +772,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 +919,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({
@@ -1337,8 +1377,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 +1403,7 @@ async function reconcileManagedClaworldRuntime({
   const existingInstall = inspectManagedClaworldInstall({
     cfg: currentConfig,
     accountId,
+    installerState: currentInstallerState,
     overrides: {
       agentId,
       workspace,
@@ -1405,6 +1448,7 @@ async function reconcileManagedClaworldRuntime({
   const preflight = inspectManagedClaworldInstall({
     cfg: currentConfig,
     accountId: installAccountId,
+    installerState: currentInstallerState,
     overrides: {
       agentId: installAgentId,
       workspace,
@@ -1453,6 +1497,7 @@ async function reconcileManagedClaworldRuntime({
 
   const managedOptions = resolveClaworldManagedRuntimeOptions({
     cfg: currentConfig,
+    installerState: currentInstallerState,
     accountId: installAccountId,
     input: {
       name: desiredDisplayName,
@@ -1526,6 +1571,16 @@ async function reconcileManagedClaworldRuntime({
     );
   }
 
+  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,
@@ -1540,6 +1595,8 @@ async function reconcileManagedClaworldRuntime({
     workspaceActions,
     runtimeRefresh,
     verification,
+    installerStatePath,
+    installerStateChanged,
   };
 }
 
@@ -1567,6 +1624,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 +1632,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 +1679,10 @@ export async function runClaworldInstallerInstall({
   const lifecycle = await reconcileManagedClaworldRuntime({
     openclawBin,
     configPath: resolvedConfigPath,
+    installerStatePath,
     stateDir: resolvedStateDir,
     currentConfigState,
+    currentInstallerState,
     currentConfig,
     host,
     serverUrl,
@@ -1646,6 +1707,7 @@ export async function runClaworldInstallerInstall({
     ok: true,
     command: CLAWORLD_INSTALLER_COMMAND,
     configPath: resolvedConfigPath,
+    installerStatePath,
     stateDir: resolvedStateDir,
     host,
     plugin,
@@ -1674,6 +1736,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 +1744,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 +1776,10 @@ export async function runClaworldInstallerUpdate({
   const lifecycle = await reconcileManagedClaworldRuntime({
     openclawBin,
     configPath: resolvedConfigPath,
+    installerStatePath,
     stateDir: resolvedStateDir,
     currentConfigState: refreshedConfigState,
+    currentInstallerState,
     currentConfig,
     host,
     serverUrl,
@@ -1737,6 +1803,7 @@ export async function runClaworldInstallerUpdate({
     ok: true,
     command: CLAWORLD_UPDATE_COMMAND,
     configPath: resolvedConfigPath,
+    installerStatePath,
     stateDir: resolvedStateDir,
     host,
     plugin,
@@ -1744,6 +1811,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,

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),
     },
   };
 }