@newbase-clawchat/openclaw-clawchat 2026.4.21 → 2026.4.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newbase-clawchat/openclaw-clawchat",
-  "version": "2026.4.21",
+  "version": "2026.4.22",
   "description": "OpenClaw ClawChat channel plugin",
   "files": [
     "index.ts",

package/src/api-client.test.ts

@@ -96,6 +96,25 @@ describe("openclaw-clawchat api-client", () => {
     expect((init.headers as Record<string, string>)["content-type"]).toBe("application/json");
   });
 
+  it("updateMyProfile forwards bio in the JSON body", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: { user_id: "u1", bio: "hello there" },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      userId: "agent-1",
+      fetchImpl,
+    });
+    await client.updateMyProfile({ bio: "hello there" });
+    const init = fetchImpl.mock.calls[0]![1] as RequestInit;
+    expect(JSON.parse(init.body as string)).toEqual({ bio: "hello there" });
+  });
+
   it("updateMyProfile throws validation error when userId is not configured", async () => {
     const fetchImpl = vi.fn();
     const client = createOpenclawClawlingApiClient({

package/src/api-client.ts

@@ -24,7 +24,7 @@ export interface OpenclawClawlingApiClient {
   getMyProfile(): Promise<Profile>;
   getUserInfo(userId: string): Promise<Profile>;
   listFriends(params: { page?: number; pageSize?: number }): Promise<FriendList>;
-  updateMyProfile(patch: { nick_name?: string; avatar?: string }): Promise<Profile>;
+  updateMyProfile(patch: { nick_name?: string; avatar_url?: string; bio?: string }): Promise<Profile>;
   uploadMedia(params: { buffer: Buffer; filename: string; mime?: string }): Promise<UploadResult>;
   /**
    * Exchange an invite code for an agent token.
@@ -172,7 +172,7 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
       }
       return await call<Profile>(
         "PATCH",
-        `/v1/agents/${encodeURIComponent(opts.userId.trim())}`,
+        `/v1/users/me`,
         {
           body: JSON.stringify(patch),
           headers: { "content-type": "application/json" },

package/src/api-types.ts

@@ -7,9 +7,9 @@
  */
 
 export interface Profile {
-  user_id: string;
-  nick_name: string;
-  avatar?: string;
+  id: string;
+  nickname?: string;
+  avatar_url?: string;
   bio?: string;
 }
 

package/src/channel.outbound.test.ts

@@ -0,0 +1,116 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const getClientMock = vi.hoisted(() => vi.fn());
+const getRuntimeMock = vi.hoisted(() => vi.fn());
+const uploadOutboundMediaMock = vi.hoisted(() => vi.fn());
+const createApiClientMock = vi.hoisted(() => vi.fn());
+const sendTextMock = vi.hoisted(() => vi.fn());
+const sendMediaMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./runtime.ts", () => ({
+  getOpenclawClawlingClient: getClientMock,
+  getOpenclawClawlingRuntime: getRuntimeMock,
+  startOpenclawClawlingGateway: vi.fn(),
+}));
+
+vi.mock("./media-runtime.ts", () => ({
+  uploadOutboundMedia: uploadOutboundMediaMock,
+}));
+
+vi.mock("./api-client.ts", () => ({
+  createOpenclawClawlingApiClient: createApiClientMock,
+}));
+
+vi.mock("./outbound.ts", () => ({
+  sendOpenclawClawlingText: sendTextMock,
+  sendOpenclawClawlingMedia: sendMediaMock,
+}));
+
+describe("openclaw-clawchat channel outbound", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    getClientMock.mockReset();
+    getRuntimeMock.mockReset();
+    uploadOutboundMediaMock.mockReset();
+    createApiClientMock.mockReset();
+    sendTextMock.mockReset();
+    sendMediaMock.mockReset();
+  });
+
+  it("sendMedia uploads mediaUrl and sends resulting fragments", async () => {
+    const client = { sendMessage: vi.fn() };
+    const runtime = { media: { loadWebMedia: vi.fn() } };
+    const apiClient = { uploadMedia: vi.fn() };
+    getClientMock.mockReturnValue(client);
+    getRuntimeMock.mockReturnValue(runtime);
+    createApiClientMock.mockReturnValue(apiClient);
+    uploadOutboundMediaMock.mockResolvedValue([
+      { kind: "image", url: "https://cdn/uploaded.png", mime: "image/png" },
+    ]);
+    sendMediaMock.mockResolvedValue({ messageId: "m-1", acceptedAt: 123 });
+
+    const { openclawClawlingOutbound } = await import("./outbound.ts");
+    const result = await openclawClawlingOutbound.sendMedia!({
+      cfg: {
+        channels: {
+          "openclaw-clawchat": {
+            enabled: true,
+            websocketUrl: "ws://t",
+            baseUrl: "https://api.example.com",
+            token: "tk",
+            userId: "agent-1",
+          },
+        },
+      } as never,
+      to: "cc:group:room-1",
+      text: "caption",
+      mediaUrl: "/tmp/photo.png",
+      mediaLocalRoots: ["/tmp"],
+    });
+
+    expect(createApiClientMock).toHaveBeenCalledWith({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      userId: "agent-1",
+    });
+    expect(uploadOutboundMediaMock).toHaveBeenCalledWith(["/tmp/photo.png"], {
+      apiClient,
+      runtime,
+      mediaLocalRoots: ["/tmp"],
+    });
+    expect(sendMediaMock).toHaveBeenCalledWith({
+      client,
+      account: expect.objectContaining({ userId: "agent-1", baseUrl: "https://api.example.com" }),
+      to: { chatId: "room-1", chatType: "group" },
+      text: "caption",
+      mediaFragments: [{ kind: "image", url: "https://cdn/uploaded.png", mime: "image/png" }],
+    });
+    expect(result).toEqual({
+      channel: "openclaw-clawchat",
+      to: "cc:group:room-1",
+      messageId: "m-1",
+    });
+  });
+
+  it("sendMedia rejects missing mediaUrl", async () => {
+    getClientMock.mockReturnValue({ sendMessage: vi.fn() });
+    const { openclawClawlingOutbound } = await import("./outbound.ts");
+    await expect(
+      openclawClawlingOutbound.sendMedia!({
+        cfg: {
+          channels: {
+            "openclaw-clawchat": {
+              enabled: true,
+              websocketUrl: "ws://t",
+              baseUrl: "https://api.example.com",
+              token: "tk",
+              userId: "agent-1",
+            },
+          },
+        } as never,
+        to: "cc:user-1",
+        text: "caption",
+      }),
+    ).rejects.toThrow(/requires mediaUrl/);
+  });
+});

package/src/channel.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { openclawClawlingPlugin } from "./channel.ts";
+import { parseOpenclawRecipient } from "./outbound.ts";
 
 describe("openclaw-clawchat plugin", () => {
   it("publishes openclaw-clawchat channel metadata", () => {
@@ -68,5 +69,23 @@ describe("openclaw-clawchat plugin", () => {
     });
     expect(Array.isArray(hints) && hints.length).toBeGreaterThan(0);
     expect(hints!.some((h) => /ClawChat/.test(h))).toBe(true);
+    expect(hints!.some((h) => /update.*profile|profile.*bio/i.test(h))).toBe(true);
+    expect(hints!.some((h) => /update.*avatar|profile picture|clawchat_upload_avatar/i.test(h))).toBe(
+      true,
+    );
+  });
+
+  it("normalizes openclaw-clawchat targets for host resolution", () => {
+    const normalized = openclawClawlingPlugin.messaging?.normalizeTarget?.(
+      "openclaw-clawchat:usr_01KPN6SQFQEGM9HR11CHRHPMMT",
+    );
+    expect(normalized).toBe("usr_01KPN6SQFQEGM9HR11CHRHPMMT");
+  });
+
+  it("parses openclaw-clawchat target prefix as a direct recipient", () => {
+    expect(parseOpenclawRecipient("openclaw-clawchat:usr_01KPN6SQFQEGM9HR11CHRHPMMT")).toEqual({
+      chatId: "usr_01KPN6SQFQEGM9HR11CHRHPMMT",
+      chatType: "direct",
+    });
   });
 });

package/src/channel.ts

@@ -6,7 +6,6 @@ import {
   type OpenClawConfig,
 } from "openclaw/plugin-sdk/core";
 import { createEmptyChannelDirectoryAdapter } from "openclaw/plugin-sdk/directory-runtime";
-import { chunkMarkdownText } from "openclaw/plugin-sdk/reply-runtime";
 import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
 import {
   createComputedAccountStatusAdapter,
@@ -19,53 +18,8 @@ import {
   resolveOpenclawClawlingAccount,
   type ResolvedOpenclawClawlingAccount,
 } from "./config.ts";
-import type { ChatType } from "./client.ts";
-import { sendOpenclawClawlingText } from "./outbound.ts";
-import { startOpenclawClawlingGateway, getOpenclawClawlingClient } from "./runtime.ts";
-
-/**
- * Parse an agent-initiated outbound recipient string into the new-protocol
- * `chat_id` + `chat_type` pair.
- *
- * Accepted forms (case-insensitive prefix):
- *   - `cc:{chat_id}`                  → direct
- *   - `clawchat:{chat_id}`            → direct
- *   - `cc:direct:{chat_id}`           → direct
- *   - `cc:group:{chat_id}`            → group
- *   - `clawchat:direct:{chat_id}`     → direct
- *   - `clawchat:group:{chat_id}`      → group
- *   - bare `{chat_id}`                → direct (backward compat)
- */
-export function parseOpenclawRecipient(to: string): { chatId: string; chatType: ChatType } {
-  const raw = (to ?? "").trim();
-  if (!raw) throw new Error("openclaw-clawchat: outbound `to` is empty");
-
-  // Split on the first ":" to detect the scheme. If no scheme, treat as a
-  // bare chat_id defaulting to direct.
-  const firstColon = raw.indexOf(":");
-  if (firstColon < 0) return { chatId: raw, chatType: "direct" };
-
-  const scheme = raw.slice(0, firstColon).toLowerCase();
-  const rest = raw.slice(firstColon + 1);
-  if (scheme !== "cc" && scheme !== "clawchat") {
-    // Unknown scheme — treat the whole string as the chat_id for robustness.
-    return { chatId: raw, chatType: "direct" };
-  }
-
-  // After the scheme we optionally accept `direct:` / `group:` type prefix.
-  const secondColon = rest.indexOf(":");
-  if (secondColon >= 0) {
-    const typeToken = rest.slice(0, secondColon).toLowerCase();
-    const chatId = rest.slice(secondColon + 1).trim();
-    if ((typeToken === "direct" || typeToken === "group") && chatId) {
-      return { chatId, chatType: typeToken };
-    }
-  }
-  // No explicit type token → default to direct, chat_id is `rest`.
-  const chatId = rest.trim();
-  if (!chatId) throw new Error(`openclaw-clawchat: missing chat_id in \"${to}\"`);
-  return { chatId, chatType: "direct" };
-}
+import { openclawClawlingOutbound } from "./outbound.ts";
+import { startOpenclawClawlingGateway } from "./runtime.ts";
 
 const configAdapter = createTopLevelChannelConfigAdapter<ResolvedOpenclawClawlingAccount>({
   sectionKey: CHANNEL_ID,
@@ -244,35 +198,25 @@ export const openclawClawlingPlugin: ChannelPlugin<ResolvedOpenclawClawlingAccou
         messageToolHints: () => [
           "To send an image or file to the current user, use the message tool with action='send' and set 'media' to a local file path or a remote URL. You do not need to specify 'to' — the current conversation recipient is used automatically.",
           "When the user asks you to find an image from the web, use a web search or browser tool to find a suitable image URL, then send it using the message tool with 'media' set to that HTTPS image URL — do NOT download the image first.",
+          "When the user asks you to update your profile, nickname, bio, self-introduction, or personal introduction, use `clawchat_update_my_profile` with the relevant fields (`nickname`, `bio`, and/or `avatar_url`).",
+          "When the user asks you to change or update your avatar/profile picture using a local image, first use `clawchat_upload_avatar` to get the avatar URL, then call `clawchat_update_my_profile` with `avatar_url`.",
           "- ClawChat targeting: omit `target` to reply to the current chat (auto-inferred). To send to a specific chat, use `cc:{chat_id}` (direct, default) or `cc:group:{chat_id}` (group). `clawchat:` is accepted as a synonym of `cc:`.",
           "- ClawChat supports media fragments (image / file / audio / video) alongside text in the same message.",
           "- ClawChat stream mode emits `message.created` → progressive `message.add` deltas → `message.done`, followed by a consolidated `message.reply` with the merged text.",
         ],
       },
-    },
-    outbound: {
-      deliveryMode: "direct",
-      chunker: (text, limit) => chunkMarkdownText(text, limit),
-      chunkerMode: "markdown",
-      textChunkLimit: 4000,
-      sendText: async ({ cfg, to, text }) => {
-        const account = resolveOpenclawClawlingAccount(cfg);
-        const client = getOpenclawClawlingClient(account.accountId);
-        if (!client) {
-          throw new Error(`openclaw-clawchat client not running for account ${account.accountId}`);
-        }
-        const recipient = parseOpenclawRecipient(to);
-        const result = await sendOpenclawClawlingText({
-          client,
-          account,
-          to: recipient,
-          text,
-        });
-        return {
-          channel: CHANNEL_ID,
-          to,
-          messageId: result?.messageId ?? `${account.userId}-${Date.now()}`,
-        };
+      messaging: {
+        normalizeTarget: (target) =>
+          target
+            .trim()
+            .replace(/^openclaw-clawchat:/i, "")
+            .replace(/^clawchat:/i, "")
+            .replace(/^cc:/i, ""),
+        targetResolver: {
+          looksLikeId: (raw, normalized) => Boolean((normalized ?? raw).trim()),
+          hint: "active-session",
+        },
       },
     },
+    outbound: openclawClawlingOutbound,
   });

package/src/inbound.test.ts

@@ -230,6 +230,23 @@ describe("openclaw-clawchat inbound", () => {
     ]);
   });
 
+  it("dispatches image-only messages", async () => {
+    const ingest = vi.fn().mockResolvedValue(undefined);
+    const env = buildSendEnvelope({ text: "   " });
+    env.payload.message.body.fragments = [{ kind: "image", url: "https://cdn/x.png" }];
+    await dispatchOpenclawClawlingInbound({
+      envelope: env,
+      cfg: {} as never,
+      runtime: {} as never,
+      account: baseAccount(),
+      ingest,
+    });
+    expect(ingest).toHaveBeenCalledTimes(1);
+    const call = ingest.mock.calls[0]![0];
+    expect(call.rawBody).toBe("![image](https://cdn/x.png)");
+    expect(call.mediaItems).toEqual([{ kind: "image", url: "https://cdn/x.png" }]);
+  });
+
   it("dispatches when sender is only on envelope.sender (real wire, no message.sender)", async () => {
     const ingest = vi.fn().mockResolvedValue(undefined);
     const env = buildSendEnvelope({ text: "hello" });

package/src/inbound.ts

@@ -131,7 +131,9 @@ export async function dispatchOpenclawClawlingInbound(
     return;
   }
   if (!hasRenderableText(message)) {
-    log?.info?.(`[${account.accountId}] openclaw-clawchat skip empty msg=${payload.message_id}`);
+    log?.info?.(
+      `[${account.accountId}] openclaw-clawchat skip empty msg=${payload.message_id}`,
+    );
     return;
   }
   if (rememberAndCheck(payload.message_id)) {

package/src/media-runtime.test.ts

@@ -6,13 +6,6 @@ import {
   type MediaItem,
 } from "./media-runtime.ts";
 
-// loadWebMedia is imported directly in media-runtime.ts (not via runtime.channel.media)
-// because the channel runtime only exposes fetchRemoteMedia/saveMediaBuffer.
-const loadWebMediaMock = vi.hoisted(() => vi.fn());
-vi.mock("openclaw/plugin-sdk/web-media", () => ({
-  loadWebMedia: loadWebMediaMock,
-}));
-
 describe("inferMediaKindFromMime", () => {
   it("maps image/* to image", () => {
     expect(inferMediaKindFromMime("image/png")).toBe("image");
@@ -99,20 +92,21 @@ describe("uploadOutboundMedia", () => {
     } as unknown as ReturnType<typeof import("./api-client.ts").createOpenclawClawlingApiClient>;
   }
 
-  function setupLoadWebMedia() {
-    loadWebMediaMock.mockResolvedValue({
+  function buildRuntime() {
+    const loadWebMedia = vi.fn().mockResolvedValue({
       buffer: Buffer.from("loaded-bytes"),
       contentType: "image/png",
       fileName: "img.png",
     });
-    return loadWebMediaMock;
+    const runtime = {
+      media: { loadWebMedia },
+    } as unknown as import("openclaw/plugin-sdk/core").PluginRuntime;
+    return { runtime, loadWebMedia };
   }
 
   it("loads each url and uploads", async () => {
-    const loadWebMedia = setupLoadWebMedia();
+    const { runtime, loadWebMedia } = buildRuntime();
     const apiClient = buildApiClient();
-    // runtime is unused for uploadOutboundMedia (loadWebMedia is a direct import)
-    const runtime = {} as unknown as import("openclaw/plugin-sdk/core").PluginRuntime;
     const fragments = await uploadOutboundMedia(["https://cdn/in.png", "https://cdn/in2.png"], {
       apiClient,
       runtime,
@@ -137,11 +131,10 @@ describe("uploadOutboundMedia", () => {
   });
 
   it("drops a single failed upload, returns the rest", async () => {
-    setupLoadWebMedia();
+    const { runtime } = buildRuntime();
     const apiClient = buildApiClient();
     (apiClient.uploadMedia as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error("boom"));
     const log = { info: vi.fn(), error: vi.fn() };
-    const runtime = {} as unknown as import("openclaw/plugin-sdk/core").PluginRuntime;
     const fragments = await uploadOutboundMedia(["https://cdn/a.png", "https://cdn/b.png"], {
       apiClient,
       runtime,
@@ -153,7 +146,7 @@ describe("uploadOutboundMedia", () => {
 
   it("returns empty array for empty input", async () => {
     const apiClient = buildApiClient();
-    const runtime = {} as unknown as import("openclaw/plugin-sdk/core").PluginRuntime;
+    const { runtime } = buildRuntime();
     expect(await uploadOutboundMedia([], { apiClient, runtime })).toEqual([]);
   });
 });

package/src/media-runtime.ts

@@ -1,5 +1,4 @@
 import type { PluginRuntime } from "openclaw/plugin-sdk/core";
-import { loadWebMedia } from "openclaw/plugin-sdk/web-media";
 import type { OpenclawClawlingApiClient } from "./api-client.ts";
 
 /**
@@ -98,8 +97,9 @@ export async function fetchInboundMedia(
  * Upload each URL (remote or local path) to /media/upload via the api
  * client and return a fragment ready to splice into `body.fragments`.
  *
- * Uses `loadWebMedia` from `openclaw/plugin-sdk/web-media` (not the channel
- * runtime media helpers, which only expose fetchRemoteMedia/saveMediaBuffer).
+ * Uses the host runtime's `runtime.media.loadWebMedia`, so local-root
+ * enforcement and media-loading policy stay aligned with the current
+ * OpenClaw runtime instead of a directly imported helper.
  *
  * Single-upload failures log at error and are dropped; the remaining
  * fragments still come back so a partially-failing batch still sends the
@@ -114,7 +114,7 @@ export async function uploadOutboundMedia(
   const out: ClawlingMediaFragment[] = [];
   for (const url of urls) {
     try {
-      const loaded = await loadWebMedia(url, {
+      const loaded = await ctx.runtime.media.loadWebMedia(url, {
         maxBytes,
         ...(ctx.mediaLocalRoots && ctx.mediaLocalRoots.length > 0
           ? { localRoots: ctx.mediaLocalRoots }

package/src/outbound.ts

@@ -1,8 +1,15 @@
 import type { ClawlingChatClient, Envelope, Fragment, MessageAckPayload } from "@newbase-clawchat/sdk";
+import {
+  createAttachedChannelResultAdapter,
+  type ChannelOutboundAdapter,
+} from "openclaw/plugin-sdk/channel-send-result";
+import { chunkMarkdownText } from "openclaw/plugin-sdk/reply-runtime";
 import type { ChatType } from "./client.ts";
-import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
-import type { ClawlingMediaFragment } from "./media-runtime.ts";
+import { createOpenclawClawlingApiClient } from "./api-client.ts";
+import { CHANNEL_ID, resolveOpenclawClawlingAccount, type ResolvedOpenclawClawlingAccount } from "./config.ts";
 import { textToFragments } from "./message-mapper.ts";
+import { uploadOutboundMedia, type ClawlingMediaFragment } from "./media-runtime.ts";
+import { getOpenclawClawlingClient, getOpenclawClawlingRuntime } from "./runtime.ts";
 
 export interface OutboundTarget {
   chatId: string;
@@ -37,6 +44,48 @@ export interface SendResult {
   acceptedAt: number;
 }
 
+/**
+ * Parse an agent-initiated outbound recipient string into the new-protocol
+ * `chat_id` + `chat_type` pair.
+ *
+ * Accepted forms (case-insensitive prefix):
+ *   - `cc:{chat_id}`                  → direct
+ *   - `clawchat:{chat_id}`            → direct
+ *   - `openclaw-clawchat:{chat_id}`   → direct
+ *   - `cc:direct:{chat_id}`           → direct
+ *   - `cc:group:{chat_id}`            → group
+ *   - `clawchat:direct:{chat_id}`     → direct
+ *   - `clawchat:group:{chat_id}`      → group
+ *   - `openclaw-clawchat:direct:{chat_id}` → direct
+ *   - `openclaw-clawchat:group:{chat_id}`  → group
+ *   - bare `{chat_id}`                → direct (backward compat)
+ */
+export function parseOpenclawRecipient(to: string): { chatId: string; chatType: ChatType } {
+  const raw = (to ?? "").trim();
+  if (!raw) throw new Error("openclaw-clawchat: outbound `to` is empty");
+
+  const firstColon = raw.indexOf(":");
+  if (firstColon < 0) return { chatId: raw, chatType: "direct" };
+
+  const scheme = raw.slice(0, firstColon).toLowerCase();
+  const rest = raw.slice(firstColon + 1);
+  if (scheme !== "cc" && scheme !== "clawchat" && scheme !== CHANNEL_ID) {
+    return { chatId: raw, chatType: "direct" };
+  }
+
+  const secondColon = rest.indexOf(":");
+  if (secondColon >= 0) {
+    const typeToken = rest.slice(0, secondColon).toLowerCase();
+    const chatId = rest.slice(secondColon + 1).trim();
+    if ((typeToken === "direct" || typeToken === "group") && chatId) {
+      return { chatId, chatType: typeToken };
+    }
+  }
+  const chatId = rest.trim();
+  if (!chatId) throw new Error(`openclaw-clawchat: missing chat_id in "${to}"`);
+  return { chatId, chatType: "direct" };
+}
+
 export async function sendOpenclawClawlingText(params: SendParams): Promise<SendResult | null> {
   const text = (params.text ?? "").trim();
   const mediaFragments = params.mediaFragments ?? [];
@@ -139,3 +188,65 @@ export async function sendOpenclawClawlingMedia(
     ...(params.log ? { log: params.log } : {}),
   });
 }
+
+export const openclawClawlingOutbound: ChannelOutboundAdapter = {
+  deliveryMode: "direct",
+  chunker: (text, limit) => chunkMarkdownText(text, limit),
+  chunkerMode: "markdown",
+  textChunkLimit: 4000,
+  ...createAttachedChannelResultAdapter({
+    channel: CHANNEL_ID,
+    sendText: async ({ cfg, to, text }) => {
+      const account = resolveOpenclawClawlingAccount(cfg);
+      const client = getOpenclawClawlingClient(account.accountId);
+      if (!client) {
+        throw new Error(`openclaw-clawchat client not running for account ${account.accountId}`);
+      }
+      const result = await sendOpenclawClawlingText({
+        client,
+        account,
+        to: parseOpenclawRecipient(to),
+        text,
+      });
+      return {
+        to,
+        messageId: result?.messageId ?? `${account.userId}-${Date.now()}`,
+      };
+    },
+    sendMedia: async ({ cfg, to, text, mediaUrl, mediaLocalRoots }) => {
+      const account = resolveOpenclawClawlingAccount(cfg);
+      const client = getOpenclawClawlingClient(account.accountId);
+      if (!client) {
+        throw new Error(`openclaw-clawchat client not running for account ${account.accountId}`);
+      }
+      if (!mediaUrl?.trim()) {
+        throw new Error("openclaw-clawchat sendMedia requires mediaUrl");
+      }
+      const runtime = getOpenclawClawlingRuntime();
+      const apiClient = createOpenclawClawlingApiClient({
+        baseUrl: account.baseUrl,
+        token: account.token,
+        userId: account.userId,
+      });
+      const mediaFragments = await uploadOutboundMedia([mediaUrl.trim()], {
+        apiClient,
+        runtime,
+        ...(mediaLocalRoots ? { mediaLocalRoots } : {}),
+      });
+      if (mediaFragments.length === 0) {
+        throw new Error(`openclaw-clawchat failed to upload media: ${mediaUrl}`);
+      }
+      const result = await sendOpenclawClawlingMedia({
+        client,
+        account,
+        to: parseOpenclawRecipient(to),
+        text,
+        mediaFragments,
+      });
+      return {
+        to,
+        messageId: result?.messageId ?? `${account.userId}-${Date.now()}`,
+      };
+    },
+  }),
+};

package/src/protocol.test.ts

@@ -36,7 +36,9 @@ describe("openclaw-clawchat protocol guards", () => {
 
   it("detects renderable text", () => {
     expect(hasRenderableText({ body: { fragments: [{ kind: "text", text: "hi" }] } })).toBe(true);
-    expect(hasRenderableText({ body: { fragments: [{ kind: "image", url: "x" }] } })).toBe(false);
+    expect(hasRenderableText({ body: { fragments: [{ kind: "image", url: "x" }] } })).toBe(true);
+    expect(hasRenderableText({ body: { fragments: [{ kind: "file", url: "x" }] } })).toBe(true);
     expect(hasRenderableText({ body: { fragments: [{ kind: "text", text: "  " }] } })).toBe(false);
+    expect(hasRenderableText({ body: { fragments: [{ kind: "image" }] } })).toBe(false);
   });
 });

package/src/protocol.ts

@@ -31,8 +31,12 @@ export function hasRenderableText(message: {
   const fragments = message?.body?.fragments ?? [];
   return fragments.some(
     (f) =>
-      (f as { kind?: string }).kind === "text" &&
-      typeof (f as { text?: unknown }).text === "string" &&
-      (f as { text: string }).text.trim().length > 0,
+      (((f as { kind?: string }).kind === "text" &&
+        typeof (f as { text?: unknown }).text === "string" &&
+        (f as { text: string }).text.trim().length > 0) ||
+        (typeof (f as { kind?: unknown }).kind === "string" &&
+          ["image", "file", "audio", "video"].includes((f as { kind: string }).kind) &&
+          typeof (f as { url?: unknown }).url === "string" &&
+          (f as { url: string }).url.trim().length > 0)),
   );
 }

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,152 @@ 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");
   });
 });
 

package/src/runtime.ts

@@ -80,6 +80,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;
@@ -152,7 +156,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 +166,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,12 +238,14 @@ 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(",")}]`,
         );
+        const dispatchResult = await rt.reply.withReplyDispatcher({
+          dispatcher,
+          onSettled: () => markDispatchIdle(),
+          run: () =>
+            rt.reply.dispatchReplyFromConfig({ ctx: ctxPayload, cfg, dispatcher, replyOptions }),
+        });
         try {
-          const dispatchResult = await rt.reply.withReplyDispatcher({
-            dispatcher,
-            run: () =>
-              rt.reply.dispatchReplyFromConfig({ ctx: ctxPayload, cfg, dispatcher, replyOptions }),
-          });
+          
           const counts = (dispatchResult as { counts?: Record<string, number> } | undefined)?.counts ?? {};
           const queuedFinal = Boolean(
             (dispatchResult as { queuedFinal?: boolean } | undefined)?.queuedFinal,
@@ -255,8 +265,6 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
             `[${accountId}] openclaw-clawchat dispatch failed msg=${turn.messageId}: ${String(err)}`,
           );
           throw err;
-        } finally {
-          markDispatchIdle();
         }
       },
     }).catch((err) => {

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)",
   );
 }