@newbase-clawchat/openclaw-clawchat 2026.4.29 → 2026.4.30

package/src/login.runtime.ts

@@ -1,8 +1,7 @@
 import { createInterface, type Interface as ReadlineInterface } from "node:readline/promises";
-import { writeConfigFile } from "openclaw/plugin-sdk/config-runtime";
 import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
 import { createOpenclawClawlingApiClient } from "./api-client.ts";
-import { ClawlingApiError } from "./api-types.ts";
+import { ClawlingApiError, type AgentConnectResult } from "./api-types.ts";
 import {
   CHANNEL_ID,
   mergeOpenclawClawchatToolAllow,
@@ -20,6 +19,14 @@ export const AGENTS_CONNECT_PLATFORM = "openclaw" as const;
  */
 export const AGENTS_CONNECT_TYPE = "clawbot" as const;
 
+export type OpenclawClawchatMutateConfigFile = <T = void>(params: {
+  afterWrite: { mode: "auto" } | { mode: "none" | "restart"; reason: string };
+  mutate: (
+    draft: OpenClawConfig,
+    context: { snapshot: unknown; previousHash: string | null },
+  ) => Promise<T | void> | T | void;
+}) => Promise<unknown>;
+
 export interface LoginParams {
   cfg: OpenClawConfig;
   accountId?: string | null;
@@ -31,7 +38,9 @@ export interface LoginParams {
   readInviteCode?: () => Promise<string>;
   /** Override for the HTTP client — used by tests. */
   apiClientFactory?: typeof createOpenclawClawlingApiClient;
-  /** Override for config persistence — used by tests. */
+  /** Official runtime config mutator. Production callers must provide this. */
+  mutateConfigFile?: OpenclawClawchatMutateConfigFile;
+  /** Test-only config persistence override. */
   persistConfig?: (cfg: OpenClawConfig) => Promise<void> | void;
 }
 
@@ -60,6 +69,46 @@ async function promptInviteCodeFromStdin(runtime: {
   }
 }
 
+function buildLoginConfig(cfg: OpenClawConfig, result: AgentConnectResult): OpenClawConfig {
+  const channels = (cfg.channels ?? {}) as Record<string, unknown>;
+  const existing = (channels[CHANNEL_ID] ?? {}) as Record<string, unknown>;
+  const nextSection: Record<string, unknown> = {
+    ...existing,
+    enabled: true,
+    token: result.access_token,
+    userId: result.agent.user_id,
+  };
+  if (result.refresh_token) {
+    nextSection.refreshToken = result.refresh_token;
+  }
+  return mergeOpenclawClawchatToolAllow({
+    ...cfg,
+    channels: { ...channels, [CHANNEL_ID]: nextSection },
+  });
+}
+
+async function persistLoginConfig(
+  params: LoginParams,
+  result: AgentConnectResult,
+): Promise<void> {
+  if (params.mutateConfigFile) {
+    await params.mutateConfigFile({
+      afterWrite: { mode: "auto" },
+      mutate(draft) {
+        Object.assign(draft, buildLoginConfig(draft, result));
+      },
+    });
+    return;
+  }
+
+  if (params.persistConfig) {
+    await params.persistConfig(buildLoginConfig(params.cfg, result));
+    return;
+  }
+
+  throw new Error("openclaw-clawchat: mutateConfigFile is required to persist login credentials");
+}
+
 /**
  * Run the `openclaw channels login --channel openclaw-clawchat` flow:
  *   1. Read the existing channel section; require `baseUrl` to be set so we
@@ -67,7 +116,7 @@ async function promptInviteCodeFromStdin(runtime: {
  *   2. Prompt the user for an invite code on stdin.
  *   3. POST it to `${baseUrl}/v1/agents/connect`.
  *   4. Write the returned `websocket_url` / `token` / `user_id` back into
- *      the config so subsequent `openclaw gateway run` picks them up.
+ *      the config so subsequent Gateway runs pick them up.
  *
  * Errors surface with clear messages (missing baseUrl, empty invite,
  * server-side rejection) so the caller can relay them to the operator.
@@ -115,34 +164,13 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
     );
   }
 
-  // Merge credentials into cfg.channels.openclaw-clawchat and persist
-  // immediately so a subsequent `openclaw gateway run` picks them up
-  // without any manual edit. `baseUrl` / `websocketUrl` stay untouched —
-  // the built-in defaults (or operator overrides) remain authoritative
-  // because `/v1/agents/connect` doesn't return them.
-  const channels = (cfg.channels ?? {}) as Record<string, unknown>;
-  const existing = (channels[CHANNEL_ID] ?? {}) as Record<string, unknown>;
-  const nextSection: Record<string, unknown> = {
-    ...existing,
-    enabled: true,
-    token: result.access_token,
-    userId: result.agent.user_id,
-  };
-  if (result.refresh_token) {
-    nextSection.refreshToken = result.refresh_token;
-  }
-  const nextCfg: OpenClawConfig = mergeOpenclawClawchatToolAllow({
-    ...cfg,
-    channels: { ...channels, [CHANNEL_ID]: nextSection },
-  });
-
   const tokenPreview = redactToken(result.access_token);
   runtime.log(
     `Updating config: channels.${CHANNEL_ID}.token=${tokenPreview} userId=${result.agent.user_id}${
       result.refresh_token ? " refreshToken=***" : ""
     } …`,
   );
-  await (params.persistConfig ?? writeConfigFile)(nextCfg);
+  await persistLoginConfig(params, result);
   runtime.log(`Config file updated.`);
 
   runtime.log(

package/src/manifest.test.ts

@@ -6,11 +6,24 @@ import packageJson from "../package.json" with { type: "json" };
 interface PackageJsonWithOpenclaw {
   name: string;
   files: string[];
+  scripts: Record<string, string>;
+  devDependencies: Record<string, string>;
+  peerDependencies: Record<string, string>;
   openclaw: {
     extensions: string[];
+    runtimeExtensions?: string[];
     setupEntry?: string;
-    channel?: { id: string; aliases?: string[]; cliAddOptions?: Array<{ flags: string }> };
-    install: { npmSpec: string };
+    channel?: {
+      id: string;
+      label: string;
+      selectionLabel?: string;
+      docsPath?: string;
+      docsLabel?: string;
+      blurb: string;
+      order?: number;
+      aliases?: string[];
+    };
+    install: { npmSpec: string; minHostVersion: string };
   };
 }
 
@@ -31,23 +44,52 @@ describe("openclaw-clawchat manifest", () => {
     expect(pkg.openclaw.install.npmSpec).toBe("@newbase-clawchat/openclaw-clawchat");
   });
 
+  it("requires an OpenClaw host with runtime config mutation support", () => {
+    const pkg = packageJson as PackageJsonWithOpenclaw;
+    expect(pkg.peerDependencies.openclaw).toBe("^2026.4.29");
+    expect(pkg.devDependencies.openclaw).toBe("2026.4.29");
+    expect(pkg.openclaw.install.minHostVersion).toBe(">=2026.4.29");
+  });
+
+  it("publishes compiled runtime entrypoints for npm plugin installs", () => {
+    const pkg = packageJson as PackageJsonWithOpenclaw;
+    expect(pkg.openclaw.extensions).toEqual(["./index.ts"]);
+    expect(pkg.openclaw.runtimeExtensions).toEqual(["./dist/index.js"]);
+    expect(pkg.files).toContain("dist");
+    expect(pkg.scripts.build).toBe("tsc -p tsconfig.build.json");
+    expect(pkg.scripts.prepack).toBe("npm run build");
+    expect(fs.existsSync(new URL("../tsconfig.build.json", import.meta.url))).toBe(true);
+  });
+
+  it("publishes channel catalog metadata for OpenClaw CLI discovery", () => {
+    const pkg = packageJson as PackageJsonWithOpenclaw;
+    expect(pkg.openclaw.channel).toEqual({
+      id: "openclaw-clawchat",
+      label: "Clawling Chat",
+      selectionLabel: "Clawling Chat",
+      docsPath: "/channels/openclaw-clawchat",
+      docsLabel: "openclaw-clawchat",
+      blurb: "Clawling Protocol v2 over WebSocket (chat-sdk).",
+      order: 110,
+    });
+  });
+
   it("declares supported channel/command activation hints for plugin loading", () => {
     expect(pluginManifest.activation).toEqual({
+      onStartup: true,
       onChannels: ["openclaw-clawchat"],
       onCommands: ["clawchat-login"],
     });
-    expect(pluginManifest.activation).not.toHaveProperty("onStartup");
     expect(pluginManifest.commandAliases).toEqual([
       { name: "clawchat-login", kind: "runtime-slash" },
     ]);
   });
 
-  it("does not publish setup migration or setup-runtime channel metadata", () => {
+  it("does not publish setup migration or setup-runtime entry metadata", () => {
     const pkg = packageJson as PackageJsonWithOpenclaw;
     expect(pkg.files).not.toContain("setup-api.ts");
     expect(pkg.files).not.toContain("setup-entry.ts");
     expect(pkg.openclaw.setupEntry).toBeUndefined();
-    expect(pkg.openclaw.channel).toBeUndefined();
     expect(fs.existsSync(new URL("../setup-api.ts", import.meta.url))).toBe(false);
     expect(fs.existsSync(new URL("../setup-entry.ts", import.meta.url))).toBe(false);
   });
@@ -73,16 +115,50 @@ describe("openclaw-clawchat manifest", () => {
     expect(skill).not.toMatch(/clawchat_activate/);
   });
 
-  it("keeps the activation skill on channel login without tool or slash-command dispatch", () => {
+  it("declares ownership of registered ClawChat agent tools", () => {
+    expect(pluginManifest.contracts?.tools).toEqual([
+      "clawchat_activate",
+      "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("keeps the optional OpenClaw source checkout local-only", () => {
+    expect(fs.existsSync(new URL("../.gitmodules", import.meta.url))).toBe(false);
+
+    const gitignore = fs.readFileSync(new URL("../.gitignore", import.meta.url), "utf8");
+    expect(gitignore).toMatch(/^tmp\/openclaw\/$/m);
+
+    const pkg = packageJson as PackageJsonWithOpenclaw;
+    expect(pkg.scripts["dev:openclaw-source"]).toBe(
+      "test -d tmp/openclaw || git clone --depth=1 https://github.com/openclaw/openclaw.git tmp/openclaw",
+    );
+
+    const readme = fs.readFileSync(new URL("../README.md", import.meta.url), "utf8");
+    expect(readme).toMatch(/npm run dev:openclaw-source/);
+    expect(readme).toMatch(
+      /git clone --depth=1 https:\/\/github\.com\/openclaw\/openclaw\.git tmp\/openclaw/,
+    );
+    expect(readme).toMatch(/local-only/i);
+  });
+
+  it("keeps default Vitest discovery scoped to plugin sources", () => {
+    const configUrl = new URL("../vitest.config.ts", import.meta.url);
+    expect(fs.existsSync(configUrl)).toBe(true);
+    const config = fs.readFileSync(configUrl, "utf8");
+    expect(config).toMatch(/include:\s*\["src\/\*\*\/\*\.test\.ts"\]/);
+    expect(config).toMatch(/"tmp\/\*\*"/);
+    expect(config).toMatch(/"\.e2e\/\*\*"/);
+  });
+
+  it("keeps the activation skill on clawchat_activate with channel-login fallback", () => {
     const skill = fs.readFileSync(new URL("../skills/clawchat-activate/SKILL.md", import.meta.url), "utf8");
     expect(skill).toMatch(/name:\s*clawchat-activate/);
-    expect(skill).not.toMatch(/clawchat_activate/);
-    expect(skill).not.toMatch(/command-dispatch:\s*tool/);
-    expect(skill).not.toMatch(/command-tool:/);
-    expect(skill).not.toMatch(/command-dispatch:/);
-    expect(skill).not.toMatch(/command-command:/);
-    expect(skill).not.toMatch(/command-arg-mode:/);
-    expect(skill).not.toMatch(/user-invocable:/);
+    expect(skill).toMatch(/clawchat_activate/);
     expect(skill).not.toMatch(/`clawchat\s+A1B2C3`/i);
     expect(skill).not.toMatch(/`clawchat\s*<code>`/i);
     expect(skill).not.toMatch(/\/clawchat_activate A1B2C3/);
@@ -92,33 +168,33 @@ describe("openclaw-clawchat manifest", () => {
     expect(skill).toMatch(/do not append/i);
     expect(skill).toMatch(/prompt[^\n]+invite code[^\n]+provide/i);
     expect(skill).toMatch(/channel login/i);
+    expect(skill).toMatch(/openclaw channels status --probe/);
     expect(skill).toMatch(/openclaw gateway restart/);
     expect(skill).not.toMatch(/ask the user to send/i);
     expect(skill).not.toMatch(/give the exact/i);
-    expect(skill).toMatch(/execute[^\n]+openclaw channels login --channel openclaw-clawchat/i);
-    expect(skill).toMatch(/execute[^\n]+openclaw gateway restart/i);
+    expect(skill).toMatch(/restart[^\n]+only when/i);
   });
 
-  it("documents channel login as the natural-language activation path", () => {
+  it("documents clawchat_activate as the natural-language activation path with CLI fallback", () => {
     const readme = fs.readFileSync(new URL("../README.md", import.meta.url), "utf8");
     const docs = fs.readFileSync(new URL("../docs/openclaw-clawchat.md", import.meta.url), "utf8");
+    expect(readme).toMatch(/clawchat_activate/i);
+    expect(docs).toMatch(/clawchat_activate/i);
     expect(readme).toMatch(/openclaw channels login --channel openclaw-clawchat/i);
     expect(docs).toMatch(/openclaw channels login --channel openclaw-clawchat/i);
+    expect(readme).toMatch(/openclaw channels status --probe/i);
+    expect(docs).toMatch(/openclaw channels status --probe/i);
     expect(readme).toMatch(/openclaw gateway restart/i);
     expect(docs).toMatch(/openclaw gateway restart/i);
     expect(readme).not.toMatch(/activation skill[^.]+\/clawchat-login/i);
     expect(docs).not.toMatch(/natural-language activation requests[^.]+\/clawchat-login/i);
     expect(readme).not.toMatch(/\/clawchat-activate\s+A1B2C3/i);
     expect(docs).not.toMatch(/\/clawchat-activate\s+A1B2C3/i);
-    expect(readme).not.toMatch(/clawchat_activate/);
-    expect(docs).not.toMatch(/clawchat_activate/);
     expect(readme).not.toMatch(/\/clawchat_activate\s+A1B2C3/i);
     expect(docs).not.toMatch(/\/clawchat_activate\s+A1B2C3/i);
     expect(readme).not.toMatch(/direct users to/i);
     expect(docs).not.toMatch(/direct the\s+user/i);
-    expect(docs).not.toMatch(/call the tool with the extracted code/i);
-    expect(docs).not.toMatch(/AGT->>PLG: clawchat_activate/);
-    expect(readme).toMatch(/activation skill[^.]+execute/i);
-    expect(docs).toMatch(/natural-language activation requests[^.]+execute/i);
+    expect(readme).toMatch(/activation skill calls/i);
+    expect(docs).toMatch(/Natural-language activation requests should call `clawchat_activate`/i);
   });
 });

package/src/outbound.test.ts

@@ -65,9 +65,9 @@ describe("openclaw-clawchat outbound", () => {
     });
     expect((client.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0]).toMatchObject({
       chat_id: "user-1",
-      chat_type: "direct",
       body: { fragments: [{ kind: "text", text: "hello" }] },
     });
+    expect((client.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0]).not.toHaveProperty("chat_type");
     expect(client.replyMessage).not.toHaveBeenCalled();
     expect(result?.messageId).toBe("server-m1");
     expect(result?.acceptedAt).toBe(1234);
@@ -78,26 +78,27 @@ describe("openclaw-clawchat outbound", () => {
     await sendOpenclawClawlingText({
       client,
       account: baseAccount(),
-      to: { chatId: "user-1", chatType: "direct" },
+      to: { chatId: "chat-1", chatType: "direct" },
       text: "reply",
       replyCtx: {
         replyToMessageId: "m-orig",
+        replyPreviewChatId: "chat-1",
         replyPreviewSenderId: "user-2",
         replyPreviewNickName: "Sender",
         replyPreviewText: "original",
       },
     });
     expect((client.replyMessage as ReturnType<typeof vi.fn>).mock.calls[0][0]).toMatchObject({
-      chat_id: "user-1",
-      chat_type: "direct",
+      chat_id: "chat-1",
       replyTo: {
         msgId: "m-orig",
-        senderId: "user-2",
+        senderId: "chat-1",
         nickName: "Sender",
         fragments: [{ kind: "text", text: "original" }],
       },
       body: { fragments: [{ kind: "text", text: "reply" }] },
     });
+    expect((client.replyMessage as ReturnType<typeof vi.fn>).mock.calls[0][0]).not.toHaveProperty("chat_type");
     expect(client.sendMessage).not.toHaveBeenCalled();
   });
 

package/src/outbound.ts

@@ -22,6 +22,7 @@ export interface OutboundTarget {
 
 export interface OutboundReplyCtx {
   replyToMessageId: string;
+  replyPreviewChatId?: string;
   replyPreviewSenderId: string;
   replyPreviewNickName: string;
   replyPreviewText: string;
@@ -38,6 +39,7 @@ export interface SendParams {
   to: OutboundTarget;
   text: string;
   replyCtx?: OutboundReplyCtx;
+  richFragments?: Fragment[];
   mediaFragments?: ClawlingMediaFragment[];
   mentions?: string[];
   log?: LogSink;
@@ -92,8 +94,9 @@ export function parseOpenclawRecipient(to: string): { chatId: string; chatType:
 
 export async function sendOpenclawClawlingText(params: SendParams): Promise<SendResult | null> {
   const text = (params.text ?? "").trim();
+  const richFragments = params.richFragments ?? [];
   const mediaFragments = params.mediaFragments ?? [];
-  if (!text && mediaFragments.length === 0) {
+  if (!text && richFragments.length === 0 && mediaFragments.length === 0) {
     params.log?.info?.(
       `[${params.account.accountId}] openclaw-clawchat outbound suppressed: empty text and no media`,
     );
@@ -106,7 +109,7 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
   // with one of the SDK's narrow Fragment members (ImageFragment / FileFragment /
   // AudioFragment / VideoFragment) based on its runtime `kind`. The wide local
   // shape lets us build a single uniform array without a per-kind switch.
-  const fragments = [...textFragments, ...mediaFragments] as Fragment[];
+  const fragments = [...textFragments, ...richFragments, ...mediaFragments] as Fragment[];
 
   const useReply = params.replyCtx && mediaFragments.length === 0;
   if (params.replyCtx && mediaFragments.length > 0) {
@@ -121,26 +124,24 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
     mode = "reply";
     ack = await params.client.replyMessage({
       chat_id: params.to.chatId,
-      chat_type: params.to.chatType,
       mode: "normal",
       replyTo: {
         msgId: params.replyCtx.replyToMessageId,
-        senderId: params.replyCtx.replyPreviewSenderId,
+        senderId: params.replyCtx.replyPreviewChatId ?? params.replyCtx.replyPreviewSenderId,
         nickName: params.replyCtx.replyPreviewNickName,
         fragments: [{ kind: "text", text: params.replyCtx.replyPreviewText }],
       },
       body: { fragments },
       context: { mentions },
-    });
+    } as Parameters<ClawlingChatClient["replyMessage"]>[0]);
   } else {
     mode = "send";
     ack = await params.client.sendMessage({
       chat_id: params.to.chatId,
-      chat_type: params.to.chatType,
       mode: "normal",
       body: { fragments },
       context: { mentions, reply: null },
-    });
+    } as Parameters<ClawlingChatClient["sendMessage"]>[0]);
   }
   params.log?.info?.(
     `[${params.account.accountId}] openclaw-clawchat outbound mode=${mode} msg=${ack.payload.message_id} text_len=${text.length} media=${mediaFragments.length} trace=${ack.trace_id}`,