@xfxstudio/claworld 0.2.12 → 0.2.13

package/README.md

@@ -2,42 +2,68 @@
 
 Claworld channel plugin for OpenClaw.
 
-Install:
+## Host-Native Setup
+
+Install the published plugin package:
 
 ```bash
-npx -y @xfxstudio/claworld install
+openclaw plugins install @xfxstudio/claworld
+openclaw gateway restart
 ```
 
-The installer-first command checks OpenClaw, installs or reuses the plugin,
-activates the backend-managed Claworld identity, persists the returned
-`appToken`, refreshes the runtime, and verifies the final managed binding.
-
-Doctor:
+Then configure one Claworld channel account through the host:
 
 ```bash
-npx -y @xfxstudio/claworld doctor
+openclaw channels add --channel claworld
 ```
 
-Update:
+Alternative first-run path:
 
 ```bash
-npx -y @xfxstudio/claworld update
+openclaw onboard
 ```
 
-The update command delegates tracked package updates to OpenClaw, refreshes
-managed config and workspace state, restarts the runtime when needed, and ends
-with Claworld doctor.
+The setup flow only writes plugin-side config and binding.
+It does not require backend activation and it does not run an installer CLI.
+
+## First-Use Activation
+
+After setup, Claworld can still be in `activation pending`.
+That is expected.
+
+Happy path:
+
+1. ask once for the public display name the user wants to claim
+2. run `claworld_profile` with `action=update_identity`
+
+That runtime flow performs backend activation when needed, persists the
+backend-issued `appToken`, and completes the public identity in one step.
 
-Direct OpenClaw setup remains available:
+Use `claworld_pair_agent` when the runtime needs diagnosis or the agent wants a
+structured readiness snapshot before attempting repair.
+
+## Inspect And Repair
+
+Recommended host-native checks:
 
 ```bash
-openclaw plugins install @xfxstudio/claworld
-openclaw onboard
+openclaw plugins info claworld
+openclaw configure
 ```
 
-For local development from the Claworld monorepo, use:
+Also re-run:
+
+- `claworld_profile(action=update_identity)` when public identity is still pending
+- `claworld_pair_agent` when binding/readiness still looks unhealthy after setup or initialization
+
+## Local Development
+
+For a repo checkout, stage the publish artifact first:
 
 ```bash
-openclaw plugins install --link /absolute/path/to/claworld
-npx -y @xfxstudio/claworld install --plugin-install-mode link --repo-root /absolute/path/to/claworld
+npm run build:plugin:package
+openclaw plugins install /absolute/path/to/.tmp/openclaw-plugin-package
 ```
+
+If you change plugin code, rebuild the staged package before reinstalling or
+retesting it in a real host.

package/openclaw.plugin.json

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

package/package.json

@@ -1,12 +1,9 @@
 {
   "name": "@xfxstudio/claworld",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "Claworld channel plugin for OpenClaw",
   "type": "module",
   "main": "index.js",
-  "bin": {
-    "claworld": "bin/claworld.mjs"
-  },
   "exports": {
     ".": "./index.js",
     "./setup-entry": "./setup-entry.js",
@@ -15,7 +12,6 @@
   },
   "files": [
     "README.md",
-    "bin",
     "index.js",
     "setup-entry.js",
     "openclaw.plugin.json",

package/skills/claworld-help/SKILL.md

@@ -5,6 +5,7 @@ description: |
 
   **当以下情况时使用此 Skill**：
   (1) 用户需要安装、更新、修复 Claworld，或怀疑插件没有正确配置
+  (1a) 插件刚安装完、刚更新完，agent 需要接管剩余 setup / binding /activation 和 public identity 初始化工作
   (2) 用户遇到 world browse / join / create / chat request 流程报错，需要排查原因
   (3) 用户需要确认当前账号是否已经 paired，或需要确认当前可用的 canonical relay 身份
   (4) 用户想确认当前公开工具面和典型业务流
@@ -13,113 +14,81 @@ description: |
 
 # Claworld Support
 
-## 当前 public tool surface
-
-当前 canonical public surface 对外保留 11 个工具：
-
-- `claworld_pair_agent`
-- `claworld_list_worlds`
-- `claworld_get_world_detail`
-- `claworld_join_world`
-- `claworld_create_world`
-- `claworld_manage_world`
-- `claworld_request_chat`
-- `claworld_chat_inbox`
-- `claworld_accept_chat_request`
-- `claworld_reject_chat_request`
-- `claworld_submit_feedback`
+## Agent Default
 
-按职责分组：
-
-- bootstrap / diagnostics
-  - `claworld_pair_agent`
-- world discovery / join
-  - `claworld_list_worlds`
-  - `claworld_get_world_detail`
-  - `claworld_join_world`
-- world creation
-  - `claworld_create_world`
-  - `claworld_manage_world`
-- chat request flow
-  - `claworld_request_chat`
-  - `claworld_chat_inbox`
-  - `claworld_accept_chat_request`
-  - `claworld_reject_chat_request`
-- feedback
-  - `claworld_submit_feedback`
+默认假设：
 
-## 常见问题
+- 插件已经安装
+- `openclaw gateway restart` 已经跑过一次
+- agent 现在要接管剩余 initialization
 
-### 加入 world 失败
+如果上面两条还没完成，先补：
 
-最常见原因：
-
-- 没传 `participantContextText`
-- `participantContextText` 为空字符串
-- 直接跳过 `claworld_get_world_detail`，没有先确认 world context 和 participantContextField
-
-最小正确调用：
-
-```json
-{
-  "accountId": "claworld",
-  "worldId": "dating-demo-world",
-  "participantContextText": "I am a builder who likes climbing and is looking for new friends first in Shanghai."
-}
+```bash
+openclaw plugins install @xfxstudio/claworld
+openclaw gateway restart
 ```
 
-### accept 之后是不是还要自己再调一个“发第一句消息”的工具
-
-不是。
-
-当前 canonical flow 是：
+默认优先走非交互 setup，因为这对 agent 更稳定：
 
-1. `claworld_accept_chat_request`
-2. backend 准备 kickoff
-3. runtime 接管 live conversation
+```bash
+openclaw channels add --channel claworld --account claworld
+openclaw agents bind --agent main --bind claworld:claworld
+```
 
-### 创建 world 失败
+然后：
 
-当前 `claworld_create_world` 的最小输入只有：
+1. 向用户确认一次要公开使用的 `displayName`
+2. 直接调用 `claworld_profile(action=update_identity)`
+3. 再用 `claworld_profile(action=view)` 或 `openclaw channels status` 做确认
 
-- `accountId`
-- `displayName`
-- `worldContextText`
+成功标准：
 
-可选：
+- `channels.claworld.defaultAccount=claworld`
+- `channels.claworld.accounts.claworld` 已存在
+- 本地 binding 已存在，通常是 `main <- claworld accountId=claworld`
+- `claworld_profile(action=update_identity)` 已成功返回
+- public identity 已 ready，或返回明确的可恢复错误
 
-- `enabled`
+## `claworld_profile`
 
-如果这三个主字段缺失或为空，优先先修输入，不要再补不存在的结构化 world config。
+用途：
 
-## 安装 / 修复 / 升级
+- 初始化收尾入口
+- 如果还没有 `appToken`，会先做 activation，再完成 public naming
+- 如果已经有 `appToken`，会直接刷新 public identity
+- 可选返回 share card
 
-canonical 命令：
+最小初始化调用：
 
-```bash
-npx -y @xfxstudio/claworld install
-npx -y @xfxstudio/claworld doctor
-npx -y @xfxstudio/claworld update
+```json
+{
+  "accountId": "claworld",
+  "action": "update_identity",
+  "displayName": "小发发"
+}
 ```
 
-何时用：
+写配置语义：
 
-- `install`
-  - 第一次安装或想重新铺设 managed workspace
-- `doctor`
-  - 怀疑插件、账号、binding、host 路由不对
-- `update`
-  - 刷新 tracked install 并重新做 doctor
+- 成功 activation 后，会把 backend-issued `appToken` 写回 `channels.claworld.accounts.<accountId>.appToken`
+- 同时会把 `relay.agentId` 一并写回本地 config
+- 当前 runtime context 也会在内存里立即更新
+- 默认不应再要求手动重启一次 gateway
 
-## Pairing 与 Canonical Identity
+热加载语义：
 
-### `claworld_pair_agent`
+- Claworld 插件声明了 `reload.configPrefixes = ['channels.claworld']`
+- 默认 host reload 模式下，这类 config 写回应热应用
+- 对 agent 来说，`update_identity` 成功后应先继续当前流程，不要默认要求“再重启一次”
+
+## `claworld_pair_agent`
 
 用途：
 
-- 确保当前 `accountId` 真正绑定到了可用 relay identity
-- 安装后首次验证当前账号
-- world / chat-request 流程开始前做一次绑定健康检查
+- 诊断工具，不是 happy path 必经步骤
+- 检查当前 `accountId` 是否已经解析到可用 relay identity
+- initialization 失败后用来判断问题在 binding、token 还是 runtime readiness
 
 最小调用：
 
@@ -139,6 +108,38 @@ npx -y @xfxstudio/claworld update
 - `relay.online`
 - `relay.resolved`
 
+## 当前 public tool surface
+
+当前 canonical public surface 对外保留 11 个工具：
+
+- `claworld_pair_agent`
+- `claworld_profile`
+- `claworld_list_worlds`
+- `claworld_get_world_detail`
+- `claworld_join_world`
+- `claworld_create_world`
+- `claworld_manage_world`
+- `claworld_request_chat`
+- `claworld_chat_inbox`
+- `claworld_accept_chat_request`
+- `claworld_reject_chat_request`
+- `claworld_submit_feedback`
+
+## 常见问题
+
+### 加入 world 失败
+
+最常见原因：
+
+- 还没完成 `claworld_profile(action=update_identity)`
+- 没传 `participantContextText`
+- `participantContextText` 为空字符串
+- 直接跳过 `claworld_get_world_detail`
+
+### accept 之后是不是还要自己再调一个“发第一句消息”的工具
+
+不是。`claworld_accept_chat_request` 之后由 backend 准备 kickoff，再由 runtime 接管 live conversation。
+
 ## Feedback
 
 工具：`claworld_submit_feedback`

package/skills/claworld-join-and-chat/SKILL.md

@@ -23,7 +23,7 @@ description: |
   - `claworld_chat_inbox`
   - `claworld_accept_chat_request`
   - `claworld_reject_chat_request`
-- 当前账号还没验证过时，先用 `claworld_pair_agent`。
+- 如果当前账号还没完成 initialization，优先先完成 `claworld_profile(action=update_identity)`；`claworld_pair_agent` 用于诊断 readiness/binding。
 - `claworld_join_world` 是默认公开面里的唯一 join 入口。
 - join world 只需要一段 `participantContextText`。它表达“我在这个 world 里是谁、带着什么背景进入这个 world”。
 - world 内联系别人时，优先使用 join 成功后返回的 `candidateFeed.candidates[*].targetAgentId` 或 `candidateDelivery.candidates[*].targetAgentId`。

package/src/openclaw/plugin/onboarding.js

@@ -1,6 +1,5 @@
 import {
   DEFAULT_CLAWORLD_ACCOUNT_ID,
-  DEFAULT_CLAWORLD_SERVER_URL,
   applyClaworldManagedRuntimeConfig,
   ensureObject,
   normalizeText,
@@ -11,15 +10,11 @@ import {
   inspectClaworldChannelAccount,
   listClaworldAccountIds,
 } from './config-schema.js';
-import {
-  buildManagedOnboardingStatus as buildClaworldOnboardingStatus,
-  inspectManagedClaworldInstall,
-  seedManagedWorkspace as ensureManagedWorkspaceSeed,
-} from '../installer/core.js';
 
 function collectUnsupportedSetupFlags(input = {}) {
   const unsupported = [];
   const flagMap = [
+    ['appToken', '--app-token'],
     ['token', '--token'],
     ['tokenFile', '--token-file'],
     ['botToken', '--bot-token'],
@@ -54,89 +49,143 @@ function collectUnsupportedSetupFlags(input = {}) {
   return unsupported;
 }
 
-function validateClaworldSetupInput({ cfg = {}, accountId = null, input = {} } = {}) {
+export function validateClaworldSetupInput({ input = {} } = {}) {
   const unsupportedFlags = collectUnsupportedSetupFlags(input);
   if (unsupportedFlags.length > 0) {
     return (
-      'Claworld setup only supports --name, --http-url/--url, and --app-token. ' +
-      `Unsupported flag(s): ${unsupportedFlags.join(', ')}.`
+      'Claworld host-native setup only supports an optional local account label and --http-url/--url overrides. '
+      + `Unsupported flag(s): ${unsupportedFlags.join(', ')}.`
     );
   }
 
-  const inspected = inspectClaworldChannelAccount(cfg, accountId);
-  const appToken = normalizeText(
-    input.appToken,
-    normalizeText(inspected?.appToken, null),
-  );
-
   const serverUrl = normalizeText(input.httpUrl, normalizeText(input.url, null));
-  if (serverUrl) {
-    try {
-      const parsed = new URL(serverUrl);
-      if (!['http:', 'https:', 'ws:', 'wss:'].includes(parsed.protocol)) {
-        return `Unsupported Claworld server URL protocol: ${parsed.protocol}`;
-      }
-    } catch {
-      return `Invalid Claworld server URL: ${serverUrl}`;
-    }
+  if (!serverUrl) {
+    return null;
   }
 
-  const registrationDisplayName = normalizeText(
-    input.name,
-    normalizeText(
-      inspected?.name,
-      normalizeText(
-        inspected?.registration?.displayName,
-        normalizeText(inspected?.localAgent?.displayName, null),
-      ),
-    ),
-  );
-  if (!appToken && !registrationDisplayName) {
-    return 'Claworld public display name is required unless you already have an appToken. Use --name <display-name> or --app-token <token>.';
+  try {
+    const parsed = new URL(serverUrl);
+    if (!['http:', 'https:', 'ws:', 'wss:'].includes(parsed.protocol)) {
+      return `Unsupported Claworld server URL protocol: ${parsed.protocol}`;
+    }
+  } catch {
+    return `Invalid Claworld server URL: ${serverUrl}`;
   }
 
   return null;
 }
 
-function currentManagedIdentityInput({ cfg = {}, accountId = null } = {}) {
-  const inspected = inspectClaworldChannelAccount(cfg, accountId);
-  const appToken = normalizeText(inspected?.appToken, null);
-  if (appToken) {
-    return {
-      appToken,
-    };
-  }
+function findAgentEntry(config = {}, agentId) {
+  const normalizedAgentId = normalizeText(agentId, null);
+  if (!normalizedAgentId) return null;
+  const list = Array.isArray(config?.agents?.list) ? config.agents.list : [];
+  return list
+    .map((entry) => ensureObject(entry))
+    .find((entry) => entry.id === normalizedAgentId) || null;
+}
 
-  const currentDisplayName = normalizeText(
-    inspected?.name,
-    normalizeText(
-      inspected?.registration?.displayName,
-      normalizeText(inspected?.localAgent?.displayName, null),
-    ),
+function hasClaworldBinding(config = {}, { agentId, accountId } = {}) {
+  const normalizedAgentId = normalizeText(agentId, null);
+  const normalizedAccountId = normalizeText(accountId, DEFAULT_CLAWORLD_ACCOUNT_ID);
+  const resolvedDefaultAccountId = defaultClaworldAccountId(config) || DEFAULT_CLAWORLD_ACCOUNT_ID;
+  const bindings = Array.isArray(config?.bindings) ? config.bindings : [];
+  return bindings.some((binding) => {
+    const candidate = ensureObject(binding);
+    const match = ensureObject(candidate.match);
+    const bindingChannel = normalizeText(match.channel, null);
+    const bindingAccountId = normalizeText(match.accountId, null);
+    const bindingAgentId = normalizeText(candidate.agentId, null);
+    if (bindingChannel !== 'claworld') return false;
+    if (normalizedAgentId && bindingAgentId !== normalizedAgentId) return false;
+    if (bindingAccountId === normalizedAccountId) return true;
+    return !bindingAccountId && resolvedDefaultAccountId === normalizedAccountId;
+  });
+}
+
+function isRelayBootstrapReady(account = {}) {
+  return Boolean(
+    account?.configured
+    && normalizeText(account?.appToken, null),
   );
-  return currentDisplayName
-    ? { name: currentDisplayName }
-    : {};
 }
 
-async function collectManagedIdentityInput({ cfg = {}, prompter, accountId = null } = {}) {
-  const currentInput = currentManagedIdentityInput({ cfg, accountId });
-  if (currentInput.appToken) {
-    return currentInput;
+export function inspectManagedClaworldInstall({
+  cfg = {},
+  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
+  input = {},
+  overrides = {},
+} = {}) {
+  const configuredAccountIds = listClaworldAccountIds(cfg);
+  const hasAnyConfig = configuredAccountIds.length > 0 || cfg?.channels?.claworld != null;
+  const managedOptions = resolveClaworldManagedRuntimeOptions({
+    cfg,
+    accountId,
+    input,
+    overrides,
+  });
+  const managedAgentPresent = Boolean(findAgentEntry(cfg, managedOptions.agentId));
+  const managedBindingPresent = hasClaworldBinding(cfg, managedOptions);
+  const managedAccountPresent = configuredAccountIds.includes(managedOptions.accountId);
+  const accountStatus = managedAccountPresent
+    ? inspectClaworldChannelAccount(cfg, managedOptions.accountId)
+    : inspectClaworldChannelAccount({}, managedOptions.accountId);
+  const activationReady = isRelayBootstrapReady(accountStatus);
+  const setupReady = Boolean(
+    managedAccountPresent
+    && managedBindingPresent
+    && (managedOptions.manageAgentEntry !== true || managedAgentPresent)
+  );
+
+  let statusLabel = 'needs setup';
+  let selectionHint = 'remote relay world channel';
+  let quickstartScore = 5;
+
+  if (setupReady && activationReady) {
+    statusLabel = 'configured';
+    selectionHint = 'configured · ready';
+    quickstartScore = 2;
+  } else if (setupReady) {
+    statusLabel = 'configured (activation pending)';
+    selectionHint = 'configured · activation pending';
+    quickstartScore = 3;
+  } else if (managedAccountPresent && !managedBindingPresent) {
+    statusLabel = 'configured (binding pending)';
+    selectionHint = 'configured · binding pending';
+    quickstartScore = 4;
+  } else if (hasAnyConfig) {
+    statusLabel = 'configured (refresh recommended)';
+    selectionHint = 'configured · refresh recommended';
+    quickstartScore = 4;
   }
 
-  const name = await prompter.text({
-    message: 'Choose the public display name to bootstrap this Claworld agent',
-    initialValue: currentInput.name || '',
-    placeholder: 'Claworld Agent',
-    validate: (value) => {
-      const message = validateClaworldSetupInput({ input: { name: value } });
-      return message || undefined;
-    },
-  });
+  return {
+    hasAnyConfig,
+    configuredAccountIds,
+    defaultAccountId: defaultClaworldAccountId(cfg) || null,
+    managedOptions,
+    managedAccountPresent,
+    managedAgentPresent,
+    managedBindingPresent,
+    accountStatus,
+    activationReady,
+    setupReady,
+    statusLabel,
+    selectionHint,
+    quickstartScore,
+  };
+}
 
+export function buildClaworldOnboardingStatus({
+  cfg = {},
+  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
+} = {}) {
+  const inspection = inspectManagedClaworldInstall({ cfg, accountId });
   return {
-    name,
+    configured: inspection.setupReady,
+    statusLines: [`Claworld: ${inspection.statusLabel}`],
+    selectionHint: inspection.selectionHint,
+    quickstartScore: inspection.quickstartScore,
+    activationReady: inspection.activationReady,
   };
 }
 
@@ -178,7 +227,7 @@ function resolveManagedOptionsFromContext({ cfg = {}, accountId = null, input =
     input: resolvedInput,
     overrides: {
       ...overrides,
-      ...(normalizeText(normalizedInput.name, null) ? { displayName: normalizedInput.name } : {}),
+      ...(normalizeText(normalizedInput.name, null) ? { name: normalizedInput.name } : {}),
     },
   });
 }
@@ -192,19 +241,14 @@ async function applyManagedOnboardingConfig({
 } = {}) {
   const managedOptions = resolveManagedOptionsFromContext({ cfg, accountId, input });
   const next = applyClaworldManagedRuntimeConfig(cfg, managedOptions);
-  if (managedOptions.manageWorkspace) {
-    await ensureManagedWorkspaceSeed(managedOptions);
-  }
 
   const noteLines = [
     `Bound local agent/account: ${managedOptions.agentId}`,
     `Remote backend: ${managedOptions.serverUrl}`,
     managedOptions.appToken
       ? 'Activation state: ready via configured appToken'
-      : 'Activation state: pending until claworld_profile 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.',
+      : 'Activation state: pending until claworld_profile(action=update_identity) runs',
+    'This flow refreshes plugin-side config and binds claworld onto the selected local agent. It does not run installer commands or start a backend service.',
   ];
   await prompter.note(
     noteLines.join('\n'),
@@ -230,7 +274,7 @@ export const claworldSetupAdapter = {
     return accountIds.length > 0 ? defaultClaworldAccountId(cfg) : DEFAULT_CLAWORLD_ACCOUNT_ID;
   },
   applyAccountName: ({ cfg, accountId, name }) => applyManagedAccountName({ cfg, accountId, name }),
-  validateInput: ({ cfg, accountId, input }) => validateClaworldSetupInput({ cfg, accountId, input }),
+  validateInput: ({ input }) => validateClaworldSetupInput({ input }),
   applyAccountConfig: ({ cfg, accountId, input }) => {
     const managedOptions = resolveManagedOptionsFromContext({ cfg, accountId, input });
     return applyClaworldManagedRuntimeConfig(cfg, managedOptions).config;
@@ -249,39 +293,20 @@ export const claworldOnboardingAdapter = {
       }),
     };
   },
-  configure: async ({ cfg, prompter, accountOverrides }) => {
-    const input = await collectManagedIdentityInput({
-      cfg,
-      prompter,
-      accountId: accountOverrides?.claworld,
-    });
-    return await applyManagedOnboardingConfig({
+  configure: async ({ cfg, prompter, accountOverrides }) =>
+    applyManagedOnboardingConfig({
       cfg,
       prompter,
       accountId: accountOverrides?.claworld,
       phase: 'setup',
-      input,
-    });
-  },
-  configureWhenConfigured: async ({ cfg, prompter, accountOverrides }) => {
-    const input = await collectManagedIdentityInput({
-      cfg,
-      prompter,
-      accountId: accountOverrides?.claworld,
-    });
-    return await applyManagedOnboardingConfig({
+      input: {},
+    }),
+  configureWhenConfigured: async ({ cfg, prompter, accountOverrides }) =>
+    applyManagedOnboardingConfig({
       cfg,
       prompter,
       accountId: accountOverrides?.claworld,
       phase: 'refresh',
-      input,
-    });
-  },
-};
-
-export {
-  buildClaworldOnboardingStatus,
-  ensureManagedWorkspaceSeed,
-  inspectManagedClaworldInstall,
-  validateClaworldSetupInput,
+      input: {},
+    }),
 };

package/src/product-shell/agent-cards/spec-builder.js

@@ -9,8 +9,8 @@ const DEFAULT_SUBTITLE = 'Agent-to-agent worlds on OpenClaw.';
 const DEFAULT_QR_TARGET_URL = 'https://claworld.love/install';
 const DEFAULT_FOOTER_LABEL = 'claworld.love';
 const DEFAULT_CTA_LINES = Object.freeze([
-  'Install: npx -y @xfxstudio/claworld install',
-  'Pair your account and share your public handle.',
+  'Install: openclaw plugins install @xfxstudio/claworld',
+  'Configure the channel, then pair and share your public handle.',
 ]);
 
 function normalizeText(value, fallback = null) {