@newbase-clawchat/openclaw-clawchat 2026.4.24 → 2026.4.30

package/src/tools.ts

@@ -1,29 +1,30 @@
 import fs from "node:fs";
 import path from "node:path";
-import type { AgentToolResult } from "@mariozechner/pi-agent-core";
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/feishu";
+import type { OpenClawAgentToolResult } from "openclaw/plugin-sdk/agent-harness-runtime";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import type { OpenclawClawchatMutateConfigFile } from "./login.runtime.ts";
 import { createOpenclawClawlingApiClient } from "./api-client.ts";
 import { ClawlingApiError, type Profile } from "./api-types.ts";
 import { resolveOpenclawClawlingAccount } from "./config.ts";
 import {
   ClawchatActivateSchema,
-  ClawchatGetMyProfileSchema,
-  ClawchatGetUserInfoSchema,
-  ClawchatListFriendsSchema,
-  ClawchatUpdateMyProfileSchema,
-  ClawchatUploadAvatarSchema,
-  ClawchatUploadFileSchema,
+  ClawchatGetAccountProfileSchema,
+  ClawchatGetUserProfileSchema,
+  ClawchatListAccountFriendsSchema,
+  ClawchatUpdateAccountProfileSchema,
+  ClawchatUploadAvatarImageSchema,
+  ClawchatUploadMediaFileSchema,
   type ClawchatActivateParams,
-  type ClawchatGetUserInfoParams,
-  type ClawchatListFriendsParams,
-  type ClawchatUpdateMyProfileParams,
-  type ClawchatUploadAvatarParams,
-  type ClawchatUploadFileParams,
+  type ClawchatGetUserProfileParams,
+  type ClawchatListAccountFriendsParams,
+  type ClawchatUpdateAccountProfileParams,
+  type ClawchatUploadAvatarImageParams,
+  type ClawchatUploadMediaFileParams,
 } from "./tools-schema.ts";
 
 const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
 
-function jsonResponse(data: unknown): AgentToolResult<unknown> {
+function jsonResponse(data: unknown): OpenClawAgentToolResult<unknown> {
   return {
     content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
     details: data,
@@ -46,6 +47,13 @@ function validationError(message: string) {
   return jsonResponse({ error: "validation", message });
 }
 
+function resolveActivateCode(params: ClawchatActivateParams & { command?: unknown }): string {
+  const explicit = typeof params.code === "string" ? params.code.trim() : "";
+  if (explicit) return explicit;
+  const command = typeof params.command === "string" ? params.command.trim() : "";
+  return command.match(/\b[A-Z0-9]{6}\b/u)?.[0] ?? "";
+}
+
 function genericError(err: unknown) {
   return jsonResponse({
     error: "unknown",
@@ -87,31 +95,27 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
     return;
   }
 
-  // -----------------------------------------------------------------------
-  // `clawchat_activate` is registered UNCONDITIONALLY — it is the tool the
-  // agent invokes to onboard this plugin, so it must be available even when
-  // `account.configured === false`. All other tools below require a valid
-  // token and are gated on `account.configured`.
-  // -----------------------------------------------------------------------
   api.registerTool(
     {
       name: "clawchat_activate",
       label: "Clawling: Activate (Login with Invite Code)",
       description:
-        "Activate this agent on ClawChat by exchanging an invite code for a token. " +
+        "Activate this OpenClaw plugin on ClawChat by exchanging an invite code for a token. " +
+        "Invite codes use six uppercase letters/digits, e.g. A1B2C3. " +
         "TRIGGER — invoke this tool whenever the user's message matches ANY of: " +
-        "(1) the pattern `clawchat <code>` or `clawchat: <code>` — e.g. 'clawchat INV-ABC123' " +
-        "means: call this tool with `code = \"INV-ABC123\"`; " +
-        "(2) phrases like 'activate clawchat', 'login to clawchat', 'use invite code XYZ', " +
-        "'connect clawchat with XYZ'; " +
-        "(3) the user pastes anything that looks like an invite code (e.g. `INV-…`, `CC-…`). " +
+        "(1) activation intent with an embedded invite code, such as 'activate ClawChat with invite code A1B2C3', " +
+        "'login to ClawChat with invite code A1B2C3', 'connect ClawChat using invite code A1B2C3', " +
+        "or '绑定 ClawChat，邀请码 A1B2C3' — call this tool with `code = \"A1B2C3\"`; " +
+        "(2) generic activation intent without an embedded code, such as 'activate ClawChat' or " +
+        "'login to ClawChat' — ask for invite code before calling the tool; " +
+        "(3) activation intent with an embedded code, such as 'use invite code A1B2C3', " +
+        "or the user pasting an invite code in the context of ClawChat activation. " +
         "Extract the code verbatim — do NOT normalize / lowercase / add prefixes. " +
         "On success the tool persists the resulting token + userId to the config, so " +
-        "subsequent `clawchat_*` calls work without any other setup.",
+        "subsequent `clawchat_*` calls work without another plugin registration pass.",
       parameters: ClawchatActivateSchema,
       async execute(_callId, params) {
-        const p = params as ClawchatActivateParams;
-        const code = p.code?.trim();
+        const code = resolveActivateCode(params as ClawchatActivateParams & { command?: unknown });
         if (!code) {
           return validationError("openclaw-clawchat: code is required");
         }
@@ -122,10 +126,13 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
             accountId: null,
             runtime: { log: (message: string) => api.logger.info?.(message) },
             readInviteCode: async () => code,
+            mutateConfigFile: (api.runtime.config as unknown as {
+              mutateConfigFile: OpenclawClawchatMutateConfigFile;
+            }).mutateConfigFile,
           });
           return jsonResponse({
             ok: true,
-            message: "✅ ClawChat activated successfully.",
+            message: "ClawChat activated successfully.",
           });
         } catch (err) {
           if (err instanceof ClawlingApiError) return apiError(err);
@@ -136,23 +143,14 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
     { name: "clawchat_activate" },
   );
 
-  const account = resolveOpenclawClawlingAccount(api.config);
-  if (!account.configured) {
-    api.logger.debug?.(
-      "openclaw-clawchat: account not yet configured; only clawchat_activate is registered. " +
-        "The remaining tools will register on the next config reload after activation.",
-    );
-    return;
-  }
-
   // Re-resolve at call time so config reloads pick up new tokens / baseUrl.
   function resolveCurrent() {
     return resolveOpenclawClawlingAccount(api.config!);
   }
 
   type ClientResult =
-    | { error: AgentToolResult<unknown>; client?: never }
-    | { client: ReturnType<typeof createOpenclawClawlingApiClient>; error?: never };
+    | { ok: false; error: OpenClawAgentToolResult<unknown> }
+    | { ok: true; client: ReturnType<typeof createOpenclawClawlingApiClient> };
 
   function buildClient(): ClientResult {
     const acct = resolveCurrent();
@@ -160,9 +158,10 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
     // only need to gate on `token` here (which is populated by `openclaw
     // channel login`).
     if (!acct.token) {
-      return { error: configError("openclaw-clawchat: token is required") };
+      return { ok: false, error: configError("openclaw-clawchat: token is required") };
     }
     return {
+      ok: true,
       client: createOpenclawClawlingApiClient({
         baseUrl: acct.baseUrl,
         token: acct.token,
@@ -173,10 +172,10 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
 
   function withClient<T>(
     fn: (client: ReturnType<typeof createOpenclawClawlingApiClient>) => Promise<T>,
-  ): Promise<AgentToolResult<unknown>> {
-    return (async (): Promise<AgentToolResult<unknown>> => {
+  ): Promise<OpenClawAgentToolResult<unknown>> {
+    return (async (): Promise<OpenClawAgentToolResult<unknown>> => {
       const built = buildClient();
-      if (built.error !== undefined) return built.error;
+      if (!built.ok) return built.error;
       try {
         const data = await fn(built.client);
         return jsonResponse(data);
@@ -189,39 +188,50 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
 
   api.registerTool(
     {
-      name: "clawchat_get_my_profile",
-      label: "Get Profile",
-      description: "Fetch the agent's own Clawling profile (id, display name, avatar, bio).",
-      parameters: ClawchatGetMyProfileSchema,
+      name: "clawchat_get_account_profile",
+      label: "Get ClawChat Account Profile",
+      description:
+        "Fetch the configured ClawChat account profile (user id, nickname/display name, avatar, bio). " +
+        "TRIGGER — invoke when the user asks for the ClawChat account/profile connected to this plugin, " +
+        "such as 'show my ClawChat profile', 'what is the configured ClawChat account?', " +
+        "'当前 ClawChat 账号资料', or 'ClawChat 昵称头像简介'. " +
+        "Do not use this for OpenClaw agent persona/profile questions unless the user explicitly means the ClawChat account.",
+      parameters: ClawchatGetAccountProfileSchema,
       async execute(_callId, _params) {
         return await withClient((c) => c.getMyProfile());
       },
     },
-    { name: "clawchat_get_my_profile" },
+    { name: "clawchat_get_account_profile" },
   );
 
   api.registerTool(
     {
-      name: "clawchat_get_user_info",
-      label: "Get User Info",
-      description: "Fetch a Clawling user's public profile by userId.",
-      parameters: ClawchatGetUserInfoSchema,
+      name: "clawchat_get_user_profile",
+      label: "Get ClawChat User Profile",
+      description:
+        "Fetch a ClawChat user's public profile by userId. " +
+        "TRIGGER — invoke when the user asks to look up, view, or inspect a specific ClawChat user's public profile " +
+        "and provides a concrete userId. Do not guess or infer userId from a nickname/display name.",
+      parameters: ClawchatGetUserProfileSchema,
       async execute(_callId, params) {
-        const p = params as ClawchatGetUserInfoParams;
+        const p = params as ClawchatGetUserProfileParams;
         return await withClient((c) => c.getUserInfo(p.userId));
       },
     },
-    { name: "clawchat_get_user_info" },
+    { name: "clawchat_get_user_profile" },
   );
 
   api.registerTool(
     {
-      name: "clawchat_list_friends",
-      label: "List Friends",
-      description: "List the agent's friends, paginated (page=1, pageSize=20 by default).",
-      parameters: ClawchatListFriendsSchema,
+      name: "clawchat_list_account_friends",
+      label: "List ClawChat Account Friends",
+      description:
+        "List the configured ClawChat account's friends/contacts, paginated (page=1, pageSize=20 by default). " +
+        "TRIGGER — invoke when the user asks for this ClawChat account's friends, contacts, friend list, " +
+        "or asks to show more friends with pagination.",
+      parameters: ClawchatListAccountFriendsSchema,
       async execute(_callId, params) {
-        const p = (params ?? {}) as ClawchatListFriendsParams;
+        const p = (params ?? {}) as ClawchatListAccountFriendsParams;
         return await withClient((c) =>
           c.listFriends({
             ...(p.page !== undefined ? { page: p.page } : { page: 1 }),
@@ -230,32 +240,31 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
         );
       },
     },
-    { name: "clawchat_list_friends" },
+    { name: "clawchat_list_account_friends" },
   );
 
   api.registerTool(
     {
-      name: "clawchat_update_my_profile",
-      label: "Update Profile",
+      name: "clawchat_update_account_profile",
+      label: "Update ClawChat Account Profile",
       description:
-        "Update this agent's own ClawChat profile (nickname and/or avatar and/or bio). " +
-        "TRIGGER — invoke this tool whenever the user's message matches ANY of: " +
-        "(1) nickname/name change: 'change your name to X', 'your name is X', 'rename yourself to X', " +
-        "'I'll call you X', 'from now on you are X', '你叫 X', '改名为 X', '我叫你 X', " +
-        "'你的新名字是 X' → call with `nickname = X`; " +
-        "(2) avatar change or generation: 'change your avatar', 'update your profile picture', " +
-        "'generate a new avatar', 'use this image as your avatar', '换个头像', '生成头像', " +
-        "'把头像改为 …' → first obtain the avatar URL (generate + upload via " +
-        "`clawchat_upload_avatar`, OR use a provided URL directly), then call this tool " +
-        "with `avatar_url = <url>`; " +
-        "(3) bio/self-introduction change: 'update your bio', 'set your profile bio to X', " +
-        "'change your self introduction', '把简介改成 X', '更新自我介绍', '个人简介改为 X' " +
+        "Update the configured ClawChat account profile (nickname and/or avatar and/or bio). " +
+        "TRIGGER — invoke this tool whenever the user's message explicitly asks to change the ClawChat account profile: " +
+        "(1) ClawChat account nickname/name change: 'change the ClawChat account nickname to X', " +
+        "'set this ClawChat account name to X', 'ClawChat 昵称改为 X', '账号昵称改成 X', '账号名字叫 X' " +
+        "→ call with `nickname = X`; " +
+        "(2) ClawChat account avatar/profile-picture change: 'change the ClawChat account avatar', " +
+        "'use this image as the ClawChat profile picture', 'ClawChat 头像改为 …', '账号头像换成 …' " +
+        "→ first obtain the avatar URL (upload via `clawchat_upload_avatar_image`, OR use a provided URL directly), " +
+        "then call this tool with `avatar_url = <url>`; " +
+        "(3) ClawChat account bio/self-introduction change: 'update the ClawChat bio', " +
+        "'set the ClawChat account self-introduction to X', 'ClawChat 简介改成 X', '账号简介改为 X', '个人简介改为 X' " +
         "→ call with `bio = X`. " +
         "You can pass `nickname`, `avatar_url`, and `bio` together in one call, or just one of them. " +
-        "At least one of the three must be present.",
-      parameters: ClawchatUpdateMyProfileSchema,
+        "At least one of the three must be present. Do not use this for OpenClaw agent persona changes unless the user explicitly refers to the ClawChat account.",
+      parameters: ClawchatUpdateAccountProfileSchema,
       async execute(_callId, params) {
-        const p = (params ?? {}) as ClawchatUpdateMyProfileParams;
+        const p = (params ?? {}) as ClawchatUpdateAccountProfileParams;
         const patch: { nickname?: string; avatar_url?: string; bio?: string } = {};
         if (typeof p.nickname === "string") patch.nickname = p.nickname;
         if (typeof p.avatar_url === "string") patch.avatar_url = p.avatar_url;
@@ -268,19 +277,20 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
         return await withClient((c): Promise<Profile> => c.updateMyProfile(patch));
       },
     },
-    { name: "clawchat_update_my_profile" },
+    { name: "clawchat_update_account_profile" },
   );
 
   api.registerTool(
     {
-      name: "clawchat_upload_avatar",
-      label: "Upload Avatar",
+      name: "clawchat_upload_avatar_image",
+      label: "Upload ClawChat Avatar Image",
       description:
-        "Upload a local avatar image to Clawling avatar storage (max 20MB) and return the public URL. " +
-        "Use this before `clawchat_update_my_profile` when changing the profile picture.",
-      parameters: ClawchatUploadAvatarSchema,
+        "Upload a local image file to ClawChat avatar storage (max 20MB) and return the hosted avatar URL. " +
+        "TRIGGER — invoke when the user provides an absolute local image path and asks to upload it for the ClawChat account avatar/profile picture. " +
+        "This tool does not update or set the account avatar by itself; call `clawchat_update_account_profile` with `avatar_url` after this tool returns a URL.",
+      parameters: ClawchatUploadAvatarImageSchema,
       async execute(_callId, params) {
-        const p = params as ClawchatUploadAvatarParams;
+        const p = params as ClawchatUploadAvatarImageParams;
         if (!p.filePath || !path.isAbsolute(p.filePath)) {
           return validationError("openclaw-clawchat: filePath must be an absolute local path");
         }
@@ -306,18 +316,20 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
         return await withClient((c) => c.uploadAvatar({ buffer, filename, mime }));
       },
     },
-    { name: "clawchat_upload_avatar" },
+    { name: "clawchat_upload_avatar_image" },
   );
 
   api.registerTool(
     {
-      name: "clawchat_upload_file",
-      label: "Upload File",
+      name: "clawchat_upload_media_file",
+      label: "Upload ClawChat Media File",
       description:
-        "Upload a local file to Clawling media storage (max 20MB) and return the public URL.",
-      parameters: ClawchatUploadFileSchema,
+        "Upload a local file or media file to ClawChat media storage (max 20MB) and return the public URL/shareable URL. " +
+        "TRIGGER — invoke when the user provides an absolute local file path and asks to upload, share, or create a ClawChat-accessible link for that file. " +
+        "Do not use this for account avatar changes; use `clawchat_upload_avatar_image` for avatar images.",
+      parameters: ClawchatUploadMediaFileSchema,
       async execute(_callId, params) {
-        const p = params as ClawchatUploadFileParams;
+        const p = params as ClawchatUploadMediaFileParams;
         if (!p.filePath || !path.isAbsolute(p.filePath)) {
           return validationError("openclaw-clawchat: filePath must be an absolute local path");
         }
@@ -343,10 +355,10 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
         return await withClient((c) => c.uploadMedia({ buffer, filename, mime }));
       },
     },
-    { name: "clawchat_upload_file" },
+    { name: "clawchat_upload_media_file" },
   );
 
-  api.logger.info?.(
-    "openclaw-clawchat: registered 7 clawchat_* tools (activate, get_my_profile, get_user_info, list_friends, update_my_profile, upload_avatar, upload_file)",
+  api.logger.debug?.(
+    "openclaw-clawchat: registered 7 clawchat_* tools (activate, get_account_profile, get_user_profile, list_account_friends, update_account_profile, upload_avatar_image, upload_media_file)",
   );
 }