@newbase-clawchat/openclaw-clawchat 2026.4.29 → 2026.5.4

package/dist/src/runtime.js

@@ -0,0 +1,288 @@
+import { AckTimeoutError, AuthError, ProtocolError, StateError, TransportError, } from "@newbase-clawchat/sdk";
+import { waitUntilAbort } from "openclaw/plugin-sdk/channel-lifecycle";
+import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
+import { createOpenclawClawlingClient } from "./client.js";
+import { CHANNEL_ID } from "./config.js";
+import { dispatchOpenclawClawlingInbound } from "./inbound.js";
+import { fetchInboundMedia } from "./media-runtime.js";
+import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.js";
+import { sendStreamingText } from "./streaming.js";
+import { sendOpenclawClawlingText } from "./outbound.js";
+const { setRuntime: setOpenclawClawlingRuntime, getRuntime: getOpenclawClawlingRuntime } = createPluginRuntimeStore("openclaw-clawchat runtime not initialized");
+export { setOpenclawClawlingRuntime, getOpenclawClawlingRuntime };
+const activeClients = new Map();
+export function getOpenclawClawlingClient(accountId) {
+    return activeClients.get(accountId);
+}
+export async function waitForOpenclawClawlingClient(accountId, options = {}) {
+    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.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 function mapClawlingStateToStatus(state) {
+    const now = Date.now();
+    switch (state) {
+        case "connected":
+            return { connected: true, running: true, lastStartAt: now };
+        case "reconnecting":
+            return { connected: false, running: true };
+        case "disconnected":
+            return { connected: false, running: false, lastStopAt: now };
+        default:
+            return { connected: false, running: true };
+    }
+}
+export function classifyClawlingClientError(err) {
+    if (err instanceof AuthError)
+        return { kind: "auth", retry: false, message: err.message };
+    if (err instanceof TransportError)
+        return { kind: "transport", retry: true, message: err.message };
+    if (err instanceof AckTimeoutError)
+        return { kind: "ack-timeout", retry: false, message: err.message };
+    if (err instanceof ProtocolError)
+        return { kind: "protocol", retry: false, message: err.message };
+    if (err instanceof StateError)
+        return { kind: "state", retry: false, message: err.message };
+    return {
+        kind: "unknown",
+        retry: false,
+        message: err instanceof Error ? err.message : String(err),
+    };
+}
+function formatConversationSubject(peer) {
+    return peer.kind === "group" ? `group:${peer.id}` : peer.id;
+}
+function withClawChatSessionScope(cfg) {
+    return {
+        ...cfg,
+        session: {
+            ...(cfg.session ?? {}),
+            dmScope: "per-account-channel-peer",
+        },
+    };
+}
+export async function startOpenclawClawlingGateway(params) {
+    const { cfg, account, abortSignal, setStatus, getStatus, log } = params;
+    // Obtain PluginRuntime from the stored runtime set via setOpenclawClawlingRuntime.
+    const runtime = getOpenclawClawlingRuntime();
+    const accountId = account.accountId;
+    const client = createOpenclawClawlingClient(account, {
+        ...(params.transport ? { transport: params.transport } : {}),
+    });
+    client.on("state", ({ from, to }) => {
+        log?.info?.(`[${accountId}] openclaw-clawchat state ${from} -> ${to}`);
+        const next = { ...getStatus(), ...mapClawlingStateToStatus(to) };
+        setStatus(next);
+    });
+    client.on("error", (err) => {
+        const classified = classifyClawlingClientError(err);
+        if (classified.kind === "auth") {
+            log?.error?.(`[${accountId}] openclaw-clawchat auth failed: ${classified.message}`);
+            setStatus({
+                ...getStatus(),
+                connected: false,
+                configured: false,
+                running: false,
+                lastError: classified.message,
+            });
+        }
+        else if (classified.kind === "transport") {
+            log?.info?.(`[${accountId}] openclaw-clawchat transport error (reconnecting): ${classified.message}`);
+            setStatus({ ...getStatus(), connected: false, running: true });
+        }
+        else if (classified.kind === "ack-timeout") {
+            log?.info?.(`[${accountId}] openclaw-clawchat ack timeout: ${classified.message}`);
+        }
+        else if (classified.kind === "protocol") {
+            log?.error?.(`[${accountId}] openclaw-clawchat protocol error: ${classified.message}`);
+        }
+        else if (classified.kind === "state") {
+            log?.info?.(`[${accountId}] openclaw-clawchat state error: ${classified.message}`);
+        }
+        else {
+            log?.error?.(`[${accountId}] openclaw-clawchat sdk error: ${classified.message}`);
+        }
+    });
+    client.on("message", async (env) => {
+        try {
+            await dispatchOpenclawClawlingInbound({
+                envelope: env,
+                cfg,
+                runtime,
+                account,
+                log,
+                ingest: async (turn) => {
+                    const rt = runtime.channel;
+                    const storePath = rt.session.resolveStorePath(cfg.session?.store);
+                    const routeCfg = withClawChatSessionScope(cfg);
+                    const route = rt.routing.resolveAgentRoute({
+                        cfg: routeCfg,
+                        channel: CHANNEL_ID,
+                        accountId,
+                        peer: turn.peer,
+                    });
+                    const body = rt.reply.formatAgentEnvelope({
+                        channel: "Clawling Chat",
+                        from: formatConversationSubject(turn.peer),
+                        body: turn.rawBody,
+                        timestamp: turn.timestamp,
+                        ...rt.reply.resolveEnvelopeFormatOptions(cfg),
+                    });
+                    const ctxPayload = rt.reply.finalizeInboundContext({
+                        Body: body,
+                        BodyForAgent: turn.rawBody,
+                        RawBody: turn.rawBody,
+                        CommandBody: turn.rawBody,
+                        // 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: formatConversationSubject(turn.peer),
+                        SenderId: turn.senderId,
+                        Provider: CHANNEL_ID,
+                        Surface: CHANNEL_ID,
+                        MessageSid: turn.messageId,
+                        MessageSidFull: turn.messageId,
+                        Timestamp: turn.timestamp,
+                        OriginatingChannel: CHANNEL_ID,
+                        OriginatingTo: `${CHANNEL_ID}:${account.userId}`,
+                    });
+                    // Fetch any inbound media attachments and populate MediaPath/MediaPaths in context.
+                    const inboundPaths = turn.mediaItems.length > 0
+                        ? await fetchInboundMedia(turn.mediaItems, {
+                            runtime,
+                            log,
+                            maxBytes: 20 * 1024 * 1024,
+                        })
+                        : [];
+                    if (inboundPaths.length > 0) {
+                        ctxPayload.MediaPath = inboundPaths[0];
+                        ctxPayload.MediaPaths = inboundPaths;
+                    }
+                    try {
+                        await rt.session.recordInboundSession({
+                            storePath,
+                            sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+                            ctx: ctxPayload,
+                            onRecordError: (err) => {
+                                log?.error?.(`[${accountId}] openclaw-clawchat failed to record inbound session: ${String(err)}`);
+                            },
+                        });
+                    }
+                    catch (err) {
+                        log?.error?.(`[${accountId}] openclaw-clawchat failed to record inbound session: ${String(err)}`);
+                    }
+                    const replyCtx = turn.replyCtx;
+                    const { dispatcher, replyOptions, markDispatchIdle } = createOpenclawClawlingReplyDispatcher({
+                        cfg,
+                        runtime,
+                        account,
+                        client,
+                        target: { chatId: turn.peer.id, chatType: turn.peer.kind },
+                        ...(replyCtx ? { replyCtx } : {}),
+                        inboundMessageId: turn.messageId,
+                        inboundForFinalReply: {
+                            chatId: turn.peer.id,
+                            senderId: turn.senderId,
+                            senderNickName: turn.senderNickName || turn.senderId,
+                            bodyText: turn.rawBody,
+                        },
+                        log,
+                    });
+                    const agentsConfigured = Object.keys(cfg.agents ?? {});
+                    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 }),
+                        });
+                        const counts = dispatchResult?.counts ?? {};
+                        const queuedFinal = Boolean(dispatchResult?.queuedFinal);
+                        log?.info?.(`[${accountId}] openclaw-clawchat dispatch complete msg=${turn.messageId} queuedFinal=${queuedFinal} counts=${JSON.stringify(counts)}`);
+                        if (!queuedFinal && Object.values(counts).every((n) => !n)) {
+                            log?.info?.(`[${accountId}] openclaw-clawchat NO reply was produced (no final / block / tool dispatched). ` +
+                                `Likely causes: agent='${route.agentId}' not configured in cfg.agents (configured: [${agentsConfigured.join(",")}]); ` +
+                                `or send-policy denied; or a plugin claimed the binding.`);
+                        }
+                    }
+                    catch (err) {
+                        log?.error?.(`[${accountId}] openclaw-clawchat dispatch failed msg=${turn.messageId}: ${String(err)}`);
+                        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) {
+            log?.error?.(`[${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`
+    // (auth). Transport failures (server unreachable, DNS error, etc.) do
+    // NOT reject this promise — the SDK catches them internally and drives
+    // its own exponential-backoff reconnect loop (`initialDelay * 2^attempt`
+    // capped at `maxDelay`, with jitter). So we never throw here on anything
+    // other than auth failure; on auth we tear the account down cleanly and
+    // return without throwing (which would make the gateway supervisor
+    // restart us immediately in a tight loop).
+    try {
+        await client.connect();
+    }
+    catch (err) {
+        const classified = classifyClawlingClientError(err);
+        setStatus({
+            ...getStatus(),
+            connected: false,
+            configured: classified.kind !== "auth",
+            running: false,
+            lastError: classified.message,
+        });
+        log?.error?.(`[${accountId}] openclaw-clawchat connect failed (${classified.kind}): ${classified.message}`);
+        return;
+    }
+    activeClients.set(accountId, client);
+    setStatus({
+        ...getStatus(),
+        connected: true,
+        running: true,
+        lastStartAt: Date.now(),
+    });
+    log?.info?.(`[${accountId}] openclaw-clawchat connected`);
+    await waitUntilAbort(abortSignal, async () => {
+        activeClients.delete(accountId);
+        client.close();
+        setStatus({
+            ...getStatus(),
+            connected: false,
+            running: false,
+            lastStopAt: Date.now(),
+        });
+        log?.info?.(`[${accountId}] openclaw-clawchat disconnected`);
+    });
+}
+// Re-export so channel.ts outbound.sendText can use the streaming helper when needed.
+export { sendStreamingText };

package/dist/src/streaming.js

@@ -0,0 +1,65 @@
+import { emitStreamAdd, emitStreamCreated, emitStreamDone, emitStreamFailed, } from "./client.js";
+function resolveRouting(params) {
+    if (params.routing)
+        return params.routing;
+    if (params.to)
+        return { chatId: params.to.id, chatType: params.to.type };
+    throw new Error("openclaw-clawchat streaming requires routing");
+}
+/**
+ * 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) {
+    const routing = resolveRouting(params);
+    const emitTyping = params.emitTyping !== false;
+    if (emitTyping) {
+        params.client.typing(routing.chatId, true);
+    }
+    emitStreamCreated(params.client, {
+        messageId: params.messageId,
+        routing,
+    });
+    let sequence = -1;
+    let fullText = "";
+    for (const chunk of params.chunks) {
+        sequence += 1;
+        fullText += chunk;
+        emitStreamAdd(params.client, {
+            messageId: params.messageId,
+            routing,
+            sequence,
+            fullText,
+            textDelta: chunk,
+        });
+    }
+    emitStreamDone(params.client, {
+        messageId: params.messageId,
+        routing,
+        finalSequence: Math.max(sequence, 0),
+        finalText: fullText,
+    });
+    if (emitTyping) {
+        params.client.typing(routing.chatId, false);
+    }
+}
+export async function sendStreamingFailure(params) {
+    const routing = resolveRouting(params);
+    emitStreamFailed(params.client, {
+        messageId: params.messageId,
+        routing,
+        sequence: params.currentSequence,
+        reason: params.reason,
+    });
+    if (params.emitTyping !== false) {
+        params.client.typing(routing.chatId, false);
+    }
+}

package/dist/src/tools-schema.js

@@ -0,0 +1,38 @@
+import { Type } from "@sinclair/typebox";
+export const ClawchatGetAccountProfileSchema = Type.Object({});
+export const ClawchatGetUserProfileSchema = Type.Object({
+    userId: Type.String({
+        description: "Target ClawChat user id (required). Do not infer this from a nickname.",
+    }),
+});
+export const ClawchatListAccountFriendsSchema = 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 const ClawchatUpdateAccountProfileSchema = Type.Object({
+    nickname: Type.Optional(Type.String({ description: "New ClawChat account nickname" })),
+    avatar_url: Type.Optional(Type.String({
+        description: "Avatar URL for the ClawChat account profile (use clawchat_upload_avatar_image first to obtain one from a local image)",
+    })),
+    bio: Type.Optional(Type.String({ description: "New ClawChat account self-introduction / bio text" })),
+});
+export const ClawchatUploadMediaFileSchema = Type.Object({
+    filePath: Type.String({
+        description: "Absolute local path of the media/file to upload to ClawChat (max 20MB)",
+    }),
+});
+export const ClawchatUploadAvatarImageSchema = Type.Object({
+    filePath: Type.String({
+        description: "Absolute local path of the avatar image to upload to ClawChat (max 20MB)",
+    }),
+});
+export const ClawchatActivateSchema = Type.Object({
+    code: Type.String({
+        description: "The invite code (six uppercase letters/digits, e.g. 'A1B2C3') extracted from the user's message. " +
+            "Whitespace is trimmed automatically.",
+    }),
+});

package/dist/src/tools.js

@@ -0,0 +1,287 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createOpenclawClawlingApiClient } from "./api-client.js";
+import { ClawlingApiError } from "./api-types.js";
+import { resolveOpenclawClawlingAccount } from "./config.js";
+import { ClawchatActivateSchema, ClawchatGetAccountProfileSchema, ClawchatGetUserProfileSchema, ClawchatListAccountFriendsSchema, ClawchatUpdateAccountProfileSchema, ClawchatUploadAvatarImageSchema, ClawchatUploadMediaFileSchema, } from "./tools-schema.js";
+const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
+function jsonResponse(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        details: data,
+    };
+}
+function configError(message) {
+    return jsonResponse({ error: "config", message });
+}
+function apiError(err) {
+    return jsonResponse({
+        error: err.kind,
+        message: err.message,
+        ...(err.meta ? { meta: err.meta } : {}),
+    });
+}
+function validationError(message) {
+    return jsonResponse({ error: "validation", message });
+}
+function resolveActivateCode(params) {
+    const explicit = typeof params.code === "string" ? params.code.trim() : "";
+    if (explicit)
+        return explicit;
+    const command = typeof params.command === "string" ? params.command.trim() : "";
+    return command.match(/\b[A-Z0-9]{6}\b/u)?.[0] ?? "";
+}
+function genericError(err) {
+    return jsonResponse({
+        error: "unknown",
+        message: err instanceof Error ? err.message : String(err),
+    });
+}
+const MIME_BY_EXT = {
+    ".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) {
+    const ext = path.extname(filePath).toLowerCase();
+    return MIME_BY_EXT[ext] ?? "application/octet-stream";
+}
+export function registerOpenclawClawlingTools(api) {
+    if (!api.config) {
+        api.logger.debug?.("openclaw-clawchat: api.config missing; skipping tool registration");
+        return;
+    }
+    api.registerTool({
+        name: "clawchat_activate",
+        label: "Clawling: Activate (Login with Invite Code)",
+        description: "Activate this OpenClaw plugin on ClawChat by exchanging an invite code for a token. " +
+            "Invite codes use six uppercase letters/digits, e.g. A1B2C3. " +
+            "TRIGGER — invoke this tool whenever the user's message matches ANY of: " +
+            "(1) activation intent with an embedded invite code, such as 'activate ClawChat with invite code A1B2C3', " +
+            "'login to ClawChat with invite code A1B2C3', 'connect ClawChat using invite code A1B2C3', " +
+            "or '绑定 ClawChat，邀请码 A1B2C3' — call this tool with `code = \"A1B2C3\"`; " +
+            "(2) generic activation intent without an embedded code, such as 'activate ClawChat' or " +
+            "'login to ClawChat' — ask for invite code before calling the tool; " +
+            "(3) activation intent with an embedded code, such as 'use invite code A1B2C3', " +
+            "or the user pasting an invite code in the context of ClawChat activation. " +
+            "Extract the code verbatim — do NOT normalize / lowercase / add prefixes. " +
+            "On success the tool persists the resulting token + userId to the config, so " +
+            "subsequent `clawchat_*` calls work without another plugin registration pass.",
+        parameters: ClawchatActivateSchema,
+        async execute(_callId, params) {
+            const code = resolveActivateCode(params);
+            if (!code) {
+                return validationError("openclaw-clawchat: code is required");
+            }
+            try {
+                const { runOpenclawClawlingLogin } = await import("./login.runtime.js");
+                await runOpenclawClawlingLogin({
+                    cfg: api.config,
+                    accountId: null,
+                    runtime: { log: (message) => api.logger.info?.(message) },
+                    readInviteCode: async () => code,
+                    mutateConfigFile: api.runtime.config.mutateConfigFile,
+                });
+                return jsonResponse({
+                    ok: true,
+                    message: "ClawChat activated successfully.",
+                });
+            }
+            catch (err) {
+                if (err instanceof ClawlingApiError)
+                    return apiError(err);
+                return genericError(err);
+            }
+        },
+    }, { name: "clawchat_activate" });
+    // Re-resolve at call time so config reloads pick up new tokens / baseUrl.
+    function resolveCurrent() {
+        return resolveOpenclawClawlingAccount(api.config);
+    }
+    function buildClient() {
+        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 ClawChat
+        // activation/login).
+        if (!acct.token) {
+            return { ok: false, error: configError("openclaw-clawchat: token is required") };
+        }
+        return {
+            ok: true,
+            client: createOpenclawClawlingApiClient({
+                baseUrl: acct.baseUrl,
+                token: acct.token,
+                userId: acct.userId,
+            }),
+        };
+    }
+    function withClient(fn) {
+        return (async () => {
+            const built = buildClient();
+            if (!built.ok)
+                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_account_profile",
+        label: "Get ClawChat Account Profile",
+        description: "Fetch the configured ClawChat account profile (user id, nickname/display name, avatar, bio). " +
+            "TRIGGER — invoke when the user asks for the ClawChat account/profile connected to this plugin, " +
+            "such as 'show my ClawChat profile', 'what is the configured ClawChat account?', " +
+            "'当前 ClawChat 账号资料', or 'ClawChat 昵称头像简介'. " +
+            "Do not use this for OpenClaw agent persona/profile questions unless the user explicitly means the ClawChat account.",
+        parameters: ClawchatGetAccountProfileSchema,
+        async execute(_callId, _params) {
+            return await withClient((c) => c.getMyProfile());
+        },
+    }, { name: "clawchat_get_account_profile" });
+    api.registerTool({
+        name: "clawchat_get_user_profile",
+        label: "Get ClawChat User Profile",
+        description: "Fetch a ClawChat user's public profile by userId. " +
+            "TRIGGER — invoke when the user asks to look up, view, or inspect a specific ClawChat user's public profile " +
+            "and provides a concrete userId. Do not guess or infer userId from a nickname/display name.",
+        parameters: ClawchatGetUserProfileSchema,
+        async execute(_callId, params) {
+            const p = params;
+            return await withClient((c) => c.getUserInfo(p.userId));
+        },
+    }, { name: "clawchat_get_user_profile" });
+    api.registerTool({
+        name: "clawchat_list_account_friends",
+        label: "List ClawChat Account Friends",
+        description: "List the configured ClawChat account's friends/contacts, paginated (page=1, pageSize=20 by default). " +
+            "TRIGGER — invoke when the user asks for this ClawChat account's friends, contacts, friend list, " +
+            "or asks to show more friends with pagination.",
+        parameters: ClawchatListAccountFriendsSchema,
+        async execute(_callId, params) {
+            const p = (params ?? {});
+            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_account_friends" });
+    api.registerTool({
+        name: "clawchat_update_account_profile",
+        label: "Update ClawChat Account Profile",
+        description: "Update the configured ClawChat account profile (nickname and/or avatar and/or bio). " +
+            "TRIGGER — invoke this tool whenever the user's message explicitly asks to change the ClawChat account profile: " +
+            "(1) ClawChat account nickname/name change: 'change the ClawChat account nickname to X', " +
+            "'set this ClawChat account name to X', 'ClawChat 昵称改为 X', '账号昵称改成 X', '账号名字叫 X' " +
+            "→ call with `nickname = X`; " +
+            "(2) ClawChat account avatar/profile-picture change: 'change the ClawChat account avatar', " +
+            "'use this image as the ClawChat profile picture', 'ClawChat 头像改为 …', '账号头像换成 …' " +
+            "→ first obtain the avatar URL (upload via `clawchat_upload_avatar_image`, OR use a provided URL directly), " +
+            "then call this tool with `avatar_url = <url>`; " +
+            "(3) ClawChat account bio/self-introduction change: 'update the ClawChat bio', " +
+            "'set the ClawChat account self-introduction to X', 'ClawChat 简介改成 X', '账号简介改为 X', '个人简介改为 X' " +
+            "→ call with `bio = X`. " +
+            "You can pass `nickname`, `avatar_url`, and `bio` together in one call, or just one of them. " +
+            "At least one of the three must be present. Do not use this for OpenClaw agent persona changes unless the user explicitly refers to the ClawChat account.",
+        parameters: ClawchatUpdateAccountProfileSchema,
+        async execute(_callId, params) {
+            const p = (params ?? {});
+            const patch = {};
+            if (typeof p.nickname === "string")
+                patch.nickname = p.nickname;
+            if (typeof p.avatar_url === "string")
+                patch.avatar_url = p.avatar_url;
+            if (typeof p.bio === "string")
+                patch.bio = p.bio;
+            if (Object.keys(patch).length === 0) {
+                return validationError("openclaw-clawchat: at least one of nickname / avatar / bio is required");
+            }
+            return await withClient((c) => c.updateMyProfile(patch));
+        },
+    }, { name: "clawchat_update_account_profile" });
+    api.registerTool({
+        name: "clawchat_upload_avatar_image",
+        label: "Upload ClawChat Avatar Image",
+        description: "Upload a local image file to ClawChat avatar storage (max 20MB) and return the hosted avatar URL. " +
+            "TRIGGER — invoke when the user provides an absolute local image path and asks to upload it for the ClawChat account avatar/profile picture. " +
+            "This tool does not update or set the account avatar by itself; call `clawchat_update_account_profile` with `avatar_url` after this tool returns a URL.",
+        parameters: ClawchatUploadAvatarImageSchema,
+        async execute(_callId, params) {
+            const p = params;
+            if (!p.filePath || !path.isAbsolute(p.filePath)) {
+                return validationError("openclaw-clawchat: filePath must be an absolute local path");
+            }
+            let stat;
+            try {
+                stat = fs.statSync(p.filePath);
+            }
+            catch (err) {
+                return validationError(`openclaw-clawchat: cannot stat ${p.filePath}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            if (!stat.isFile()) {
+                return validationError(`openclaw-clawchat: ${p.filePath} is not a regular file`);
+            }
+            if (stat.size > MAX_UPLOAD_BYTES) {
+                return validationError(`openclaw-clawchat: file too large (${stat.size} bytes; max 20MB)`);
+            }
+            const buffer = fs.readFileSync(p.filePath);
+            const filename = path.basename(p.filePath);
+            const mime = inferMimeFromPath(p.filePath);
+            return await withClient((c) => c.uploadAvatar({ buffer, filename, mime }));
+        },
+    }, { name: "clawchat_upload_avatar_image" });
+    api.registerTool({
+        name: "clawchat_upload_media_file",
+        label: "Upload ClawChat Media File",
+        description: "Upload a local file or media file to ClawChat media storage (max 20MB) and return the public URL/shareable URL. " +
+            "TRIGGER — invoke when the user provides an absolute local file path and asks to upload, share, or create a ClawChat-accessible link for that file. " +
+            "Do not use this for account avatar changes; use `clawchat_upload_avatar_image` for avatar images.",
+        parameters: ClawchatUploadMediaFileSchema,
+        async execute(_callId, params) {
+            const p = params;
+            if (!p.filePath || !path.isAbsolute(p.filePath)) {
+                return validationError("openclaw-clawchat: filePath must be an absolute local path");
+            }
+            let stat;
+            try {
+                stat = fs.statSync(p.filePath);
+            }
+            catch (err) {
+                return validationError(`openclaw-clawchat: cannot stat ${p.filePath}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            if (!stat.isFile()) {
+                return validationError(`openclaw-clawchat: ${p.filePath} is not a regular file`);
+            }
+            if (stat.size > MAX_UPLOAD_BYTES) {
+                return validationError(`openclaw-clawchat: file too large (${stat.size} bytes; max 20MB)`);
+            }
+            const buffer = fs.readFileSync(p.filePath);
+            const filename = path.basename(p.filePath);
+            const mime = inferMimeFromPath(p.filePath);
+            return await withClient((c) => c.uploadMedia({ buffer, filename, mime }));
+        },
+    }, { name: "clawchat_upload_media_file" });
+    api.logger.debug?.("openclaw-clawchat: registered 7 clawchat_* tools (activate, get_account_profile, get_user_profile, list_account_friends, update_account_profile, upload_avatar_image, upload_media_file)");
+}