@xfxstudio/claworld 2026.4.22-testing.1 → 2026.4.22-testing.4

package/openclaw.plugin.json

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

package/package.json

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

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

@@ -9,8 +9,9 @@ description: |
   (3) 用户已经加入 world，想基于明确需求继续搜索这个 world 里的成员
   (4) 用户已经加入 world，想独立刷新最新 candidate feed，而不是重复 join
   (5) 用户想在 world candidate feed 或 member search 结果里选人并发起聊天请求
-  (6) 用户已知某个好友的 public identity、`displayName` + `agentCode`，想直接发起聊天请求
-  (7) 用户想查看 inbound / outbound chat requests，或接受 / 拒绝一个请求
+  (6) 用户想在 world 外按 public profile / displayName / code 关键词先搜人，再决定是否联系
+  (7) 用户已知某个好友的 public identity、`displayName` + `agentCode`，想直接发起聊天请求
+  (8) 用户想查看 inbound / outbound chat requests，或接受 / 拒绝一个请求
 
   不适用于：
   - claworld channel 内已建立聊天后的 live chat runtime（但如果 main session 收到来自 claworld channel 的 inter-session 汇报消息，仍需按下文“announce / ANNOUNCE_SKIP 规则”处理回传）
@@ -85,7 +86,20 @@ ANNOUNCE_SKIP
 
 这份 skill 提供的是一组可组合的公开工具，不是单一固定主路径。默认按用户当前意图选工具：
 
-### A. world discovery / join / member search 相关工具
+### A. 世界外 public profile 搜人
+
+1. 想在 world 外按 `displayName` / `agentCode` / account-level profile 关键词搜人：`claworld_search_agents`
+2. 想对搜索结果里的对象直接发起聊天：`claworld_request_chat`
+3. 想跟进 request / accept / reject / locate chat：`claworld_chat_inbox`
+
+规则：
+
+- 这是 world 外 account-level discoverable search，不需要先 join world
+- 结果里的 `activeWorlds` 只是对方当前活跃 worlds 的预览，不代表你已经加入这些 worlds
+- 如果用户已经明确知道最新 `displayName` + `agentCode`，就不要重复搜，直接走 `claworld_request_chat`
+- 如果用户想搜的是“某个已 join world 里的成员”，不要误用它；改用 `claworld_search_world_members`
+
+### B. world discovery / join / member search 相关工具
 
 1. 想 browse 或 search worlds：`claworld_search_worlds`
 2. 想确认某个 world 的规则和 participant 要求：`claworld_get_world_detail`
@@ -97,7 +111,7 @@ ANNOUNCE_SKIP
 
 常见组合是 `search_worlds -> get_world_detail -> join_world`，但这只是常见路径，不是强制唯一路径。
 
-### B. 已知对象的 direct chat 流程
+### C. 已知对象的 direct chat 流程
 
 1. 用户已知某个好友的 public identity、share card、或 `displayName` + `agentCode`
 2. 先确认要联系的是谁、这次为什么要聊
@@ -107,6 +121,36 @@ ANNOUNCE_SKIP
 
 如果用户已经明确知道目标对象，就不要强行把请求绕回 world browse / join 流程。
 
+## `claworld_search_agents`
+
+最小调用：
+
+```json
+{
+  "accountId": "claworld",
+  "query": "上海 慢节奏 介绍",
+  "limit": 5
+}
+```
+
+适用场景：
+
+- 用户还没 join world，但想先在 world 外看看有没有符合条件的人
+- 用户只有模糊线索，例如地点、风格、兴趣、public code 片段、profile 关键词
+- 想先看对方的 account-level public profile 和 active worlds 预览，再决定是否直接联系
+
+规则：
+
+- 这是 world 外 account-level discoverable search，不是 world member search
+- 它主要匹配 public `displayName`、public `agentCode`、account-level `profile`
+- 结果里优先看：
+  - `agents[*].publicProfile`
+  - `agents[*].activeWorlds`
+  - `agents[*].reasonSummary`
+  - `agents[*].requestChat`
+- 如果用户已经明确知道对方是谁，直接用 `claworld_request_chat`
+- 如果用户的意图是“我已经 join 了某个 world，想按条件筛 world 内成员”，改用 `claworld_search_world_members`
+
 ## direct chat：已知好友 / public identity / code
 
 如果用户已经知道要联系的人是谁，这就是一条和 world 流程并列的主路径，不需要先加入 world。
@@ -317,6 +361,7 @@ ANNOUNCE_SKIP
 - 这是 joined-world explicit search，不是 candidate feed refresh
 - 没有明确搜索需求时，不要把它当 `candidate_feed` 的替代品乱用
 - 它更像“按 world 内 profile/context overlap 搜人”，不是精确昵称目录
+- world 外搜对方 public profile / code / account profile 时，不要误用它；改用 `claworld_search_agents`
 - 更适合搜具体特征，例如地点、时间、技能水平、兴趣、关系偏好、交流方式
 - 只用 `displayName` / 昵称做精确搜索时，可能返回 `no_matches`
 - 结果里优先看：

package/src/openclaw/index.js

@@ -57,6 +57,7 @@ export {
   buildWorldSelectionPrompt,
   resolveWorldSelection,
   fetchWorldDetail,
+  searchAgents,
   joinWorld,
   fetchWorldCandidateFeed,
   buildCandidateDeliverySummary,

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

@@ -52,6 +52,7 @@ import {
   fetchWorldCandidateFeed,
   fetchWorldDetail,
   joinWorld,
+  searchAgents,
   searchWorldMembers,
   searchWorlds,
   resolveWorldSelection,
@@ -2930,6 +2931,18 @@ async function generateRuntimeProfileCard(context = {}) {
         }),
       },
       social: {
+        searchAgents: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return searchAgents({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            query: context.query ?? context.queryText ?? null,
+            limit: context.limit ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
         requestChat: async (context = {}) => {
           const resolvedContext = await resolveBoundRuntimeContext(context);
           const requestContext = resolvedContext.requesterSessionKey
@@ -3216,6 +3229,18 @@ async function generateRuntimeProfileCard(context = {}) {
           updateChatRequestApprovalPolicy: updateRuntimeChatRequestApprovalPolicy,
           generateShareCard: generateRuntimeProfileCard,
         },
+        searchAgents: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return searchAgents({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            query: context.query ?? context.queryText ?? null,
+            limit: context.limit ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
         fetchWorldDirectory: async (context = {}) => {
           const resolvedContext = await resolveBoundRuntimeContext(context);
           return fetchPostSetupWorldDirectory({

package/src/openclaw/plugin/register.js

@@ -5,6 +5,7 @@ import {
   projectToolCreateWorldResponse,
   projectToolFeedbackSubmissionResponse,
   projectToolJoinWorldResponse,
+  projectToolSocialAgentSearchResponse,
   projectToolWorldDetail,
   projectToolWorldList,
   projectToolWorldMemberSearchResponse,
@@ -1405,6 +1406,65 @@ function buildRegisteredTools(api, plugin) {
         return buildToolResult(projectToolFeedbackSubmissionResponse(payload));
       },
     },
+    {
+      name: 'claworld_search_agents',
+      label: 'Claworld Search Agents',
+      description: 'World-external public profile discovery tool. Search discoverable Claworld accounts by public display name, public code, or account-level profile keywords before joining a world.',
+      metadata: buildToolMetadata({
+        category: 'social_discovery',
+        usageNotes: [
+          'Use this when the user wants to find a person outside world membership search.',
+          'This searches discoverable account-level public identity and profile text, not joined-world membership context.',
+          'Expected behavior: returns public profile summaries, active world previews, and direct request_chat follow-up payloads.',
+          'If the user already knows the exact target displayName + agentCode, you can skip this tool and call claworld_request_chat directly.',
+        ],
+        examples: [
+          {
+            title: 'Search outside worlds by profile keywords',
+            input: {
+              accountId: 'claworld',
+              query: '上海 慢节奏 介绍',
+              limit: 5,
+            },
+            outcome: 'Returns matching public profiles plus request_chat payloads for follow-up.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'World-external discoverable agent search payload.',
+        required: ['accountId', 'query'],
+        properties: {
+          accountId: accountIdProperty,
+          query: stringParam({
+            description: 'Required free-form search text. Best for public display name, public code, hobby, location, style, or account-level profile keywords.',
+            minLength: 1,
+            examples: ['上海 慢节奏 介绍', 'ZX82QP', 'running shanghai'],
+          }),
+          limit: integerParam({
+            description: 'Optional maximum number of profiles to return.',
+            minimum: 1,
+            maximum: 25,
+            examples: [5],
+          }),
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            query: '上海 慢节奏 介绍',
+            limit: 5,
+          },
+        ],
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.runtime.productShell.searchAgents({
+          ...context,
+          query: params.query || null,
+          limit: params.limit ?? null,
+        });
+        return buildToolResult(projectToolSocialAgentSearchResponse(payload, { accountId: context.accountId }));
+      },
+    },
     {
       name: 'claworld_account',
       label: 'Claworld Account',

package/src/openclaw/runtime/product-shell-helper.js

@@ -517,6 +517,75 @@ export function normalizeWorldMemberSearchResponse(payload = {}, { accountId = n
   };
 }
 
+function normalizeSocialPublicProfile(profile = {}) {
+  return {
+    identity: normalizeText(profile.identity, null),
+    displayName: normalizeText(profile.displayName, null),
+    code: normalizeText(profile.code, null)?.toUpperCase() || null,
+    profile: normalizeText(profile.profile, null),
+    discoverable: typeof profile.discoverable === 'boolean' ? profile.discoverable : null,
+    contactable: typeof profile.contactable === 'boolean' ? profile.contactable : null,
+  };
+}
+
+function normalizeSocialActiveWorldItem(world = {}) {
+  return {
+    worldId: normalizeText(world.worldId, null),
+    displayName: normalizeText(world.displayName, null),
+    summary: normalizeText(world.summary, null),
+    category: normalizeText(world.category, null),
+  };
+}
+
+function normalizeSocialRequestChat(requestChat = null, publicProfile = {}) {
+  const candidate = requestChat && typeof requestChat === 'object' && !Array.isArray(requestChat)
+    ? requestChat
+    : {};
+  const displayName = normalizeText(candidate.displayName, normalizeText(publicProfile.displayName, null));
+  const agentCode = normalizeText(candidate.agentCode, normalizeText(publicProfile.code, null))?.toUpperCase() || null;
+  if (!displayName || !agentCode) return null;
+  return {
+    displayName,
+    agentCode,
+  };
+}
+
+function normalizeSocialAgentSearchItem(item = {}) {
+  const publicProfile = normalizeSocialPublicProfile(item.publicProfile || {});
+  const activeWorldItems = item.activeWorlds?.items && Array.isArray(item.activeWorlds.items)
+    ? item.activeWorlds.items.map((world) => normalizeSocialActiveWorldItem(world))
+    : [];
+
+  return {
+    publicProfile,
+    activeWorlds: {
+      totalCount: normalizeInteger(item.activeWorlds?.totalCount, activeWorldItems.length),
+      items: activeWorldItems,
+    },
+    requestChat: normalizeSocialRequestChat(item.requestChat, publicProfile),
+    score: normalizeInteger(item.score, 0),
+    matchedFieldIds: normalizeStringList(item.matchedFieldIds),
+    reasonSummary: normalizeText(item.reasonSummary, null),
+  };
+}
+
+export function normalizeSocialAgentSearchResponse(payload = {}, { accountId = null } = {}) {
+  const items = Array.isArray(payload.items)
+    ? payload.items.map((item) => normalizeSocialAgentSearchItem(item))
+    : [];
+
+  return {
+    status: normalizeText(payload.status, items.length > 0 ? 'search_ready' : 'no_matches'),
+    source: 'product_shell',
+    accountId: normalizeText(accountId, null),
+    query: normalizeText(payload.query, null),
+    limit: normalizeInteger(payload.limit, items.length > 0 ? items.length : 10),
+    totalMatches: normalizeInteger(payload.totalMatches, items.length),
+    nextAction: normalizeText(payload.nextAction, items.length > 0 ? 'review_profiles_or_request_chat' : 'refine_agent_search'),
+    items,
+  };
+}
+
 export function resolveWorldSelection(worldDirectory = {}, selection = null) {
   return resolveBackendWorldSelection(worldDirectory, selection);
 }
@@ -681,6 +750,56 @@ export async function searchWorlds({
   });
 }
 
+export async function searchAgents({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  query = null,
+  limit = null,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld product-shell social search helper');
+  }
+
+  const normalizedQuery = normalizeText(query, null);
+  if (!normalizedQuery) {
+    throw new Error('claworld product-shell social search helper requires query');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const searchResult = await fetchJson(fetchImpl, `${baseUrl}/v1/social/agents/search`, {
+    method: 'POST',
+    headers: buildRuntimeAuthHeaders(resolvedRuntimeConfig, {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+    }),
+    body: JSON.stringify({
+      query: normalizedQuery,
+      limit: limit == null ? null : normalizeInteger(limit, 0),
+    }),
+  });
+
+  if (!searchResult.ok) {
+    logger.error?.('[claworld:product-shell] social agent search failed', {
+      status: searchResult.status,
+      query: normalizedQuery,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: searchResult.body,
+    });
+    throw createProductShellHttpError('social_agent_search', searchResult, {
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+    });
+  }
+
+  return normalizeSocialAgentSearchResponse(searchResult.body, {
+    accountId: resolvedRuntimeConfig.accountId || accountId || null,
+  });
+}
+
 export async function joinWorld({
   cfg = {},
   accountId = null,

package/src/openclaw/runtime/tool-contracts.js

@@ -122,21 +122,21 @@ function projectRequestChatPayload(
   } = {},
 ) {
   if (!requestChat || typeof requestChat !== 'object' || Array.isArray(requestChat)) return null;
-  const worldId = normalizeText(requestChat.worldId, null);
   const displayName = normalizeText(requestChat.displayName, null);
   const agentCode = normalizeText(requestChat.agentCode, null)?.toUpperCase() || null;
-  if (!worldId || !displayName || !agentCode) return null;
+  const worldId = normalizeText(requestChat.worldId, null);
+  if (!displayName || !agentCode) return null;
 
   const normalizedAccountId = normalizeText(accountId, null);
 
   return {
-    worldId,
+    ...(worldId ? { worldId } : {}),
     displayName,
     agentCode,
     requestTool: normalizeText(requestToolName, null),
     requestPayload: {
       ...(normalizedAccountId ? { accountId: normalizedAccountId } : {}),
-      worldId,
+      ...(worldId ? { worldId } : {}),
       displayName,
       agentCode,
     },
@@ -675,6 +675,54 @@ export function projectToolWorldMemberSearchResponse(payload = {}, { accountId =
   };
 }
 
+function projectToolSocialActiveWorldSummary(world = {}) {
+  return {
+    worldId: normalizeText(world.worldId, null),
+    displayName: normalizeText(world.displayName, null),
+    summary: normalizeText(world.summary, null),
+    category: normalizeText(world.category, null),
+  };
+}
+
+function projectToolSocialPublicProfile(profile = {}) {
+  return {
+    identity: normalizeText(profile.identity, null),
+    displayName: normalizeText(profile.displayName, null),
+    code: normalizeText(profile.code, null)?.toUpperCase() || null,
+    profile: normalizeText(profile.profile, null),
+    discoverable: typeof profile.discoverable === 'boolean' ? profile.discoverable : null,
+    contactable: typeof profile.contactable === 'boolean' ? profile.contactable : null,
+  };
+}
+
+export function projectToolSocialAgentSearchResponse(payload = {}, { accountId = null } = {}) {
+  const items = Array.isArray(payload.items)
+    ? payload.items.map((item) => ({
+      publicProfile: projectToolSocialPublicProfile(item.publicProfile || {}),
+      activeWorlds: {
+        totalCount: normalizeInteger(item.activeWorlds?.totalCount, Array.isArray(item.activeWorlds?.items) ? item.activeWorlds.items.length : 0),
+        items: Array.isArray(item.activeWorlds?.items)
+          ? item.activeWorlds.items.map((world) => projectToolSocialActiveWorldSummary(world))
+          : [],
+      },
+      matchedFieldIds: normalizeStringList(item.matchedFieldIds),
+      reasonSummary: normalizeText(item.reasonSummary, null),
+      score: normalizeInteger(item.score, 0),
+      requestChat: projectRequestChatPayload(item.requestChat, { accountId }),
+    }))
+    : [];
+
+  return {
+    accountId: normalizeText(accountId, null),
+    status: normalizeText(payload.status, items.length > 0 ? 'search_ready' : 'no_matches'),
+    query: normalizeText(payload.query, null),
+    limit: normalizeInteger(payload.limit, items.length > 0 ? items.length : 10),
+    totalMatches: normalizeInteger(payload.totalMatches, items.length),
+    nextAction: normalizeText(payload.nextAction, items.length > 0 ? 'review_profiles_or_request_chat' : 'refine_agent_search'),
+    agents: items,
+  };
+}
+
 export function projectToolFeedbackSubmissionResponse(result = {}) {
   const feedback = result.feedback && typeof result.feedback === 'object' ? result.feedback : {};
   const reporter = feedback.reporter && typeof feedback.reporter === 'object' ? feedback.reporter : {};

package/src/openclaw/runtime/tool-inventory.js

@@ -9,6 +9,10 @@ export const CLAWORLD_ACCOUNT_TOOL_NAMES = Object.freeze([
   'claworld_account',
 ]);
 
+export const CLAWORLD_SOCIAL_DISCOVERY_TOOL_NAMES = Object.freeze([
+  'claworld_search_agents',
+]);
+
 export const CLAWORLD_FEEDBACK_TOOL_NAMES = Object.freeze([
   'claworld_submit_feedback',
 ]);
@@ -29,6 +33,7 @@ export const CLAWORLD_WORLD_ADMIN_PUBLIC_TOOL_NAMES = Object.freeze([
 
 export const CLAWORLD_REGISTERED_TOOL_NAMES = Object.freeze([
   ...CLAWORLD_ACCOUNT_TOOL_NAMES,
+  ...CLAWORLD_SOCIAL_DISCOVERY_TOOL_NAMES,
   ...CLAWORLD_WORLD_TOOL_NAMES,
   ...CLAWORLD_WORLD_ADMIN_PUBLIC_TOOL_NAMES,
   ...CLAWORLD_CHAT_REQUEST_TOOL_NAMES,
@@ -53,6 +58,7 @@ export const CLAWORLD_READ_ONLY_OPENCLAW_TOOL_NAMES = Object.freeze([
 
 export const CLAWORLD_PLUGIN_SMOKE_REQUIRED_TOOL_NAMES = Object.freeze([
   ...CLAWORLD_ACCOUNT_TOOL_NAMES,
+  ...CLAWORLD_SOCIAL_DISCOVERY_TOOL_NAMES,
   ...CLAWORLD_WORLD_TOOL_NAMES,
   ...CLAWORLD_WORLD_ADMIN_PUBLIC_TOOL_NAMES,
   ...CLAWORLD_CHAT_REQUEST_TOOL_NAMES,