@xfxstudio/claworld 0.2.10-beta.0 → 0.2.10-beta.1

package/openclaw.plugin.json

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

package/package.json

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

package/src/openclaw/installer/cli.js

@@ -296,10 +296,9 @@ function printInstallSummary(result) {
   console.log('Claworld installer complete');
   console.log('===========================');
   console.log(`Managed account:    ${result.transformed?.config?.channels?.claworld?.defaultAccount || 'claworld'}`);
-  console.log(`Canonical agentId:  ${result.activation?.agentId || '(unknown)'}`);
   console.log(`OpenClaw version:   ${result.host?.version || '(unknown)'}`);
   console.log(`Plugin action:      ${result.plugin?.action || 'unknown'}`);
-  console.log(`Activation mode:    ${result.activationMode}`);
+  console.log(`Activation:         ${result.activationStatus === 'ready' ? 'ready' : 'pending via claworld_update_public_identity'}`);
   console.log(`Runtime refresh:    ${result.runtimeRefresh?.action || 'unknown'}`);
   console.log(`Config path:        ${result.configPath}`);
   console.log(`Backup path:        ${result.backupPath || '(unchanged or new file)'}`);
@@ -315,10 +314,10 @@ function printUpdateSummary(result, doctorResult) {
   console.log('Claworld update complete');
   console.log('========================');
   console.log(`Managed account:    ${result.managedOptions?.accountId || 'claworld'}`);
-  console.log(`Canonical agentId:  ${result.activation?.agentId || '(unknown)'}`);
   console.log(`OpenClaw version:   ${result.host?.version || '(unknown)'}`);
   console.log(`Plugin action:      ${result.plugin?.action || 'unknown'}`);
   console.log(`Tracked install:    ${trackedSummary}`);
+  console.log(`Activation:         ${result.activationStatus === 'ready' ? 'ready' : 'pending via claworld_update_public_identity'}`);
   console.log(`Runtime refresh:    ${result.runtimeRefresh?.action || 'unknown'}`);
   console.log(`Doctor status:      ${doctorResult?.status || 'unknown'}`);
   console.log(`Config path:        ${result.configPath}`);

package/src/openclaw/installer/core.js

@@ -143,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?.displayName, null)
-      )
-    ),
+    && normalizeText(account?.appToken, null),
   );
 }
 
@@ -756,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 {
@@ -1288,6 +1282,7 @@ export async function verifyClaworldInstall({
   attempts = DEFAULT_VERIFICATION_ATTEMPTS,
   delayMs = DEFAULT_VERIFICATION_DELAY_MS,
   requireGatewayRunning = resolveRequireGatewayRunning(env),
+  requireChannelToken = true,
 } = {}) {
   let lastResult = null;
 
@@ -1341,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);
@@ -1358,6 +1356,7 @@ export async function verifyClaworldInstall({
       channelReady,
       bindingReady,
       requireGatewayRunning,
+      requireChannelToken,
     };
 
     if (lastResult.ok) {
@@ -1419,30 +1418,13 @@ 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({
@@ -1465,51 +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,
@@ -1562,11 +1508,12 @@ 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 },
     );
   }
@@ -1585,10 +1532,8 @@ async function reconcileManagedClaworldRuntime({
     backupPath,
     existingInstall,
     effectiveServerUrl,
-    manifest,
     preflight,
-    activationMode,
-    activation,
+    activationStatus: managedOptions.appToken ? 'ready' : 'pending',
     managedOptions,
     transformed,
     configChanged,

package/src/openclaw/installer/doctor.js

@@ -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/claworld-channel-plugin.js

@@ -52,6 +52,7 @@ import {
   normalizeRuntimeBoundaryError,
   serializeRuntimeBoundaryError,
 } from '../../lib/runtime-errors.js';
+import { PUBLIC_IDENTITY_STATUS } from '../../lib/public-identity.js';
 import { v4 as uuidv4 } from 'uuid';
 
 function normalizeRelayHttpBaseUrl(serverUrl) {
@@ -909,6 +910,48 @@ async function fetchPublicIdentity({
   agentId = null,
   fetchImpl,
 }) {
+  if (!resolveRuntimeAppToken(runtimeConfig)) {
+    const recommendedDisplayName = normalizeClaworldText(
+      runtimeConfig?.name,
+      normalizeClaworldText(runtimeConfig?.registration?.displayName, null),
+    );
+    return {
+      status: 'pending',
+      agentId: normalizeClaworldText(agentId, null),
+      ready: false,
+      publicIdentity: {
+        status: PUBLIC_IDENTITY_STATUS.PENDING,
+        displayName: null,
+        code: null,
+        displayIdentity: null,
+        confirmedAt: null,
+        updatedAt: null,
+      },
+      recommendedDisplayName,
+      nextAction: 'set_public_identity',
+      requiredAction: 'set_public_identity',
+      nextTool: 'claworld_update_public_identity',
+      missingFields: [
+        {
+          fieldId: 'displayName',
+          label: 'Public Name',
+          description: 'A public display name used in Claworld identity surfaces.',
+        },
+        {
+          fieldId: 'code',
+          label: 'Public Code',
+          description: 'A system-generated unique suffix used in the public identity.',
+        },
+      ],
+      feedbackSummary: {
+        totalLikesReceived: 0,
+        totalDislikesReceived: 0,
+        totalLikesGiven: 0,
+        totalDislikesGiven: 0,
+      },
+    };
+  }
+
   const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
   const path = buildRelayJsonPath('/v1/profile/public-identity', {
     agentId,
@@ -950,31 +993,85 @@ async function updatePublicIdentity({
       context: { field: 'displayName' },
     });
   }
+  let resolvedRuntimeConfig = applyRuntimeIdentity(runtimeConfig);
+  let resolvedAgentId = normalizeClaworldText(agentId, normalizeClaworldText(resolvedRuntimeConfig?.relay?.agentId, null));
+
+  if (!resolveRuntimeAppToken(resolvedRuntimeConfig)) {
+    const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+    const activationResult = await fetchJson(fetchImpl, `${baseUrl}/v1/onboarding/activate`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+        ...buildRuntimeAuthHeaders(resolvedRuntimeConfig),
+      },
+      body: JSON.stringify({
+        displayName: normalizedDisplayName,
+      }),
+    });
+    if (!activationResult.ok) {
+      createRelayRouteError({
+        result: activationResult,
+        runtimeConfig: resolvedRuntimeConfig,
+        code: 'claworld_activation_failed',
+        publicMessage: 'failed to activate Claworld account',
+      });
+    }
+    const activatedToken = normalizeClaworldText(activationResult.body?.appToken, null);
+    const activatedAgentId = normalizeClaworldText(activationResult.body?.agentId, null);
+    if (!activatedToken || !activatedAgentId) {
+      throw createRuntimeBoundaryError({
+        code: 'claworld_activation_failed',
+        category: 'runtime',
+        status: 502,
+        message: 'claworld activation did not return appToken and agentId',
+        publicMessage: 'failed to activate Claworld account',
+        recoverable: true,
+      });
+    }
+    resolvedRuntimeConfig = applyRuntimeIdentity(resolvedRuntimeConfig, {
+      appToken: activatedToken,
+      relay: {
+        ...(resolvedRuntimeConfig?.relay && typeof resolvedRuntimeConfig.relay === 'object' ? resolvedRuntimeConfig.relay : {}),
+        agentId: activatedAgentId,
+      },
+    });
+    resolvedAgentId = activatedAgentId;
+  }
   const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
   const result = await fetchJson(fetchImpl, `${baseUrl}/v1/profile/public-identity`, {
     method: 'PUT',
     headers: {
       'content-type': 'application/json',
-      ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
-      ...buildRuntimeAuthHeaders(runtimeConfig),
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+      ...buildRuntimeAuthHeaders(resolvedRuntimeConfig),
     },
     body: JSON.stringify({
-      ...(normalizeClaworldText(agentId, null) ? { agentId: normalizeClaworldText(agentId, null) } : {}),
+      ...(resolvedAgentId ? { agentId: resolvedAgentId } : {}),
       displayName: normalizedDisplayName,
     }),
   });
   if (!result.ok) {
     createRelayRouteError({
       result,
-      runtimeConfig,
+      runtimeConfig: resolvedRuntimeConfig,
       code: 'public_identity_update_failed',
       publicMessage: 'failed to update public identity',
       context: {
-        agentId: normalizeClaworldText(agentId, null),
+        agentId: resolvedAgentId,
       },
     });
   }
-  return result.body || {};
+  return {
+    ...(result.body || {}),
+    runtimeActivation: !resolveRuntimeAppToken(runtimeConfig)
+      ? {
+          status: 'activated',
+          agentId: resolvedAgentId,
+        }
+      : null,
+    runtimeConfig: resolvedRuntimeConfig,
+  };
 }
 
 async function registerRelayBinding({ runtimeConfig, fetchImpl, logger }) {
@@ -1890,6 +1987,18 @@ export function createClaworldChannelPlugin({
     });
   }
 
+  function rememberAccountBinding({ runtimeConfig, accountId = null, bindingSource = 'binding_cache', relayAgent = null }) {
+    const normalizedRuntimeConfig = applyRuntimeIdentity(runtimeConfig);
+    const accountKey = resolveAccountBindingKey(normalizedRuntimeConfig, accountId || null);
+    accountBindingStates.set(accountKey, {
+      binding: {
+        runtimeConfig: normalizedRuntimeConfig,
+        bindingSource,
+        ...(relayAgent ? { relayAgent } : {}),
+      },
+    });
+  }
+
   async function ensureAccountRelayBinding({ runtimeConfig, accountId = null }) {
     const normalizedRuntimeConfig = applyRuntimeIdentity(runtimeConfig);
     const accountKey = resolveAccountBindingKey(normalizedRuntimeConfig, accountId || null);
@@ -1937,7 +2046,7 @@ export function createClaworldChannelPlugin({
     return promise;
   }
 
-  async function persistRuntimeAppToken({ runtime, accountId, appToken }) {
+  async function persistRuntimeAppToken({ runtime, accountId, appToken, relayAgentId = null }) {
     if (!runtime?.config?.loadConfig || !runtime?.config?.writeConfigFile) {
       return { skipped: true, reason: 'missing_runtime_config_io' };
     }
@@ -1960,43 +2069,67 @@ export function createClaworldChannelPlugin({
       ? accounts[accountId]
       : {};
 
-    if (normalizeClaworldText(account.appToken, null) === appToken) {
+    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' };
     }
 
     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);
     return { skipped: false, ok: true };
   }
 
-  async function resolveBoundRuntimeContext(context = {}) {
+  function resolveConfiguredRuntimeContext(context = {}) {
     const cfg = context.cfg || {};
     const accountId = context.accountId || null;
     const runtimeContext = accountRuntimeContexts.get(accountId || 'default') || null;
-    let runtimeConfig = runtimeContext?.runtimeConfig || context.runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+    const runtimeConfig = runtimeContext?.runtimeConfig || context.runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+    return {
+      ...context,
+      cfg: runtimeContext?.cfg || cfg,
+      accountId: runtimeConfig.accountId || accountId || null,
+      runtimeConfig,
+      agentId: context.agentId || runtimeConfig.relay?.agentId || null,
+      bindingSource: runtimeContext?.deferredFailure ? 'runtime_context_deferred' : 'runtime_context',
+    };
+  }
+
+  async function resolveBoundRuntimeContext(context = {}) {
+    const configuredContext = resolveConfiguredRuntimeContext(context);
+    const cfg = configuredContext.cfg || {};
+    const accountId = configuredContext.accountId || null;
+    let runtimeConfig = configuredContext.runtimeConfig;
+    const runtimeContext = accountRuntimeContexts.get(accountId || 'default') || null;
     if (runtimeContext?.runtimeConfig && !runtimeContext?.deferredFailure) {
       return {
-        ...context,
+        ...configuredContext,
         cfg: runtimeContext.cfg || cfg,
         accountId: runtimeConfig.accountId || accountId || null,
         runtimeConfig,
-        agentId: context.agentId || runtimeConfig.relay?.agentId || null,
+        agentId: configuredContext.agentId || runtimeConfig.relay?.agentId || null,
         bindingSource: 'runtime_context',
       };
     }
     const binding = await ensureAccountRelayBinding({ runtimeConfig, accountId });
     runtimeConfig = binding.runtimeConfig;
     return {
-      ...context,
+      ...configuredContext,
       cfg,
       accountId: runtimeConfig.accountId || accountId || null,
       runtimeConfig,
-      agentId: context.agentId || runtimeConfig.relay?.agentId || null,
+      agentId: configuredContext.agentId || runtimeConfig.relay?.agentId || null,
       bindingSource: binding.bindingSource,
     };
   }
@@ -2117,6 +2250,7 @@ export function createClaworldChannelPlugin({
               runtime: pluginRuntime,
               accountId: runtimeConfig.accountId,
               appToken: resolveRuntimeAppToken(runtimeConfig),
+              relayAgentId: runtimeConfig.relay?.agentId || null,
             });
             if (!persisted.skipped) {
               logger.info?.(`[claworld:${runtimeAccountId}] persisted runtime appToken`, {
@@ -2304,6 +2438,77 @@ export function createClaworldChannelPlugin({
     };
   }
 
+  async function getRuntimePublicIdentity(context = {}) {
+    const resolvedContext = resolveConfiguredRuntimeContext(context);
+    return fetchPublicIdentity({
+      runtimeConfig: resolvedContext.runtimeConfig,
+      agentId: resolvedContext.agentId || null,
+      fetchImpl,
+    });
+  }
+
+  async function updateRuntimePublicIdentity(context = {}) {
+    const resolvedContext = resolveConfiguredRuntimeContext(context);
+    const updateResult = await updatePublicIdentity({
+      runtimeConfig: resolvedContext.runtimeConfig,
+      agentId: resolvedContext.agentId || null,
+      displayName: context.displayName || null,
+      fetchImpl,
+    });
+
+    const runtimeActivation = updateResult?.runtimeActivation && typeof updateResult.runtimeActivation === 'object'
+      ? updateResult.runtimeActivation
+      : null;
+    const nextRuntimeConfig = updateResult?.runtimeConfig && typeof updateResult.runtimeConfig === 'object'
+      ? updateResult.runtimeConfig
+      : resolvedContext.runtimeConfig;
+    const nextAgentId = normalizeClaworldText(
+      runtimeActivation?.agentId,
+      normalizeClaworldText(resolvedContext.agentId, normalizeClaworldText(nextRuntimeConfig?.relay?.agentId, null)),
+    );
+
+    if (runtimeActivation && resolveRuntimeAppToken(nextRuntimeConfig)) {
+      const runtimeResolution = resolvePluginRuntimeCandidate(context.runtime || null);
+      try {
+        await persistRuntimeAppToken({
+          runtime: runtimeResolution.runtime,
+          accountId: resolvedContext.accountId || nextRuntimeConfig.accountId || null,
+          appToken: resolveRuntimeAppToken(nextRuntimeConfig),
+          relayAgentId: nextAgentId,
+        });
+      } catch (error) {
+        logger.warn?.('[claworld:profile] failed to persist activated runtime binding', {
+          accountId: resolvedContext.accountId || nextRuntimeConfig.accountId || null,
+          error: error?.message || String(error),
+        });
+      }
+
+      rememberAccountBinding({
+        runtimeConfig: nextRuntimeConfig,
+        accountId: resolvedContext.accountId || nextRuntimeConfig.accountId || null,
+        bindingSource: 'activated_app_token',
+      });
+
+      const accountKey = resolveAccountBindingKey(nextRuntimeConfig, resolvedContext.accountId || null);
+      const currentRuntimeContext = accountRuntimeContexts.get(accountKey) || null;
+      if (currentRuntimeContext) {
+        accountRuntimeContexts.set(accountKey, {
+          ...currentRuntimeContext,
+          runtimeConfig: nextRuntimeConfig,
+          deferredFailure: null,
+          deferredErrorMessage: null,
+        });
+      }
+    }
+
+    const payload = updateResult && typeof updateResult === 'object' && !Array.isArray(updateResult)
+      ? { ...updateResult }
+      : {};
+    delete payload.runtimeActivation;
+    delete payload.runtimeConfig;
+    return payload;
+  }
+
   return {
     id: 'claworld',
     meta: {
@@ -2556,23 +2761,8 @@ export function createClaworldChannelPlugin({
         },
       },
       profile: {
-        getPublicIdentity: async (context = {}) => {
-          const resolvedContext = await resolveBoundRuntimeContext(context);
-          return fetchPublicIdentity({
-            runtimeConfig: resolvedContext.runtimeConfig,
-            agentId: resolvedContext.agentId || null,
-            fetchImpl,
-          });
-        },
-        updatePublicIdentity: async (context = {}) => {
-          const resolvedContext = await resolveBoundRuntimeContext(context);
-          return updatePublicIdentity({
-            runtimeConfig: resolvedContext.runtimeConfig,
-            agentId: resolvedContext.agentId || null,
-            displayName: context.displayName || null,
-            fetchImpl,
-          });
-        },
+        getPublicIdentity: getRuntimePublicIdentity,
+        updatePublicIdentity: updateRuntimePublicIdentity,
       },
       postSetup: {
         fetchWorldDirectory: async (context = {}) => {
@@ -2725,23 +2915,8 @@ export function createClaworldChannelPlugin({
       demo,
       productShell: {
         profile: {
-          getPublicIdentity: async (context = {}) => {
-            const resolvedContext = await resolveBoundRuntimeContext(context);
-            return fetchPublicIdentity({
-              runtimeConfig: resolvedContext.runtimeConfig || null,
-              agentId: resolvedContext.agentId || null,
-              fetchImpl,
-            });
-          },
-          updatePublicIdentity: async (context = {}) => {
-            const resolvedContext = await resolveBoundRuntimeContext(context);
-            return updatePublicIdentity({
-              runtimeConfig: resolvedContext.runtimeConfig || null,
-              agentId: resolvedContext.agentId || null,
-              displayName: context.displayName || null,
-              fetchImpl,
-            });
-          },
+          getPublicIdentity: getRuntimePublicIdentity,
+          updatePublicIdentity: updateRuntimePublicIdentity,
         },
         fetchWorldDirectory: async (context = {}) => {
           const resolvedContext = await resolveBoundRuntimeContext(context);

package/src/openclaw/plugin/managed-config.js

@@ -355,7 +355,7 @@ function buildManagedAccountEntry(options = {}) {
 
   if (options.appToken) {
     base.appToken = options.appToken;
-  } else {
+  } else if (normalizeText(options.registrationDisplayName, null)) {
     base.registration = {
       enabled: true,
       displayName: normalizeText(options.registrationDisplayName, options.displayName),
@@ -404,10 +404,18 @@ function buildMergedAccountEntry(existingAccount = {}, options = {}) {
   delete merged.toolProfile;
 
   if (options.appToken) {
-    return {
+    const withToken = {
       ...merged,
       appToken: options.appToken,
     };
+    delete withToken.registration;
+    return withToken;
+  }
+
+  if (!normalizeText(options.registrationDisplayName, null)) {
+    const withoutRegistration = { ...merged };
+    delete withoutRegistration.registration;
+    return withoutRegistration;
   }
 
   return {
@@ -512,7 +520,9 @@ export function buildWorkspaceAgentsContent({
 } = {}) {
   const identityLine = appToken
     ? '- relay binding is resolved from the configured appToken at runtime'
-    : '- relay binding is created during runtime bootstrap and persists as backend-issued credentials';
+    : registrationDisplayName
+      ? '- relay binding is created during runtime bootstrap and persists as backend-issued credentials'
+      : '- activation is pending until the user completes Claworld public identity setup';
 
   return `# Claworld Channel Agent
 
@@ -522,7 +532,7 @@ Routing contract:
 
 - local OpenClaw agent id: \`${agentId}\`
 - claworld account id: \`${accountId}\`
-${registrationDisplayName ? `- bootstrap display name: \`${registrationDisplayName}\`` : '- credential mode: appToken/manual binding'}
+${registrationDisplayName ? `- bootstrap display name: \`${registrationDisplayName}\`` : (appToken ? '- credential mode: appToken/manual binding' : '- credential mode: activation pending')}
 ${identityLine}
 ${defaultTargetAgentId ? `- default outbound target agentId: \`${defaultTargetAgentId}\`` : '- outbound sends require explicit target agentId inputs'}
 
@@ -553,7 +563,9 @@ export function buildWorkspaceMemoryContent({
 } = {}) {
   const identityLine = appToken
     ? '- relay binding: resolved from appToken at runtime'
-    : '- relay binding: assigned during runtime bootstrap';
+    : registrationDisplayName
+      ? '- relay binding: assigned during runtime bootstrap'
+      : '- relay binding: pending until public identity setup completes';
 
   return `# Claworld Memory
 
@@ -661,10 +673,7 @@ export function resolveClaworldManagedRuntimeOptions({
     ? null
     : normalizeRegistrationDisplayName(
         explicitRegistrationDisplayName,
-        normalizeRegistrationDisplayName(
-          existingRegistrationDisplayName,
-          displayName,
-        ),
+        existingRegistrationDisplayName,
       );
   const approvalMode = normalizeChatRequestApprovalMode(
     normalizeText(overrides.approvalMode, null),
@@ -716,10 +725,6 @@ export function applyClaworldManagedRuntimeConfig(inputConfig = {}, options = {}
   const sessionDmScope = normalizeText(options.sessionDmScope, DEFAULT_CLAWORLD_DM_SCOPE);
   const manageAgentEntry = options.manageAgentEntry === true;
 
-  if (!options.appToken && !normalizeText(options.registrationDisplayName, null)) {
-    throw new Error('claworld registration displayName is required when appToken is absent');
-  }
-
   const removedManagedToolNames = new Set([
     ...CLAWORLD_PUBLIC_TOOL_NAMES,
     ...CLAWORLD_COMPATIBILITY_TOOL_NAMES,

package/src/openclaw/plugin/onboarding.js

@@ -84,8 +84,11 @@ function validateClaworldSetupInput({ cfg = {}, accountId = null, input = {} } =
   const registrationDisplayName = normalizeText(
     input.name,
     normalizeText(
-      inspected?.registration?.displayName,
-      normalizeText(inspected?.localAgent?.displayName, null),
+      inspected?.name,
+      normalizeText(
+        inspected?.registration?.displayName,
+        normalizeText(inspected?.localAgent?.displayName, null),
+      ),
     ),
   );
   if (!appToken && !registrationDisplayName) {
@@ -105,8 +108,11 @@ function currentManagedIdentityInput({ cfg = {}, accountId = null } = {}) {
   }
 
   const currentDisplayName = normalizeText(
-    inspected?.registration?.displayName,
-    normalizeText(inspected?.localAgent?.displayName, null),
+    inspected?.name,
+    normalizeText(
+      inspected?.registration?.displayName,
+      normalizeText(inspected?.localAgent?.displayName, null),
+    ),
   );
   return currentDisplayName
     ? { name: currentDisplayName }
@@ -163,11 +169,17 @@ function applyManagedAccountName({ cfg = {}, accountId, name } = {}) {
 }
 
 function resolveManagedOptionsFromContext({ cfg = {}, accountId = null, input = {}, overrides = {} } = {}) {
+  const normalizedInput = ensureObject(input);
+  const resolvedInput = { ...normalizedInput };
+  delete resolvedInput.name;
   return resolveClaworldManagedRuntimeOptions({
     cfg,
     accountId: normalizeText(accountId, DEFAULT_CLAWORLD_ACCOUNT_ID),
-    input,
-    overrides,
+    input: resolvedInput,
+    overrides: {
+      ...overrides,
+      ...(normalizeText(normalizedInput.name, null) ? { displayName: normalizedInput.name } : {}),
+    },
   });
 }
 
@@ -187,9 +199,9 @@ async function applyManagedOnboardingConfig({
   const noteLines = [
     `Bound local agent/account: ${managedOptions.agentId}`,
     `Remote backend: ${managedOptions.serverUrl}`,
-    managedOptions.registrationDisplayName
-      ? `Bootstrap mode: registration (${managedOptions.registrationDisplayName})`
-      : 'Bootstrap mode: appToken/manual binding',
+    managedOptions.appToken
+      ? 'Activation state: ready via configured appToken'
+      : 'Activation state: pending until claworld_update_public_identity runs',
     managedOptions.manageWorkspace
       ? 'This flow refreshes plugin-side config and the dedicated claworld workspace contract. It does not start a backend service.'
       : 'This flow refreshes plugin-side config and binds claworld onto the existing local agent. It does not start a backend service.',

package/src/openclaw/plugin/register.js

@@ -178,12 +178,12 @@ function withToolErrorBoundary(toolName, execute) {
   };
 }
 
-async function resolveToolContext(api, plugin, params = {}) {
+async function resolveToolContext(api, plugin, params = {}, { bindRuntime = true } = {}) {
   const cfg = await loadCurrentConfig(api);
   const accountId = normalizeText(params.accountId, plugin.config.defaultAccountId(cfg) || null);
   const runtimeConfig = plugin.config.resolveRuntimeConfig(cfg, accountId);
 
-  if (typeof plugin.helpers?.resolveToolRuntimeContext === 'function') {
+  if (bindRuntime && typeof plugin.helpers?.resolveToolRuntimeContext === 'function') {
     return await plugin.helpers.resolveToolRuntimeContext({
       cfg,
       accountId,
@@ -1128,19 +1128,30 @@ function buildRegisteredTools(api, plugin) {
           runtimeConfig,
         });
         const pairedAgentId = payload.runtimeConfig?.relay?.agentId || payload.relayAgent?.agentId || null;
-        const publicIdentity = pairedAgentId
-          ? await plugin.runtime.productShell.profile.getPublicIdentity({
-            cfg,
-            accountId,
-            runtimeConfig,
-            agentId: pairedAgentId,
-          })
-          : null;
+        const publicIdentity = await plugin.runtime.productShell.profile.getPublicIdentity({
+          cfg,
+          accountId,
+          runtimeConfig: payload.runtimeConfig || runtimeConfig,
+          agentId: pairedAgentId,
+        });
+        const ready = payload.status === 'paired' && publicIdentity?.ready === true;
+        const readiness = payload.status === 'paired'
+          ? (publicIdentity?.ready === true ? 'paired_and_ready' : 'paired_but_identity_pending')
+          : 'installed_unactivated';
         return buildToolResult({
-          status: payload.status,
+          status: ready ? 'ready' : 'pending',
+          ready,
+          readiness,
           reason: payload.reason || null,
+          requiredAction: publicIdentity?.requiredAction || (ready ? null : 'set_public_identity'),
+          nextAction: publicIdentity?.nextAction || (ready ? 'continue_claworld_flow' : 'set_public_identity'),
+          nextTool: publicIdentity?.nextTool || (ready ? null : 'claworld_update_public_identity'),
+          missingFields: Array.isArray(publicIdentity?.missingFields) ? publicIdentity.missingFields : [],
           accountId: payload.runtimeConfig?.accountId || accountId,
           bindingSource: payload.bindingSource || null,
+          activation: {
+            status: payload.status === 'paired' ? 'ready' : 'pending',
+          },
           relay: {
             agentId: payload.runtimeConfig?.relay?.agentId || payload.relayAgent?.agentId || null,
             displayName: payload.relayAgent?.displayName || null,
@@ -1148,6 +1159,7 @@ function buildRegisteredTools(api, plugin) {
             contactable: payload.relayAgent?.contactable ?? null,
             online: payload.relayAgent?.online ?? null,
             resolved: payload.relayAgent?.resolved ?? null,
+            bindingStatus: payload.status === 'paired' ? 'bound' : 'unactivated',
           },
           publicIdentity: publicIdentity
             ? {
@@ -1192,7 +1204,7 @@ function buildRegisteredTools(api, plugin) {
         },
       }),
       async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params);
+        const context = await resolveToolContext(api, plugin, params, { bindRuntime: false });
         const payload = await plugin.runtime.productShell.profile.getPublicIdentity(context);
         return buildToolResult(payload);
       },
@@ -1221,7 +1233,7 @@ function buildRegisteredTools(api, plugin) {
         },
       }),
       async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params);
+        const context = await resolveToolContext(api, plugin, params, { bindRuntime: false });
         const payload = await plugin.runtime.productShell.profile.updatePublicIdentity({
           ...context,
           displayName: params.displayName,

package/src/product-shell/onboarding/onboarding-service.js

@@ -164,9 +164,9 @@ export function createOnboardingService({ worldService, store = null } = {}) {
           'installer validates OpenClaw availability and minimum host version',
           'installer verifies or installs the claworld OpenClaw plugin package',
           'installer writes or refreshes the managed claworld channel config and binds it to the local main agent by default',
-          'installer calls POST /v1/onboarding/activate to obtain agentId and appToken when reuse is not possible',
-          'installer persists the returned appToken into the managed claworld account config',
-          'installer reloads or starts the runtime and verifies the relay binding',
+          'installer reloads or starts the runtime and verifies the managed channel shape without requiring backend activation',
+          'first-run readiness goes through claworld_pair_agent and then claworld_update_public_identity',
+          'claworld_update_public_identity performs activation when needed and completes the public displayName#code identity',
           `ongoing lifecycle uses ${CLAWORLD_UPDATE_COMMAND} for tracked package updates plus managed repair, then ${CLAWORLD_DOCTOR_COMMAND} for health confirmation`,
         ],
         recommendedWorlds,
@@ -182,8 +182,9 @@ export function createOnboardingService({ worldService, store = null } = {}) {
         selectedWorld: selectedWorld ? { worldId: selectedWorld.worldId, displayName: selectedWorld.displayName } : null,
         actions: [
           'install the claworld plugin and write the managed config shape',
-          'activate the install through POST /v1/onboarding/activate',
-          'persist the returned appToken and verify the runtime binding',
+          'run claworld_pair_agent to confirm readiness after install',
+          'if public identity is pending, call claworld_update_public_identity',
+          'claworld_update_public_identity activates the backend binding when needed and persists the returned appToken',
           'collect required world profile fields',
           'validate world membership eligibility',
           'start the first A2A loop or deliver world content',