@newbase-clawchat/openclaw-clawchat 2026.5.4 → 2026.5.12-13

package/src/tools.ts

@@ -2,21 +2,47 @@ import fs from "node:fs";
 import path from "node:path";
 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 {
+  ClawlingApiError,
+  type ConversationDetails,
+  type ConversationListItem,
+  type Profile,
+} from "./api-types.ts";
 import { resolveOpenclawClawlingAccount } from "./config.ts";
 import {
-  ClawchatActivateSchema,
+  clawChatDbPathForStateDir,
+  getClawChatStore,
+  type ClawChatStore,
+} from "./storage.ts";
+import {
   ClawchatGetAccountProfileSchema,
+  ClawchatGetConversationSchema,
   ClawchatGetUserProfileSchema,
+  ClawchatCreateMomentCommentSchema,
+  ClawchatCreateMomentSchema,
+  ClawchatDeleteMomentCommentSchema,
+  ClawchatDeleteMomentSchema,
   ClawchatListAccountFriendsSchema,
+  ClawchatListConversationsSchema,
+  ClawchatListMomentsSchema,
+  ClawchatReplyMomentCommentSchema,
+  ClawchatSearchUsersSchema,
+  ClawchatToggleMomentReactionSchema,
   ClawchatUpdateAccountProfileSchema,
   ClawchatUploadAvatarImageSchema,
   ClawchatUploadMediaFileSchema,
-  type ClawchatActivateParams,
+  type ClawchatCreateMomentCommentParams,
+  type ClawchatCreateMomentParams,
+  type ClawchatDeleteMomentCommentParams,
+  type ClawchatDeleteMomentParams,
+  type ClawchatGetConversationParams,
   type ClawchatGetUserProfileParams,
-  type ClawchatListAccountFriendsParams,
+  type ClawchatListConversationsParams,
+  type ClawchatListMomentsParams,
+  type ClawchatReplyMomentCommentParams,
+  type ClawchatSearchUsersParams,
+  type ClawchatToggleMomentReactionParams,
   type ClawchatUpdateAccountProfileParams,
   type ClawchatUploadAvatarImageParams,
   type ClawchatUploadMediaFileParams,
@@ -47,13 +73,6 @@ 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",
@@ -84,70 +103,180 @@ const MIME_BY_EXT: Record<string, string> = {
   ".webm": "video/webm",
 };
 
+const DIRECT_TOOL_GUARD =
+  "Use this registered ClawChat plugin tool directly. Do not use execute, shell commands, Python scripts, curl, handwritten API clients, generic fallback tools, or direct ClawChat HTTP calls for this ClawChat API action.";
+
+type ToolStore = Pick<
+  ClawChatStore,
+  "recordToolCall"
+> &
+  Partial<
+    Pick<
+      ClawChatStore,
+      "upsertConversationSummary" | "upsertConversationDetails" | "deleteConversationCache"
+    >
+  >;
+
+function toolDescription(...parts: string[]): string {
+  return `${parts.join("")} ${DIRECT_TOOL_GUARD}`;
+}
+
 function inferMimeFromPath(filePath: string): string {
   const ext = path.extname(filePath).toLowerCase();
   return MIME_BY_EXT[ext] ?? "application/octet-stream";
 }
 
-export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
+function parseTimestamp(value: unknown): number | null {
+  if (typeof value !== "string") return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function upsertConversationSummaryCache(
+  store: ToolStore | null,
+  accountId: string,
+  conversation: ConversationListItem,
+): void {
+  if (!store?.upsertConversationSummary) return;
+  store.upsertConversationSummary({
+    platform: "openclaw",
+    accountId,
+    conversationId: conversation.id,
+    conversationType: conversation.type,
+    lastSeenAt: parseTimestamp(conversation.updated_at),
+    lastRefreshedAt: Date.now(),
+    raw: conversation,
+  });
+}
+
+function upsertConversationDetailsCache(
+  store: ToolStore | null,
+  accountId: string,
+  conversation: ConversationDetails,
+): void {
+  if (!store?.upsertConversationDetails) return;
+  const refreshedAt = Date.now();
+  store.upsertConversationDetails({
+    platform: "openclaw",
+    accountId,
+    conversationId: conversation.id,
+    conversationType: conversation.type,
+    lastSeenAt: parseTimestamp(conversation.updated_at),
+    lastRefreshedAt: refreshedAt,
+    raw: conversation,
+    ...(conversation.type === "group"
+      ? {
+          groupProfile: {
+            title: conversation.title,
+            raw: conversation,
+            lastRefreshedAt: refreshedAt,
+          },
+        }
+      : {}),
+    members: conversation.participants.map((participant) => ({
+      userId: participant.user_id,
+      role: participant.role,
+      raw: participant,
+      lastSeenAt: parseTimestamp(participant.joined_at),
+    })),
+    membersComplete: true,
+  });
+}
+
+function isConversationNotFound(err: ClawlingApiError): boolean {
+  return err.meta?.status === 404 || err.meta?.code === 404 || err.meta?.code === 40401;
+}
+
+export function registerOpenclawClawlingTools(
+  api: OpenClawPluginApi,
+  options: { store?: ToolStore | null } = {},
+): void {
   if (!api.config) {
     api.logger.debug?.("openclaw-clawchat: api.config missing; skipping tool registration");
     return;
   }
 
-  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. " +
-        "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 another plugin registration pass.",
-      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,
-            mutateConfigFile: (api.runtime.config as unknown as {
-              mutateConfigFile: OpenclawClawchatMutateConfigFile;
-            }).mutateConfigFile,
-          });
-          return jsonResponse({
-            ok: true,
-            message: "ClawChat activated successfully.",
-          });
-        } catch (err) {
-          if (err instanceof ClawlingApiError) return apiError(err);
-          return genericError(err);
-        }
-      },
-    },
-    { name: "clawchat_activate" },
-  );
-
   // Re-resolve at call time so config reloads pick up new tokens / baseUrl.
   function resolveCurrent() {
     return resolveOpenclawClawlingAccount(api.config!);
   }
 
+  function resolveStore(): ToolStore | null {
+    if ("store" in options) return options.store ?? null;
+    try {
+      const stateDir = api.runtime.state?.resolveStateDir?.();
+      return getClawChatStore({
+        ...(stateDir ? { dbPath: clawChatDbPathForStateDir(stateDir) } : {}),
+        log: { error: (message) => api.logger.error?.(message) },
+      });
+    } catch {
+      api.logger.error?.("openclaw-clawchat sqlite tool persistence unavailable; continuing");
+      return null;
+    }
+  }
+
+  function detailsError(details: unknown): string | null {
+    if (!details || typeof details !== "object") return null;
+    const raw = details as { error?: unknown; message?: unknown };
+    if (typeof raw.error !== "string" || !raw.error) return null;
+    return typeof raw.message === "string" && raw.message
+      ? `${raw.error}: ${raw.message}`
+      : raw.error;
+  }
+
+  function persistToolCall(input: Parameters<ToolStore["recordToolCall"]>[0]): void {
+    try {
+      resolveStore()?.recordToolCall(input);
+    } catch {
+      api.logger.error?.("openclaw-clawchat sqlite tool call insert failed; continuing");
+    }
+  }
+
+  function persistConversationCache(fn: (store: ToolStore) => void): void {
+    try {
+      const store = resolveStore();
+      if (store) fn(store);
+    } catch {
+      api.logger.error?.("openclaw-clawchat sqlite conversation cache update failed; continuing");
+    }
+  }
+
+  async function recordClawchatToolCall<T>(
+    toolName: string,
+    params: unknown,
+    fn: () => Promise<OpenClawAgentToolResult<T>>,
+  ): Promise<OpenClawAgentToolResult<T>> {
+    const startedAt = Date.now();
+    const account = resolveCurrent();
+    try {
+      const result = await fn();
+      const details = (result as { details?: unknown }).details ?? result;
+      persistToolCall({
+        platform: "openclaw",
+        accountId: account.accountId,
+        toolName,
+        args: params ?? {},
+        result: details,
+        error: detailsError(details),
+        startedAt,
+        endedAt: Date.now(),
+      });
+      return result;
+    } catch (err) {
+      persistToolCall({
+        platform: "openclaw",
+        accountId: account.accountId,
+        toolName,
+        args: params ?? {},
+        result: null,
+        error: err instanceof Error ? err.message : String(err),
+        startedAt,
+        endedAt: Date.now(),
+      });
+      throw err;
+    }
+  }
+
   type ClientResult =
     | { ok: false; error: OpenClawAgentToolResult<unknown> }
     | { ok: true; client: ReturnType<typeof createOpenclawClawlingApiClient> };
@@ -190,15 +319,19 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
     {
       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, " +
+      description: toolDescription(
+        "Fetch the agent's connected ClawChat account profile (the configured ClawChat account: user id, nickname/display name, avatar, bio). " +
+        "This profile is the platform-side mirror of the local assistant identity; if fields are missing, report them as unset instead of inventing values. " +
+        "TRIGGER — invoke when the user asks for the ClawChat account/profile connected to this agent, " +
         "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.",
+        "Do not frame this as a human user's personal account.",
+      ),
       parameters: ClawchatGetAccountProfileSchema,
-      async execute(_callId, _params) {
-        return await withClient((c) => c.getMyProfile());
+      async execute(_callId, params) {
+        return await recordClawchatToolCall("clawchat_get_account_profile", params, async () =>
+          withClient((c) => c.getMyProfile()),
+        );
       },
     },
     { name: "clawchat_get_account_profile" },
@@ -208,14 +341,18 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
     {
       name: "clawchat_get_user_profile",
       label: "Get ClawChat User Profile",
-      description:
+      description: toolDescription(
         "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.",
+        "and provides a concrete userId. Do not guess or infer userId from a nickname/display name. " +
+        "Use `clawchat_get_account_profile` for the agent's own connected ClawChat account unless an explicit userId is provided.",
+      ),
       parameters: ClawchatGetUserProfileSchema,
       async execute(_callId, params) {
-        const p = params as ClawchatGetUserProfileParams;
-        return await withClient((c) => c.getUserInfo(p.userId));
+        return await recordClawchatToolCall("clawchat_get_user_profile", params, async () => {
+          const p = params as ClawchatGetUserProfileParams;
+          return await withClient((c) => c.getUserInfo(p.userId));
+        });
       },
     },
     { name: "clawchat_get_user_profile" },
@@ -225,56 +362,332 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
     {
       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.",
+      description: toolDescription(
+        "List friends/contacts of the agent's connected ClawChat account (the configured ClawChat account). " +
+        "These are the agent's ClawChat-platform contacts. " +
+        "TRIGGER — invoke when the user asks for this ClawChat account's friends, contacts, or friend list.",
+      ),
       parameters: ClawchatListAccountFriendsSchema,
       async execute(_callId, params) {
-        const p = (params ?? {}) as ClawchatListAccountFriendsParams;
-        return await withClient((c) =>
-          c.listFriends({
-            ...(p.page !== undefined ? { page: p.page } : { page: 1 }),
-            ...(p.pageSize !== undefined ? { pageSize: p.pageSize } : { pageSize: 20 }),
-          }),
+        return await recordClawchatToolCall("clawchat_list_account_friends", params, async () =>
+          withClient((c) => c.listFriends()),
         );
       },
     },
     { name: "clawchat_list_account_friends" },
   );
 
+  api.registerTool(
+    {
+      name: "clawchat_search_users",
+      label: "Search ClawChat Users",
+      description: toolDescription(
+        "Search ClawChat users by username or nickname. " +
+        "TRIGGER - invoke when the user asks to search, find, or look up ClawChat users by a typed query, name, username, or nickname, such as \"search ClawChat users named Alice\", \"查找用户 Alice\", or \"搜一下昵称 Alice\". " +
+        "Empty q returns no users. Use this tool before fetching a profile when the user only provides a nickname or search term; do not guess a userId from the query text.",
+      ),
+      parameters: ClawchatSearchUsersSchema,
+      async execute(_callId, params) {
+        return await recordClawchatToolCall("clawchat_search_users", params, async () => {
+          const p = (params ?? {}) as ClawchatSearchUsersParams;
+          return await withClient((c) =>
+            c.searchUsers({
+              ...(typeof p.q === "string" ? { q: p.q } : {}),
+              ...(typeof p.limit === "number" ? { limit: p.limit } : {}),
+            }),
+          );
+        });
+      },
+    },
+    { name: "clawchat_search_users" },
+  );
+
+  api.registerTool(
+    {
+      name: "clawchat_list_conversations",
+      label: "List ClawChat Conversations",
+      description: toolDescription(
+        "List ClawChat direct and group conversations visible to the configured account. " +
+          "TRIGGER - invoke when the user asks to list, browse, inspect, or paginate ClawChat conversations, chats, groups, or direct messages. " +
+          "This is read-only and does not create, update, leave, dissolve, or administer conversations.",
+      ),
+      parameters: ClawchatListConversationsSchema,
+      async execute(_callId, params) {
+        return await recordClawchatToolCall("clawchat_list_conversations", params, async () => {
+          const p = (params ?? {}) as ClawchatListConversationsParams;
+          const account = resolveCurrent();
+          return await withClient(async (c) => {
+            const data = await c.listConversations({
+              ...(typeof p.before === "string" ? { before: p.before } : {}),
+              ...(typeof p.limit === "number" ? { limit: p.limit } : {}),
+            });
+            for (const conversation of data.conversations) {
+              persistConversationCache((store) =>
+                upsertConversationSummaryCache(store, account.accountId, conversation),
+              );
+            }
+            return data;
+          });
+        });
+      },
+    },
+    { name: "clawchat_list_conversations" },
+  );
+
+  api.registerTool(
+    {
+      name: "clawchat_get_conversation",
+      label: "Get ClawChat Conversation",
+      description: toolDescription(
+        "Fetch read-only ClawChat conversation details, including group membership when returned by the API. " +
+          "TRIGGER - invoke when the user asks to inspect a specific ClawChat conversation or group and provides a concrete conversationId. " +
+          "This is read-only and does not create, update, leave, dissolve, or administer conversations.",
+      ),
+      parameters: ClawchatGetConversationSchema,
+      async execute(_callId, params) {
+        return await recordClawchatToolCall("clawchat_get_conversation", params, async () => {
+          const p = params as ClawchatGetConversationParams;
+          const account = resolveCurrent();
+          const built = buildClient();
+          if (!built.ok) return built.error;
+          try {
+            const data = await built.client.getConversation(p.conversationId);
+            persistConversationCache((store) =>
+              upsertConversationDetailsCache(store, account.accountId, data.conversation),
+            );
+            return jsonResponse(data);
+          } catch (err) {
+            if (err instanceof ClawlingApiError) {
+              if (isConversationNotFound(err)) {
+                persistConversationCache((store) =>
+                  store.deleteConversationCache?.({
+                    platform: "openclaw",
+                    accountId: account.accountId,
+                    conversationId: p.conversationId,
+                  }),
+                );
+              }
+              return apiError(err);
+            }
+            return genericError(err);
+          }
+        });
+      },
+    },
+    { name: "clawchat_get_conversation" },
+  );
+
+  api.registerTool(
+    {
+      name: "clawchat_list_moments",
+      label: "List ClawChat Moments",
+      description: toolDescription(
+        "List the configured ClawChat account's visible moments feed, including moments from the account and its friends. " +
+        "TRIGGER - invoke when the user asks to view, browse, refresh, or paginate ClawChat moments/dynamics/feed, such as \"show my ClawChat moments\", \"查看动态\", \"朋友圈动态\", or \"more moments\". " +
+        "Use before/comment/reaction/delete actions when the user needs to choose a moment id. This is a friends-only feed endpoint, not a global public timeline.",
+      ),
+      parameters: ClawchatListMomentsSchema,
+      async execute(_callId, params) {
+        return await recordClawchatToolCall("clawchat_list_moments", params, async () => {
+          const p = (params ?? {}) as ClawchatListMomentsParams;
+          return await withClient((c) =>
+            c.listMoments({
+              ...(typeof p.before === "number" ? { before: p.before } : {}),
+              ...(typeof p.limit === "number" ? { limit: p.limit } : {}),
+            }),
+          );
+        });
+      },
+    },
+    { name: "clawchat_list_moments" },
+  );
+
+  api.registerTool(
+    {
+      name: "clawchat_create_moment",
+      label: "Create ClawChat Moment",
+      description: toolDescription(
+        "Create a new ClawChat moment/dynamic for the configured ClawChat account. " +
+        "TRIGGER - invoke when the user asks to publish, post, or send a ClawChat moment/dynamic, such as \"post a ClawChat moment saying ...\", \"发布动态 ...\", or \"发朋友圈 ...\". " +
+        "At least one of text or images must be present. For local image files, upload first with the appropriate media upload tool and pass the returned URLs in images; do not pass local file paths as images.",
+      ),
+      parameters: ClawchatCreateMomentSchema,
+      async execute(_callId, params) {
+        return await recordClawchatToolCall("clawchat_create_moment", params, async () => {
+          const p = (params ?? {}) as ClawchatCreateMomentParams;
+          const text = typeof p.text === "string" ? p.text : undefined;
+          const images = Array.isArray(p.images) ? p.images : undefined;
+          if (!text && (!images || images.length === 0)) {
+            return validationError("openclaw-clawchat: at least one of text or images is required");
+          }
+          return await withClient((c) =>
+            c.createMoment({
+              ...(text !== undefined ? { text } : {}),
+              ...(images !== undefined ? { images } : {}),
+            }),
+          );
+        });
+      },
+    },
+    { name: "clawchat_create_moment" },
+  );
+
+  api.registerTool(
+    {
+      name: "clawchat_delete_moment",
+      label: "Delete ClawChat Moment",
+      description: toolDescription(
+        "Delete a ClawChat moment by moment id. " +
+        "TRIGGER - invoke when the user asks to delete/remove one of the configured account's ClawChat moments/dynamics and provides or selects a concrete moment id. " +
+        "Only the moment author can delete it. Do not guess the id; list moments first if the user refers to a moment ambiguously.",
+      ),
+      parameters: ClawchatDeleteMomentSchema,
+      async execute(_callId, params) {
+        return await recordClawchatToolCall("clawchat_delete_moment", params, async () => {
+          const p = params as ClawchatDeleteMomentParams;
+          return await withClient((c) => c.deleteMoment(p.momentId));
+        });
+      },
+    },
+    { name: "clawchat_delete_moment" },
+  );
+
+  api.registerTool(
+    {
+      name: "clawchat_toggle_moment_reaction",
+      label: "Toggle ClawChat Moment Reaction",
+      description: toolDescription(
+        "Toggle an emoji reaction on a ClawChat moment. " +
+        "TRIGGER - invoke when the user asks to react, like, unlike, emoji-react, or remove the same emoji reaction on a specific ClawChat moment, such as \"like moment 123 with 👍\", \"给动态 123 点赞\", or \"取消这个 👍 反应\". " +
+        "The API adds the reaction if missing and removes it if already present. Require a concrete moment id and emoji.",
+      ),
+      parameters: ClawchatToggleMomentReactionSchema,
+      async execute(_callId, params) {
+        return await recordClawchatToolCall("clawchat_toggle_moment_reaction", params, async () => {
+          const p = params as ClawchatToggleMomentReactionParams;
+          if (!p.emoji?.trim()) {
+            return validationError("openclaw-clawchat: emoji is required");
+          }
+          return await withClient((c) =>
+            c.toggleMomentReaction({ momentId: p.momentId, emoji: p.emoji }),
+          );
+        });
+      },
+    },
+    { name: "clawchat_toggle_moment_reaction" },
+  );
+
+  api.registerTool(
+    {
+      name: "clawchat_create_moment_comment",
+      label: "Create ClawChat Moment Comment",
+      description: toolDescription(
+        "Create a top-level comment on a ClawChat moment. " +
+        "TRIGGER - invoke when the user asks to comment/reply directly to a moment/dynamic, not to another comment, such as \"comment on moment 123: ...\", \"评论动态 123 ...\", or \"在这条动态下留言 ...\". " +
+        "Require a concrete moment id and non-empty text. Use clawchat_reply_moment_comment when the user is replying to another user's comment.",
+      ),
+      parameters: ClawchatCreateMomentCommentSchema,
+      async execute(_callId, params) {
+        return await recordClawchatToolCall("clawchat_create_moment_comment", params, async () => {
+          const p = params as ClawchatCreateMomentCommentParams;
+          if (!p.text?.trim()) {
+            return validationError("openclaw-clawchat: text is required");
+          }
+          return await withClient((c) =>
+            c.createMomentComment({ momentId: p.momentId, text: p.text }),
+          );
+        });
+      },
+    },
+    { name: "clawchat_create_moment_comment" },
+  );
+
+  api.registerTool(
+    {
+      name: "clawchat_reply_moment_comment",
+      label: "Reply To ClawChat Moment Comment",
+      description: toolDescription(
+        "Reply to an existing ClawChat moment comment with a single-level reply. " +
+        "TRIGGER - invoke when the user asks to reply to another user's comment on a moment/dynamic, such as \"reply to comment 456 on moment 123: ...\", \"回复评论 456 ...\", or \"回复他那条评论 ...\". " +
+        "Require concrete moment and comment ids; do not use this for top-level comments.",
+      ),
+      parameters: ClawchatReplyMomentCommentSchema,
+      async execute(_callId, params) {
+        return await recordClawchatToolCall("clawchat_reply_moment_comment", params, async () => {
+          const p = params as ClawchatReplyMomentCommentParams;
+          if (!p.text?.trim()) {
+            return validationError("openclaw-clawchat: text is required");
+          }
+          return await withClient((c) =>
+            c.replyMomentComment({
+              momentId: p.momentId,
+              replyToCommentId: p.replyToCommentId,
+              text: p.text,
+            }),
+          );
+        });
+      },
+    },
+    { name: "clawchat_reply_moment_comment" },
+  );
+
+  api.registerTool(
+    {
+      name: "clawchat_delete_moment_comment",
+      label: "Delete ClawChat Moment Comment",
+      description: toolDescription(
+        "Delete a comment on a ClawChat moment. " +
+        "TRIGGER - invoke when the user asks to delete/remove a specific comment or reply from a ClawChat moment/dynamic and provides concrete moment and comment ids. " +
+        "The caller may delete comments they authored or comments on moments they authored. Do not guess ids; list moments first if needed.",
+      ),
+      parameters: ClawchatDeleteMomentCommentSchema,
+      async execute(_callId, params) {
+        return await recordClawchatToolCall("clawchat_delete_moment_comment", params, async () => {
+          const p = params as ClawchatDeleteMomentCommentParams;
+          return await withClient((c) =>
+            c.deleteMomentComment({ momentId: p.momentId, commentId: p.commentId }),
+          );
+        });
+      },
+    },
+    { name: "clawchat_delete_moment_comment" },
+  );
+
   api.registerTool(
     {
       name: "clawchat_update_account_profile",
       label: "Update ClawChat Account Profile",
-      description:
-        "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: " +
+      description: toolDescription(
+        "Update nickname/avatar_url/bio on the agent's connected ClawChat account (the configured ClawChat account), which mirrors the local assistant identity. " +
+        "TRIGGER — invoke this tool whenever the user's message asks to change the ClawChat account profile or local assistant name/profile while ClawChat is connected: " +
         "(1) ClawChat account nickname/name change: 'change the ClawChat account nickname to X', " +
-        "'set this ClawChat account name to X', 'ClawChat 昵称改为 X', '账号昵称改成 X', '账号名字叫 X' " +
+        "'set this assistant 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 头像改为 …', '账号头像换成 …' " +
+        "'use this image as the assistant 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' " +
+        "'set the assistant 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. Do not use this for OpenClaw agent persona changes unless the user explicitly refers to the ClawChat account.",
+        "At least one of the three must be present. Do not frame this as updating a human user's personal account.",
+      ),
       parameters: ClawchatUpdateAccountProfileSchema,
       async execute(_callId, params) {
-        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;
-        if (typeof p.bio === "string") patch.bio = p.bio;
-        if (Object.keys(patch).length === 0) {
-          return validationError(
-            "openclaw-clawchat: at least one of nickname / avatar / bio is required",
-          );
-        }
-        return await withClient((c): Promise<Profile> => c.updateMyProfile(patch));
+        return await recordClawchatToolCall("clawchat_update_account_profile", params, async () => {
+          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;
+          if (typeof p.bio === "string") patch.bio = p.bio;
+          if (Object.keys(patch).length === 0) {
+            return validationError(
+              "openclaw-clawchat: at least one of nickname / avatar / bio is required",
+            );
+          }
+          return await withClient((c): Promise<Profile> => c.updateMyProfile(patch));
+        });
       },
     },
     { name: "clawchat_update_account_profile" },
@@ -284,36 +697,39 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
     {
       name: "clawchat_upload_avatar_image",
       label: "Upload ClawChat Avatar Image",
-      description:
-        "Upload a local image file to ClawChat avatar storage (max 20MB) and return the hosted avatar URL. " +
+      description: toolDescription(
+        "Upload an absolute local image path for use as the agent's connected ClawChat account avatar (max 20MB), returning a 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.",
+        "This tool does not update or set the account avatar by itself; when the user asked to set or sync the avatar, call `clawchat_update_account_profile` with `avatar_url` after this tool returns a URL.",
+      ),
       parameters: ClawchatUploadAvatarImageSchema,
       async execute(_callId, params) {
-        const p = params as ClawchatUploadAvatarImageParams;
-        if (!p.filePath || !path.isAbsolute(p.filePath)) {
-          return validationError("openclaw-clawchat: filePath must be an absolute local path");
-        }
-        let stat: fs.Stats;
-        try {
-          stat = fs.statSync(p.filePath);
-        } catch (err) {
-          return validationError(
-            `openclaw-clawchat: cannot stat ${p.filePath}: ${err instanceof Error ? err.message : String(err)}`,
-          );
-        }
-        if (!stat.isFile()) {
-          return validationError(`openclaw-clawchat: ${p.filePath} is not a regular file`);
-        }
-        if (stat.size > MAX_UPLOAD_BYTES) {
-          return validationError(
-            `openclaw-clawchat: file too large (${stat.size} bytes; max 20MB)`,
-          );
-        }
-        const buffer = fs.readFileSync(p.filePath);
-        const filename = path.basename(p.filePath);
-        const mime = inferMimeFromPath(p.filePath);
-        return await withClient((c) => c.uploadAvatar({ buffer, filename, mime }));
+        return await recordClawchatToolCall("clawchat_upload_avatar_image", params, async () => {
+          const p = params as ClawchatUploadAvatarImageParams;
+          if (!p.filePath || !path.isAbsolute(p.filePath)) {
+            return validationError("openclaw-clawchat: filePath must be an absolute local path");
+          }
+          let stat: fs.Stats;
+          try {
+            stat = fs.statSync(p.filePath);
+          } catch (err) {
+            return validationError(
+              `openclaw-clawchat: cannot stat ${p.filePath}: ${err instanceof Error ? err.message : String(err)}`,
+            );
+          }
+          if (!stat.isFile()) {
+            return validationError(`openclaw-clawchat: ${p.filePath} is not a regular file`);
+          }
+          if (stat.size > MAX_UPLOAD_BYTES) {
+            return validationError(
+              `openclaw-clawchat: file too large (${stat.size} bytes; max 20MB)`,
+            );
+          }
+          const buffer = fs.readFileSync(p.filePath);
+          const filename = path.basename(p.filePath);
+          const mime = inferMimeFromPath(p.filePath);
+          return await withClient((c) => c.uploadAvatar({ buffer, filename, mime }));
+        });
       },
     },
     { name: "clawchat_upload_avatar_image" },
@@ -323,42 +739,46 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
     {
       name: "clawchat_upload_media_file",
       label: "Upload ClawChat Media File",
-      description:
-        "Upload a local file or media file to ClawChat media storage (max 20MB) and return the public URL/shareable URL. " +
+      description: toolDescription(
+        "Upload an absolute local file/media path to ClawChat media storage (max 20MB) and return a ClawChat-accessible public/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.",
+        "Do not use this tool to send an attachment in the current chat; use the current runtime's native media-send mechanism instead (for example, MEDIA:/absolute/local/path where supported). " +
+        "Do not use this for account avatar changes; use `clawchat_upload_avatar_image` for avatar images. Do not use this just to mirror local assistant identity.",
+      ),
       parameters: ClawchatUploadMediaFileSchema,
       async execute(_callId, params) {
-        const p = params as ClawchatUploadMediaFileParams;
-        if (!p.filePath || !path.isAbsolute(p.filePath)) {
-          return validationError("openclaw-clawchat: filePath must be an absolute local path");
-        }
-        let stat: fs.Stats;
-        try {
-          stat = fs.statSync(p.filePath);
-        } catch (err) {
-          return validationError(
-            `openclaw-clawchat: cannot stat ${p.filePath}: ${err instanceof Error ? err.message : String(err)}`,
-          );
-        }
-        if (!stat.isFile()) {
-          return validationError(`openclaw-clawchat: ${p.filePath} is not a regular file`);
-        }
-        if (stat.size > MAX_UPLOAD_BYTES) {
-          return validationError(
-            `openclaw-clawchat: file too large (${stat.size} bytes; max 20MB)`,
-          );
-        }
-        const buffer = fs.readFileSync(p.filePath);
-        const filename = path.basename(p.filePath);
-        const mime = inferMimeFromPath(p.filePath);
-        return await withClient((c) => c.uploadMedia({ buffer, filename, mime }));
+        return await recordClawchatToolCall("clawchat_upload_media_file", params, async () => {
+          const p = params as ClawchatUploadMediaFileParams;
+          if (!p.filePath || !path.isAbsolute(p.filePath)) {
+            return validationError("openclaw-clawchat: filePath must be an absolute local path");
+          }
+          let stat: fs.Stats;
+          try {
+            stat = fs.statSync(p.filePath);
+          } catch (err) {
+            return validationError(
+              `openclaw-clawchat: cannot stat ${p.filePath}: ${err instanceof Error ? err.message : String(err)}`,
+            );
+          }
+          if (!stat.isFile()) {
+            return validationError(`openclaw-clawchat: ${p.filePath} is not a regular file`);
+          }
+          if (stat.size > MAX_UPLOAD_BYTES) {
+            return validationError(
+              `openclaw-clawchat: file too large (${stat.size} bytes; max 20MB)`,
+            );
+          }
+          const buffer = fs.readFileSync(p.filePath);
+          const filename = path.basename(p.filePath);
+          const mime = inferMimeFromPath(p.filePath);
+          return await withClient((c) => c.uploadMedia({ buffer, filename, mime }));
+        });
       },
     },
     { name: "clawchat_upload_media_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)",
+    "openclaw-clawchat: registered 16 clawchat_* tools (get_account_profile, get_user_profile, list_account_friends, search_users, list_conversations, get_conversation, list_moments, create_moment, delete_moment, toggle_moment_reaction, create_moment_comment, reply_moment_comment, delete_moment_comment, update_account_profile, upload_avatar_image, upload_media_file)",
   );
 }