@newbase-clawchat/openclaw-clawchat 2026.5.12-2 → 2026.5.12-21

package/src/tools.ts

@@ -1,18 +1,49 @@
 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 { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk/core";
 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 {
+  clawChatDbPathForStateDir,
+  getClawChatStore,
+  type ClawChatStore,
+} from "./storage.ts";
+import {
+  editClawChatMemoryBody,
+  readClawChatMemoryFile,
+  resolveClawChatMemoryPath,
+  writeClawChatMemoryBody,
+  type ClawChatMemoryTargetType,
+} from "./clawchat-memory.ts";
+import {
+  pullGroupMetadata,
+  pullOwnerMetadata,
+  pullUserMetadata,
+  pushMetadata,
+  updateMetadata,
+} from "./clawchat-metadata.ts";
 import {
   ClawchatGetAccountProfileSchema,
+  ClawchatGetConversationSchema,
   ClawchatGetUserProfileSchema,
+  ClawchatMemoryEditSchema,
+  ClawchatMemoryReadSchema,
+  ClawchatMemoryWriteSchema,
+  ClawchatMetadataSyncSchema,
+  ClawchatMetadataUpdateSchema,
   ClawchatCreateMomentCommentSchema,
   ClawchatCreateMomentSchema,
   ClawchatDeleteMomentCommentSchema,
   ClawchatDeleteMomentSchema,
   ClawchatListAccountFriendsSchema,
+  ClawchatListConversationsSchema,
   ClawchatListMomentsSchema,
   ClawchatReplyMomentCommentSchema,
   ClawchatSearchUsersSchema,
@@ -20,12 +51,18 @@ import {
   ClawchatUpdateAccountProfileSchema,
   ClawchatUploadAvatarImageSchema,
   ClawchatUploadMediaFileSchema,
+  type ClawchatMemoryEditParams,
+  type ClawchatMemoryReadParams,
+  type ClawchatMemoryWriteParams,
+  type ClawchatMetadataSyncParams,
+  type ClawchatMetadataUpdateParams,
   type ClawchatCreateMomentCommentParams,
   type ClawchatCreateMomentParams,
   type ClawchatDeleteMomentCommentParams,
   type ClawchatDeleteMomentParams,
+  type ClawchatGetConversationParams,
   type ClawchatGetUserProfileParams,
-  type ClawchatListAccountFriendsParams,
+  type ClawchatListConversationsParams,
   type ClawchatListMomentsParams,
   type ClawchatReplyMomentCommentParams,
   type ClawchatSearchUsersParams,
@@ -93,16 +130,89 @@ const MIME_BY_EXT: Record<string, string> = {
 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.";
 
+const MEMORY_READ_DEFAULT_LIMIT = 20_000;
+const MEMORY_READ_MAX_LIMIT = 100_000;
+
+type ToolStore = Pick<
+  ClawChatStore,
+  "recordToolCall"
+> &
+  Partial<
+    Pick<
+      ClawChatStore,
+      "upsertConversationSummary" | "upsertConversationDetails" | "deleteConversationCache"
+    >
+  >;
+
 function toolDescription(...parts: string[]): string {
   return `${parts.join("")} ${DIRECT_TOOL_GUARD}`;
 }
 
+function memoryToolDescription(...parts: string[]): string {
+  return parts.join("");
+}
+
 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,
+    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;
@@ -113,6 +223,82 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
     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> };
@@ -151,6 +337,327 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
     })();
   }
 
+  function workspaceRoot(ctx: OpenClawPluginToolContext): string | null {
+    const root = typeof ctx.workspaceDir === "string" ? ctx.workspaceDir.trim() : "";
+    return root || null;
+  }
+
+  function targetFromParams(params: {
+    targetType: ClawChatMemoryTargetType;
+    targetId: string;
+  }) {
+    return { targetType: params.targetType, targetId: params.targetId };
+  }
+
+  function validateTarget(root: string, params: {
+    targetType: ClawChatMemoryTargetType;
+    targetId: string;
+  }): string | null {
+    try {
+      resolveClawChatMemoryPath(root, targetFromParams(params));
+      return null;
+    } catch (err) {
+      return err instanceof Error ? err.message : String(err);
+    }
+  }
+
+  function normalizeReadBounds(params: ClawchatMemoryReadParams): {
+    offset: number;
+    limit: number;
+  } {
+    const offset = typeof params.offset === "number" && Number.isFinite(params.offset)
+      ? Math.max(0, Math.trunc(params.offset))
+      : 0;
+    const limit = typeof params.limit === "number" && Number.isFinite(params.limit)
+      ? Math.min(MEMORY_READ_MAX_LIMIT, Math.max(1, Math.trunc(params.limit)))
+      : MEMORY_READ_DEFAULT_LIMIT;
+    return { offset, limit };
+  }
+
+  function metadataPatchAllowedKeys(targetType: ClawChatMemoryTargetType): readonly string[] {
+    if (targetType === "group") return ["title", "description"];
+    if (targetType === "owner") return ["nickname", "avatar_url", "bio", "behavior"];
+    return ["nickname", "avatar_url", "bio"];
+  }
+
+  function validateMetadataUpdatePatch(params: ClawchatMetadataUpdateParams): string | null {
+    const patch = params.patch as Record<string, unknown> | undefined;
+    if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
+      return "openclaw-clawchat: metadata patch is required";
+    }
+    const keys = Object.keys(patch);
+    if (keys.length === 0) {
+      return "openclaw-clawchat: metadata patch must include at least one mutable field";
+    }
+    const allowed = new Set(metadataPatchAllowedKeys(params.targetType));
+    const invalid = keys.filter((key) => !allowed.has(key));
+    if (invalid.length > 0) {
+      return `openclaw-clawchat: metadata patch contains unsupported field(s): ${invalid.join(", ")}`;
+    }
+    const nonString = keys.filter((key) => typeof patch[key] !== "string");
+    if (nonString.length > 0) {
+      return `openclaw-clawchat: metadata patch field(s) must be strings: ${nonString.join(", ")}`;
+    }
+    return null;
+  }
+
+  function isUnsafeMemoryPathError(message: string): boolean {
+    return /Unsafe clawchat memory|Resolved clawchat memory path is outside root/i.test(message);
+  }
+
+  function memoryToolError(err: unknown) {
+    if (err instanceof ClawlingApiError) return apiError(err);
+    const message = err instanceof Error ? err.message : String(err);
+    if (isUnsafeMemoryPathError(message)) {
+      return validationError("openclaw-clawchat: unsafe ClawChat memory target");
+    }
+    return validationError(message);
+  }
+
+  function registerMemoryTools(): void {
+    api.registerTool(
+      (ctx) => ({
+        name: "clawchat_memory_read",
+        label: "Read ClawChat Memory",
+        description: memoryToolDescription(
+          "Read a ClawChat memory Markdown file by explicit targetType and targetId. " +
+          "Use this when you need existing owner, user, or group memory content. " +
+          "Do not guess ids from names. " +
+          "This reads metadata and agent-authored body; it does not contact the ClawChat server.",
+        ),
+        parameters: ClawchatMemoryReadSchema,
+        async execute(_callId, params) {
+          const root = workspaceRoot(ctx);
+          if (!root) {
+            return validationError("openclaw-clawchat: OpenClaw workspaceDir is required");
+          }
+          try {
+            const p = params as ClawchatMemoryReadParams;
+            const targetError = validateTarget(root, p);
+            if (targetError) return memoryToolError(new Error(targetError));
+            const { offset, limit } = normalizeReadBounds(p);
+            const file = await readClawChatMemoryFile(root, targetFromParams(p));
+            if (!file.exists) {
+              return jsonResponse({
+                exists: false,
+                content: "",
+                offset,
+                limit,
+                truncated: false,
+                totalLength: 0,
+                nextOffset: null,
+              });
+            }
+            const totalLength = file.raw.length;
+            const end = Math.min(totalLength, offset + limit);
+            const truncated = end < totalLength;
+            return jsonResponse({
+              exists: true,
+              content: file.raw.slice(offset, end),
+              offset,
+              limit,
+              truncated,
+              totalLength,
+              nextOffset: truncated ? end : null,
+            });
+          } catch (err) {
+            return memoryToolError(err);
+          }
+        },
+      }),
+      { name: "clawchat_memory_read" },
+    );
+
+    api.registerTool(
+      (ctx) => ({
+        name: "clawchat_memory_write",
+        label: "Write ClawChat Memory",
+        description: memoryToolDescription(
+          "Append to or replace only the agent-authored body of a ClawChat memory Markdown file by explicit targetType and targetId. " +
+          "This never modifies the metadata block. " +
+          "Do not use this to write or refresh ClawChat profile/metadata fields such as nickname, avatar_url, bio, profile_type, title, description, or behavior. " +
+          "When the user asks to refresh, sync, or update local ClawChat owner/user/group profile information, use clawchat_metadata_sync with direction=pull instead. " +
+          "Use append for new long-term memory notes and replace only when intentionally rewriting the whole body.",
+        ),
+        parameters: ClawchatMemoryWriteSchema,
+        async execute(_callId, params) {
+          const root = workspaceRoot(ctx);
+          if (!root) {
+            return validationError("openclaw-clawchat: OpenClaw workspaceDir is required");
+          }
+          try {
+            const p = params as ClawchatMemoryWriteParams;
+            const targetError = validateTarget(root, p);
+            if (targetError) return memoryToolError(new Error(targetError));
+            await writeClawChatMemoryBody(root, targetFromParams(p), p.mode, p.content);
+            return jsonResponse({ ok: true, targetType: p.targetType, targetId: p.targetId, mode: p.mode });
+          } catch (err) {
+            return memoryToolError(err);
+          }
+        },
+      }),
+      { name: "clawchat_memory_write" },
+    );
+
+    api.registerTool(
+      (ctx) => ({
+        name: "clawchat_memory_edit",
+        label: "Edit ClawChat Memory",
+        description: memoryToolDescription(
+          "Replace exactly one existing text span in the agent-authored body of a ClawChat memory Markdown file. " +
+          "This never modifies the metadata block. " +
+          "Do not use this to edit ClawChat profile/metadata fields such as nickname, avatar_url, bio, profile_type, title, description, or behavior. " +
+          "Use clawchat_metadata_sync or clawchat_metadata_update for metadata. " +
+          "The oldText must match exactly once; use read first when unsure.",
+        ),
+        parameters: ClawchatMemoryEditSchema,
+        async execute(_callId, params) {
+          const root = workspaceRoot(ctx);
+          if (!root) {
+            return validationError("openclaw-clawchat: OpenClaw workspaceDir is required");
+          }
+          try {
+            const p = params as ClawchatMemoryEditParams;
+            const targetError = validateTarget(root, p);
+            if (targetError) return memoryToolError(new Error(targetError));
+            await editClawChatMemoryBody(root, targetFromParams(p), p.oldText, p.newText);
+            return jsonResponse({ ok: true, targetType: p.targetType, targetId: p.targetId });
+          } catch (err) {
+            return memoryToolError(err);
+          }
+        },
+      }),
+      { name: "clawchat_memory_edit" },
+    );
+
+    api.registerTool(
+      (ctx) => ({
+        name: "clawchat_metadata_sync",
+        label: "Sync ClawChat Metadata",
+        description: memoryToolDescription(
+          "Synchronize the ClawChat metadata block for an explicit owner, user, or group target. " +
+          "Use direction=pull when the user asks to refresh, sync, or update local ClawChat profile information, user information, group information, or owner behavior from the server; this fetches the authoritative server record and rewrites only the metadata block. " +
+          "Use direction=push only to push selected existing local metadata fields to the server, then refresh the metadata block from the server response. " +
+          "For direction=push, pass non-empty fields containing only pushable metadata field names. " +
+          "This does not modify the agent-authored body. " +
+          "Do not combine clawchat_get_user_profile with clawchat_memory_write to update local profile metadata.",
+        ),
+        parameters: ClawchatMetadataSyncSchema,
+        async execute(_callId, params) {
+          const root = workspaceRoot(ctx);
+          if (!root) {
+            return validationError("openclaw-clawchat: OpenClaw workspaceDir is required");
+          }
+          const built = buildClient();
+          if (!built.ok) return built.error;
+          try {
+            const p = params as ClawchatMetadataSyncParams;
+            const targetError = validateTarget(root, p);
+            if (targetError) return memoryToolError(new Error(targetError));
+            const account = resolveCurrent();
+            if (p.direction === "push") {
+              if (!Array.isArray(p.fields) || p.fields.length === 0) {
+                return validationError("openclaw-clawchat: fields are required for metadata push");
+              }
+              if (p.targetType === "owner" && !account.agentId) {
+                return configError("openclaw-clawchat: agentId is required");
+              }
+              if (p.targetType === "user" && !account.userId) {
+                return configError("openclaw-clawchat: userId is required");
+              }
+              return jsonResponse(
+                await pushMetadata({
+                  memoryRoot: root,
+                  targetType: p.targetType,
+                  targetId: p.targetId,
+                  fields: p.fields,
+                  agentId: account.agentId,
+                  accountUserId: account.userId,
+                  api: built.client,
+                }),
+              );
+            }
+            if (p.targetType === "owner") {
+              if (!account.agentId) return configError("openclaw-clawchat: agentId is required");
+              return jsonResponse(
+                await pullOwnerMetadata({
+                  memoryRoot: root,
+                  agentId: account.agentId,
+                  accountUserId: account.userId,
+                  accountOwnerUserId: account.ownerUserId || undefined,
+                  api: built.client,
+                }),
+              );
+            }
+            if (p.targetType === "user") {
+              return jsonResponse(
+                await pullUserMetadata({ memoryRoot: root, userId: p.targetId, api: built.client }),
+              );
+            }
+            return jsonResponse(
+              await pullGroupMetadata({ memoryRoot: root, groupId: p.targetId, api: built.client }),
+            );
+          } catch (err) {
+            return memoryToolError(err);
+          }
+        },
+      }),
+      { name: "clawchat_metadata_sync" },
+    );
+
+    api.registerTool(
+      (ctx) => ({
+        name: "clawchat_metadata_update",
+        label: "Update ClawChat Metadata",
+        description: memoryToolDescription(
+          "Update ClawChat server metadata for an explicit owner, connected user account, or group target, then refresh the local metadata block from the server response. " +
+          "Use this only when the user wants to change server-side metadata fields. " +
+          "To refresh local metadata from the server without changing the server, use clawchat_metadata_sync with direction=pull. " +
+          "This always pushes to the server first and does not modify the agent-authored body.",
+        ),
+        parameters: ClawchatMetadataUpdateSchema,
+        async execute(_callId, params) {
+          const root = workspaceRoot(ctx);
+          if (!root) {
+            return validationError("openclaw-clawchat: OpenClaw workspaceDir is required");
+          }
+          const built = buildClient();
+          if (!built.ok) return built.error;
+          try {
+            const p = params as ClawchatMetadataUpdateParams;
+            const targetError = validateTarget(root, p);
+            if (targetError) return memoryToolError(new Error(targetError));
+            const patchError = validateMetadataUpdatePatch(p);
+            if (patchError) return validationError(patchError);
+            const account = resolveCurrent();
+            if (p.targetType === "owner" && !account.agentId) {
+              return configError("openclaw-clawchat: agentId is required");
+            }
+            if (p.targetType === "user" && !account.userId) {
+              return configError("openclaw-clawchat: userId is required");
+            }
+            return jsonResponse(
+              await updateMetadata({
+                memoryRoot: root,
+                targetType: p.targetType,
+                targetId: p.targetId,
+                agentId: account.agentId,
+                accountUserId: account.userId,
+                patch: p.patch,
+                api: built.client,
+              }),
+            );
+          } catch (err) {
+            return memoryToolError(err);
+          }
+        },
+      }),
+      { name: "clawchat_metadata_update" },
+    );
+  }
+
+  registerMemoryTools();
+
   api.registerTool(
     {
       name: "clawchat_get_account_profile",
@@ -164,8 +671,10 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
         "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" },
@@ -179,12 +688,16 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
         "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. " +
+        "This is a read-only lookup and does not update local ClawChat Memory files. " +
+        "When the user asks to refresh, sync, or update that user's local profile information, call clawchat_metadata_sync with targetType=user, that targetId, and direction=pull. " +
         "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" },
@@ -195,18 +708,14 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
       name: "clawchat_list_account_friends",
       label: "List ClawChat Account Friends",
       description: toolDescription(
-        "List friends/contacts of the agent's connected ClawChat account (the configured ClawChat account), paginated (page=1, pageSize=20 by default). " +
+        "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, friend list, or asks to show more friends with pagination.",
+        "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()),
         );
       },
     },
@@ -224,18 +733,95 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
       ),
       parameters: ClawchatSearchUsersSchema,
       async execute(_callId, params) {
-        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 } : {}),
-          }),
-        );
+        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",
@@ -247,13 +833,15 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
       ),
       parameters: ClawchatListMomentsSchema,
       async execute(_callId, params) {
-        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 } : {}),
-          }),
-        );
+        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" },
@@ -270,18 +858,20 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
       ),
       parameters: ClawchatCreateMomentSchema,
       async execute(_callId, params) {
-        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 } : {}),
-          }),
-        );
+        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" },
@@ -298,8 +888,10 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
       ),
       parameters: ClawchatDeleteMomentSchema,
       async execute(_callId, params) {
-        const p = params as ClawchatDeleteMomentParams;
-        return await withClient((c) => c.deleteMoment(p.momentId));
+        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" },
@@ -316,13 +908,15 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
       ),
       parameters: ClawchatToggleMomentReactionSchema,
       async execute(_callId, params) {
-        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 }),
-        );
+        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" },
@@ -339,13 +933,15 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
       ),
       parameters: ClawchatCreateMomentCommentSchema,
       async execute(_callId, params) {
-        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 }),
-        );
+        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" },
@@ -362,17 +958,19 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
       ),
       parameters: ClawchatReplyMomentCommentSchema,
       async execute(_callId, params) {
-        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,
-          }),
-        );
+        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" },
@@ -389,10 +987,12 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
       ),
       parameters: ClawchatDeleteMomentCommentSchema,
       async execute(_callId, params) {
-        const p = params as ClawchatDeleteMomentCommentParams;
-        return await withClient((c) =>
-          c.deleteMomentComment({ momentId: p.momentId, commentId: p.commentId }),
-        );
+        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" },
@@ -420,17 +1020,19 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
       ),
       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" },
@@ -447,30 +1049,32 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
       ),
       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" },
@@ -488,36 +1092,38 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
       ),
       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 14 clawchat_* tools (get_account_profile, get_user_profile, list_account_friends, search_users, 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)",
+    "openclaw-clawchat: registered 21 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, memory_read, memory_write, memory_edit, metadata_sync, metadata_update)",
   );
 }