@newbase-clawchat/openclaw-clawchat 2026.5.4 → 2026.5.12-13

package/src/login.runtime.ts

@@ -4,9 +4,11 @@ import { createOpenclawClawlingApiClient } from "./api-client.ts";
 import { ClawlingApiError, type AgentConnectResult } from "./api-types.ts";
 import {
   CHANNEL_ID,
+  mergeOpenclawClawchatRuntimePluginActivation,
   mergeOpenclawClawchatToolAllow,
   resolveOpenclawClawlingAccount,
 } from "./config.ts";
+import { getClawChatStore, type ClawChatStore } from "./storage.ts";
 
 /**
  * Platform tag sent to `/v1/agents/connect`. Identifies the host of this
@@ -42,6 +44,10 @@ export interface LoginParams {
   mutateConfigFile?: OpenclawClawchatMutateConfigFile;
   /** Test-only config persistence override. */
   persistConfig?: (cfg: OpenClawConfig) => Promise<void> | void;
+  /** Test/runtime override for best-effort activation persistence. */
+  store?: Pick<ClawChatStore, "upsertActivation">;
+  /** Optional database path resolved by the host runtime. */
+  dbPath?: string;
 }
 
 /**
@@ -72,19 +78,28 @@ 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 groupMode = existing.groupMode === "mention" || existing.groupMode === "all"
+    ? existing.groupMode
+    : "all";
   const nextSection: Record<string, unknown> = {
     ...existing,
     enabled: true,
+    groupMode,
     token: result.access_token,
     userId: result.agent.user_id,
+    ownerUserId: result.agent.owner_id,
   };
   if (result.refresh_token) {
     nextSection.refreshToken = result.refresh_token;
+  } else {
+    delete nextSection.refreshToken;
   }
-  return mergeOpenclawClawchatToolAllow({
-    ...cfg,
-    channels: { ...channels, [CHANNEL_ID]: nextSection },
-  });
+  return mergeOpenclawClawchatRuntimePluginActivation(
+    mergeOpenclawClawchatToolAllow({
+      ...cfg,
+      channels: { ...channels, [CHANNEL_ID]: nextSection },
+    }),
+  );
 }
 
 async function persistLoginConfig(
@@ -92,25 +107,58 @@ async function persistLoginConfig(
   result: AgentConnectResult,
 ): Promise<void> {
   if (params.mutateConfigFile) {
+    params.runtime.log(
+      `Persisting ClawChat credentials and plugin activation for userId=${result.agent.user_id} ownerUserId=${result.agent.owner_id} with Gateway restart intent.`,
+    );
     await params.mutateConfigFile({
-      afterWrite: { mode: "auto" },
+      afterWrite: {
+        mode: "restart",
+        reason: "openclaw-clawchat credentials changed",
+      },
       mutate(draft) {
         Object.assign(draft, buildLoginConfig(draft, result));
       },
     });
+    params.runtime.log(
+      `ClawChat credentials and plugin activation persisted for userId=${result.agent.user_id} ownerUserId=${result.agent.owner_id}.`,
+    );
     return;
   }
 
   if (params.persistConfig) {
+    params.runtime.log(
+      `Persisting ClawChat credentials and plugin activation for userId=${result.agent.user_id} ownerUserId=${result.agent.owner_id}.`,
+    );
     await params.persistConfig(buildLoginConfig(params.cfg, result));
+    params.runtime.log(
+      `ClawChat credentials and plugin activation persisted for userId=${result.agent.user_id} ownerUserId=${result.agent.owner_id}.`,
+    );
     return;
   }
 
   throw new Error("openclaw-clawchat: mutateConfigFile is required to persist login credentials");
 }
 
+function requireConnectString(value: unknown, fieldName: string): string {
+  if (typeof value !== "string") {
+    throw new Error(`agents/connect response missing required fields (${fieldName})`);
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new Error(`agents/connect response missing required fields (${fieldName})`);
+  }
+  return trimmed;
+}
+
+function readOptionalConnectString(value: unknown, fieldName: string): string | undefined {
+  if (value == null) {
+    return undefined;
+  }
+  return requireConnectString(value, fieldName);
+}
+
 /**
- * Run the invite-code credential exchange used by `clawchat_activate`,
+ * Run the invite-code credential exchange used by `/clawchat-login`,
  * `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
@@ -160,29 +208,63 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
     throw err;
   }
 
-  if (!result?.access_token || !result?.agent?.user_id) {
-    throw new Error(
-      `agents/connect response missing required fields (access_token / agent.user_id): ${JSON.stringify(result)}`,
-    );
+  const accessToken = requireConnectString(result?.access_token, "access_token");
+  const agentUserId = requireConnectString(result?.agent?.user_id, "agent.user_id");
+  const ownerUserId = requireConnectString(result?.agent?.owner_id, "agent.owner_id");
+  const agentId = readOptionalConnectString(result?.agent?.id, "agent.id");
+
+  let conversationId: string | null = null;
+  if (result?.conversation != null) {
+    conversationId = requireConnectString(result.conversation.id, "conversation.id");
   }
 
-  const tokenPreview = redactToken(result.access_token);
+  const normalizedResult: AgentConnectResult = {
+    ...result,
+    access_token: accessToken,
+    refresh_token: typeof result?.refresh_token === "string" ? result.refresh_token.trim() : "",
+    agent: {
+      ...result.agent,
+      ...(agentId ? { id: agentId } : {}),
+      owner_id: ownerUserId,
+      user_id: agentUserId,
+    },
+    ...(conversationId
+      ? {
+          conversation: {
+            ...result.conversation,
+            id: conversationId,
+          },
+        }
+      : {}),
+  };
+
   runtime.log(
-    `Updating config: channels.${CHANNEL_ID}.token=${tokenPreview} userId=${result.agent.user_id}${
-      result.refresh_token ? " refreshToken=***" : ""
-    } …`,
+    `Updating config: channels.${CHANNEL_ID}.token=[REDACTED] userId=${normalizedResult.agent.user_id} ownerUserId=${normalizedResult.agent.owner_id}${
+      normalizedResult.refresh_token ? " refreshToken=[REDACTED]" : ""
+    } plugins.entries.${CHANNEL_ID}.enabled=true plugins.allow+=${CHANNEL_ID} …`,
   );
-  await persistLoginConfig(params, result);
+  await persistLoginConfig(params, normalizedResult);
+  try {
+    const store =
+      params.store ??
+      getClawChatStore({
+        ...(params.dbPath ? { dbPath: params.dbPath } : {}),
+        log: { error: runtime.log },
+      });
+    store.upsertActivation({
+      platform: "openclaw",
+      accountId: account.accountId,
+      userId: normalizedResult.agent.user_id,
+      ownerUserId: normalizedResult.agent.owner_id,
+      conversationId: normalizedResult.conversation?.id ?? null,
+      loginMethod: "login",
+    });
+  } catch {
+    runtime.log("openclaw-clawchat sqlite activation persistence failed; login continues.");
+  }
   runtime.log(`Config file updated.`);
 
   runtime.log(
-    `openclaw-clawchat login succeeded (user_id=${result.agent.user_id}, nickname=${result.agent.nickname || "-"}).`,
+    `openclaw-clawchat login succeeded (user_id=${normalizedResult.agent.user_id}, owner_user_id=${normalizedResult.agent.owner_id}, nickname=${normalizedResult.agent.nickname || "-"}).`,
   );
 }
-
-/** Shortens a token for display logs without revealing the full secret. */
-function redactToken(token: string): string {
-  if (!token) return "(empty)";
-  if (token.length <= 8) return "***";
-  return `${token.slice(0, 4)}…${token.slice(-4)}`;
-}

package/src/manifest.test.ts

@@ -2,6 +2,10 @@ import fs from "node:fs";
 import { describe, expect, it } from "vitest";
 import pluginManifest from "../openclaw.plugin.json" with { type: "json" };
 import packageJson from "../package.json" with { type: "json" };
+import {
+  CLAWCHAT_OWNER_USER_ID_ENV,
+  openclawClawlingConfigSchema,
+} from "./config.ts";
 
 interface PackageJsonWithOpenclaw {
   name: string;
@@ -13,6 +17,11 @@ interface PackageJsonWithOpenclaw {
     extensions: string[];
     runtimeExtensions?: string[];
     setupEntry?: string;
+    runtimeSetupEntry?: string;
+    plugin?: {
+      id: string;
+      label: string;
+    };
     channel?: {
       id: string;
       label: string;
@@ -22,6 +31,7 @@ interface PackageJsonWithOpenclaw {
       blurb: string;
       order?: number;
       aliases?: string[];
+      cliAddOptions?: Array<{ flags: string; description: string }>;
     };
     install: { npmSpec: string; minHostVersion: string };
   };
@@ -31,7 +41,7 @@ describe("openclaw-clawchat manifest", () => {
   it("keeps plugin id / channel id / package name aligned", () => {
     expect(pluginManifest.id).toBe("openclaw-clawchat");
     expect(pluginManifest.channels).toContain("openclaw-clawchat");
-    expect(pluginManifest.skills).toContain("./skills");
+    expect(pluginManifest.skills).toEqual(["./skills"]);
     expect(pluginManifest.channelConfigs?.["openclaw-clawchat"]?.label).toBe(
       "Clawling Chat",
     );
@@ -55,22 +65,38 @@ describe("openclaw-clawchat manifest", () => {
     const pkg = packageJson as PackageJsonWithOpenclaw;
     expect(pkg.openclaw.extensions).toEqual(["./index.ts"]);
     expect(pkg.openclaw.runtimeExtensions).toEqual(["./dist/index.js"]);
+    expect(pkg.openclaw.setupEntry).toBe("./setup-entry.ts");
+    expect(pkg.openclaw.runtimeSetupEntry).toBe("./dist/setup-entry.js");
     expect(pkg.files).toContain("dist");
+    expect(pkg.files).toContain("setup-entry.ts");
+    expect(pkg.files).toContain("skills");
+    expect(pkg.files).toContain("INSTALL.md");
     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);
+    expect(fs.existsSync(new URL("../setup-entry.ts", import.meta.url))).toBe(true);
   });
 
   it("publishes channel catalog metadata for OpenClaw CLI discovery", () => {
     const pkg = packageJson as PackageJsonWithOpenclaw;
+    expect(pkg.openclaw.plugin).toEqual({
+      id: "openclaw-clawchat",
+      label: "Clawling Chat",
+    });
     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).",
+      blurb: "ClawChat Protocol v2 over WebSocket.",
       order: 110,
+      cliAddOptions: [
+        {
+          flags: "--token <invite-code>",
+          description: "ClawChat invite code",
+        },
+      ],
     });
   });
 
@@ -90,6 +116,7 @@ describe("openclaw-clawchat manifest", () => {
       "openclaw-clawchat": [
         "CLAWCHAT_TOKEN",
         "CLAWCHAT_USER_ID",
+        CLAWCHAT_OWNER_USER_ID_ENV,
         "CLAWCHAT_REFRESH_TOKEN",
         "CLAWCHAT_BASE_URL",
         "CLAWCHAT_WEBSOCKET_URL",
@@ -97,42 +124,105 @@ describe("openclaw-clawchat manifest", () => {
     });
   });
 
-  it("does not publish setup migration or setup-runtime entry metadata", () => {
+  it("keeps host manifest channel schemas aligned with runtime config schema", () => {
+    expect(pluginManifest.configSchema).toEqual(openclawClawlingConfigSchema);
+    expect(pluginManifest.channelConfigs?.["openclaw-clawchat"]?.schema).toEqual(
+      openclawClawlingConfigSchema,
+    );
+  });
+
+  it("keeps setup entry on a lightweight setup surface", () => {
     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(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);
+    const setupEntry = fs.readFileSync(new URL("../setup-entry.ts", import.meta.url), "utf8");
+    expect(setupEntry).toMatch(/defineSetupPluginEntry/);
+    expect(setupEntry).toMatch(/openclawClawlingSetupPlugin/);
+    expect(setupEntry).not.toMatch(/\.\/src\/channel\.ts/);
+    expect(setupEntry).not.toMatch(/\.\/src\/runtime(?:\.ts)?/);
+    expect(setupEntry).not.toMatch(/\.\/src\/outbound(?:\.ts)?/);
+  });
+
+  it("uses the OpenClaw channel entry helper for registration-mode splitting", () => {
+    const entry = fs.readFileSync(new URL("../index.ts", import.meta.url), "utf8");
+    expect(entry).toMatch(/defineChannelPluginEntry/);
+    expect(entry).toMatch(/registerFull/);
+    expect(entry).toMatch(/registerOpenclawClawlingCommands/);
+    expect(entry).toMatch(/registerOpenclawClawlingTools/);
+    expect(entry).not.toMatch(/register\(api: OpenClawPluginApi\)/);
   });
 
-  it("documents channels add --token as the first-time CLI activation path", () => {
+  it("documents runtime activation as the reliable first-time 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).toMatch(/openclaw channels add --channel openclaw-clawchat --token/i);
-    expect(docs).toMatch(/openclaw channels add --channel openclaw-clawchat --token/i);
+    expect(readme).not.toMatch(/clawchat_activate/i);
+    expect(docs).not.toMatch(/clawchat_activate/i);
+    expect(readme).toMatch(/\/clawchat-login A1B2C3/i);
+    expect(docs).toMatch(/\/clawchat-login A1B2C3/i);
+    expect(readme).toMatch(/OpenClaw 2026\.5\.5/i);
+    expect(docs).toMatch(/OpenClaw 2026\.5\.5/i);
+    expect(readme).toMatch(/Unknown channel: openclaw-clawchat/i);
+    expect(docs).toMatch(/Unknown channel: openclaw-clawchat/i);
   });
 
-  it("publishes a ClawChat account tools skill for non-activation workflows", () => {
-    const skill = fs.readFileSync(new URL("../skills/clawchat-account-tools/SKILL.md", import.meta.url), "utf8");
-    expect(skill).toMatch(/^---\nname: clawchat-account-tools\n/m);
-    expect(skill).toMatch(/description: .*Use when/i);
+  it("publishes the repository-provided ClawChat skill", () => {
+    const pkg = packageJson as PackageJsonWithOpenclaw;
+    expect(pluginManifest.skills).toEqual(["./skills"]);
+    expect(pkg.files).toContain("skills");
+
+    const skillUrl = new URL("../skills/clawchat/SKILL.md", import.meta.url);
+    expect(fs.existsSync(skillUrl)).toBe(true);
+    const skill = fs.readFileSync(skillUrl, "utf8");
+    expect(skill).toMatch(
+      /^---\nname: clawchat\ndescription: Use when a request involves ClawChat profile, friends, user search, moments\/dynamics, comments, reactions, avatar, media, or read-only conversation lookup\.\n---/m,
+    );
+    expect(skill).toMatch(
+      /This skill guides agent behavior for ClawChat-aware tasks\. Use the registered ClawChat tools for profile, friends, user search, moments, comments, reactions, avatar, media, and read-only conversation list\/get operations instead of direct HTTP calls, shell scripts, or handwritten clients\./,
+    );
     expect(skill).toMatch(/clawchat_get_account_profile/);
-    expect(skill).toMatch(/clawchat_get_user_profile/);
-    expect(skill).toMatch(/clawchat_list_account_friends/);
-    expect(skill).toMatch(/clawchat_update_account_profile/);
+    expect(skill).toMatch(/clawchat_search_users/);
     expect(skill).toMatch(/clawchat_upload_avatar_image/);
     expect(skill).toMatch(/clawchat_upload_media_file/);
-    expect(skill).toMatch(/configured ClawChat account/i);
-    expect(skill).not.toMatch(/clawchat_activate/);
+    expect(skill).toMatch(/clawchat_list_conversations/);
+    expect(skill).toMatch(/clawchat_get_conversation/);
+    expect(skill).toMatch(/conversations?\/groups?.*read-only/i);
+    expect(skill).not.toMatch(
+      /conversations?\/groups?.*(?:create|update|leave|dissolve|add members|remove members|administer)/i,
+    );
+    expect(skill).not.toMatch(/clawchat_create_group_conversation/);
+    expect(skill).not.toMatch(/clawchat_update_conversation/);
+    expect(skill).not.toMatch(/clawchat_leave_conversation/);
+    expect(skill).not.toMatch(/clawchat_dissolve_conversation/);
+    expect(skill).not.toMatch(/clawchat_add_conversation_member/);
+    expect(skill).not.toMatch(/clawchat_remove_conversation_member/);
+    expect(skill).not.toMatch(/clawchat_list_conversation_users/);
+    expect(skill).toMatch(/## Profile And Identity Sync/);
+    expect(skill).toMatch(/When updating the OpenClaw agent identity file/);
+    expect(skill).toMatch(/display name \/ nickname \| `clawchat_update_account_profile` with `nickname`/);
+    expect(skill).toMatch(/bio \/ self-introduction \| `clawchat_update_account_profile` with `bio`/);
+    expect(skill).toMatch(/local avatar image \| `clawchat_upload_avatar_image`, then `clawchat_update_account_profile` with `avatar_url`/);
+    expect(skill).toMatch(/Do not invent invite codes, tokens, moment ids, comment ids, user ids, emoji reactions, image URLs, or file paths/);
+    expect(skill).not.toMatch(/hermes/i);
+    expect(skill).not.toMatch(/target hermes/i);
+    expect(skill).not.toMatch(/choosing among registered clawchat_\*/);
+    expect(skill).not.toMatch(/\b(?:whe|regis|plu)\s*$/m);
   });
 
   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_search_users",
+      "clawchat_list_conversations",
+      "clawchat_get_conversation",
+      "clawchat_list_moments",
+      "clawchat_create_moment",
+      "clawchat_delete_moment",
+      "clawchat_toggle_moment_reaction",
+      "clawchat_create_moment_comment",
+      "clawchat_reply_moment_comment",
+      "clawchat_delete_moment_comment",
       "clawchat_update_account_profile",
       "clawchat_upload_avatar_image",
       "clawchat_upload_media_file",
@@ -167,84 +257,66 @@ describe("openclaw-clawchat manifest", () => {
     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).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 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(/restart[^\n]+only when/i);
-  });
-
-  it("documents clawchat_activate as the natural-language activation path with channels-add CLI fallback", () => {
+  it("documents slash command as the chat 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).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(/Current activation paths/i);
+    expect(docs).toMatch(/Current activation paths/i);
+    expect(readme).not.toMatch(/clawchat_activate/i);
+    expect(docs).not.toMatch(/clawchat_activate/i);
+    expect(readme).toMatch(/\/clawchat-login A1B2C3/i);
+    expect(docs).toMatch(/\/clawchat-login A1B2C3/i);
+    expect(readme).toMatch(/openclaw channels add --channel openclaw-clawchat --token "\$CLAWCHAT_INVITE_CODE"/i);
+    expect(docs).toMatch(/openclaw channels add --channel openclaw-clawchat --token "\$CLAWCHAT_INVITE_CODE"/i);
+    expect(readme).toMatch(/openclaw channels login --channel openclaw-clawchat/i);
+    expect(docs).toMatch(/openclaw channels login --channel openclaw-clawchat/i);
+    expect(readme).toMatch(/refresh credentials/i);
+    expect(docs).toMatch(/refresh credentials/i);
+    expect(readme).toMatch(/OpenClaw 2026\.5\.5/i);
+    expect(docs).toMatch(/OpenClaw 2026\.5\.5/i);
+    expect(readme).toMatch(/Unknown channel: openclaw-clawchat/i);
+    expect(docs).toMatch(/Unknown 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\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(readme).toMatch(/activation skill calls/i);
-    expect(docs).toMatch(/Natural-language activation requests should call `clawchat_activate`/i);
+    expect(readme).toMatch(/runtime slash command/i);
+    expect(docs).toMatch(/runtime slash command/i);
   });
 
-  it("documents gateway restart as the required next step after plugin install or update", () => {
+  it("documents the numbered install restart step", () => {
     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);
+    const restart = install.indexOf("## 3. Restart");
+    const activate = install.indexOf("## 4. Activate");
+    const installSection = install.slice(restart, 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);
+    expect(installSection).toMatch(/First restart completed/);
+    expect(installSection).not.toMatch(/kill -TERM 1/);
+    expect(installSection).not.toMatch(/docker restart <container>/);
   });
 
-  it("documents activation as a direct channels-add command after restarting the Openclaw Gateway", () => {
+  it("documents numbered CLI activation, hot reload verification, and restart fallback", () => {
     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 activate = install.indexOf("## 4. Activate");
+    const verify = install.indexOf("## 5. 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).toMatch(/Activation completed/);
     expect(activateSection).not.toMatch(/openclaw channels status --probe/i);
-    expect(activateSection).not.toMatch(/verify the channel/i);
+    expect(activateSection).not.toMatch(/openclaw gateway restart/i);
+    expect(install).not.toMatch(/## 5\. Restart Again/i);
+    expect(install).not.toMatch(/Second restart completed/);
 
     const verifySection = install.slice(verify);
+    expect(verifySection).toMatch(/sleep 5/);
     expect(verifySection).toMatch(/openclaw channels status --probe/i);
+    expect(verifySection).toMatch(/Verification completed/);
     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);
+    expect(verifySection).toMatch(/restart OpenClaw/i);
+    expect(verifySection).toMatch(/installation flow is complete/i);
   });
 });

package/src/media-runtime.test.ts

@@ -85,7 +85,9 @@ describe("uploadOutboundMedia", () => {
   function buildApiClient() {
     return {
       uploadMedia: vi.fn().mockResolvedValue({
+        kind: "image",
         url: "https://cdn/uploaded.png",
+        name: "uploaded.png",
         size: 12,
         mime: "image/png",
       }),
@@ -118,18 +120,71 @@ describe("uploadOutboundMedia", () => {
         url: "https://cdn/uploaded.png",
         mime: "image/png",
         size: 12,
-        name: "img.png",
+        name: "uploaded.png",
       },
       {
         kind: "image",
         url: "https://cdn/uploaded.png",
         mime: "image/png",
         size: 12,
-        name: "img.png",
+        name: "uploaded.png",
+      },
+    ]);
+  });
+
+  it("uses server-returned kind and name for uploaded media fragments", async () => {
+    const { runtime } = buildRuntime();
+    const apiClient = buildApiClient();
+    (apiClient.uploadMedia as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      kind: "file",
+      url: "https://cdn/server.bin",
+      name: "server.bin",
+      size: 12,
+      mime: "image/png",
+    });
+
+    const fragments = await uploadOutboundMedia(["https://cdn/in.png"], {
+      apiClient,
+      runtime,
+    });
+
+    expect(fragments).toEqual([
+      {
+        kind: "file",
+        url: "https://cdn/server.bin",
+        mime: "image/png",
+        size: 12,
+        name: "server.bin",
       },
     ]);
   });
 
+  it("passes host media access options to loadWebMedia", async () => {
+    const { runtime, loadWebMedia } = buildRuntime();
+    const apiClient = buildApiClient();
+    const readFile = vi.fn(async () => Buffer.from("host-read"));
+
+    await uploadOutboundMedia(["relative/image.png"], {
+      apiClient,
+      runtime,
+      mediaAccess: {
+        localRoots: ["/workspace"],
+        readFile,
+        workspaceDir: "/workspace",
+      },
+    });
+
+    expect(loadWebMedia).toHaveBeenCalledWith(
+      "relative/image.png",
+      expect.objectContaining({
+        localRoots: ["/workspace"],
+        readFile,
+        hostReadCapability: true,
+        workspaceDir: "/workspace",
+      }),
+    );
+  });
+
   it("drops a single failed upload, returns the rest", async () => {
     const { runtime } = buildRuntime();
     const apiClient = buildApiClient();