@newbase-clawchat/openclaw-clawchat 2026.4.21 → 2026.4.23

package/src/runtime.test.ts

@@ -166,6 +166,8 @@ describe("openclaw-clawchat runtime media ingest", () => {
         event: "message.send",
         trace_id: "ti",
         emitted_at: Date.now(),
+        chat_id: "chat-1",
+        chat_type: "direct",
         to: { id: "u", type: "direct" },
         sender: { sender_id: "user-1", type: "direct", display_name: "User" },
         payload: {
@@ -198,6 +200,302 @@ describe("openclaw-clawchat runtime media ingest", () => {
     expect(fetched).toEqual([{ url: "https://cdn/a.png" }]);
     expect(capturedCtx?.MediaPath).toBe("/cache/1.png");
     expect(capturedCtx?.MediaPaths).toEqual(["/cache/1.png"]);
+    expect(capturedCtx?.From).toBe("openclaw-clawchat:chat-1");
+    expect(capturedCtx?.ConversationLabel).toBe("chat-1");
+    expect(capturedCtx?.SenderId).toBe("user-1");
+  });
+
+  it("uses group chat_id as the canonical conversation identity", async () => {
+    let capturedCtx: Record<string, unknown> | undefined;
+    const finalizeInboundContext = vi.fn((ctx: Record<string, unknown>) => {
+      capturedCtx = ctx;
+      return ctx;
+    });
+
+    const runtime = {
+      channel: {
+        routing: {
+          resolveAgentRoute: vi.fn(() => ({
+            agentId: "u",
+            accountId: "default",
+            sessionKey: "s",
+          })),
+        },
+        session: {
+          resolveStorePath: vi.fn(() => "/tmp/sessions.json"),
+          recordInboundSession: vi.fn().mockResolvedValue(undefined),
+        },
+        reply: {
+          formatAgentEnvelope: vi.fn((p: { body: string }) => p.body),
+          resolveEnvelopeFormatOptions: vi.fn(() => ({})),
+          finalizeInboundContext,
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle: vi.fn(),
+            markRunComplete: vi.fn(),
+          })),
+          withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => {
+            await opts.run();
+          }),
+          dispatchReplyFromConfig: vi.fn().mockResolvedValue(undefined),
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(),
+          saveMediaBuffer: vi.fn(),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as import("openclaw/plugin-sdk/core").PluginRuntime;
+
+    setOpenclawClawlingRuntime(runtime);
+
+    const { startOpenclawClawlingGateway } = await import("./runtime.ts");
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    const startPromise = startOpenclawClawlingGateway({
+      cfg: {} as import("openclaw/plugin-sdk/core").OpenClawConfig,
+      account: {
+        accountId: "default",
+        name: "openclaw-clawchat",
+        enabled: true,
+        configured: true,
+        websocketUrl: "ws://t",
+        baseUrl: "https://api.example.com",
+        token: "tk",
+        userId: "u",
+        replyMode: "static",
+        groupMode: "all",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        allowFrom: [],
+        stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+        reconnect: {
+          initialDelay: 1000,
+          maxDelay: 30000,
+          jitterRatio: 0.3,
+          maxRetries: Number.POSITIVE_INFINITY,
+        },
+        heartbeat: { interval: 25000, timeout: 10000 },
+        ack: { timeout: 10000, autoResendOnTimeout: false },
+      },
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ accountId: "default" })),
+      log: { info: () => {}, error: () => {} },
+      transport,
+    });
+
+    await new Promise((r) => setTimeout(r, 0));
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "tc",
+        emitted_at: Date.now(),
+        payload: { nonce: "n" },
+      }),
+    );
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: "th",
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await new Promise((r) => setTimeout(r, 5));
+
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "message.send",
+        trace_id: "tg",
+        emitted_at: Date.now(),
+        chat_id: "grp-1",
+        chat_type: "group",
+        to: { id: "u", type: "group" },
+        sender: { sender_id: "user-1", type: "group", display_name: "Alice" },
+        payload: {
+          message_id: "m-group",
+          message_mode: "normal",
+          message: {
+            body: {
+              fragments: [{ kind: "text", text: "hello group" }],
+            },
+            context: { mentions: [], reply: null },
+            streaming: {
+              status: "static",
+              sequence: 0,
+              mutation_policy: "sealed",
+              started_at: null,
+              completed_at: null,
+            },
+          },
+        },
+      }),
+    );
+    await new Promise((r) => setTimeout(r, 30));
+    abortController.abort();
+    await startPromise;
+
+    expect(capturedCtx?.From).toBe("openclaw-clawchat:group:grp-1");
+    expect(capturedCtx?.ConversationLabel).toBe("group:grp-1");
+    expect(capturedCtx?.SenderId).toBe("user-1");
+    expect(capturedCtx?.ChatType).toBe("group");
+  });
+});
+
+describe("openclaw-clawchat runtime reply dispatch lifecycle", () => {
+  it("marks dispatch idle when reply dispatch fails", async () => {
+    const markDispatchIdle = vi.fn();
+    const withReplyDispatcher = vi.fn(
+      async (opts: { run: () => Promise<unknown>; onSettled?: () => void | Promise<void> }) => {
+        try {
+          await opts.run();
+        } finally {
+          await opts.onSettled?.();
+        }
+      },
+    );
+    const dispatchReplyFromConfig = vi.fn().mockRejectedValue(new Error("dispatch boom"));
+    const logError = vi.fn();
+
+    const runtime = {
+      channel: {
+        routing: {
+          resolveAgentRoute: vi.fn(() => ({
+            agentId: "u",
+            accountId: "default",
+            sessionKey: "s",
+          })),
+        },
+        session: {
+          resolveStorePath: vi.fn(() => "/tmp/sessions.json"),
+          recordInboundSession: vi.fn().mockResolvedValue(undefined),
+        },
+        reply: {
+          formatAgentEnvelope: vi.fn((p: { body: string }) => p.body),
+          resolveEnvelopeFormatOptions: vi.fn(() => ({})),
+          finalizeInboundContext: vi.fn((ctx: Record<string, unknown>) => ctx),
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle,
+          })),
+          withReplyDispatcher,
+          dispatchReplyFromConfig,
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(),
+          saveMediaBuffer: vi.fn(),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as PluginRuntime;
+
+    setOpenclawClawlingRuntime(runtime);
+
+    const { startOpenclawClawlingGateway } = await import("./runtime.ts");
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    const startPromise = startOpenclawClawlingGateway({
+      cfg: {} as OpenClawConfig,
+      account: {
+        accountId: "default",
+        name: "openclaw-clawchat",
+        enabled: true,
+        configured: true,
+        websocketUrl: "ws://t",
+        baseUrl: "https://api.example.com",
+        token: "tk",
+        userId: "u",
+        replyMode: "static",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        allowFrom: [],
+        stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+        reconnect: {
+          initialDelay: 1000,
+          maxDelay: 30000,
+          jitterRatio: 0.3,
+          maxRetries: Number.POSITIVE_INFINITY,
+        },
+        heartbeat: { interval: 25000, timeout: 10000 },
+        ack: { timeout: 10000, autoResendOnTimeout: false },
+      },
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ accountId: "default" })),
+      log: { info: vi.fn(), error: logError },
+      transport,
+    });
+
+    await new Promise((r) => setTimeout(r, 0));
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "tc",
+        emitted_at: Date.now(),
+        payload: { nonce: "n" },
+      }),
+    );
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: "th",
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await new Promise((r) => setTimeout(r, 5));
+
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "message.send",
+        trace_id: "tm",
+        emitted_at: Date.now(),
+        chat_id: "chat-1",
+        chat_type: "direct",
+        to: { id: "u", type: "direct" },
+        sender: { sender_id: "user-1", type: "direct", display_name: "User" },
+        payload: {
+          message_id: "m-fail",
+          message_mode: "normal",
+          message: {
+            body: {
+              fragments: [{ kind: "text", text: "hello" }],
+            },
+            context: { mentions: [], reply: null },
+            streaming: {
+              status: "static",
+              sequence: 0,
+              mutation_policy: "sealed",
+              started_at: null,
+              completed_at: null,
+            },
+          },
+        },
+      }),
+    );
+
+    await new Promise((r) => setTimeout(r, 30));
+    abortController.abort();
+    await startPromise;
+
+    expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+    expect(markDispatchIdle).toHaveBeenCalledTimes(1);
+    expect(logError).toHaveBeenCalledWith(
+      expect.stringContaining("openclaw-clawchat message handler error:"),
+    );
   });
 });
 

package/src/runtime.ts

@@ -19,6 +19,7 @@ import { dispatchOpenclawClawlingInbound } from "./inbound.ts";
 import { fetchInboundMedia } from "./media-runtime.ts";
 import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.ts";
 import { sendStreamingText } from "./streaming.ts";
+import { sendOpenclawClawlingText } from "./outbound.ts";
 
 type Log = { info?: (m: string) => void; error?: (m: string) => void };
 
@@ -33,6 +34,28 @@ export function getOpenclawClawlingClient(accountId: string): ClawlingChatClient
   return activeClients.get(accountId);
 }
 
+export async function waitForOpenclawClawlingClient(
+  accountId: string,
+  options: { timeoutMs?: number; pollMs?: number } = {},
+): Promise<ClawlingChatClient> {
+  const timeoutMs = options.timeoutMs ?? 15_000;
+  const pollMs = options.pollMs ?? 100;
+  const deadline = Date.now() + timeoutMs;
+
+  for (;;) {
+    const client = activeClients.get(accountId);
+    if (client && (client as { state?: string }).state === "connected") {
+      return client;
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `openclaw-clawchat client did not activate within ${timeoutMs}ms for account ${accountId}`,
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+}
+
 export type ClawlingState =
   | "idle"
   | "connecting"
@@ -80,6 +103,10 @@ export function classifyClawlingClientError(err: unknown): {
   };
 }
 
+function formatConversationSubject(peer: { kind: "direct" | "group"; id: string }): string {
+  return peer.kind === "group" ? `group:${peer.id}` : peer.id;
+}
+
 export interface StartGatewayParams {
   cfg: OpenClawConfig;
   account: ResolvedOpenclawClawlingAccount;
@@ -134,8 +161,9 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     }
   });
 
-  client.on("message", (env: Envelope) => {
-    dispatchOpenclawClawlingInbound({
+  client.on("message", async (env: Envelope) => {
+    try {
+      await dispatchOpenclawClawlingInbound({
       envelope: env as Envelope<DownlinkMessageSendPayload>,
       cfg,
       runtime,
@@ -152,7 +180,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         });
         const body = rt.reply.formatAgentEnvelope({
           channel: "Clawling Chat",
-          from: turn.senderNickName || turn.senderId,
+          from: formatConversationSubject(turn.peer),
           body: turn.rawBody,
           timestamp: turn.timestamp,
           ...rt.reply.resolveEnvelopeFormatOptions(cfg),
@@ -162,12 +190,16 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
           BodyForAgent: turn.rawBody,
           RawBody: turn.rawBody,
           CommandBody: turn.rawBody,
-          From: `${CHANNEL_ID}:${turn.senderId}`,
+          // Clawling v2 routes by chat_id. `senderId` is still preserved as
+          // structured metadata, but the conversation target must be based on
+          // `peer.id` so follow-up sends address the active chat, not merely
+          // the human sender identity.
+          From: `${CHANNEL_ID}:${formatConversationSubject(turn.peer)}`,
           To: `${CHANNEL_ID}:${account.userId}`,
           SessionKey: route.sessionKey,
           AccountId: route.accountId ?? accountId,
           ChatType: turn.peer.kind,
-          ConversationLabel: turn.senderNickName || turn.senderId,
+          ConversationLabel: formatConversationSubject(turn.peer),
           SenderId: turn.senderId,
           Provider: CHANNEL_ID,
           Surface: CHANNEL_ID,
@@ -230,9 +262,11 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         log?.info?.(
           `[${accountId}] openclaw-clawchat dispatching reply msg=${turn.messageId} session=${ctxPayload.SessionKey ?? route.sessionKey} agent=${route.agentId} agentsConfigured=[${agentsConfigured.join(",")}]`,
         );
+        
         try {
           const dispatchResult = await rt.reply.withReplyDispatcher({
             dispatcher,
+            onSettled: () => markDispatchIdle(),
             run: () =>
               rt.reply.dispatchReplyFromConfig({ ctx: ctxPayload, cfg, dispatcher, replyOptions }),
           });
@@ -254,16 +288,24 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
           log?.error?.(
             `[${accountId}] openclaw-clawchat dispatch failed msg=${turn.messageId}: ${String(err)}`,
           );
-          throw err;
-        } finally {
-          markDispatchIdle();
+          await sendOpenclawClawlingText({
+            client,
+            account: turn.account,
+            to: {
+              chatId: turn.peer.id,
+              chatType: turn.peer.kind === "group" ? "group" : "direct",
+            },
+            text: String(err),
+            ...(turn.replyCtx ? { replyCtx: turn.replyCtx } : {}),
+          });
         }
       },
-    }).catch((err) => {
+      })
+    } catch (err) {
       log?.error?.(
-        `[${accountId}] openclaw-clawchat inbound dispatch error: ${err instanceof Error ? err.stack || err.message : String(err)}`,
+        `[${accountId}] openclaw-clawchat message handler error: ${err instanceof Error ? err.stack || err.message : String(err)}`,
       );
-    });
+    }
   });
 
   // `client.connect()` resolves on `hello-ok` or rejects on `hello-fail`

package/src/tools-schema.ts

@@ -22,9 +22,10 @@ export type ClawchatListFriendsParams = Static<typeof ClawchatListFriendsSchema>
 
 export const ClawchatUpdateMyProfileSchema = Type.Object({
   nickname: Type.Optional(Type.String({ description: "New Nick Name" })),
-  avatar: Type.Optional(
-    Type.String({ description: "Avatar URL (use clawchat_upload_file first to obtain)" }),
+  avatar_url: Type.Optional(
+    Type.String({ description: "Avatar URL (use clawchat_upload_avatar first to obtain)" }),
   ),
+  bio: Type.Optional(Type.String({ description: "New self-introduction / bio text" })),
 });
 export type ClawchatUpdateMyProfileParams = Static<typeof ClawchatUpdateMyProfileSchema>;
 
@@ -35,6 +36,13 @@ export const ClawchatUploadFileSchema = Type.Object({
 });
 export type ClawchatUploadFileParams = Static<typeof ClawchatUploadFileSchema>;
 
+export const ClawchatUploadAvatarSchema = Type.Object({
+  filePath: Type.String({
+    description: "Absolute local path of the avatar image to upload (max 20MB)",
+  }),
+});
+export type ClawchatUploadAvatarParams = Static<typeof ClawchatUploadAvatarSchema>;
+
 export const ClawchatActivateSchema = Type.Object({
   code: Type.String({
     description:

package/src/tools.test.ts

@@ -55,7 +55,7 @@ describe("registerOpenclawClawlingTools", () => {
     expect(registered).toHaveLength(0);
   });
 
-  it("registers all six tools when configured (regardless of baseUrl)", () => {
+  it("registers all seven tools when configured (regardless of baseUrl)", () => {
     const { api, registered } = buildApi({
       configChannel: configuredChannel(/* no baseUrl */),
     });
@@ -67,6 +67,7 @@ describe("registerOpenclawClawlingTools", () => {
       "clawchat_get_user_info",
       "clawchat_list_friends",
       "clawchat_update_my_profile",
+      "clawchat_upload_avatar",
       "clawchat_upload_file",
     ]);
   });
@@ -91,7 +92,7 @@ describe("registerOpenclawClawlingTools", () => {
     expect(activate.description).toMatch(/verbatim/i);
   });
 
-  it("clawchat_update_my_profile description names name + avatar triggers (EN + ZH)", () => {
+  it("clawchat_update_my_profile description names name + avatar + bio triggers (EN + ZH)", () => {
     const { api } = buildApi({ configChannel: configuredChannel() });
     const fullTools: Array<{ name: string; description?: string }> = [];
     api.registerTool = (tool: { name: string; description?: string }) => {
@@ -104,6 +105,34 @@ describe("registerOpenclawClawlingTools", () => {
     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(/自我介绍|个人简介/);
+  });
+
+  it("clawchat_upload_avatar 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");
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-clawchat-"));
+    const big = path.join(tmp, "avatar-big.bin");
+    const handle = await fs.open(big, "w");
+    await handle.truncate(21 * 1024 * 1024);
+    await handle.close();
+    try {
+      const { api, registered } = buildApi({
+        configChannel: configuredChannel({ baseUrl: "https://api.example.com" }),
+      });
+      registerOpenclawClawlingTools(api);
+      const tool = registered.find((t) => t.name === "clawchat_upload_avatar")!;
+      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 };
+      expect(parsed.error).toBe("validation");
+      expect(parsed.message).toMatch(/20 ?MB|too large/i);
+    } finally {
+      await fs.rm(tmp, { recursive: true, force: true });
+    }
   });
 
 

package/src/tools.ts

@@ -11,11 +11,13 @@ import {
   ClawchatGetUserInfoSchema,
   ClawchatListFriendsSchema,
   ClawchatUpdateMyProfileSchema,
+  ClawchatUploadAvatarSchema,
   ClawchatUploadFileSchema,
   type ClawchatActivateParams,
   type ClawchatGetUserInfoParams,
   type ClawchatListFriendsParams,
   type ClawchatUpdateMyProfileParams,
+  type ClawchatUploadAvatarParams,
   type ClawchatUploadFileParams,
 } from "./tools-schema.ts";
 
@@ -188,7 +190,7 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
   api.registerTool(
     {
       name: "clawchat_get_my_profile",
-      label: "Clawling: Get My Profile",
+      label: "Get Profile",
       description: "Fetch the agent's own Clawling profile (id, display name, avatar, bio).",
       parameters: ClawchatGetMyProfileSchema,
       async execute(_callId, _params) {
@@ -201,7 +203,7 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
   api.registerTool(
     {
       name: "clawchat_get_user_info",
-      label: "Clawling: Get User Info",
+      label: "Get User Info",
       description: "Fetch a Clawling user's public profile by userId.",
       parameters: ClawchatGetUserInfoSchema,
       async execute(_callId, params) {
@@ -215,7 +217,7 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
   api.registerTool(
     {
       name: "clawchat_list_friends",
-      label: "Clawling: List Friends",
+      label: "List Friends",
       description: "List the agent's friends, paginated (page=1, pageSize=20 by default).",
       parameters: ClawchatListFriendsSchema,
       async execute(_callId, params) {
@@ -234,9 +236,9 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
   api.registerTool(
     {
       name: "clawchat_update_my_profile",
-      label: "Clawling: Update My Profile",
+      label: "Update Profile",
       description:
-        "Update this agent's own ClawChat profile (nickname and/or avatar). " +
+        "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', " +
@@ -244,19 +246,23 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
         "(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_file`, OR use a provided URL directly), then call this tool " +
-        "with `avatar = <url>`. " +
-        "You can pass `nickname` and `avatar` together in one call, or just one of them. " +
-        "At least one of the two must be present.",
+        "`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' " +
+        "→ 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,
       async execute(_callId, params) {
         const p = (params ?? {}) as ClawchatUpdateMyProfileParams;
-        const patch: { nick_name?: string; avatar?: string } = {};
-        if (typeof p.nickname === "string") patch.nick_name = p.nickname;
-        if (typeof p.avatar === "string") patch.avatar = p.avatar;
+        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 is required",
+            "openclaw-clawchat: at least one of nickname / avatar / bio is required",
           );
         }
         return await withClient((c): Promise<Profile> => c.updateMyProfile(patch));
@@ -265,10 +271,48 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
     { name: "clawchat_update_my_profile" },
   );
 
+  api.registerTool(
+    {
+      name: "clawchat_upload_avatar",
+      label: "Upload Avatar",
+      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,
+      async execute(_callId, params) {
+        const p = params as ClawchatUploadAvatarParams;
+        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" },
+  );
+
   api.registerTool(
     {
       name: "clawchat_upload_file",
-      label: "Clawling: Upload File",
+      label: "Upload File",
       description:
         "Upload a local file to Clawling media storage (max 20MB) and return the public URL.",
       parameters: ClawchatUploadFileSchema,
@@ -303,6 +347,6 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
   );
 
   api.logger.info?.(
-    "openclaw-clawchat: registered 6 clawchat_* tools (activate, get_my_profile, get_user_info, list_friends, update_my_profile, upload_file)",
+    "openclaw-clawchat: registered 7 clawchat_* tools (activate, get_my_profile, get_user_info, list_friends, update_my_profile, upload_avatar, upload_file)",
   );
 }