@xfxstudio/claworld 2026.6.3-testing.2 → 2026.6.3-testing.3

package/openclaw.plugin.json

@@ -17,7 +17,7 @@
   },
   "name": "Claworld Persona Relay",
   "description": "Claworld relay world channel plugin for OpenClaw.",
-  "version": "2026.6.3-testing.2",
+  "version": "2026.6.3-testing.3",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfxstudio/claworld",
-  "version": "2026.6.3-testing.2",
+  "version": "2026.6.3-testing.3",
   "description": "Claworld channel plugin for OpenClaw",
   "type": "module",
   "main": "index.js",

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

@@ -267,6 +267,10 @@ function normalizeClaworldText(value, fallback = null) {
   return normalized || fallback;
 }
 
+function isClaworldPlainObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
 function resolveNormalizedText(value, fallback = null) {
   return normalizeClaworldText(value, fallback);
 }
@@ -3309,48 +3313,196 @@ export function createClaworldChannelPlugin({
     return promise;
   }
 
-  async function persistRuntimeAppToken({ runtime, accountId, appToken, relayAgentId = null }) {
+  function buildRuntimeAppTokenAccountConfig(existingAccount = {}, {
+    accountId,
+    appToken,
+    relayAgentId = null,
+    runtimeConfig = null,
+  } = {}) {
+    const account = isClaworldPlainObject(existingAccount) ? existingAccount : {};
+    const sourceRuntimeConfig = isClaworldPlainObject(runtimeConfig) ? runtimeConfig : {};
+    const existingRelay = isClaworldPlainObject(account.relay) ? account.relay : {};
+    const runtimeRelay = isClaworldPlainObject(sourceRuntimeConfig.relay) ? sourceRuntimeConfig.relay : {};
+    const normalizedAccountId = normalizeClaworldText(accountId, normalizeClaworldText(sourceRuntimeConfig.accountId, null));
+    const normalizedRelayAgentId = normalizeClaworldText(
+      relayAgentId,
+      normalizeClaworldText(existingRelay.agentId, normalizeClaworldText(runtimeRelay.agentId, null)),
+    );
+    const normalizedAppToken = normalizeClaworldText(appToken, resolveRuntimeAppToken(sourceRuntimeConfig));
+    const serverUrl = normalizeClaworldText(account.serverUrl, normalizeClaworldText(sourceRuntimeConfig.serverUrl, null));
+    const apiKey = normalizeClaworldText(account.apiKey, normalizeClaworldText(sourceRuntimeConfig.apiKey, null));
+    const name = normalizeClaworldText(account.name, normalizeClaworldText(sourceRuntimeConfig.name, null));
+    const toolProfile = normalizeClaworldText(account.toolProfile, normalizeClaworldText(sourceRuntimeConfig.toolProfile, null));
+    const heartbeatSeconds = Number.isInteger(account.heartbeatSeconds)
+      ? account.heartbeatSeconds
+      : (Number.isInteger(sourceRuntimeConfig.heartbeatSeconds) ? sourceRuntimeConfig.heartbeatSeconds : null);
+    const reconnect = typeof account.reconnect === 'boolean'
+      ? account.reconnect
+      : (typeof sourceRuntimeConfig.reconnect === 'boolean' ? sourceRuntimeConfig.reconnect : null);
+    const routing = isClaworldPlainObject(account.routing)
+      ? account.routing
+      : (isClaworldPlainObject(sourceRuntimeConfig.routing) ? sourceRuntimeConfig.routing : null);
+    const testing = isClaworldPlainObject(account.testing)
+      ? account.testing
+      : (isClaworldPlainObject(sourceRuntimeConfig.testing) ? sourceRuntimeConfig.testing : null);
+
+    const nextAccount = {
+      ...account,
+      enabled: typeof account.enabled === 'boolean'
+        ? account.enabled
+        : (typeof sourceRuntimeConfig.enabled === 'boolean' ? sourceRuntimeConfig.enabled : true),
+      ...(serverUrl ? { serverUrl } : {}),
+      ...(apiKey ? { apiKey } : {}),
+      ...(normalizedAccountId ? { accountId: normalizedAccountId } : {}),
+      ...(normalizedAppToken ? { appToken: normalizedAppToken } : {}),
+      ...(name ? { name } : {}),
+      ...(toolProfile ? { toolProfile } : {}),
+      ...(heartbeatSeconds ? { heartbeatSeconds } : {}),
+      ...(typeof reconnect === 'boolean' ? { reconnect } : {}),
+      ...(routing ? { routing } : {}),
+      ...(testing ? { testing } : {}),
+    };
+
+    const relayAppToken = normalizeClaworldText(existingRelay.appToken, normalizeClaworldText(runtimeRelay.appToken, null));
+    const relayCredentialToken = normalizeClaworldText(
+      existingRelay.credentialToken,
+      normalizeClaworldText(runtimeRelay.credentialToken, null),
+    );
+    const relayDefaultTargetAgentId = normalizeClaworldText(
+      existingRelay.defaultTargetAgentId,
+      normalizeClaworldText(runtimeRelay.defaultTargetAgentId, null),
+    );
+    const relay = {
+      ...(relayAppToken ? { appToken: relayAppToken } : {}),
+      ...(relayCredentialToken ? { credentialToken: relayCredentialToken } : {}),
+      ...(relayDefaultTargetAgentId ? { defaultTargetAgentId: relayDefaultTargetAgentId } : {}),
+      ...(normalizedRelayAgentId ? { agentId: normalizedRelayAgentId } : {}),
+    };
+    if (Object.keys(relay).length > 0) nextAccount.relay = relay;
+    else delete nextAccount.relay;
+    delete nextAccount.registration;
+
+    const missingRequired = [];
+    if (typeof nextAccount.enabled !== 'boolean') missingRequired.push('enabled');
+    if (!normalizeClaworldText(nextAccount.serverUrl, null)) missingRequired.push('serverUrl');
+    if (!normalizeClaworldText(nextAccount.apiKey, null)) missingRequired.push('apiKey');
+    if (!normalizeClaworldText(nextAccount.accountId, null)) missingRequired.push('accountId');
+
+    return { account: nextAccount, missingRequired };
+  }
+
+  function applyRuntimeAppTokenConfigMutation(configDraft, {
+    accountId,
+    appToken,
+    relayAgentId = null,
+    runtimeConfig = null,
+  } = {}) {
+    if (!isClaworldPlainObject(configDraft)) {
+      return { skipped: true, reason: 'invalid_config_draft' };
+    }
+    const normalizedAccountId = normalizeClaworldText(accountId, normalizeClaworldText(runtimeConfig?.accountId, null));
+    if (!normalizedAccountId || !normalizeClaworldText(appToken, resolveRuntimeAppToken(runtimeConfig))) {
+      return { skipped: true, reason: 'missing_account_or_token' };
+    }
+
+    configDraft.channels = isClaworldPlainObject(configDraft.channels) ? configDraft.channels : {};
+    const claworldRoot = isClaworldPlainObject(configDraft.channels.claworld)
+      ? configDraft.channels.claworld
+      : {};
+    const accounts = isClaworldPlainObject(claworldRoot.accounts) ? claworldRoot.accounts : {};
+    const currentAccount = isClaworldPlainObject(accounts[normalizedAccountId])
+      ? accounts[normalizedAccountId]
+      : {};
+    const built = buildRuntimeAppTokenAccountConfig(currentAccount, {
+      accountId: normalizedAccountId,
+      appToken,
+      relayAgentId,
+      runtimeConfig,
+    });
+    if (built.missingRequired.length > 0) {
+      return {
+        skipped: true,
+        reason: 'missing_required_config_fields',
+        accountId: normalizedAccountId,
+        missingRequired: built.missingRequired,
+      };
+    }
+
+    if (JSON.stringify(currentAccount) === JSON.stringify(built.account)) {
+      return {
+        skipped: true,
+        reason: 'already_persisted',
+        accountId: normalizedAccountId,
+      };
+    }
+
+    accounts[normalizedAccountId] = built.account;
+    claworldRoot.accounts = accounts;
+    if (!normalizeClaworldText(claworldRoot.defaultAccount, null)) {
+      claworldRoot.defaultAccount = normalizedAccountId;
+    }
+    configDraft.channels.claworld = claworldRoot;
+    return {
+      skipped: false,
+      ok: true,
+      accountId: normalizedAccountId,
+    };
+  }
+
+  async function persistRuntimeAppToken({ runtime, accountId, appToken, relayAgentId = null, runtimeConfig = null }) {
     if (!accountId || !appToken) {
       return { skipped: true, reason: 'missing_account_or_token' };
     }
 
     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 } : {}),
+    try {
+      if (typeof runtime?.config?.mutateConfigFile === 'function') {
+        let mutationOutcome = null;
+        const mutationParams = {
+          base: 'source',
+          afterWrite: { mode: 'auto' },
+          mutate: (draft) => {
+            mutationOutcome = applyRuntimeAppTokenConfigMutation(draft, {
+              accountId,
+              appToken,
+              relayAgentId,
+              runtimeConfig,
+            });
+            return mutationOutcome;
           },
         };
-        delete accounts[accountId].registration;
-        claworldRoot.accounts = accounts;
-        nextCfg.channels.claworld = claworldRoot;
-        await runtime.config.writeConfigFile(nextCfg);
-        configPersistResult = { skipped: false, ok: true };
+        const mutationResult = await runtime.config.mutateConfigFile(mutationParams);
+        configPersistResult = {
+          ...(mutationResult?.result || mutationOutcome || { skipped: false, ok: true }),
+          method: 'mutateConfigFile',
+        };
+      } else if (runtime?.config?.loadConfig && runtime?.config?.writeConfigFile) {
+        const currentCfg = await runtime.config.loadConfig();
+        const nextCfg = JSON.parse(JSON.stringify(currentCfg || {}));
+        const mutationOutcome = applyRuntimeAppTokenConfigMutation(nextCfg, {
+          accountId,
+          appToken,
+          relayAgentId,
+          runtimeConfig,
+        });
+        configPersistResult = {
+          ...mutationOutcome,
+          method: 'loadConfig_writeConfigFile',
+        };
+        if (!mutationOutcome.skipped) {
+          await runtime.config.writeConfigFile(nextCfg);
+        }
       }
+    } catch (error) {
+      configPersistResult = {
+        skipped: true,
+        reason: 'config_persist_failed',
+        error: error?.message || String(error),
+      };
+      logger.warn?.(`[claworld:${accountId || 'default'}] failed to persist runtime appToken to OpenClaw config`, {
+        accountId,
+        error: configPersistResult.error,
+      });
     }
 
     let backupPersistResult = { skipped: true, reason: 'missing_runtime_config_loader' };
@@ -3358,6 +3510,9 @@ export function createClaworldChannelPlugin({
       backupPersistResult = await persistClaworldRuntimeBackup({
         runtime,
         accountId,
+        runtimeConfig,
+        appToken,
+        relayAgentId,
       });
     } catch (error) {
       backupPersistResult = {
@@ -3399,8 +3554,10 @@ export function createClaworldChannelPlugin({
       };
     }
 
+    const backupAgentId = normalizeClaworldText(backup?.agentId, null);
     const restoredRuntimeConfig = applyRuntimeIdentity(runtimeConfig, {
       appToken: backupToken,
+      agentId: backupAgentId,
     });
 
     try {
@@ -3408,6 +3565,8 @@ export function createClaworldChannelPlugin({
         runtime,
         accountId,
         appToken: backupToken,
+        relayAgentId: backupAgentId,
+        runtimeConfig: restoredRuntimeConfig,
       });
     } catch (error) {
       logger.warn?.(`[claworld:${accountId || 'default'}] failed to persist restored runtime appToken`, {
@@ -3621,6 +3780,7 @@ export function createClaworldChannelPlugin({
             accountId: runtimeConfig.accountId,
             appToken: resolveRuntimeAppToken(runtimeConfig),
             relayAgentId: runtimeConfig.relay?.agentId || null,
+            runtimeConfig,
           });
           if (!persisted.skipped || persisted.backup?.skipped === false) {
             logger.info?.(`[claworld:${runtimeAccountId}] persisted runtime binding state`, {
@@ -3874,6 +4034,7 @@ async function updateRuntimePublicIdentity(context = {}) {
           accountId: resolvedContext.accountId || boundRuntimeConfig.accountId || null,
           appToken: nextAppToken,
           relayAgentId: nextAgentId,
+          runtimeConfig: boundRuntimeConfig,
         });
       } catch (error) {
         logger.warn?.('[claworld:profile] failed to persist activated runtime binding', {

package/src/openclaw/plugin/register.js

@@ -2061,14 +2061,16 @@ function buildRegisteredTools(api, plugin) {
           }));
         }
 
-        const cfg = await loadCurrentConfig(api);
-        const accountId = normalizeText(params.accountId, plugin.config.defaultAccountId(cfg) || null);
-        const runtimeConfig = plugin.config.resolveRuntimeConfig(cfg, accountId);
+        const context = await resolveToolContext(api, plugin, params);
+        const cfg = context.cfg || await loadCurrentConfig(api);
+        const accountId = context.accountId;
+        const runtimeConfig = context.runtimeConfig || plugin.config.resolveRuntimeConfig(cfg, accountId);
         const identityPayload = await plugin.runtime.productShell.profile.getPublicIdentity({
+          ...context,
           cfg,
           accountId,
           runtimeConfig,
-          agentId: runtimeConfig.relay?.agentId || null,
+          agentId: context.agentId || runtimeConfig.relay?.agentId || null,
           generateShareCard,
           expiresInSeconds: params.expiresInSeconds ?? null,
         });

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

@@ -8,6 +8,7 @@ import {
   setClaworldManagedRuntimeBackupState,
   stripClaworldManagedRuntimeConfig,
 } from './managed-config.js';
+import { resolveRuntimeAppToken } from './account-identity.js';
 
 function normalizeText(value, fallback = null) {
   if (value == null) return fallback;
@@ -67,18 +68,53 @@ export async function persistClaworldRuntimeBackup({
   runtime = null,
   accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
   configPath = resolveDefaultOpenClawConfigPath(),
+  runtimeConfig = null,
+  appToken = null,
+  relayAgentId = null,
 } = {}) {
-  if (!runtime?.config?.loadConfig) {
+  if (!runtime?.config?.loadConfig && !runtimeConfig && !appToken) {
     return { skipped: true, reason: 'missing_runtime_config_loader' };
   }
 
-  const currentConfig = await runtime.config.loadConfig();
-  const { backup } = stripClaworldManagedRuntimeConfig(currentConfig, {
+  let currentConfig = {};
+  if (runtime?.config?.loadConfig) {
+    try {
+      currentConfig = await runtime.config.loadConfig();
+    } catch (error) {
+      if (!runtimeConfig && !appToken) throw error;
+      currentConfig = {};
+    }
+  }
+  const { backup: configBackup } = stripClaworldManagedRuntimeConfig(currentConfig, {
     accountId,
     preserveBackup: true,
   });
+  const explicitRuntimeConfig = runtimeConfig && typeof runtimeConfig === 'object' && !Array.isArray(runtimeConfig)
+    ? runtimeConfig
+    : {};
+  const backup = {
+    ...configBackup,
+    version: configBackup?.version || 1,
+    accountId: normalizeText(configBackup?.accountId, normalizeText(explicitRuntimeConfig.accountId, accountId)),
+    agentId: normalizeText(relayAgentId, normalizeText(configBackup?.agentId, normalizeText(explicitRuntimeConfig?.relay?.agentId, null))),
+    serverUrl: normalizeText(configBackup?.serverUrl, normalizeText(explicitRuntimeConfig.serverUrl, null)),
+    apiKey: normalizeText(configBackup?.apiKey, normalizeText(explicitRuntimeConfig.apiKey, null)),
+    appToken: normalizeText(appToken, normalizeText(configBackup?.appToken, resolveRuntimeAppToken(explicitRuntimeConfig))),
+    displayName: normalizeText(
+      configBackup?.displayName,
+      normalizeText(explicitRuntimeConfig.name, normalizeText(explicitRuntimeConfig.registration?.displayName, null)),
+    ),
+    name: normalizeText(configBackup?.name, normalizeText(explicitRuntimeConfig.name, null)),
+    registrationDisplayName: normalizeText(
+      configBackup?.registrationDisplayName,
+      normalizeText(explicitRuntimeConfig.registration?.displayName, null),
+    ),
+    sessionDmScope: normalizeText(configBackup?.sessionDmScope, null),
+    toolProfile: normalizeText(configBackup?.toolProfile, null),
+    preservedAt: new Date().toISOString(),
+  };
 
-  if (!backup?.appToken) {
+  if (!backup.appToken) {
     return { skipped: true, reason: 'missing_app_token', backup: null };
   }