@xfxstudio/claworld 0.2.21 → 0.2.23-beta.0

package/openclaw.plugin.json

@@ -8,7 +8,7 @@
   ],
   "name": "Claworld Persona Relay",
   "description": "Claworld relay world channel plugin for OpenClaw.",
-  "version": "0.2.21",
+  "version": "0.2.23-beta.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfxstudio/claworld",
-  "version": "0.2.21",
+  "version": "0.2.23-beta.0",
   "description": "Claworld channel plugin for OpenClaw",
   "type": "module",
   "main": "index.js",

package/src/openclaw/plugin/claworld-channel-plugin.js

@@ -17,6 +17,10 @@ import {
   resolveClaworldRuntimeConfig,
   validateClaworldChannelConfig,
 } from './config-schema.js';
+import {
+  loadClaworldRuntimeBackup,
+  persistClaworldRuntimeBackup,
+} from './runtime-backup.js';
 import {
   claworldOnboardingAdapter,
   claworldSetupAdapter,
@@ -1324,6 +1328,30 @@ function createDeliveryReplyDispatcher({
     runtimeOutputSummary.counts[kind] += 1;
   };
 
+  const submitRelayReply = async (replyText) => {
+    if (typeof relayClient?.submitDeliveryReply !== 'function') {
+      throw new Error('relay client does not support reply submission');
+    }
+    return await relayClient.submitDeliveryReply({
+      deliveryId,
+      sessionKey,
+      replyText,
+      source: 'openclaw-autochain',
+    });
+  };
+
+  const submitRelayKeptSilent = async (reason) => {
+    if (typeof relayClient?.submitDeliveryKeptSilent !== 'function') {
+      throw new Error('relay client does not support kept_silent submission');
+    }
+    return await relayClient.submitDeliveryKeptSilent({
+      deliveryId,
+      sessionKey,
+      reason,
+      source: 'openclaw-autochain',
+    });
+  };
+
   const flushReply = async (text) => {
     const normalized = String(text || '').trim();
     if (!normalized || replied || suppressed) return false;
@@ -1331,25 +1359,9 @@ function createDeliveryReplyDispatcher({
       suppressed = true;
       return false;
     }
-    if (typeof relayClient.sendReplyAndWaitForAck === 'function') {
-      const replyResult = await relayClient.sendReplyAndWaitForAck({
-        deliveryId,
-        sessionKey,
-        replyText: normalized,
-        source: 'openclaw-autochain',
-      });
-      replyTransport = replyResult?.transport || 'websocket';
-      replyFallbackUsed = replyResult?.fallbackUsed === true;
-    } else {
-      relayClient.sendReply({
-        deliveryId,
-        sessionKey,
-        replyText: normalized,
-        source: 'openclaw-autochain',
-      });
-      replyTransport = 'websocket-fire-and-forget';
-      replyFallbackUsed = false;
-    }
+    const replyResult = await submitRelayReply(normalized);
+    replyTransport = replyResult?.transport || null;
+    replyFallbackUsed = replyResult?.fallbackUsed === true;
     replied = true;
     return true;
   };
@@ -1360,19 +1372,11 @@ function createDeliveryReplyDispatcher({
       suppressed = true;
       return false;
     }
-    if (typeof relayClient.sendKeepSilentAndWaitForAck === 'function') {
-      const silentResult = await relayClient.sendKeepSilentAndWaitForAck({
-        deliveryId,
-        sessionKey,
-        reason: normalizePluginOptionalText(reason) || 'no_renderable_reply',
-        source: 'openclaw-autochain',
-      });
-      keptSilentTransport = silentResult?.transport || 'websocket';
-      keptSilentFallbackUsed = silentResult?.fallbackUsed === true;
-    } else {
-      keptSilentTransport = 'unsupported';
-      keptSilentFallbackUsed = false;
-    }
+    const silentResult = await submitRelayKeptSilent(
+      normalizePluginOptionalText(reason) || 'no_renderable_reply',
+    );
+    keptSilentTransport = silentResult?.transport || null;
+    keptSilentFallbackUsed = silentResult?.fallbackUsed === true;
     keptSilent = true;
     return true;
   };
@@ -1705,12 +1709,13 @@ async function maybeBridgeRuntimeDelivery({
   });
 
   try {
-    if (typeof relayClient?.sendAcceptedAndWaitForAck === 'function') {
-      await relayClient.sendAcceptedAndWaitForAck({
-        deliveryId,
-        sessionKey,
-        source: 'runtime_dispatch',
-      });
+    const acceptedResult = await relayClient.acceptDeliveryHttp({
+      deliveryId,
+      sessionKey,
+      source: 'runtime_dispatch',
+    });
+    if (acceptedResult.status < 200 || acceptedResult.status >= 300) {
+      throw new Error(`failed to submit relay delivery acceptance: ${acceptedResult.status}`);
     }
   } catch (error) {
     logger.warn?.(`[claworld:${runtimeAccountId}] delivery acceptance acknowledgement failed`, {
@@ -1895,48 +1900,118 @@ export function createClaworldChannelPlugin({
   }
 
   async function persistRuntimeAppToken({ runtime, accountId, appToken, relayAgentId = null }) {
-    if (!runtime?.config?.loadConfig || !runtime?.config?.writeConfigFile) {
-      return { skipped: true, reason: 'missing_runtime_config_io' };
-    }
     if (!accountId || !appToken) {
       return { skipped: true, reason: 'missing_account_or_token' };
     }
 
-    const currentCfg = await runtime.config.loadConfig();
-    const nextCfg = JSON.parse(JSON.stringify(currentCfg || {}));
-    nextCfg.channels = nextCfg.channels && typeof nextCfg.channels === 'object' && !Array.isArray(nextCfg.channels)
-      ? nextCfg.channels
-      : {};
-    const claworldRoot = nextCfg.channels.claworld && typeof nextCfg.channels.claworld === 'object' && !Array.isArray(nextCfg.channels.claworld)
-      ? nextCfg.channels.claworld
-      : {};
-    const accounts = claworldRoot.accounts && typeof claworldRoot.accounts === 'object' && !Array.isArray(claworldRoot.accounts)
-      ? claworldRoot.accounts
-      : {};
-    const account = accounts[accountId] && typeof accounts[accountId] === 'object' && !Array.isArray(accounts[accountId])
-      ? accounts[accountId]
-      : {};
+    let configPersistResult = { skipped: true, reason: 'missing_runtime_config_io' };
+    if (runtime?.config?.loadConfig && runtime?.config?.writeConfigFile) {
+      const currentCfg = await runtime.config.loadConfig();
+      const nextCfg = JSON.parse(JSON.stringify(currentCfg || {}));
+      nextCfg.channels = nextCfg.channels && typeof nextCfg.channels === 'object' && !Array.isArray(nextCfg.channels)
+        ? nextCfg.channels
+        : {};
+      const claworldRoot = nextCfg.channels.claworld && typeof nextCfg.channels.claworld === 'object' && !Array.isArray(nextCfg.channels.claworld)
+        ? nextCfg.channels.claworld
+        : {};
+      const accounts = claworldRoot.accounts && typeof claworldRoot.accounts === 'object' && !Array.isArray(claworldRoot.accounts)
+        ? claworldRoot.accounts
+        : {};
+      const account = accounts[accountId] && typeof accounts[accountId] === 'object' && !Array.isArray(accounts[accountId])
+        ? accounts[accountId]
+        : {};
+
+      const normalizedRelayAgentId = normalizeClaworldText(relayAgentId, normalizeClaworldText(account?.relay?.agentId, null));
+      const currentAppToken = normalizeClaworldText(account.appToken, null);
+      const currentRelayAgentId = normalizeClaworldText(account?.relay?.agentId, null);
+      if (currentAppToken === appToken && currentRelayAgentId === normalizedRelayAgentId) {
+        configPersistResult = { skipped: true, reason: 'already_persisted' };
+      } else {
+        accounts[accountId] = {
+          ...account,
+          appToken,
+          relay: {
+            ...(account?.relay && typeof account.relay === 'object' && !Array.isArray(account.relay) ? account.relay : {}),
+            ...(normalizedRelayAgentId ? { agentId: normalizedRelayAgentId } : {}),
+          },
+        };
+        delete accounts[accountId].registration;
+        claworldRoot.accounts = accounts;
+        nextCfg.channels.claworld = claworldRoot;
+        await runtime.config.writeConfigFile(nextCfg);
+        configPersistResult = { skipped: false, ok: true };
+      }
+    }
+
+    let backupPersistResult = { skipped: true, reason: 'missing_runtime_config_loader' };
+    try {
+      backupPersistResult = await persistClaworldRuntimeBackup({
+        runtime,
+        accountId,
+      });
+    } catch (error) {
+      backupPersistResult = {
+        skipped: true,
+        reason: 'backup_persist_failed',
+        error: error?.message || String(error),
+      };
+    }
+
+    return {
+      ...configPersistResult,
+      backup: backupPersistResult,
+    };
+  }
 
-    const normalizedRelayAgentId = normalizeClaworldText(relayAgentId, normalizeClaworldText(account?.relay?.agentId, null));
-    const currentAppToken = normalizeClaworldText(account.appToken, null);
-    const currentRelayAgentId = normalizeClaworldText(account?.relay?.agentId, null);
-    if (currentAppToken === appToken && currentRelayAgentId === normalizedRelayAgentId) {
-      return { skipped: true, reason: 'already_persisted' };
+  async function maybeRestoreRuntimeAppToken({ runtime, accountId, runtimeConfig }) {
+    if (resolveRuntimeAppToken(runtimeConfig)) {
+      return { restored: false, reason: 'already_configured', runtimeConfig };
     }
 
-    accounts[accountId] = {
-      ...account,
-      appToken,
-      relay: {
-        ...(account?.relay && typeof account.relay === 'object' && !Array.isArray(account.relay) ? account.relay : {}),
-        ...(normalizedRelayAgentId ? { agentId: normalizedRelayAgentId } : {}),
-      },
+    const backupState = await loadClaworldRuntimeBackup({ accountId });
+    const backup = backupState.backup;
+    const backupToken = normalizeClaworldText(backup?.appToken, null);
+    if (!backupToken) {
+      return {
+        restored: false,
+        reason: 'backup_missing_app_token',
+        runtimeConfig,
+      };
+    }
+
+    const backupServerUrl = normalizeClaworldText(backup?.serverUrl, null);
+    const currentServerUrl = normalizeClaworldText(runtimeConfig?.serverUrl, null);
+    if (backupServerUrl && currentServerUrl && normalizeRelayHttpBaseUrl(backupServerUrl) !== normalizeRelayHttpBaseUrl(currentServerUrl)) {
+      return {
+        restored: false,
+        reason: 'backup_server_mismatch',
+        runtimeConfig,
+      };
+    }
+
+    const restoredRuntimeConfig = applyRuntimeIdentity(runtimeConfig, {
+      appToken: backupToken,
+    });
+
+    try {
+      await persistRuntimeAppToken({
+        runtime,
+        accountId,
+        appToken: backupToken,
+      });
+    } catch (error) {
+      logger.warn?.(`[claworld:${accountId || 'default'}] failed to persist restored runtime appToken`, {
+        error: error?.message || String(error),
+      });
+    }
+
+    return {
+      restored: true,
+      reason: 'installer_state_backup',
+      runtimeConfig: restoredRuntimeConfig,
+      backup,
+      installerStatePath: backupState.installerStatePath,
     };
-    delete accounts[accountId].registration;
-    claworldRoot.accounts = accounts;
-    nextCfg.channels.claworld = claworldRoot;
-    await runtime.config.writeConfigFile(nextCfg);
-    return { skipped: false, ok: true };
   }
 
   function resolveConfiguredRuntimeContext(context = {}) {
@@ -1959,6 +2034,19 @@ export function createClaworldChannelPlugin({
     const cfg = configuredContext.cfg || {};
     const accountId = configuredContext.accountId || null;
     let runtimeConfig = configuredContext.runtimeConfig;
+    const runtimeResolution = resolvePluginRuntimeCandidate(context.runtime || null);
+    const restoredBinding = await maybeRestoreRuntimeAppToken({
+      runtime: runtimeResolution.runtime,
+      accountId,
+      runtimeConfig,
+    });
+    if (restoredBinding.restored) {
+      runtimeConfig = restoredBinding.runtimeConfig;
+      logger.info?.(`[claworld:${accountId || 'default'}] restored runtime binding from installer state`, {
+        installerStatePath: restoredBinding.installerStatePath || null,
+        relayAgentId: runtimeConfig?.relay?.agentId || null,
+      });
+    }
     const runtimeContext = accountRuntimeContexts.get(accountId || 'default') || null;
     if (runtimeContext?.runtimeConfig && !runtimeContext?.deferredFailure) {
       return {
@@ -2009,6 +2097,20 @@ export function createClaworldChannelPlugin({
           runtimeConfigShape: summarizeObjectShape(runtimeConfig),
         });
 
+        const runtimeResolution = resolvePluginRuntimeCandidate(context.runtime || null);
+        const restoredBinding = await maybeRestoreRuntimeAppToken({
+          runtime: runtimeResolution.runtime,
+          accountId: runtimeAccountId,
+          runtimeConfig,
+        });
+        if (restoredBinding.restored) {
+          runtimeConfig = restoredBinding.runtimeConfig;
+          logger.info?.(`[claworld:${runtimeAccountId}] restored runtime binding from installer state`, {
+            installerStatePath: restoredBinding.installerStatePath || null,
+            relayAgentId: runtimeConfig?.relay?.agentId || null,
+          });
+        }
+
         const validation = validateClaworldChannelConfig(configSource, context.accountId);
         if (!validation.ok && sourceType !== 'root_cfg') {
           logger.warn?.(`[claworld:${runtimeAccountId}] non-root runtime source would not validate as full cfg`, {
@@ -2084,7 +2186,6 @@ export function createClaworldChannelPlugin({
           return { startedDeferred: true, reason: 'missing_runtime_context', runtimeConfig };
         }
 
-        const runtimeResolution = resolvePluginRuntimeCandidate(context.runtime || null);
         const pluginRuntime = runtimeResolution.runtime;
         const runtimeSource = runtimeResolution.runtimeSource;
 
@@ -2092,24 +2193,24 @@ export function createClaworldChannelPlugin({
           runtimeSource,
         });
 
-        if (binding.bindingSource !== 'configured_app_token') {
-          try {
-            const persisted = await persistRuntimeAppToken({
-              runtime: pluginRuntime,
+        try {
+          const persisted = await persistRuntimeAppToken({
+            runtime: pluginRuntime,
+            accountId: runtimeConfig.accountId,
+            appToken: resolveRuntimeAppToken(runtimeConfig),
+            relayAgentId: runtimeConfig.relay?.agentId || null,
+          });
+          if (!persisted.skipped || persisted.backup?.skipped === false) {
+            logger.info?.(`[claworld:${runtimeAccountId}] persisted runtime binding state`, {
               accountId: runtimeConfig.accountId,
-              appToken: resolveRuntimeAppToken(runtimeConfig),
-              relayAgentId: runtimeConfig.relay?.agentId || null,
-            });
-            if (!persisted.skipped) {
-              logger.info?.(`[claworld:${runtimeAccountId}] persisted runtime appToken`, {
-                accountId: runtimeConfig.accountId,
-              });
-            }
-          } catch (error) {
-            logger.warn?.(`[claworld:${runtimeAccountId}] failed to persist runtime appToken`, {
-              error: error?.message || String(error),
+              configSkipped: persisted.skipped === true,
+              backupSkipped: persisted.backup?.skipped === true,
             });
           }
+        } catch (error) {
+          logger.warn?.(`[claworld:${runtimeAccountId}] failed to persist runtime appToken`, {
+            error: error?.message || String(error),
+          });
         }
 
         accountRuntimeContexts.set(accountKey, {

package/src/openclaw/plugin/relay-client.js

@@ -29,6 +29,21 @@ import {
   TERMINAL_CLOSE_REASONS,
 } from './relay-client-shared.js';
 
+const DELIVERY_VISIBILITY_RETRY_ATTEMPTS = 20;
+const DELIVERY_VISIBILITY_RETRY_DELAY_MS = 10;
+
+function isDeliveryVisibilityMiss(result = {}) {
+  return Number(result?.status) === 404
+    && normalizeOptionalText(result?.body?.error) === 'delivery_not_found';
+}
+
+async function waitForDeliveryVisibilityRetry() {
+  await new Promise((resolve) => {
+    const timer = setTimeout(resolve, DELIVERY_VISIBILITY_RETRY_DELAY_MS);
+    if (typeof timer?.unref === 'function') timer.unref();
+  });
+}
+
 export class ClaworldRelayClient extends EventEmitter {
   constructor({
     logger = console,
@@ -244,6 +259,18 @@ export class ClaworldRelayClient extends EventEmitter {
     return { status: response.status, body };
   }
 
+  async requestJsonWithDeliveryVisibilityRetry(pathName, init = {}, fallback = {}) {
+    let attempt = 0;
+    while (true) {
+      const result = await this.requestJson(pathName, init, fallback);
+      if (!isDeliveryVisibilityMiss(result) || attempt >= DELIVERY_VISIBILITY_RETRY_ATTEMPTS - 1) {
+        return result;
+      }
+      attempt += 1;
+      await waitForDeliveryVisibilityRetry();
+    }
+  }
+
   async openSocket({
     wsUrl,
     agentId,
@@ -459,7 +486,7 @@ export class ClaworldRelayClient extends EventEmitter {
     config,
     agentId,
     credential = null,
-    clientVersion = 'claworld-plugin/0.2.21',
+    clientVersion = 'claworld-plugin/0.2.22',
     sessionTarget,
     fallbackTarget,
   } = {}) {
@@ -879,7 +906,7 @@ export class ClaworldRelayClient extends EventEmitter {
       replyText,
       source,
     });
-    const result = await this.requestJson(`/v1/deliveries/${encodeURIComponent(envelope.deliveryId)}/reply`, {
+    const result = await this.requestJsonWithDeliveryVisibilityRetry(`/v1/deliveries/${encodeURIComponent(envelope.deliveryId)}/reply`, {
       method: 'POST',
       headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),
       body: JSON.stringify({
@@ -901,7 +928,7 @@ export class ClaworldRelayClient extends EventEmitter {
 
   async acceptDeliveryHttp({ deliveryId, sessionKey = null, source = 'runtime_dispatch' } = {}) {
     const normalizedDeliveryId = normalizeOptionalText(deliveryId);
-    const result = await this.requestJson(`/v1/deliveries/${encodeURIComponent(normalizedDeliveryId)}/accepted`, {
+    const result = await this.requestJsonWithDeliveryVisibilityRetry(`/v1/deliveries/${encodeURIComponent(normalizedDeliveryId)}/accepted`, {
       method: 'POST',
       headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),
       body: JSON.stringify({
@@ -932,6 +959,10 @@ export class ClaworldRelayClient extends EventEmitter {
     timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS,
     httpFallback = true,
   } = {}) {
+    const ackPromise = this.waitForReplyAck({
+      deliveryId,
+      timeoutMs,
+    });
     const envelope = this.sendReply({
       deliveryId,
       sessionKey,
@@ -940,10 +971,7 @@ export class ClaworldRelayClient extends EventEmitter {
     });
 
     try {
-      const ack = await this.waitForReplyAck({
-        deliveryId: envelope.deliveryId,
-        timeoutMs,
-      });
+      const ack = await ackPromise;
       return {
         ok: true,
         envelope,
@@ -1011,6 +1039,24 @@ export class ClaworldRelayClient extends EventEmitter {
     }
   }
 
+  async submitDeliveryReply({
+    deliveryId,
+    sessionKey,
+    replyText,
+    source = 'subagent',
+    timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS,
+    httpFallback = true,
+  } = {}) {
+    return await this.sendReplyAndWaitForAck({
+      deliveryId,
+      sessionKey,
+      replyText,
+      source,
+      timeoutMs,
+      httpFallback,
+    });
+  }
+
   async sendAcceptedAndWaitForAck({
     deliveryId,
     sessionKey,
@@ -1018,6 +1064,10 @@ export class ClaworldRelayClient extends EventEmitter {
     timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS,
     httpFallback = true,
   } = {}) {
+    const ackPromise = this.waitForAcceptedAck({
+      deliveryId,
+      timeoutMs,
+    });
     const envelope = this.sendAccepted({
       deliveryId,
       sessionKey,
@@ -1025,10 +1075,7 @@ export class ClaworldRelayClient extends EventEmitter {
     });
 
     try {
-      const ack = await this.waitForAcceptedAck({
-        deliveryId: envelope.deliveryId,
-        timeoutMs,
-      });
+      const ack = await ackPromise;
       return {
         ok: true,
         envelope,
@@ -1082,7 +1129,7 @@ export class ClaworldRelayClient extends EventEmitter {
 
   async keepDeliverySilentHttp({ deliveryId, reason = null, source = 'openclaw-autochain' } = {}) {
     const normalizedDeliveryId = normalizeOptionalText(deliveryId);
-    const result = await this.requestJson(`/v1/deliveries/${encodeURIComponent(normalizedDeliveryId)}/kept-silent`, {
+    const result = await this.requestJsonWithDeliveryVisibilityRetry(`/v1/deliveries/${encodeURIComponent(normalizedDeliveryId)}/kept-silent`, {
       method: 'POST',
       headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),
       body: JSON.stringify({
@@ -1113,6 +1160,10 @@ export class ClaworldRelayClient extends EventEmitter {
     timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS,
     httpFallback = true,
   } = {}) {
+    const ackPromise = this.waitForKeepSilentAck({
+      deliveryId,
+      timeoutMs,
+    });
     const envelope = this.sendKeepSilent({
       deliveryId,
       sessionKey,
@@ -1121,10 +1172,7 @@ export class ClaworldRelayClient extends EventEmitter {
     });
 
     try {
-      const ack = await this.waitForKeepSilentAck({
-        deliveryId: envelope.deliveryId,
-        timeoutMs,
-      });
+      const ack = await ackPromise;
       return {
         ok: true,
         envelope,
@@ -1192,6 +1240,24 @@ export class ClaworldRelayClient extends EventEmitter {
     }
   }
 
+  async submitDeliveryKeptSilent({
+    deliveryId,
+    sessionKey,
+    reason = null,
+    source = 'openclaw-autochain',
+    timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS,
+    httpFallback = true,
+  } = {}) {
+    return await this.sendKeepSilentAndWaitForAck({
+      deliveryId,
+      sessionKey,
+      reason,
+      source,
+      timeoutMs,
+      httpFallback,
+    });
+  }
+
   async createChatRequest({ fromAgentId, displayName, agentCode, requestContext = {} } = {}) {
     const normalized = normalizeChatRequestInput({ requestContext, source: 'direct_lookup' });
     const normalizedDisplayName = normalizeOptionalText(displayName);

package/src/openclaw/plugin/runtime-backup.js

@@ -0,0 +1,105 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  DEFAULT_CLAWORLD_ACCOUNT_ID,
+  findClaworldManagedRuntimeBackup,
+  setClaworldManagedRuntimeBackupState,
+  stripClaworldManagedRuntimeConfig,
+} from './managed-config.js';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+export function resolveDefaultOpenClawConfigPath() {
+  return path.resolve(normalizeText(
+    process.env.OPENCLAW_CONFIG_PATH,
+    path.join(os.homedir(), '.openclaw', 'openclaw.json'),
+  ));
+}
+
+export function resolveClaworldInstallerStatePath(configPath = resolveDefaultOpenClawConfigPath()) {
+  const resolvedConfigPath = path.resolve(String(configPath));
+  return path.join(path.dirname(resolvedConfigPath), '.claworld-installer-state.json');
+}
+
+async function loadInstallerStateFromDisk(installerStatePath) {
+  try {
+    const raw = await fs.readFile(installerStatePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch (error) {
+    if (error?.code === 'ENOENT') return {};
+    throw error;
+  }
+}
+
+async function writeInstallerStateToDisk(installerStatePath, installerState) {
+  const nextState = installerState && typeof installerState === 'object' && !Array.isArray(installerState)
+    ? installerState
+    : {};
+  if (Object.keys(nextState).length === 0) {
+    await fs.rm(installerStatePath, { force: true });
+    return;
+  }
+  await fs.mkdir(path.dirname(installerStatePath), { recursive: true });
+  await fs.writeFile(installerStatePath, `${JSON.stringify(nextState, null, 2)}\n`, 'utf8');
+}
+
+export async function loadClaworldRuntimeBackup({
+  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
+  configPath = resolveDefaultOpenClawConfigPath(),
+} = {}) {
+  const installerStatePath = resolveClaworldInstallerStatePath(configPath);
+  const installerState = await loadInstallerStateFromDisk(installerStatePath);
+  return {
+    installerStatePath,
+    installerState,
+    backup: findClaworldManagedRuntimeBackup(installerState, accountId),
+  };
+}
+
+export async function persistClaworldRuntimeBackup({
+  runtime = null,
+  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
+  configPath = resolveDefaultOpenClawConfigPath(),
+} = {}) {
+  if (!runtime?.config?.loadConfig) {
+    return { skipped: true, reason: 'missing_runtime_config_loader' };
+  }
+
+  const currentConfig = await runtime.config.loadConfig();
+  const { backup } = stripClaworldManagedRuntimeConfig(currentConfig, {
+    accountId,
+    preserveBackup: true,
+  });
+
+  if (!backup?.appToken) {
+    return { skipped: true, reason: 'missing_app_token', backup: null };
+  }
+
+  const installerStatePath = resolveClaworldInstallerStatePath(configPath);
+  const installerState = await loadInstallerStateFromDisk(installerStatePath);
+  const previousBackup = findClaworldManagedRuntimeBackup(installerState, accountId);
+  if (JSON.stringify(previousBackup || null) === JSON.stringify(backup)) {
+    return {
+      skipped: true,
+      reason: 'already_persisted',
+      installerStatePath,
+      backup,
+    };
+  }
+
+  setClaworldManagedRuntimeBackupState(installerState, accountId, backup);
+  await writeInstallerStateToDisk(installerStatePath, installerState);
+  return {
+    skipped: false,
+    ok: true,
+    installerStatePath,
+    backup,
+  };
+}