@newbase-clawchat/openclaw-clawchat 2026.4.15

package/src/streaming.test.ts

@@ -0,0 +1,116 @@
+import type { ClawlingChatClient } from "@newbase-clawchat/sdk";
+import { describe, expect, it, vi } from "vitest";
+import { sendStreamingText } from "./streaming.ts";
+
+type EmittedEnvelope = { event: string; payload: Record<string, unknown>; to: unknown };
+
+function mockClient() {
+  const sent: EmittedEnvelope[] = [];
+  const client = {
+    emitRaw: vi.fn(
+      (event: string, payload: Record<string, unknown>, routing?: { to?: unknown }) => {
+        sent.push({ event, payload, to: routing?.to });
+      },
+    ),
+    typing: vi.fn(),
+  } as unknown as ClawlingChatClient;
+  return { client, sent };
+}
+
+describe("openclaw-clawchat streaming", () => {
+  it("emits typing(true) -> created -> N x add -> done -> typing(false)", async () => {
+    const { client, sent } = mockClient();
+    await sendStreamingText({
+      client,
+      to: { id: "u1", type: "direct" },
+      sender: { sender_id: "a1", type: "direct", display_name: "Clawling" },
+      chunks: ["Hel", "lo ", "world"],
+      messageId: "m1",
+    });
+
+    const events = sent.map((e) => e.event);
+    expect(events).toEqual([
+      "message.created",
+      "message.add",
+      "message.add",
+      "message.add",
+      "message.done",
+    ]);
+    expect((client.typing as ReturnType<typeof vi.fn>).mock.calls).toEqual([
+      [{ id: "u1", type: "direct" }, true],
+      [{ id: "u1", type: "direct" }, false],
+    ]);
+  });
+
+  it("message.created payload is minimal (just message_id); adds carry monotonic sequences", async () => {
+    const { client, sent } = mockClient();
+    await sendStreamingText({
+      client,
+      to: { id: "u1", type: "direct" },
+      sender: { sender_id: "a1", type: "direct", display_name: "Clawling" },
+      chunks: ["a", "b", "c"],
+      messageId: "m1",
+    });
+
+    // created payload is { message_id } only — no embedded message / streaming.
+    expect(sent[0]!.payload).toEqual({ message_id: "m1" });
+    expect(sent[1]!.payload.sequence).toBe(1);
+    expect(sent[2]!.payload.sequence).toBe(2);
+    expect(sent[3]!.payload.sequence).toBe(3);
+    expect((sent[4]!.payload.streaming as { sequence: number }).sequence).toBe(3);
+  });
+
+  it("each message.add carries fragments: [{ text: cumulative, delta: new }]", async () => {
+    const { client, sent } = mockClient();
+    await sendStreamingText({
+      client,
+      to: { id: "u1", type: "direct" },
+      sender: { sender_id: "a1", type: "direct", display_name: "Clawling" },
+      chunks: ["Hel", "lo ", "world"],
+      messageId: "m1",
+    });
+
+    const adds = sent.filter((s) => s.event === "message.add");
+    expect(adds).toHaveLength(3);
+    expect((adds[0]!.payload as { fragments: unknown }).fragments).toEqual([
+      { kind: "text", text: "Hel", delta: "Hel" },
+    ]);
+    expect((adds[1]!.payload as { fragments: unknown }).fragments).toEqual([
+      { kind: "text", text: "Hello ", delta: "lo " },
+    ]);
+    expect((adds[2]!.payload as { fragments: unknown }).fragments).toEqual([
+      { kind: "text", text: "Hello world", delta: "world" },
+    ]);
+  });
+
+  it("handles zero-chunk input by going created -> done immediately", async () => {
+    const { client, sent } = mockClient();
+    await sendStreamingText({
+      client,
+      to: { id: "u1", type: "direct" },
+      sender: { sender_id: "a1", type: "direct", display_name: "Clawling" },
+      chunks: [],
+      messageId: "m1",
+    });
+    const events = sent.map((e) => e.event);
+    expect(events).toEqual(["message.created", "message.done"]);
+  });
+
+  it("sendStreamingFailure emits failed with reason and typing(false)", async () => {
+    const { client, sent } = mockClient();
+    const { sendStreamingFailure } = await import("./streaming.ts");
+    await sendStreamingFailure({
+      client,
+      to: { id: "u1", type: "direct" },
+      messageId: "m1",
+      currentSequence: 2,
+      reason: "boom",
+    });
+    expect(sent[0]!.event).toBe("message.failed");
+    expect(sent[0]!.payload.sequence).toBe(3);
+    expect(sent[0]!.payload.reason).toBe("boom");
+    expect((client.typing as ReturnType<typeof vi.fn>).mock.calls).toEqual([
+      [{ id: "u1", type: "direct" }, false],
+    ]);
+  });
+});

package/src/streaming.ts

@@ -0,0 +1,89 @@
+import type { ClawlingChatClient } from "@newbase-clawchat/sdk";
+import {
+  emitStreamAdd,
+  emitStreamCreated,
+  emitStreamDone,
+  emitStreamFailed,
+  type EnvelopeRouting,
+  type StreamSender,
+} from "./client.ts";
+
+export interface StreamingSendParams {
+  client: ClawlingChatClient;
+  routing: EnvelopeRouting;
+  sender: StreamSender;
+  /**
+   * Pre-chunked text. Use `chunkMarkdownText` from
+   * `openclaw/plugin-sdk/reply-runtime` to produce these.
+   */
+  chunks: string[];
+  messageId: string;
+  /** Emit typing.update(true/false) around the lifecycle. Default true. */
+  emitTyping?: boolean;
+}
+
+/**
+ * Emit one full streaming lifecycle for a pre-chunked reply.
+ *
+ * Sequence:
+ *   typing(true)
+ *   message.created   (sequence 0)
+ *   message.add       (sequence 1..N, one per chunk)
+ *   message.done      (sequence N)
+ *   typing(false)
+ *
+ * With zero chunks: typing(true) -> created -> done -> typing(false).
+ */
+export async function sendStreamingText(params: StreamingSendParams): Promise<void> {
+  const emitTyping = params.emitTyping !== false;
+  if (emitTyping) {
+    params.client.typing(params.routing.chatId, true, params.routing.chatType);
+  }
+  emitStreamCreated(params.client, {
+    messageId: params.messageId,
+    routing: params.routing,
+  });
+  let sequence = 0;
+  let fullText = "";
+  for (const chunk of params.chunks) {
+    sequence += 1;
+    fullText += chunk;
+    emitStreamAdd(params.client, {
+      messageId: params.messageId,
+      routing: params.routing,
+      sequence,
+      fullText,
+      textDelta: chunk,
+    });
+  }
+  emitStreamDone(params.client, {
+    messageId: params.messageId,
+    routing: params.routing,
+    finalSequence: sequence,
+    finalText: fullText,
+  });
+  if (emitTyping) {
+    params.client.typing(params.routing.chatId, false, params.routing.chatType);
+  }
+}
+
+export interface StreamingFailureParams {
+  client: ClawlingChatClient;
+  routing: EnvelopeRouting;
+  messageId: string;
+  currentSequence: number;
+  reason?: string;
+  emitTyping?: boolean;
+}
+
+export async function sendStreamingFailure(params: StreamingFailureParams): Promise<void> {
+  emitStreamFailed(params.client, {
+    messageId: params.messageId,
+    routing: params.routing,
+    sequence: params.currentSequence + 1,
+    reason: params.reason,
+  });
+  if (params.emitTyping !== false) {
+    params.client.typing(params.routing.chatId, false, params.routing.chatType);
+  }
+}

package/src/tools-schema.ts

@@ -0,0 +1,45 @@
+import { Type, type Static } from "@sinclair/typebox";
+
+export const ClawchatGetMyProfileSchema = Type.Object({});
+export type ClawchatGetMyProfileParams = Static<typeof ClawchatGetMyProfileSchema>;
+
+export const ClawchatGetUserInfoSchema = Type.Object({
+  userId: Type.String({ description: "Target user id (required)" }),
+});
+export type ClawchatGetUserInfoParams = Static<typeof ClawchatGetUserInfoSchema>;
+
+export const ClawchatListFriendsSchema = Type.Object({
+  page: Type.Optional(Type.Integer({ minimum: 1, description: "1-based page number (default 1)" })),
+  pageSize: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: 100,
+      description: "Page size 1..100 (default 20)",
+    }),
+  ),
+});
+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)" }),
+  ),
+});
+export type ClawchatUpdateMyProfileParams = Static<typeof ClawchatUpdateMyProfileSchema>;
+
+export const ClawchatUploadFileSchema = Type.Object({
+  filePath: Type.String({
+    description: "Absolute local path of the file to upload (max 20MB)",
+  }),
+});
+export type ClawchatUploadFileParams = Static<typeof ClawchatUploadFileSchema>;
+
+export const ClawchatActivateSchema = Type.Object({
+  code: Type.String({
+    description:
+      "The invite code (e.g. 'INV-ABC123') extracted from the user's message. " +
+      "Whitespace is trimmed automatically.",
+  }),
+});
+export type ClawchatActivateParams = Static<typeof ClawchatActivateSchema>;

package/src/tools.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, it, vi } from "vitest";
+import { registerOpenclawClawlingTools } from "./tools.ts";
+
+interface RegisteredTool {
+  name: string;
+  execute: (callId: string, params: unknown) => Promise<unknown>;
+}
+
+function buildApi(opts: {
+  configChannel?: Record<string, unknown> | null;
+  registerTool?: (tool: { name: string }, options?: { name: string }) => void;
+}) {
+  const registered: RegisteredTool[] = [];
+  const api = {
+    config:
+      opts.configChannel === null
+        ? undefined
+        : { channels: { "openclaw-clawchat": opts.configChannel ?? {} } },
+    logger: {
+      info: vi.fn(),
+      debug: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    },
+    registerTool: (tool: RegisteredTool, _options?: { name: string }) => {
+      registered.push(tool);
+    },
+  } as unknown as Parameters<typeof registerOpenclawClawlingTools>[0];
+  return { api, registered };
+}
+
+function configuredChannel(extra: Record<string, unknown> = {}) {
+  return {
+    websocketUrl: "wss://w",
+    token: "tk",
+    userId: "u",
+    ...extra,
+  };
+}
+
+describe("registerOpenclawClawlingTools", () => {
+  it("registers ONLY clawchat_activate when account.configured is false (onboarding path)", () => {
+    const { api, registered } = buildApi({
+      configChannel: { websocketUrl: "wss://w" /* token / userId missing */ },
+    });
+    registerOpenclawClawlingTools(api);
+    // clawchat_activate must be available before a token exists — it's the
+    // tool the agent calls to onboard.
+    expect(registered.map((t) => t.name)).toEqual(["clawchat_activate"]);
+  });
+
+  it("skips registration when api.config is undefined", () => {
+    const { api, registered } = buildApi({ configChannel: null });
+    registerOpenclawClawlingTools(api);
+    expect(registered).toHaveLength(0);
+  });
+
+  it("registers all six tools when configured (regardless of baseUrl)", () => {
+    const { api, registered } = buildApi({
+      configChannel: configuredChannel(/* no baseUrl */),
+    });
+    registerOpenclawClawlingTools(api);
+    const names = registered.map((t) => t.name).sort();
+    expect(names).toEqual([
+      "clawchat_activate",
+      "clawchat_get_my_profile",
+      "clawchat_get_user_info",
+      "clawchat_list_friends",
+      "clawchat_update_my_profile",
+      "clawchat_upload_file",
+    ]);
+  });
+
+  it("clawchat_activate description names the `clawchat <code>` trigger", () => {
+    const { api, registered } = buildApi({
+      configChannel: configuredChannel(),
+    });
+    // Re-capture full tool objects so we can see description.
+    const fullTools: Array<{ name: string; description?: string }> = [];
+    api.registerTool = (tool: { name: string; description?: string }) => {
+      fullTools.push(tool);
+    };
+    registerOpenclawClawlingTools(api);
+    const activate = fullTools.find((t) => t.name === "clawchat_activate")!;
+    expect(activate).toBeDefined();
+    // Must tell the LLM exactly how to spot + parse the trigger.
+    expect(activate.description).toMatch(/clawchat\s*<code>/i);
+    expect(activate.description).toMatch(/INV-/);
+    // Must spell out the verbatim-extraction rule so the model doesn't
+    // re-case / prefix the code.
+    expect(activate.description).toMatch(/verbatim/i);
+  });
+
+  it("clawchat_update_my_profile description names name + avatar triggers (EN + ZH)", () => {
+    const { api } = buildApi({ configChannel: configuredChannel() });
+    const fullTools: Array<{ name: string; description?: string }> = [];
+    api.registerTool = (tool: { name: string; description?: string }) => {
+      fullTools.push(tool);
+    };
+    registerOpenclawClawlingTools(api);
+    const update = fullTools.find((t) => t.name === "clawchat_update_my_profile")!;
+    expect(update).toBeDefined();
+    expect(update.description).toMatch(/change your name/i);
+    expect(update.description).toMatch(/你叫/);
+    expect(update.description).toMatch(/avatar/i);
+    expect(update.description).toMatch(/生成头像|换个头像/);
+  });
+
+
+  it("clawchat_upload_file rejects oversized files before upload", async () => {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const os = await import("node:os");
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-clawchat-"));
+    const big = path.join(tmp, "big.bin");
+    // create a sparse 21MB file (we never read it; size check fires first)
+    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_file")!;
+      const result = await tool.execute("call-1", { filePath: big });
+      const text = (result as { content: { text: string }[] }).content[0]!.text;
+      const parsed = JSON.parse(text) as { error?: string; message?: string };
+      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

@@ -0,0 +1,308 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/feishu";
+import { createOpenclawClawlingApiClient } from "./api-client.ts";
+import { ClawlingApiError, type Profile } from "./api-types.ts";
+import { resolveOpenclawClawlingAccount } from "./config.ts";
+import {
+  ClawchatActivateSchema,
+  ClawchatGetMyProfileSchema,
+  ClawchatGetUserInfoSchema,
+  ClawchatListFriendsSchema,
+  ClawchatUpdateMyProfileSchema,
+  ClawchatUploadFileSchema,
+  type ClawchatActivateParams,
+  type ClawchatGetUserInfoParams,
+  type ClawchatListFriendsParams,
+  type ClawchatUpdateMyProfileParams,
+  type ClawchatUploadFileParams,
+} from "./tools-schema.ts";
+
+const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
+
+function jsonResponse(data: unknown): AgentToolResult<unknown> {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+function configError(message: string) {
+  return jsonResponse({ error: "config", message });
+}
+
+function apiError(err: ClawlingApiError) {
+  return jsonResponse({
+    error: err.kind,
+    message: err.message,
+    ...(err.meta ? { meta: err.meta } : {}),
+  });
+}
+
+function validationError(message: string) {
+  return jsonResponse({ error: "validation", message });
+}
+
+function genericError(err: unknown) {
+  return jsonResponse({
+    error: "unknown",
+    message: err instanceof Error ? err.message : String(err),
+  });
+}
+
+const MIME_BY_EXT: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".bmp": "image/bmp",
+  ".svg": "image/svg+xml",
+  ".pdf": "application/pdf",
+  ".txt": "text/plain",
+  ".md": "text/markdown",
+  ".json": "application/json",
+  ".csv": "text/csv",
+  ".zip": "application/zip",
+  ".mp3": "audio/mpeg",
+  ".m4a": "audio/mp4",
+  ".wav": "audio/wav",
+  ".ogg": "audio/ogg",
+  ".mp4": "video/mp4",
+  ".mov": "video/quicktime",
+  ".webm": "video/webm",
+};
+
+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 {
+  if (!api.config) {
+    api.logger.debug?.("openclaw-clawchat: api.config missing; skipping tool registration");
+    return;
+  }
+
+  // -----------------------------------------------------------------------
+  // `clawchat_activate` is registered UNCONDITIONALLY — it is the tool the
+  // agent invokes to onboard this plugin, so it must be available even when
+  // `account.configured === false`. All other tools below require a valid
+  // token and are gated on `account.configured`.
+  // -----------------------------------------------------------------------
+  api.registerTool(
+    {
+      name: "clawchat_activate",
+      label: "Clawling: Activate (Login with Invite Code)",
+      description:
+        "Activate this agent on ClawChat by exchanging an invite code for a token. " +
+        "TRIGGER — invoke this tool whenever the user's message matches ANY of: " +
+        "(1) the pattern `clawchat <code>` or `clawchat: <code>` — e.g. 'clawchat INV-ABC123' " +
+        "means: call this tool with `code = \"INV-ABC123\"`; " +
+        "(2) phrases like 'activate clawchat', 'login to clawchat', 'use invite code XYZ', " +
+        "'connect clawchat with XYZ'; " +
+        "(3) the user pastes anything that looks like an invite code (e.g. `INV-…`, `CC-…`). " +
+        "Extract the code verbatim — do NOT normalize / lowercase / add prefixes. " +
+        "On success the tool persists the resulting token + userId to the config, so " +
+        "subsequent `clawchat_*` calls work without any other setup.",
+      parameters: ClawchatActivateSchema,
+      async execute(_callId, params) {
+        const p = params as ClawchatActivateParams;
+        const code = p.code?.trim();
+        if (!code) {
+          return validationError("openclaw-clawchat: code is required");
+        }
+        try {
+          const { runOpenclawClawlingLogin } = await import("./login.runtime.ts");
+          await runOpenclawClawlingLogin({
+            cfg: api.config!,
+            accountId: null,
+            runtime: { log: (message: string) => api.logger.info?.(message) },
+            readInviteCode: async () => code,
+          });
+          return jsonResponse({
+            ok: true,
+            message: "ClawChat activated successfully. Need to Restart Gateway for changes to take effect. You can now use clawchat_* tools.",
+          });
+        } catch (err) {
+          if (err instanceof ClawlingApiError) return apiError(err);
+          return genericError(err);
+        }
+      },
+    },
+    { name: "clawchat_activate" },
+  );
+
+  const account = resolveOpenclawClawlingAccount(api.config);
+  if (!account.configured) {
+    api.logger.debug?.(
+      "openclaw-clawchat: account not yet configured; only clawchat_activate is registered. " +
+        "The remaining tools will register on the next config reload after activation.",
+    );
+    return;
+  }
+
+  // Re-resolve at call time so config reloads pick up new tokens / baseUrl.
+  function resolveCurrent() {
+    return resolveOpenclawClawlingAccount(api.config!);
+  }
+
+  type ClientResult =
+    | { error: AgentToolResult<unknown>; client?: never }
+    | { client: ReturnType<typeof createOpenclawClawlingApiClient>; error?: never };
+
+  function buildClient(): ClientResult {
+    const acct = resolveCurrent();
+    // `baseUrl` always resolves via the built-in default in config.ts, so we
+    // only need to gate on `token` here (which is populated by `openclaw
+    // channel login`).
+    if (!acct.token) {
+      return { error: configError("openclaw-clawchat: token is required") };
+    }
+    return {
+      client: createOpenclawClawlingApiClient({
+        baseUrl: acct.baseUrl,
+        token: acct.token,
+        userId: acct.userId,
+      }),
+    };
+  }
+
+  function withClient<T>(
+    fn: (client: ReturnType<typeof createOpenclawClawlingApiClient>) => Promise<T>,
+  ): Promise<AgentToolResult<unknown>> {
+    return (async (): Promise<AgentToolResult<unknown>> => {
+      const built = buildClient();
+      if (built.error !== undefined) return built.error;
+      try {
+        const data = await fn(built.client);
+        return jsonResponse(data);
+      } catch (err) {
+        if (err instanceof ClawlingApiError) return apiError(err);
+        return genericError(err);
+      }
+    })();
+  }
+
+  api.registerTool(
+    {
+      name: "clawchat_get_my_profile",
+      label: "Clawling: Get My Profile",
+      description: "Fetch the agent's own Clawling profile (id, display name, avatar, bio).",
+      parameters: ClawchatGetMyProfileSchema,
+      async execute(_callId, _params) {
+        return await withClient((c) => c.getMyProfile());
+      },
+    },
+    { name: "clawchat_get_my_profile" },
+  );
+
+  api.registerTool(
+    {
+      name: "clawchat_get_user_info",
+      label: "Clawling: Get User Info",
+      description: "Fetch a Clawling user's public profile by userId.",
+      parameters: ClawchatGetUserInfoSchema,
+      async execute(_callId, params) {
+        const p = params as ClawchatGetUserInfoParams;
+        return await withClient((c) => c.getUserInfo(p.userId));
+      },
+    },
+    { name: "clawchat_get_user_info" },
+  );
+
+  api.registerTool(
+    {
+      name: "clawchat_list_friends",
+      label: "Clawling: List Friends",
+      description: "List the agent's friends, paginated (page=1, pageSize=20 by default).",
+      parameters: ClawchatListFriendsSchema,
+      async execute(_callId, params) {
+        const p = (params ?? {}) as ClawchatListFriendsParams;
+        return await withClient((c) =>
+          c.listFriends({
+            ...(p.page !== undefined ? { page: p.page } : { page: 1 }),
+            ...(p.pageSize !== undefined ? { pageSize: p.pageSize } : { pageSize: 20 }),
+          }),
+        );
+      },
+    },
+    { name: "clawchat_list_friends" },
+  );
+
+  api.registerTool(
+    {
+      name: "clawchat_update_my_profile",
+      label: "Clawling: Update My Profile",
+      description:
+        "Update this agent's own ClawChat profile (nickname and/or avatar). " +
+        "TRIGGER — invoke this tool whenever the user's message matches ANY of: " +
+        "(1) nickname/name change: 'change your name to X', 'your name is X', 'rename yourself to X', " +
+        "'I'll call you X', 'from now on you are X', '你叫 X', '改名为 X', '我叫你 X', " +
+        "'你的新名字是 X' → call with `nickname = X`; " +
+        "(2) avatar change or generation: 'change your avatar', 'update your profile picture', " +
+        "'generate a new avatar', 'use this image as your avatar', '换个头像', '生成头像', " +
+        "'把头像改为 …' → first obtain the avatar URL (generate + upload via " +
+        "`clawchat_upload_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.",
+      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;
+        if (Object.keys(patch).length === 0) {
+          return validationError(
+            "openclaw-clawchat: at least one of nickname / avatar is required",
+          );
+        }
+        return await withClient((c): Promise<Profile> => c.updateMyProfile(patch));
+      },
+    },
+    { name: "clawchat_update_my_profile" },
+  );
+
+  api.registerTool(
+    {
+      name: "clawchat_upload_file",
+      label: "Clawling: Upload File",
+      description:
+        "Upload a local file to Clawling media storage (max 20MB) and return the public URL.",
+      parameters: ClawchatUploadFileSchema,
+      async execute(_callId, params) {
+        const p = params as ClawchatUploadFileParams;
+        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_file" },
+  );
+
+  api.logger.info?.(
+    "openclaw-clawchat: registered 6 clawchat_* tools (activate, get_my_profile, get_user_info, list_friends, update_my_profile, upload_file)",
+  );
+}