@newbase-clawchat/openclaw-clawchat 2026.4.29 → 2026.5.4

package/src/config.ts

@@ -2,6 +2,11 @@ import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
 import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
 
 export const CHANNEL_ID = "openclaw-clawchat" as const;
+export const CLAWCHAT_TOKEN_ENV = "CLAWCHAT_TOKEN" as const;
+export const CLAWCHAT_USER_ID_ENV = "CLAWCHAT_USER_ID" as const;
+export const CLAWCHAT_REFRESH_TOKEN_ENV = "CLAWCHAT_REFRESH_TOKEN" as const;
+export const CLAWCHAT_BASE_URL_ENV = "CLAWCHAT_BASE_URL" as const;
+export const CLAWCHAT_WEBSOCKET_URL_ENV = "CLAWCHAT_WEBSOCKET_URL" as const;
 
 /**
  * Built-in defaults for the Clawling Chat endpoints so `openclaw channel
@@ -84,13 +89,15 @@ export type OpenclawClawlingConfig = {
   websocketUrl?: string;
   baseUrl?: string;
   token?: string;
-  /** Refresh token persisted by `openclaw channels login --channel openclaw-clawchat` (paired with `token`). */
+  /** Refresh token persisted by ClawChat activation/login (paired with `token`). */
   refreshToken?: string;
   userId?: string;
   replyMode?: ReplyMode;
   groupMode?: GroupMode;
   forwardThinking?: boolean;
   forwardToolCalls?: boolean;
+  /** Emit approval/action rich fragments instead of plain fallback text. */
+  richInteractions?: boolean;
   stream?: OpenclawClawlingStreamConfig;
   reconnect?: OpenclawClawlingReconnectConfig;
   heartbeat?: OpenclawClawlingHeartbeatConfig;
@@ -111,6 +118,7 @@ export const openclawClawlingConfigSchema = {
     groupMode: { type: "string", enum: ["mention", "all"] },
     forwardThinking: { type: "boolean" },
     forwardToolCalls: { type: "boolean" },
+    richInteractions: { type: "boolean" },
     stream: {
       type: "object",
       additionalProperties: false,
@@ -213,6 +221,7 @@ export type ResolvedOpenclawClawlingAccount = {
   groupMode: GroupMode;
   forwardThinking: boolean;
   forwardToolCalls: boolean;
+  richInteractions: boolean;
   allowFrom: string[];
   stream: Required<OpenclawClawlingStreamConfig>;
   reconnect: Required<OpenclawClawlingReconnectConfig>;
@@ -230,6 +239,10 @@ function readOptionalString(value: unknown): string {
   return typeof value === "string" ? value.trim() : "";
 }
 
+function readEnvString(env: Record<string, string | undefined>, key: string): string {
+  return readOptionalString(env[key]);
+}
+
 function readReplyMode(value: unknown): ReplyMode {
   return value === "stream" ? "stream" : "static";
 }
@@ -285,13 +298,20 @@ function readAck(raw: unknown): Required<OpenclawClawlingAckConfig> {
 
 export function resolveOpenclawClawlingAccount(
   cfg: OpenClawConfig,
+  env: Record<string, string | undefined> = process.env,
 ): ResolvedOpenclawClawlingAccount {
   const channel = readChannelSection(cfg);
   // Apply built-in defaults so login/gateway work without prior setup.
-  const websocketUrl = readOptionalString(channel.websocketUrl) || DEFAULT_WEBSOCKET_URL;
-  const baseUrl = readOptionalString(channel.baseUrl) || DEFAULT_BASE_URL;
-  const token = readOptionalString(channel.token);
-  const userId = readOptionalString(channel.userId);
+  const websocketUrl =
+    readOptionalString(channel.websocketUrl) ||
+    readEnvString(env, CLAWCHAT_WEBSOCKET_URL_ENV) ||
+    DEFAULT_WEBSOCKET_URL;
+  const baseUrl =
+    readOptionalString(channel.baseUrl) ||
+    readEnvString(env, CLAWCHAT_BASE_URL_ENV) ||
+    DEFAULT_BASE_URL;
+  const token = readOptionalString(channel.token) || readEnvString(env, CLAWCHAT_TOKEN_ENV);
+  const userId = readOptionalString(channel.userId) || readEnvString(env, CLAWCHAT_USER_ID_ENV);
   const enabled = typeof channel.enabled === "boolean" ? channel.enabled : true;
   const replyMode = readReplyMode(channel.replyMode);
   const groupMode = readGroupMode(channel.groupMode);
@@ -299,6 +319,8 @@ export function resolveOpenclawClawlingAccount(
     typeof channel.forwardThinking === "boolean" ? channel.forwardThinking : true;
   const forwardToolCalls =
     typeof channel.forwardToolCalls === "boolean" ? channel.forwardToolCalls : false;
+  const richInteractions =
+    typeof channel.richInteractions === "boolean" ? channel.richInteractions : false;
 
   return {
     accountId: DEFAULT_ACCOUNT_ID,
@@ -313,6 +335,7 @@ export function resolveOpenclawClawlingAccount(
     groupMode,
     forwardThinking,
     forwardToolCalls,
+    richInteractions,
     allowFrom: [],
     stream: readStream(channel.stream),
     reconnect: readReconnect(channel.reconnect),

package/src/inbound.test.ts

@@ -41,6 +41,7 @@ function buildSendEnvelope(
     mentions: string[];
     reply: unknown;
     messageId: string;
+    chatId: string;
   }> = {},
 ): Envelope<DownlinkMessageSendPayload> {
   return {
@@ -48,6 +49,7 @@ function buildSendEnvelope(
     event: overrides.event ?? "message.send",
     trace_id: "trace-1",
     emitted_at: 1776162600000,
+    chat_id: overrides.chatId,
     to: { id: "agent-1", type: overrides.senderType ?? "direct" },
     sender: {
       sender_id: "user-1",
@@ -174,7 +176,7 @@ describe("openclaw-clawchat inbound", () => {
       },
     };
     await dispatchOpenclawClawlingInbound({
-      envelope: buildSendEnvelope({ event: "message.reply", reply: replyRef }),
+      envelope: buildSendEnvelope({ event: "message.reply", reply: replyRef, chatId: "chat-1" }),
       cfg: {},
       runtime: {} as never,
       account: baseAccount(),
@@ -183,6 +185,7 @@ describe("openclaw-clawchat inbound", () => {
     const { replyCtx } = ingest.mock.calls[0]![0];
     expect(replyCtx).toEqual({
       replyToMessageId: "m-orig",
+      replyPreviewChatId: "chat-1",
       replyPreviewSenderId: "user-2",
       replyPreviewNickName: "User Two",
       replyPreviewText: "original text",

package/src/inbound.ts

@@ -29,6 +29,7 @@ export interface IngestTurnParams {
   mediaItems: MediaItem[];
   replyCtx?: {
     replyToMessageId: string;
+    replyPreviewChatId: string;
     replyPreviewSenderId: string;
     replyPreviewNickName: string;
     replyPreviewText: string;
@@ -191,9 +192,19 @@ export async function dispatchOpenclawClawlingInbound(
     return;
   }
 
+  log?.info?.(
+    `[${account.accountId}] openclaw-clawchat inbound event=${envelope.event === EVENT.MESSAGE_REPLY ? "reply" : "send"} msg=${payload.message_id} from=${sender.id} text_len=${rawBody.length} mentioned=${wasMentioned}`,
+  );
+
+  // New protocol: `chat_id` is the routing primary; `to` is deprecated.
+  // Fall back to sender.id if neither is present (defensive).
+  const chatId =
+    (envelope as Envelope<DownlinkMessageSendPayload> & { chat_id?: string }).chat_id ??
+    sender.id;
   const replyCtx = message.context.reply
     ? {
         replyToMessageId: message.context.reply.reply_to_msg_id,
+        replyPreviewChatId: chatId,
         replyPreviewSenderId:
           message.context.reply.reply_preview.id ??
           message.context.reply.reply_preview.sender_id ??
@@ -206,16 +217,6 @@ export async function dispatchOpenclawClawlingInbound(
       }
     : undefined;
 
-  log?.info?.(
-    `[${account.accountId}] openclaw-clawchat inbound event=${envelope.event === EVENT.MESSAGE_REPLY ? "reply" : "send"} msg=${payload.message_id} from=${sender.id} text_len=${rawBody.length} mentioned=${wasMentioned}`,
-  );
-
-  // New protocol: `chat_id` is the routing primary; `to` is deprecated.
-  // Fall back to sender.id if neither is present (defensive).
-  const chatId =
-    (envelope as Envelope<DownlinkMessageSendPayload> & { chat_id?: string }).chat_id ??
-    sender.id;
-
   await params.ingest({
     channel: "openclaw-clawchat",
     accountId: account.accountId,

package/src/login.runtime.test.ts

@@ -112,6 +112,42 @@ describe("runOpenclawClawlingLogin", () => {
     expect(log).toHaveBeenCalledWith(expect.stringContaining("login succeeded"));
   });
 
+  it("uses the runtime config mutator with auto reload intent for config writes", async () => {
+    const cfg = buildCfg({
+      baseUrl: "https://api.example.com",
+      websocketUrl: "wss://ws.example.com/v2/client",
+    });
+    const agentsConnect = vi.fn().mockResolvedValue({
+      agent: { user_id: "agent-123", nickname: "Bot" },
+      access_token: "access-tok",
+      refresh_token: "refresh-tok",
+    });
+    let mutatedCfg: OpenClawConfig | undefined;
+    const mutateConfigFile = vi.fn(async (params) => {
+      expect(params.afterWrite).toEqual({ mode: "auto" });
+      const draft = structuredClone(cfg) as OpenClawConfig;
+      await params.mutate(draft, { snapshot: {} as never, previousHash: "before" });
+      mutatedCfg = draft;
+      return { nextConfig: draft } as never;
+    });
+
+    await runOpenclawClawlingLogin({
+      cfg,
+      runtime: { log: vi.fn() },
+      readInviteCode: async () => "INV-ABC",
+      apiClientFactory: () => makeApiClient({ agentsConnect }),
+      mutateConfigFile,
+    });
+
+    expect(mutateConfigFile).toHaveBeenCalledTimes(1);
+    const section = (mutatedCfg!.channels as Record<string, Record<string, unknown>>)[
+      CHANNEL_ID
+    ]!;
+    expect(section.token).toBe("access-tok");
+    expect(section.refreshToken).toBe("refresh-tok");
+    expect(section.userId).toBe("agent-123");
+  });
+
   it("preserves other configured channels when persisting ClawChat credentials", async () => {
     const cfg = {
       channels: {

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,14 +69,56 @@ 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:
+ * Run the invite-code credential exchange used by `clawchat_activate`,
+ * `openclaw channels add --channel openclaw-clawchat --token <invite-code>`,
+ * and `openclaw channels login --channel openclaw-clawchat`:
  *   1. Read the existing channel section; require `baseUrl` to be set so we
  *      know which server to hit.
  *   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 +166,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,32 +44,73 @@ 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.5.4");
+    expect(pkg.devDependencies.openclaw).toBe("2026.5.4");
+    expect(pkg.openclaw.install.minHostVersion).toBe(">=2026.5.4");
+  });
+
+  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("declares env-driven ClawChat channel credentials for host setup/status surfaces", () => {
+    expect(pluginManifest.channelEnvVars).toEqual({
+      "openclaw-clawchat": [
+        "CLAWCHAT_TOKEN",
+        "CLAWCHAT_USER_ID",
+        "CLAWCHAT_REFRESH_TOKEN",
+        "CLAWCHAT_BASE_URL",
+        "CLAWCHAT_WEBSOCKET_URL",
+      ],
+    });
+  });
+
+  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);
   });
 
-  it("does not document channels add as an activation path", () => {
+  it("documents channels add --token as the first-time CLI activation path", () => {
     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).not.toMatch(/channels add --channel openclaw-clawchat/i);
-    expect(docs).not.toMatch(/channels add --channel openclaw-clawchat/i);
+    expect(readme).toMatch(/openclaw channels add --channel openclaw-clawchat --token/i);
+    expect(docs).toMatch(/openclaw channels add --channel openclaw-clawchat --token/i);
   });
 
   it("publishes a ClawChat account tools skill for non-activation workflows", () => {
@@ -73,52 +127,124 @@ 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 channels-add 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/);
     expect(skill).not.toMatch(/\/clawchat-activate A1B2C3/);
     expect(skill).not.toMatch(/\/clawchat-login A1B2C3/);
-    expect(skill).toMatch(/openclaw channels login --channel openclaw-clawchat/);
-    expect(skill).toMatch(/do not append/i);
-    expect(skill).toMatch(/prompt[^\n]+invite code[^\n]+provide/i);
+    expect(skill).toMatch(/openclaw channels add --channel openclaw-clawchat --token/i);
+    expect(skill).toMatch(/first-time CLI activation/i);
+    expect(skill).toMatch(/channel add/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 channels-add 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(/openclaw channels login --channel openclaw-clawchat/i);
-    expect(docs).toMatch(/openclaw channels login --channel openclaw-clawchat/i);
+    expect(readme).toMatch(/clawchat_activate/i);
+    expect(docs).toMatch(/clawchat_activate/i);
+    expect(readme).toMatch(/openclaw channels add --channel openclaw-clawchat --token/i);
+    expect(docs).toMatch(/openclaw channels add --channel openclaw-clawchat --token/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);
+  });
+
+  it("documents gateway restart as the required next step after plugin install or update", () => {
+    const install = fs.readFileSync(new URL("../INSTALL.md", import.meta.url), "utf8");
+    const installOrUpdate = install.indexOf("## Install or Update the Plugin");
+    const activate = install.indexOf("## Activate the Channel");
+    const installSection = install.slice(installOrUpdate, activate);
+
+    expect(installSection).toMatch(
+      /After installing or updating the plugin, restart the OpenClaw Gateway\. This\s+restart is required before OpenClaw can load the installed or updated ClawChat\s+plugin\.\n\n```bash\nopenclaw gateway restart/i,
+    );
+    expect(installSection).toMatch(/openclaw gateway restart/);
+    expect(installSection).toMatch(/If restarting the Gateway interrupts the current agent\/session/i);
+    expect(installSection).toMatch(/continue from \*\*Activate the Channel\*\*/i);
+    expect(installSection).not.toMatch(/runtime imports the plugin/i);
+    expect(installSection).not.toMatch(/If the Gateway is already running/i);
+  });
+
+  it("documents activation as a direct channels-add command after restarting the Openclaw Gateway", () => {
+    const install = fs.readFileSync(new URL("../INSTALL.md", import.meta.url), "utf8");
+    const activate = install.indexOf("## Activate the Channel");
+    const verify = install.indexOf("## Verify");
+    const activateSection = install.slice(activate, verify);
+
+    expect(activateSection).toMatch(/After the OpenClaw Gateway has restarted and is reachable, activate ClawChat by\s+adding the channel with the invite code/i);
+    expect(activateSection).toMatch(/openclaw channels add --channel openclaw-clawchat --token "\$CLAWCHAT_INVITE_CODE"/);
+    expect(activateSection).toMatch(/First-time CLI activation uses `channels add`/i);
+    expect(activateSection).toMatch(/refresh\s+credentials later/i);
+    expect(activateSection).not.toMatch(/clawchat_activate/i);
+    expect(activateSection).not.toMatch(/tools are visible/i);
+    expect(activateSection).not.toMatch(/openclaw channels status --probe/i);
+    expect(activateSection).not.toMatch(/verify the channel/i);
+
+    const verifySection = install.slice(verify);
+    expect(verifySection).toMatch(/openclaw channels status --probe/i);
+    expect(verifySection).toMatch(/enabled, configured, running, and\s+connected/i);
+    expect(verifySection).toMatch(/enabled, not configured, stopped, disconnected/i);
+    expect(verifySection).toMatch(/channel hot reload/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();
   });