@newbase-clawchat/openclaw-clawchat 2026.4.24 → 2026.4.29

package/src/tools.test.ts

@@ -1,6 +1,12 @@
 import { describe, expect, it, vi } from "vitest";
 import { registerOpenclawClawlingTools } from "./tools.ts";
 
+const loginRuntime = vi.hoisted(() => ({
+  runOpenclawClawlingLogin: vi.fn(),
+}));
+
+vi.mock("./login.runtime.ts", () => loginRuntime);
+
 interface RegisteredTool {
   name: string;
   execute: (callId: string, params: unknown) => Promise<unknown>;
@@ -8,6 +14,7 @@ interface RegisteredTool {
 
 function buildApi(opts: {
   configChannel?: Record<string, unknown> | null;
+  configTools?: Record<string, unknown>;
   registerTool?: (tool: { name: string }, options?: { name: string }) => void;
 }) {
   const registered: RegisteredTool[] = [];
@@ -15,7 +22,10 @@ function buildApi(opts: {
     config:
       opts.configChannel === null
         ? undefined
-        : { channels: { "openclaw-clawchat": opts.configChannel ?? {} } },
+        : {
+            channels: { "openclaw-clawchat": opts.configChannel ?? {} },
+            ...(opts.configTools ? { tools: opts.configTools } : {}),
+          },
     logger: {
       info: vi.fn(),
       debug: vi.fn(),
@@ -39,14 +49,38 @@ function configuredChannel(extra: Record<string, unknown> = {}) {
 }
 
 describe("registerOpenclawClawlingTools", () => {
-  it("registers ONLY clawchat_activate when account.configured is false (onboarding path)", () => {
+  it("registers no tools when account.configured is false", () => {
+    const { api, registered } = buildApi({
+      configChannel: { websocketUrl: "wss://w" /* token / userId missing */ },
+    });
+    registerOpenclawClawlingTools(api);
+    expect(registered.map((t) => t.name)).toEqual([]);
+  });
+
+  it("does not mutate tool policy during registration before account activation", () => {
+    const { api, registered } = buildApi({
+      configChannel: { websocketUrl: "wss://w" /* token / userId missing */ },
+      configTools: { profile: "coding", allow: [] },
+    });
+
+    registerOpenclawClawlingTools(api);
+
+    expect(registered.map((t) => t.name)).toEqual([]);
+    expect(api.config?.tools).toEqual({
+      profile: "coding",
+      allow: [],
+    });
+  });
+
+  it("does not register clawchat_activate for invite-code onboarding", async () => {
     const { api, registered } = buildApi({
       configChannel: { websocketUrl: "wss://w" /* token / userId missing */ },
     });
+
     registerOpenclawClawlingTools(api);
-    // clawchat_activate must be available before a token exists — it's the
-    // tool the agent calls to onboard.
-    expect(registered.map((t) => t.name)).toEqual(["clawchat_activate"]);
+
+    expect(registered.some((t) => t.name === "clawchat_activate")).toBe(false);
+    expect(loginRuntime.runOpenclawClawlingLogin).not.toHaveBeenCalled();
   });
 
   it("skips registration when api.config is undefined", () => {
@@ -55,62 +89,106 @@ describe("registerOpenclawClawlingTools", () => {
     expect(registered).toHaveLength(0);
   });
 
-  it("registers all seven tools when configured (regardless of baseUrl)", () => {
+  it("registers all six account tools when configured (regardless of baseUrl)", () => {
     const { api, registered } = buildApi({
       configChannel: configuredChannel(/* no baseUrl */),
     });
     registerOpenclawClawlingTools(api);
     const names = registered.map((t) => t.name).sort();
     expect(names).toEqual([
-      "clawchat_activate",
-      "clawchat_get_my_profile",
-      "clawchat_get_user_info",
-      "clawchat_list_friends",
-      "clawchat_update_my_profile",
-      "clawchat_upload_avatar",
-      "clawchat_upload_file",
+      "clawchat_get_account_profile",
+      "clawchat_get_user_profile",
+      "clawchat_list_account_friends",
+      "clawchat_update_account_profile",
+      "clawchat_upload_avatar_image",
+      "clawchat_upload_media_file",
     ]);
   });
 
-  it("clawchat_activate description names the `clawchat <code>` trigger", () => {
+  it("logs configured tool registration at debug level only", () => {
+    const { api } = buildApi({
+      configChannel: configuredChannel(),
+    });
+    const logger = api.logger as {
+      info: ReturnType<typeof vi.fn>;
+      debug: ReturnType<typeof vi.fn>;
+    };
+
+    registerOpenclawClawlingTools(api);
+
+    expect(logger.info).not.toHaveBeenCalled();
+    expect(logger.debug).toHaveBeenCalledWith(
+      "openclaw-clawchat: registered 6 clawchat_* tools (get_account_profile, get_user_profile, list_account_friends, update_account_profile, upload_avatar_image, upload_media_file)",
+    );
+  });
+
+  it("does not register clawchat_activate when configured", () => {
     const { api, registered } = buildApi({
       configChannel: configuredChannel(),
     });
-    // Re-capture full tool objects so we can see description.
+    registerOpenclawClawlingTools(api);
+    expect(registered.some((t) => t.name === "clawchat_activate")).toBe(false);
+  });
+
+  it("clawchat_update_account_profile description names account profile triggers (EN + ZH)", () => {
+    const { api } = buildApi({ configChannel: configuredChannel() });
     const fullTools: Array<{ name: string; description?: string }> = [];
     api.registerTool = (tool: { name: string; description?: string }) => {
       fullTools.push(tool);
     };
     registerOpenclawClawlingTools(api);
-    const activate = fullTools.find((t) => t.name === "clawchat_activate")!;
-    expect(activate).toBeDefined();
-    // Must tell the LLM exactly how to spot + parse the trigger.
-    expect(activate.description).toMatch(/clawchat\s*<code>/i);
-    expect(activate.description).toMatch(/INV-/);
-    // Must spell out the verbatim-extraction rule so the model doesn't
-    // re-case / prefix the code.
-    expect(activate.description).toMatch(/verbatim/i);
+    const update = fullTools.find((t) => t.name === "clawchat_update_account_profile")!;
+    expect(update).toBeDefined();
+    expect(update.description).toMatch(/configured ClawChat account|logged-in ClawChat account/i);
+    expect(update.description).toMatch(/ClawChat (account )?(nickname|name)/i);
+    expect(update.description).toMatch(/ClawChat 昵称|账号昵称|账号名字/);
+    expect(update.description).toMatch(/avatar|profile picture/i);
+    expect(update.description).toMatch(/ClawChat 头像|账号头像/);
+    expect(update.description).toMatch(/clawchat_upload_avatar_image/);
+    expect(update.description).toMatch(/bio|self-introduction/i);
+    expect(update.description).toMatch(/ClawChat 简介|账号简介|个人简介/);
+    expect(update.description).not.toMatch(
+      new RegExp(["agent's own", "rename " + "yourself", "this agent's own"].join("|"), "i"),
+    );
   });
 
-  it("clawchat_update_my_profile description names name + avatar + bio triggers (EN + ZH)", () => {
+  it("account query and upload tool descriptions include precise trigger semantics", () => {
     const { api } = buildApi({ configChannel: configuredChannel() });
     const fullTools: Array<{ name: string; description?: string }> = [];
     api.registerTool = (tool: { name: string; description?: string }) => {
       fullTools.push(tool);
     };
     registerOpenclawClawlingTools(api);
-    const update = fullTools.find((t) => t.name === "clawchat_update_my_profile")!;
-    expect(update).toBeDefined();
-    expect(update.description).toMatch(/change your name/i);
-    expect(update.description).toMatch(/你叫/);
-    expect(update.description).toMatch(/avatar/i);
-    expect(update.description).toMatch(/生成头像|换个头像/);
-    expect(update.description).toMatch(/clawchat_upload_avatar/);
-    expect(update.description).toMatch(/bio|self introduction/i);
-    expect(update.description).toMatch(/自我介绍|个人简介/);
+
+    const accountProfile = fullTools.find((t) => t.name === "clawchat_get_account_profile")!;
+    const userProfile = fullTools.find((t) => t.name === "clawchat_get_user_profile")!;
+    const friends = fullTools.find((t) => t.name === "clawchat_list_account_friends")!;
+    const avatar = fullTools.find((t) => t.name === "clawchat_upload_avatar_image")!;
+    const media = fullTools.find((t) => t.name === "clawchat_upload_media_file")!;
+
+    expect(accountProfile.description).toMatch(/configured ClawChat account|logged-in ClawChat account/i);
+    expect(accountProfile.description).toMatch(/profile|nickname|avatar|bio/i);
+    expect(accountProfile.description).not.toMatch(/agent's own|this agent's/i);
+
+    expect(userProfile.description).toMatch(/userId/);
+    expect(userProfile.description).toMatch(/public profile/i);
+    expect(userProfile.description).toMatch(/do not guess|do not infer/i);
+
+    expect(friends.description).toMatch(/configured ClawChat account|logged-in ClawChat account/i);
+    expect(friends.description).toMatch(/friends|contacts/i);
+    expect(friends.description).toMatch(/page=1|pageSize=20/);
+
+    expect(avatar.description).toMatch(/local image/i);
+    expect(avatar.description).toMatch(/avatar URL|hosted avatar URL|public URL/i);
+    expect(avatar.description).toMatch(/clawchat_update_account_profile/);
+    expect(avatar.description).toMatch(/does not update|does not set/i);
+
+    expect(media.description).toMatch(/local file|media file/i);
+    expect(media.description).toMatch(/public URL|shareable URL/i);
+    expect(media.description).toMatch(/not.*avatar|do not use.*avatar/i);
   });
 
-  it("clawchat_upload_avatar rejects oversized files before upload", async () => {
+  it("clawchat_upload_avatar_image rejects oversized files before upload", async () => {
     const fs = await import("node:fs/promises");
     const path = await import("node:path");
     const os = await import("node:os");
@@ -124,7 +202,7 @@ describe("registerOpenclawClawlingTools", () => {
         configChannel: configuredChannel({ baseUrl: "https://api.example.com" }),
       });
       registerOpenclawClawlingTools(api);
-      const tool = registered.find((t) => t.name === "clawchat_upload_avatar")!;
+      const tool = registered.find((t) => t.name === "clawchat_upload_avatar_image")!;
       const result = await tool.execute("call-1", { filePath: big });
       const text = (result as { content: { text: string }[] }).content[0]!.text;
       const parsed = JSON.parse(text) as { error?: string; message?: string };
@@ -136,7 +214,7 @@ describe("registerOpenclawClawlingTools", () => {
   });
 
 
-  it("clawchat_upload_file rejects oversized files before upload", async () => {
+  it("clawchat_upload_media_file rejects oversized files before upload", async () => {
     const fs = await import("node:fs/promises");
     const path = await import("node:path");
     const os = await import("node:os");
@@ -151,7 +229,7 @@ describe("registerOpenclawClawlingTools", () => {
         configChannel: configuredChannel({ baseUrl: "https://api.example.com" }),
       });
       registerOpenclawClawlingTools(api);
-      const tool = registered.find((t) => t.name === "clawchat_upload_file")!;
+      const tool = registered.find((t) => t.name === "clawchat_upload_media_file")!;
       const result = await tool.execute("call-1", { filePath: big });
       const text = (result as { content: { text: string }[] }).content[0]!.text;
       const parsed = JSON.parse(text) as { error?: string; message?: string };

package/src/tools.ts

@@ -1,29 +1,29 @@
 import fs from "node:fs";
 import path from "node:path";
-import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import type { OpenClawAgentToolResult } from "openclaw/plugin-sdk/agent-harness-runtime";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/feishu";
 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,
-  type ClawchatActivateParams,
-  type ClawchatGetUserInfoParams,
-  type ClawchatListFriendsParams,
-  type ClawchatUpdateMyProfileParams,
-  type ClawchatUploadAvatarParams,
-  type ClawchatUploadFileParams,
+  // ClawchatActivateSchema,
+  ClawchatGetAccountProfileSchema,
+  ClawchatGetUserProfileSchema,
+  ClawchatListAccountFriendsSchema,
+  ClawchatUpdateAccountProfileSchema,
+  ClawchatUploadAvatarImageSchema,
+  ClawchatUploadMediaFileSchema,
+  // type ClawchatActivateParams,
+  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 +46,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",
@@ -88,59 +95,60 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
   }
 
   // -----------------------------------------------------------------------
-  // `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`.
+  // `clawchat_activate` tool disabled: activation now goes through OpenClaw
+  // channel login.
   // -----------------------------------------------------------------------
-  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. " +
-        "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-…`). " +
-        "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.",
-      parameters: ClawchatActivateSchema,
-      async execute(_callId, params) {
-        const p = params as ClawchatActivateParams;
-        const code = p.code?.trim();
-        if (!code) {
-          return validationError("openclaw-clawchat: code is required");
-        }
-        try {
-          const { runOpenclawClawlingLogin } = await import("./login.runtime.ts");
-          await runOpenclawClawlingLogin({
-            cfg: api.config!,
-            accountId: null,
-            runtime: { log: (message: string) => api.logger.info?.(message) },
-            readInviteCode: async () => code,
-          });
-          return jsonResponse({
-            ok: true,
-            message: "✅ ClawChat activated successfully.",
-          });
-        } catch (err) {
-          if (err instanceof ClawlingApiError) return apiError(err);
-          return genericError(err);
-        }
-      },
-    },
-    { name: "clawchat_activate" },
-  );
+  // api.registerTool(
+  //   {
+  //     name: "clawchat_activate",
+  //     label: "Clawling: Activate (Login with Invite Code)",
+  //     description:
+  //       "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) 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. " +
+  //       "Do not ask the user to enter a bare ClawChat command; if an invite code is present, call this tool directly. " +
+  //       "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.",
+  //     parameters: ClawchatActivateSchema,
+  //     async execute(_callId, params) {
+  //       const code = resolveActivateCode(params as ClawchatActivateParams & { command?: unknown });
+  //       if (!code) {
+  //         return validationError("openclaw-clawchat: code is required");
+  //       }
+  //       try {
+  //         const { runOpenclawClawlingLogin } = await import("./login.runtime.ts");
+  //         await runOpenclawClawlingLogin({
+  //           cfg: api.config!,
+  //           accountId: null,
+  //           runtime: { log: (message: string) => api.logger.info?.(message) },
+  //           readInviteCode: async () => code,
+  //         });
+  //         return jsonResponse({
+  //           ok: true,
+  //           message: "✅ ClawChat activated successfully.",
+  //         });
+  //       } catch (err) {
+  //         if (err instanceof ClawlingApiError) return apiError(err);
+  //         return genericError(err);
+  //       }
+  //     },
+  //   },
+  //   { 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.",
+      "openclaw-clawchat: account not yet configured; account tools will register " +
+        "on the next config reload after channel login.",
     );
     return;
   }
@@ -151,7 +159,7 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
   }
 
   type ClientResult =
-    | { error: AgentToolResult<unknown>; client?: never }
+    | { error: OpenClawAgentToolResult<unknown>; client?: never }
     | { client: ReturnType<typeof createOpenclawClawlingApiClient>; error?: never };
 
   function buildClient(): ClientResult {
@@ -173,8 +181,8 @@ 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;
       try {
@@ -189,39 +197,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 +249,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 +286,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 +325,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 +364,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 6 clawchat_* tools (get_account_profile, get_user_profile, list_account_friends, update_account_profile, upload_avatar_image, upload_media_file)",
   );
 }