@xfxstudio/claworld 2026.6.30-testing.1 → 2026.7.1-testing.2

package/openclaw.plugin.json

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

package/package.json

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

package/src/lib/chat-request.js

@@ -99,6 +99,24 @@ export function normalizeChatRequestOpeningPayload(input = null) {
   return Object.keys(payload).length > 0 ? payload : null;
 }
 
+function normalizeKickoffBriefInput(kickoffBrief = null) {
+  if (kickoffBrief && typeof kickoffBrief === 'object' && !Array.isArray(kickoffBrief)) {
+    return kickoffBrief;
+  }
+  const text = normalizeText(kickoffBrief, null);
+  return text ? { text } : null;
+}
+
+function resolveKickoffBriefOpeningMessage(kickoffBrief = null, fallback = null) {
+  if (!kickoffBrief || typeof kickoffBrief !== 'object' || Array.isArray(kickoffBrief)) {
+    return normalizeText(fallback, null);
+  }
+  return normalizeText(
+    kickoffBrief.text,
+    normalizeText(kickoffBrief.openingMessage, normalizeText(kickoffBrief.message, normalizeText(fallback, null))),
+  );
+}
+
 export function resolveChatRequestOpeningMessage({
   openingMessage = null,
   openingPayload = null,
@@ -119,12 +137,8 @@ function resolveKickoffBriefSource({
   const normalizedContext = requestContext && typeof requestContext === 'object' && !Array.isArray(requestContext)
     ? requestContext
     : {};
-  const explicitKickoffBrief = kickoffBrief && typeof kickoffBrief === 'object' && !Array.isArray(kickoffBrief)
-    ? kickoffBrief
-    : null;
-  const contextKickoffBrief = normalizedContext.kickoffBrief && typeof normalizedContext.kickoffBrief === 'object' && !Array.isArray(normalizedContext.kickoffBrief)
-    ? normalizedContext.kickoffBrief
-    : null;
+  const explicitKickoffBrief = normalizeKickoffBriefInput(kickoffBrief);
+  const contextKickoffBrief = normalizeKickoffBriefInput(normalizedContext.kickoffBrief);
   const fallbackSource = normalizeText(source, null) === 'world_broadcast'
     ? 'world_broadcast_brief'
     : 'chat_request_brief';
@@ -150,12 +164,8 @@ function resolveChatRequestKickoffBrief({
   const normalizedContext = requestContext && typeof requestContext === 'object' && !Array.isArray(requestContext)
     ? requestContext
     : {};
-  const explicitKickoffBrief = kickoffBrief && typeof kickoffBrief === 'object' && !Array.isArray(kickoffBrief)
-    ? kickoffBrief
-    : null;
-  const contextKickoffBrief = normalizedContext.kickoffBrief && typeof normalizedContext.kickoffBrief === 'object' && !Array.isArray(normalizedContext.kickoffBrief)
-    ? normalizedContext.kickoffBrief
-    : null;
+  const explicitKickoffBrief = normalizeKickoffBriefInput(kickoffBrief);
+  const contextKickoffBrief = normalizeKickoffBriefInput(normalizedContext.kickoffBrief);
   const normalizedOpeningPayload = normalizeChatRequestOpeningPayload(
     explicitKickoffBrief?.payload
     ?? contextKickoffBrief?.payload
@@ -163,10 +173,10 @@ function resolveChatRequestKickoffBrief({
     ?? normalizedContext.openingPayload,
   );
   const normalizedOpeningMessage = resolveChatRequestOpeningMessage({
-    openingMessage:
-      explicitKickoffBrief?.text
-      ?? contextKickoffBrief?.text
-      ?? openingMessage,
+    openingMessage: resolveKickoffBriefOpeningMessage(
+      explicitKickoffBrief,
+      resolveKickoffBriefOpeningMessage(contextKickoffBrief, openingMessage),
+    ),
     openingPayload: normalizedOpeningPayload,
     requestContext: normalizedContext,
   });

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

@@ -271,6 +271,46 @@ function isClaworldPlainObject(value) {
   return value && typeof value === 'object' && !Array.isArray(value);
 }
 
+function resolveClaworldOpeningMessage({
+  openingMessage = null,
+  message = null,
+  text = null,
+  kickoffBrief = null,
+  openingPayload = null,
+} = {}) {
+  const brief = isClaworldPlainObject(kickoffBrief) ? kickoffBrief : null;
+  return normalizeClaworldText(
+    openingMessage,
+    normalizeClaworldText(
+      message,
+      normalizeClaworldText(
+        text,
+        normalizeClaworldText(
+          typeof kickoffBrief === 'string' ? kickoffBrief : null,
+          normalizeClaworldText(
+            brief?.text,
+            normalizeClaworldText(
+              brief?.openingMessage,
+              normalizeClaworldText(brief?.message, normalizeClaworldText(openingPayload?.text, null)),
+            ),
+          ),
+        ),
+      ),
+    ),
+  );
+}
+
+function normalizeClaworldKickoffBriefInput(kickoffBrief = null, openingMessage = null) {
+  if (isClaworldPlainObject(kickoffBrief)) {
+    return {
+      ...kickoffBrief,
+      ...(!resolveClaworldOpeningMessage({ kickoffBrief }) && openingMessage ? { text: openingMessage } : {}),
+    };
+  }
+  const text = normalizeClaworldText(kickoffBrief, null);
+  return text ? { text } : null;
+}
+
 function resolveNormalizedText(value, fallback = null) {
   return normalizeClaworldText(value, fallback);
 }
@@ -894,6 +934,10 @@ async function createChatRequest({
   displayName = null,
   agentCode = null,
   openingMessage = null,
+  message = null,
+  text = null,
+  kickoffBrief = null,
+  openingPayload = null,
   worldId = null,
   requestContext = null,
   fetchImpl,
@@ -912,7 +956,15 @@ async function createChatRequest({
     });
   }
   const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
-  const normalizedOpeningMessage = normalizeClaworldText(openingMessage, null);
+  const normalizedOpeningPayload = isClaworldPlainObject(openingPayload) ? openingPayload : null;
+  const normalizedOpeningMessage = resolveClaworldOpeningMessage({
+    openingMessage,
+    message,
+    text,
+    kickoffBrief,
+    openingPayload: normalizedOpeningPayload,
+  });
+  const normalizedKickoffBrief = normalizeClaworldKickoffBriefInput(kickoffBrief, normalizedOpeningMessage);
   if (!normalizedOpeningMessage) {
     const message = 'openingMessage is required for chat request kickoff';
     throw createRuntimeBoundaryError({
@@ -951,6 +1003,8 @@ async function createChatRequest({
       displayName: normalizedDisplayName,
       agentCode: normalizedAgentCode,
       openingMessage: normalizedOpeningMessage,
+      ...(normalizedKickoffBrief ? { kickoffBrief: normalizedKickoffBrief } : {}),
+      ...(normalizedOpeningPayload ? { openingPayload: normalizedOpeningPayload } : {}),
       ...(normalizeClaworldText(worldId, null) ? { worldId: normalizeClaworldText(worldId, null) } : {}),
       ...(requestContext && typeof requestContext === 'object' && !Array.isArray(requestContext)
         ? { requestContext }
@@ -4553,6 +4607,10 @@ async function generateRuntimeProfileCard(context = {}) {
             displayName: context.displayName || null,
             agentCode: context.agentCode || null,
             openingMessage: context.openingMessage || context.message || context.text || null,
+            message: context.message || null,
+            text: context.text || null,
+            kickoffBrief: context.kickoffBrief || null,
+            openingPayload: context.openingPayload || null,
             worldId: context.worldId || null,
             requestContext,
             fetchImpl,

package/src/openclaw/plugin/register.js

@@ -201,6 +201,28 @@ function hasExplicitAction(params = {}) {
   return Object.prototype.hasOwnProperty.call(params, 'action') && normalizeText(params.action, null) != null;
 }
 
+function resolveConversationOpeningMessage(params = {}) {
+  const kickoffBrief = params?.kickoffBrief && typeof params.kickoffBrief === 'object' && !Array.isArray(params.kickoffBrief)
+    ? params.kickoffBrief
+    : null;
+  return normalizeText(
+    params?.openingMessage,
+    normalizeText(
+      params?.message,
+      normalizeText(
+        params?.text,
+        normalizeText(
+          typeof params?.kickoffBrief === 'string' ? params.kickoffBrief : null,
+          normalizeText(
+            kickoffBrief?.text,
+            normalizeText(kickoffBrief?.openingMessage, normalizeText(kickoffBrief?.message, normalizeText(params?.openingPayload?.text, null))),
+          ),
+        ),
+      ),
+    ),
+  );
+}
+
 function normalizeTerminalAccountAction(params = {}) {
   if (hasExplicitAction(params)) {
     const explicitAction = normalizeText(params.action, null);
@@ -1069,6 +1091,16 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
           displayName: stringParam({ description: 'Target public display name for request.', minLength: 1 }),
           agentCode: stringParam({ description: 'Target public agent code for request.', minLength: 1 }),
           openingMessage: stringParam({ description: 'Request/re-engagement kickoff message.', minLength: 1 }),
+          message: stringParam({ description: 'Alias for openingMessage on action=request.', minLength: 1 }),
+          text: stringParam({ description: 'Alias for openingMessage on action=request.', minLength: 1 }),
+          kickoffBrief: objectParam({
+            description: 'Structured request kickoff brief. text/openingMessage/message are accepted as opener aliases.',
+            properties: {
+              text: stringParam({ description: 'Request/re-engagement kickoff message.', minLength: 1 }),
+              openingMessage: stringParam({ description: 'Alias for kickoff brief text.', minLength: 1 }),
+              message: stringParam({ description: 'Alias for kickoff brief text.', minLength: 1 }),
+            },
+          }),
           worldId: worldIdProperty,
           direction: stringParam({
             description: 'Top-level alias for filters.direction on action=list_related/get_state.',
@@ -1096,11 +1128,25 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
       async execute(toolCallId, params = {}) {
         const action = normalizeTerminalConversationAction(params.action, 'list_related', { throwOnInvalid: true });
         if (action === 'request') {
-          const result = await requireTerminalTool(internalTools, 'claworld_request_chat').execute(toolCallId, {
-            ...params,
-            action: 'request_chat',
+          const context = await resolveToolContext(api, plugin, params, {
+            requiredPublicIdentityCapability: 'request chat',
+          });
+          const payload = await plugin.helpers.social.requestChat({
+            ...context,
+            displayName: params.displayName,
+            agentCode: params.agentCode,
+            openingMessage: resolveConversationOpeningMessage(params),
+            message: params.message || null,
+            text: params.text || null,
+            kickoffBrief: params.kickoffBrief || null,
+            openingPayload: params.openingPayload || null,
+            worldId: params.worldId || null,
+          });
+          return buildToolResult({
+            ...projectToolChatRequestMutationResponse(payload, { accountId: context.accountId }),
+            tool: manageConversationsTool,
+            action,
           });
-          return rewriteToolResultName(result, manageConversationsTool, action);
         }
         if (action === 'list_related' || action === 'get_state') {
           const filters = normalizeManageConversationInboxQuery(params, action);
@@ -1717,93 +1763,6 @@ function buildRegisteredTools(api, plugin) {
         }));
       },
     },
-    {
-      name: 'claworld_request_chat',
-      label: 'Claworld Request Chat',
-      description: 'Use in the main session to create a new Claworld chat request or re-engage a selected public identity. Do not use for live conversation turns or current-session replies.',
-      metadata: buildToolMetadata({
-        category: 'chat_request',
-        usageNotes: [
-          'Primary actor/session: main session only. Use this tool when the user wants to start a new request or re-engage someone after an earlier request or chat went silent or ended.',
-          'If the user asks to contact the same person again, call this tool again to create a fresh request or re-engagement.',
-          'For world-scoped chat or re-engagement, use the displayName and agentCode returned by world member search.',
-          'The backend resolves the target by agentCode.',
-          'If the current displayName for that agentCode no longer matches, the tool can still route by the current owner and return an explicit warning with the current displayName.',
-          'openingMessage is required and must contain non-blank kickoff intent; missing or blank opener text fails with opening_message_required.',
-          'Do not use this tool for replying inside an already-open Claworld chat or for runtime live turns.',
-          'After creation, use claworld_chat_inbox to inspect pending, expired, rejected, opening, ending, active, silent, or ended status, or wait for the peer to accept.',
-          'Once accepted, the runtime owns the live conversation loop.',
-        ],
-        examples: [
-          {
-            title: 'Request chat with a world member',
-            input: {
-              accountId: 'claworld',
-              worldId: 'dating-demo-world',
-              displayName: 'Runtime Peer',
-              agentCode: 'ZX82QP',
-              openingMessage: 'Hi, want to compare trail-running routes in Shanghai?',
-            },
-            outcome: 'Creates one pending world-scoped chat request or re-engagement request.',
-          },
-          {
-            title: 'Re-engage a known public identity',
-            input: {
-              accountId: 'claworld',
-              displayName: 'Runtime Peer',
-              agentCode: 'ZX82QP',
-              openingMessage: 'Hi, want to compare trail-running routes in Shanghai?',
-            },
-            outcome: 'Creates one pending direct chat request toward the known public identity, including re-engagement after silence or a prior ended request.',
-          },
-        ],
-      }),
-      parameters: objectParam({
-        description: 'In the main session, create a new direct or world-scoped chat request, or re-engage a previously silent or ended relationship, for one target agent. Use this for user requests to contact, PK, continue, or send peer-facing Claworld conversation content. Provide the target displayName, agentCode, and non-blank openingMessage. Do not use this payload for current live replies.',
-        required: ['accountId', 'displayName', 'agentCode', 'openingMessage'],
-        properties: {
-          accountId: accountIdProperty,
-          displayName: stringParam({
-            description: 'Target public displayName for the request or re-engagement target.',
-            minLength: 1,
-            examples: ['Runtime Peer'],
-          }),
-          agentCode: stringParam({
-            description: 'Target public agentCode. The backend resolves the target by this code and verifies the displayName still matches. Use public identity, not local session references.',
-            minLength: 1,
-            examples: ['ZX82QP'],
-          }),
-          openingMessage: stringParam({
-            description: 'Required non-blank request or re-engagement brief that the backend uses when the peer accepts. Missing or blank opener text fails with opening_message_required. This is kickoff intent, not a live runtime reply payload.',
-            minLength: 1,
-            examples: ['Hi, want to compare trail-running routes in Shanghai?'],
-          }),
-          worldId: worldIdProperty,
-        },
-        examples: [
-          {
-            accountId: 'claworld',
-            worldId: 'dating-demo-world',
-            displayName: 'Runtime Peer',
-            agentCode: 'ZX82QP',
-            openingMessage: 'Hi, want to compare trail-running routes in Shanghai?',
-          },
-        ],
-      }),
-      async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params, {
-          requiredPublicIdentityCapability: 'request chat',
-        });
-        const payload = await plugin.helpers.social.requestChat({
-          ...context,
-          displayName: params.displayName,
-          agentCode: params.agentCode,
-          openingMessage: params.openingMessage || null,
-          worldId: params.worldId || null,
-        });
-        return buildToolResult(projectToolChatRequestMutationResponse(payload, { accountId: context.accountId }));
-      },
-    },
     {
       name: 'claworld_chat_inbox',
       label: 'Claworld Chat Inbox',

package/src/openclaw/plugin/relay-client.js

@@ -1427,10 +1427,21 @@ export class ClaworldRelayClient extends EventEmitter {
     });
   }
 
-  async createChatRequest({ fromAgentId, displayName, agentCode, requestContext = {} } = {}) {
+  async createChatRequest({
+    fromAgentId,
+    displayName,
+    agentCode,
+    kickoffBrief = null,
+    openingMessage = null,
+    openingPayload = null,
+    requestContext = {},
+  } = {}) {
     const normalized = normalizeChatRequestInput({ requestContext, source: 'direct_lookup' });
     const normalizedDisplayName = normalizeOptionalText(displayName);
     const normalizedAgentCode = normalizeOptionalText(agentCode)?.toUpperCase() || null;
+    const normalizedOpeningPayload = openingPayload && typeof openingPayload === 'object' && !Array.isArray(openingPayload)
+      ? openingPayload
+      : null;
     return await this.requestJson('/v1/chat-requests', {
       method: 'POST',
       headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),
@@ -1438,8 +1449,13 @@ export class ClaworldRelayClient extends EventEmitter {
         fromAgentId,
         ...(normalizedDisplayName ? { displayName: normalizedDisplayName } : {}),
         ...(normalizedAgentCode ? { agentCode: normalizedAgentCode } : {}),
-        kickoffBrief: normalized.kickoffBrief || null,
-        openingMessage: normalized.openingMessage || null,
+        kickoffBrief: kickoffBrief || normalized.kickoffBrief || null,
+        openingMessage:
+          normalizeOptionalText(openingMessage)
+          || normalizeOptionalText(normalized.openingMessage)
+          || normalizeOptionalText(normalizedOpeningPayload?.text)
+          || null,
+        ...(normalizedOpeningPayload ? { openingPayload: normalizedOpeningPayload } : {}),
         worldId: normalized.conversation?.worldId || null,
         requestContext: requestContext && typeof requestContext === 'object' && !Array.isArray(requestContext)
           ? requestContext
@@ -1564,6 +1580,7 @@ export class ClaworldRelayClient extends EventEmitter {
       fromAgentId,
       displayName,
       agentCode,
+      openingPayload: normalizedOpeningPayload,
       requestContext: normalizedRequestContext,
     });
     if (requestResult.status !== 201) {

package/src/openclaw/runtime/working-memory.js

@@ -1402,7 +1402,6 @@ export function buildClaworldToolMaintenanceEvent({
   const conversationToolNames = new Set([
     'claworld_manage_conversations',
     'claworld_chat_inbox',
-    'claworld_request_chat',
   ]);
   const localSessionKey = firstText(
     conversationToolNames.has(normalizedToolName) ? resultConversationSessionKey : null,