@xfxstudio/claworld 0.2.11 → 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.11",
+  "version": "0.2.13",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,12 +1,9 @@
 {
   "name": "@xfxstudio/claworld",
-  "version": "0.2.11",
+  "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/claworld-channel-plugin.js

@@ -908,6 +908,8 @@ async function fetchJson(fetchImpl, url, init = {}) {
 async function fetchPublicIdentity({
   runtimeConfig,
   agentId = null,
+  generateShareCard = false,
+  expiresInSeconds = null,
   fetchImpl,
 }) {
   if (!resolveRuntimeAppToken(runtimeConfig)) {
@@ -930,7 +932,7 @@ async function fetchPublicIdentity({
       recommendedDisplayName,
       nextAction: 'set_public_identity',
       requiredAction: 'set_public_identity',
-      nextTool: 'claworld_update_public_identity',
+      nextTool: 'claworld_profile',
       missingFields: [
         {
           fieldId: 'displayName',
@@ -953,15 +955,21 @@ async function fetchPublicIdentity({
   }
 
   const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
-  const path = buildRelayJsonPath('/v1/profile/public-identity', {
-    agentId,
-  });
-  const result = await fetchJson(fetchImpl, `${baseUrl}${path}`, {
-    method: 'GET',
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/profile`, {
+    method: 'POST',
     headers: {
+      'content-type': 'application/json',
       ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
       ...buildRuntimeAuthHeaders(runtimeConfig),
     },
+    body: JSON.stringify({
+      ...(agentId ? { agentId } : {}),
+      action: 'view',
+      ...(generateShareCard === true ? { generateShareCard: true } : {}),
+      ...(normalizeClaworldInteger(expiresInSeconds, null) > 0
+        ? { expiresInSeconds: normalizeClaworldInteger(expiresInSeconds, null) }
+        : {}),
+    }),
   });
   if (!result.ok) {
     createRelayRouteError({
@@ -979,6 +987,8 @@ async function updatePublicIdentity({
   runtimeConfig,
   agentId = null,
   displayName = null,
+  generateShareCard = true,
+  expiresInSeconds = null,
   fetchImpl,
 }) {
   const normalizedDisplayName = normalizeClaworldText(displayName, null);
@@ -1039,8 +1049,8 @@ async function updatePublicIdentity({
     resolvedAgentId = activatedAgentId;
   }
   const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
-  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/profile/public-identity`, {
-    method: 'PUT',
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/profile`, {
+    method: 'POST',
     headers: {
       'content-type': 'application/json',
       ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
@@ -1048,7 +1058,12 @@ async function updatePublicIdentity({
     },
     body: JSON.stringify({
       ...(resolvedAgentId ? { agentId: resolvedAgentId } : {}),
+      action: 'update_identity',
       displayName: normalizedDisplayName,
+      ...(generateShareCard === true ? { generateShareCard: true } : {}),
+      ...(normalizeClaworldInteger(expiresInSeconds, null) > 0
+        ? { expiresInSeconds: normalizeClaworldInteger(expiresInSeconds, null) }
+        : {}),
     }),
   });
   if (!result.ok) {
@@ -1074,6 +1089,60 @@ async function updatePublicIdentity({
   };
 }
 
+async function renderAgentCard({
+  runtimeConfig,
+  agentId = null,
+  expiresInSeconds = null,
+  forceRegenerate = true,
+  fetchImpl,
+}) {
+  const resolvedAgentId = normalizeClaworldText(
+    agentId,
+    normalizeClaworldText(runtimeConfig?.relay?.agentId, null),
+  );
+  if (!resolvedAgentId) {
+    throw createRuntimeBoundaryError({
+      code: 'tool_input_invalid',
+      category: 'input',
+      status: 400,
+      message: 'claworld profile card rendering requires agentId',
+      publicMessage: 'claworld profile card rendering requires agentId',
+      recoverable: true,
+      context: { field: 'agentId' },
+    });
+  }
+
+  const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
+  const normalizedExpiresInSeconds = normalizeClaworldInteger(expiresInSeconds, null);
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/agent-cards/render`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
+      ...buildRuntimeAuthHeaders(runtimeConfig),
+    },
+    body: JSON.stringify({
+      agentId: resolvedAgentId,
+      forceRegenerate: forceRegenerate === true,
+      ...(normalizedExpiresInSeconds && normalizedExpiresInSeconds > 0
+        ? { expiresInSeconds: normalizedExpiresInSeconds }
+        : {}),
+    }),
+  });
+  if (!result.ok) {
+    createRelayRouteError({
+      result,
+      runtimeConfig,
+      code: 'agent_card_render_failed',
+      publicMessage: 'failed to generate public identity card',
+      context: {
+        agentId: resolvedAgentId,
+      },
+    });
+  }
+  return result.body || {};
+}
+
 async function registerRelayBinding({ runtimeConfig, fetchImpl, logger }) {
   if (typeof fetchImpl !== 'function') {
     throw new Error('fetch is unavailable for relay registration');
@@ -2443,6 +2512,8 @@ export function createClaworldChannelPlugin({
     return fetchPublicIdentity({
       runtimeConfig: resolvedContext.runtimeConfig,
       agentId: resolvedContext.agentId || null,
+      generateShareCard: context.generateShareCard === true,
+      expiresInSeconds: context.expiresInSeconds ?? null,
       fetchImpl,
     });
   }
@@ -2453,6 +2524,8 @@ export function createClaworldChannelPlugin({
       runtimeConfig: resolvedContext.runtimeConfig,
       agentId: resolvedContext.agentId || null,
       displayName: context.displayName || null,
+      generateShareCard: context.generateShareCard !== false,
+      expiresInSeconds: context.expiresInSeconds ?? null,
       fetchImpl,
     });
 
@@ -2504,11 +2577,21 @@ export function createClaworldChannelPlugin({
     const payload = updateResult && typeof updateResult === 'object' && !Array.isArray(updateResult)
       ? { ...updateResult }
       : {};
-    delete payload.runtimeActivation;
     delete payload.runtimeConfig;
     return payload;
   }
 
+  async function generateRuntimeProfileCard(context = {}) {
+    const resolvedContext = await resolveBoundRuntimeContext(context);
+    return renderAgentCard({
+      runtimeConfig: resolvedContext.runtimeConfig,
+      agentId: context.agentId || resolvedContext.agentId || null,
+      expiresInSeconds: context.expiresInSeconds ?? null,
+      forceRegenerate: context.forceRegenerate !== false,
+      fetchImpl,
+    });
+  }
+
   return {
     id: 'claworld',
     meta: {
@@ -2763,6 +2846,7 @@ export function createClaworldChannelPlugin({
       profile: {
         getPublicIdentity: getRuntimePublicIdentity,
         updatePublicIdentity: updateRuntimePublicIdentity,
+        generateShareCard: generateRuntimeProfileCard,
       },
       postSetup: {
         fetchWorldDirectory: async (context = {}) => {
@@ -2917,6 +3001,7 @@ export function createClaworldChannelPlugin({
         profile: {
           getPublicIdentity: getRuntimePublicIdentity,
           updatePublicIdentity: updateRuntimePublicIdentity,
+          generateShareCard: generateRuntimeProfileCard,
         },
         fetchWorldDirectory: async (context = {}) => {
           const resolvedContext = await resolveBoundRuntimeContext(context);