@newbase-clawchat/openclaw-clawchat 2026.4.23 → 2026.4.29

package/src/runtime.ts

@@ -107,6 +107,16 @@ function formatConversationSubject(peer: { kind: "direct" | "group"; id: string
   return peer.kind === "group" ? `group:${peer.id}` : peer.id;
 }
 
+function withClawChatSessionScope(cfg: OpenClawConfig): OpenClawConfig {
+  return {
+    ...cfg,
+    session: {
+      ...(cfg.session ?? {}),
+      dmScope: "per-account-channel-peer",
+    },
+  };
+}
+
 export interface StartGatewayParams {
   cfg: OpenClawConfig;
   account: ResolvedOpenclawClawlingAccount;
@@ -172,8 +182,9 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       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,
+          cfg: routeCfg,
           channel: CHANNEL_ID,
           accountId,
           peer: turn.peer,

package/src/streaming.test.ts

@@ -37,8 +37,8 @@ describe("openclaw-clawchat streaming", () => {
       "message.done",
     ]);
     expect((client.typing as ReturnType<typeof vi.fn>).mock.calls).toEqual([
-      [{ id: "u1", type: "direct" }, true],
-      [{ id: "u1", type: "direct" }, false],
+      ["u1", true, "direct"],
+      ["u1", false, "direct"],
     ]);
   });
 
@@ -110,7 +110,7 @@ describe("openclaw-clawchat streaming", () => {
     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],
+      ["u1", false, "direct"],
     ]);
   });
 });

package/src/streaming.ts

@@ -10,7 +10,8 @@ import {
 
 export interface StreamingSendParams {
   client: ClawlingChatClient;
-  routing: EnvelopeRouting;
+  routing?: EnvelopeRouting;
+  to?: { id: string; type: "direct" | "group" };
   sender: StreamSender;
   /**
    * Pre-chunked text. Use `chunkMarkdownText` from
@@ -22,6 +23,12 @@ export interface StreamingSendParams {
   emitTyping?: boolean;
 }
 
+function resolveRouting(params: { routing?: EnvelopeRouting; to?: { id: string; type: "direct" | "group" } }): EnvelopeRouting {
+  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.
  *
@@ -35,13 +42,14 @@ export interface StreamingSendParams {
  * With zero chunks: typing(true) -> created -> done -> typing(false).
  */
 export async function sendStreamingText(params: StreamingSendParams): Promise<void> {
+  const routing = resolveRouting(params);
   const emitTyping = params.emitTyping !== false;
   if (emitTyping) {
-    params.client.typing(params.routing.chatId, true, params.routing.chatType);
+    params.client.typing(routing.chatId, true, routing.chatType);
   }
   emitStreamCreated(params.client, {
     messageId: params.messageId,
-    routing: params.routing,
+    routing,
   });
   let sequence = 0;
   let fullText = "";
@@ -50,7 +58,7 @@ export async function sendStreamingText(params: StreamingSendParams): Promise<vo
     fullText += chunk;
     emitStreamAdd(params.client, {
       messageId: params.messageId,
-      routing: params.routing,
+      routing,
       sequence,
       fullText,
       textDelta: chunk,
@@ -58,18 +66,19 @@ export async function sendStreamingText(params: StreamingSendParams): Promise<vo
   }
   emitStreamDone(params.client, {
     messageId: params.messageId,
-    routing: params.routing,
+    routing,
     finalSequence: sequence,
     finalText: fullText,
   });
   if (emitTyping) {
-    params.client.typing(params.routing.chatId, false, params.routing.chatType);
+    params.client.typing(routing.chatId, false, routing.chatType);
   }
 }
 
 export interface StreamingFailureParams {
   client: ClawlingChatClient;
-  routing: EnvelopeRouting;
+  routing?: EnvelopeRouting;
+  to?: { id: string; type: "direct" | "group" };
   messageId: string;
   currentSequence: number;
   reason?: string;
@@ -77,13 +86,14 @@ export interface StreamingFailureParams {
 }
 
 export async function sendStreamingFailure(params: StreamingFailureParams): Promise<void> {
+  const routing = resolveRouting(params);
   emitStreamFailed(params.client, {
     messageId: params.messageId,
-    routing: params.routing,
+    routing,
     sequence: params.currentSequence + 1,
     reason: params.reason,
   });
   if (params.emitTyping !== false) {
-    params.client.typing(params.routing.chatId, false, params.routing.chatType);
+    params.client.typing(routing.chatId, false, routing.chatType);
   }
 }

package/src/tools-schema.ts

@@ -1,14 +1,16 @@
 import { Type, type Static } from "@sinclair/typebox";
 
-export const ClawchatGetMyProfileSchema = Type.Object({});
-export type ClawchatGetMyProfileParams = Static<typeof ClawchatGetMyProfileSchema>;
+export const ClawchatGetAccountProfileSchema = Type.Object({});
+export type ClawchatGetAccountProfileParams = Static<typeof ClawchatGetAccountProfileSchema>;
 
-export const ClawchatGetUserInfoSchema = Type.Object({
-  userId: Type.String({ description: "Target user id (required)" }),
+export const ClawchatGetUserProfileSchema = Type.Object({
+  userId: Type.String({
+    description: "Target ClawChat user id (required). Do not infer this from a nickname.",
+  }),
 });
-export type ClawchatGetUserInfoParams = Static<typeof ClawchatGetUserInfoSchema>;
+export type ClawchatGetUserProfileParams = Static<typeof ClawchatGetUserProfileSchema>;
 
-export const ClawchatListFriendsSchema = Type.Object({
+export const ClawchatListAccountFriendsSchema = Type.Object({
   page: Type.Optional(Type.Integer({ minimum: 1, description: "1-based page number (default 1)" })),
   pageSize: Type.Optional(
     Type.Integer({
@@ -18,35 +20,42 @@ export const ClawchatListFriendsSchema = Type.Object({
     }),
   ),
 });
-export type ClawchatListFriendsParams = Static<typeof ClawchatListFriendsSchema>;
+export type ClawchatListAccountFriendsParams = Static<typeof ClawchatListAccountFriendsSchema>;
 
-export const ClawchatUpdateMyProfileSchema = Type.Object({
-  nickname: Type.Optional(Type.String({ description: "New Nick Name" })),
+export const ClawchatUpdateAccountProfileSchema = Type.Object({
+  nickname: Type.Optional(Type.String({ description: "New ClawChat account nickname" })),
   avatar_url: Type.Optional(
-    Type.String({ description: "Avatar URL (use clawchat_upload_avatar first to obtain)" }),
+    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" }),
   ),
-  bio: Type.Optional(Type.String({ description: "New self-introduction / bio text" })),
 });
-export type ClawchatUpdateMyProfileParams = Static<typeof ClawchatUpdateMyProfileSchema>;
+export type ClawchatUpdateAccountProfileParams = Static<
+  typeof ClawchatUpdateAccountProfileSchema
+>;
 
-export const ClawchatUploadFileSchema = Type.Object({
+export const ClawchatUploadMediaFileSchema = Type.Object({
   filePath: Type.String({
-    description: "Absolute local path of the file to upload (max 20MB)",
+    description: "Absolute local path of the media/file to upload to ClawChat (max 20MB)",
   }),
 });
-export type ClawchatUploadFileParams = Static<typeof ClawchatUploadFileSchema>;
+export type ClawchatUploadMediaFileParams = Static<typeof ClawchatUploadMediaFileSchema>;
 
-export const ClawchatUploadAvatarSchema = Type.Object({
+export const ClawchatUploadAvatarImageSchema = Type.Object({
   filePath: Type.String({
-    description: "Absolute local path of the avatar image to upload (max 20MB)",
+    description: "Absolute local path of the avatar image to upload to ClawChat (max 20MB)",
   }),
 });
-export type ClawchatUploadAvatarParams = Static<typeof ClawchatUploadAvatarSchema>;
+export type ClawchatUploadAvatarImageParams = Static<typeof ClawchatUploadAvatarImageSchema>;
 
 export const ClawchatActivateSchema = Type.Object({
   code: Type.String({
     description:
-      "The invite code (e.g. 'INV-ABC123') extracted from the user's message. " +
+      "The invite code (six uppercase letters/digits, e.g. 'A1B2C3') extracted from the user's message. " +
       "Whitespace is trimmed automatically.",
   }),
 });

package/src/tools.test.ts

@@ -1,6 +1,12 @@
 import { describe, expect, it, vi } from "vitest";
 import { registerOpenclawClawlingTools } from "./tools.ts";
 
+const loginRuntime = vi.hoisted(() => ({
+  runOpenclawClawlingLogin: vi.fn(),
+}));
+
+vi.mock("./login.runtime.ts", () => loginRuntime);
+
 interface RegisteredTool {
   name: string;
   execute: (callId: string, params: unknown) => Promise<unknown>;
@@ -8,6 +14,7 @@ interface RegisteredTool {
 
 function buildApi(opts: {
   configChannel?: Record<string, unknown> | null;
+  configTools?: Record<string, unknown>;
   registerTool?: (tool: { name: string }, options?: { name: string }) => void;
 }) {
   const registered: RegisteredTool[] = [];
@@ -15,7 +22,10 @@ function buildApi(opts: {
     config:
       opts.configChannel === null
         ? undefined
-        : { channels: { "openclaw-clawchat": opts.configChannel ?? {} } },
+        : {
+            channels: { "openclaw-clawchat": opts.configChannel ?? {} },
+            ...(opts.configTools ? { tools: opts.configTools } : {}),
+          },
     logger: {
       info: vi.fn(),
       debug: vi.fn(),
@@ -39,14 +49,38 @@ function configuredChannel(extra: Record<string, unknown> = {}) {
 }
 
 describe("registerOpenclawClawlingTools", () => {
-  it("registers ONLY clawchat_activate when account.configured is false (onboarding path)", () => {
+  it("registers no tools when account.configured is false", () => {
+    const { api, registered } = buildApi({
+      configChannel: { websocketUrl: "wss://w" /* token / userId missing */ },
+    });
+    registerOpenclawClawlingTools(api);
+    expect(registered.map((t) => t.name)).toEqual([]);
+  });
+
+  it("does not mutate tool policy during registration before account activation", () => {
+    const { api, registered } = buildApi({
+      configChannel: { websocketUrl: "wss://w" /* token / userId missing */ },
+      configTools: { profile: "coding", allow: [] },
+    });
+
+    registerOpenclawClawlingTools(api);
+
+    expect(registered.map((t) => t.name)).toEqual([]);
+    expect(api.config?.tools).toEqual({
+      profile: "coding",
+      allow: [],
+    });
+  });
+
+  it("does not register clawchat_activate for invite-code onboarding", async () => {
     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"]);
+
+    expect(registered.some((t) => t.name === "clawchat_activate")).toBe(false);
+    expect(loginRuntime.runOpenclawClawlingLogin).not.toHaveBeenCalled();
   });
 
   it("skips registration when api.config is undefined", () => {
@@ -55,62 +89,106 @@ describe("registerOpenclawClawlingTools", () => {
     expect(registered).toHaveLength(0);
   });
 
-  it("registers all seven tools when configured (regardless of baseUrl)", () => {
+  it("registers all six account 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_avatar",
-      "clawchat_upload_file",
+      "clawchat_get_account_profile",
+      "clawchat_get_user_profile",
+      "clawchat_list_account_friends",
+      "clawchat_update_account_profile",
+      "clawchat_upload_avatar_image",
+      "clawchat_upload_media_file",
     ]);
   });
 
-  it("clawchat_activate description names the `clawchat <code>` trigger", () => {
+  it("logs configured tool registration at debug level only", () => {
+    const { api } = buildApi({
+      configChannel: configuredChannel(),
+    });
+    const logger = api.logger as {
+      info: ReturnType<typeof vi.fn>;
+      debug: ReturnType<typeof vi.fn>;
+    };
+
+    registerOpenclawClawlingTools(api);
+
+    expect(logger.info).not.toHaveBeenCalled();
+    expect(logger.debug).toHaveBeenCalledWith(
+      "openclaw-clawchat: registered 6 clawchat_* tools (get_account_profile, get_user_profile, list_account_friends, update_account_profile, upload_avatar_image, upload_media_file)",
+    );
+  });
+
+  it("does not register clawchat_activate when configured", () => {
     const { api, registered } = buildApi({
       configChannel: configuredChannel(),
     });
-    // Re-capture full tool objects so we can see description.
+    registerOpenclawClawlingTools(api);
+    expect(registered.some((t) => t.name === "clawchat_activate")).toBe(false);
+  });
+
+  it("clawchat_update_account_profile description names account profile 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 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);
+    const update = fullTools.find((t) => t.name === "clawchat_update_account_profile")!;
+    expect(update).toBeDefined();
+    expect(update.description).toMatch(/configured ClawChat account|logged-in ClawChat account/i);
+    expect(update.description).toMatch(/ClawChat (account )?(nickname|name)/i);
+    expect(update.description).toMatch(/ClawChat 昵称|账号昵称|账号名字/);
+    expect(update.description).toMatch(/avatar|profile picture/i);
+    expect(update.description).toMatch(/ClawChat 头像|账号头像/);
+    expect(update.description).toMatch(/clawchat_upload_avatar_image/);
+    expect(update.description).toMatch(/bio|self-introduction/i);
+    expect(update.description).toMatch(/ClawChat 简介|账号简介|个人简介/);
+    expect(update.description).not.toMatch(
+      new RegExp(["agent's own", "rename " + "yourself", "this agent's own"].join("|"), "i"),
+    );
   });
 
-  it("clawchat_update_my_profile description names name + avatar + bio triggers (EN + ZH)", () => {
+  it("account query and upload tool descriptions include precise trigger semantics", () => {
     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(/生成头像|换个头像/);
-    expect(update.description).toMatch(/clawchat_upload_avatar/);
-    expect(update.description).toMatch(/bio|self introduction/i);
-    expect(update.description).toMatch(/自我介绍|个人简介/);
+
+    const accountProfile = fullTools.find((t) => t.name === "clawchat_get_account_profile")!;
+    const userProfile = fullTools.find((t) => t.name === "clawchat_get_user_profile")!;
+    const friends = fullTools.find((t) => t.name === "clawchat_list_account_friends")!;
+    const avatar = fullTools.find((t) => t.name === "clawchat_upload_avatar_image")!;
+    const media = fullTools.find((t) => t.name === "clawchat_upload_media_file")!;
+
+    expect(accountProfile.description).toMatch(/configured ClawChat account|logged-in ClawChat account/i);
+    expect(accountProfile.description).toMatch(/profile|nickname|avatar|bio/i);
+    expect(accountProfile.description).not.toMatch(/agent's own|this agent's/i);
+
+    expect(userProfile.description).toMatch(/userId/);
+    expect(userProfile.description).toMatch(/public profile/i);
+    expect(userProfile.description).toMatch(/do not guess|do not infer/i);
+
+    expect(friends.description).toMatch(/configured ClawChat account|logged-in ClawChat account/i);
+    expect(friends.description).toMatch(/friends|contacts/i);
+    expect(friends.description).toMatch(/page=1|pageSize=20/);
+
+    expect(avatar.description).toMatch(/local image/i);
+    expect(avatar.description).toMatch(/avatar URL|hosted avatar URL|public URL/i);
+    expect(avatar.description).toMatch(/clawchat_update_account_profile/);
+    expect(avatar.description).toMatch(/does not update|does not set/i);
+
+    expect(media.description).toMatch(/local file|media file/i);
+    expect(media.description).toMatch(/public URL|shareable URL/i);
+    expect(media.description).toMatch(/not.*avatar|do not use.*avatar/i);
   });
 
-  it("clawchat_upload_avatar rejects oversized files before upload", async () => {
+  it("clawchat_upload_avatar_image 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");
@@ -124,7 +202,7 @@ describe("registerOpenclawClawlingTools", () => {
         configChannel: configuredChannel({ baseUrl: "https://api.example.com" }),
       });
       registerOpenclawClawlingTools(api);
-      const tool = registered.find((t) => t.name === "clawchat_upload_avatar")!;
+      const tool = registered.find((t) => t.name === "clawchat_upload_avatar_image")!;
       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 };
@@ -136,7 +214,7 @@ describe("registerOpenclawClawlingTools", () => {
   });
 
 
-  it("clawchat_upload_file rejects oversized files before upload", async () => {
+  it("clawchat_upload_media_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");
@@ -151,7 +229,7 @@ describe("registerOpenclawClawlingTools", () => {
         configChannel: configuredChannel({ baseUrl: "https://api.example.com" }),
       });
       registerOpenclawClawlingTools(api);
-      const tool = registered.find((t) => t.name === "clawchat_upload_file")!;
+      const tool = registered.find((t) => t.name === "clawchat_upload_media_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 };