@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/login.runtime.ts

@@ -0,0 +1,277 @@
+import { createInterface, type Interface as ReadlineInterface } from "node:readline/promises";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+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
+ * agent runtime — openclaw's bundled clawchat channel.
+ */
+export const AGENTS_CONNECT_PLATFORM = "openclaw" as const;
+/**
+ * Agent type tag sent to `/v1/agents/connect`. The clawchat channel is
+ * always a bot; humans don't log in through this flow.
+ */
+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;
+  runtime: { log: (message: string) => void };
+  /**
+   * Override for the invite-code prompt — used by tests. Defaults to
+   * stdin via `node:readline/promises`.
+   */
+  readInviteCode?: () => Promise<string>;
+  /** Override for the HTTP client — used by tests. */
+  apiClientFactory?: typeof createOpenclawClawlingApiClient;
+  /** Official runtime config mutator. Production callers must provide this. */
+  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;
+}
+
+/**
+ * Prompt the operator for an invite code.
+ *
+ * The prompt text is emitted via `runtime.log` so it flows through the
+ * same openclaw logging pipeline every other channel plugin uses (no
+ * clack frame, no raw-mode takeover, no TTY detection). Input is read
+ * from stdin with `node:readline` — Enter-to-submit is plain language in
+ * the prompt so any upstream LLM / orchestrator reading the log stream
+ * knows a newline is expected, and the behavior is identical under a
+ * TTY, piped stdin, or a test harness.
+ */
+async function promptInviteCodeFromStdin(runtime: {
+  log: (message: string) => void;
+}): Promise<string> {
+  runtime.log("Please enter your ClawChat invite code (press Enter to submit):");
+  let rl: ReadlineInterface | undefined;
+  try {
+    rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await rl.question("> ");
+    return answer.trim();
+  } finally {
+    rl?.close();
+  }
+}
+
+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 groupCommandMode = existing.groupCommandMode === "all" || existing.groupCommandMode === "off"
+    ? existing.groupCommandMode
+    : "owner";
+  const nextSection: Record<string, unknown> = {
+    ...existing,
+    enabled: true,
+    groupMode,
+    groupCommandMode,
+    token: result.access_token,
+    ...(result.agent.id ? { agentId: result.agent.id } : {}),
+    userId: result.agent.user_id,
+    ownerUserId: result.agent.owner_id,
+  };
+  if (result.refresh_token) {
+    nextSection.refreshToken = result.refresh_token;
+  } else {
+    delete nextSection.refreshToken;
+  }
+  return mergeOpenclawClawchatRuntimePluginActivation(
+    mergeOpenclawClawchatToolAllow({
+      ...cfg,
+      channels: { ...channels, [CHANNEL_ID]: nextSection },
+    }),
+  );
+}
+
+async function persistLoginConfig(
+  params: LoginParams,
+  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: "restart",
+        reason: "clawchat-plugin-openclaw 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("clawchat-plugin-openclaw: 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`,
+ * `openclaw channels add --channel clawchat-plugin-openclaw --token <invite-code>`,
+ * and `openclaw channels login --channel clawchat-plugin-openclaw`:
+ *   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 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.
+ */
+export async function runOpenclawClawlingLogin(params: LoginParams): Promise<void> {
+  const { cfg, runtime } = params;
+
+  // `resolveOpenclawClawlingAccount` falls back to the built-in
+  // `DEFAULT_BASE_URL` / `DEFAULT_WEBSOCKET_URL` when the operator has not
+  // overridden them, so login works without a prior `openclaw channels setup --channel clawchat-plugin-openclaw`.
+  const account = resolveOpenclawClawlingAccount(cfg);
+
+  const inviteCode = (
+    await (params.readInviteCode ?? (() => promptInviteCodeFromStdin(runtime)))()
+  ).trim();
+  if (!inviteCode) {
+    throw new Error("Login aborted: invite code is required.");
+  }
+
+  const apiClient = (params.apiClientFactory ?? createOpenclawClawlingApiClient)({
+    baseUrl: account.baseUrl,
+    // Pre-login we may not have a token yet. Send the current one (or empty)
+    // — the server should accept an unauthenticated invite-code exchange.
+    token: account.token || "",
+  });
+
+  runtime.log("Verifying invite code …");
+  let result;
+  try {
+    result = await apiClient.agentsConnect({
+      code: inviteCode,
+      platform: AGENTS_CONNECT_PLATFORM,
+      type: AGENTS_CONNECT_TYPE,
+    });
+  } catch (err) {
+    if (err instanceof ClawlingApiError) {
+      throw new Error(`agents/connect failed (${err.kind}): ${err.message}`);
+    }
+    throw err;
+  }
+
+  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 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=[REDACTED] agentId=${normalizedResult.agent.id || "-"} 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, 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,
+      accessToken: normalizedResult.access_token,
+      refreshToken: normalizedResult.refresh_token || null,
+      conversationId: normalizedResult.conversation?.id ?? null,
+      loginMethod: "login",
+    });
+  } catch {
+    runtime.log("clawchat-plugin-openclaw sqlite activation persistence failed; login continues.");
+  }
+  runtime.log(`Config file updated.`);
+
+  runtime.log(
+    `clawchat-plugin-openclaw login succeeded (user_id=${normalizedResult.agent.user_id}, owner_user_id=${normalizedResult.agent.owner_id}, nickname=${normalizedResult.agent.nickname || "-"}).`,
+  );
+}

package/src/manifest.test.ts

@@ -0,0 +1,352 @@
+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_AGENT_ID_ENV,
+  CLAWCHAT_OWNER_USER_ID_ENV,
+  openclawClawlingConfigSchema,
+} from "./config.ts";
+
+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;
+    runtimeSetupEntry?: string;
+    plugin?: {
+      id: string;
+      label: string;
+    };
+    channel?: {
+      id: string;
+      label: string;
+      selectionLabel?: string;
+      docsPath?: string;
+      docsLabel?: string;
+      blurb: string;
+      order?: number;
+      aliases?: string[];
+      cliAddOptions?: Array<{ flags: string; description: string }>;
+    };
+    install: { npmSpec: string; minHostVersion: string };
+  };
+}
+
+describe("clawchat-plugin-openclaw manifest", () => {
+  it("keeps plugin id / channel id / package name aligned", () => {
+    expect(pluginManifest.id).toBe("clawchat-plugin-openclaw");
+    expect(pluginManifest.channels).toContain("clawchat-plugin-openclaw");
+    expect(pluginManifest.skills).toEqual(["./skills"]);
+    expect(pluginManifest.channelConfigs?.["clawchat-plugin-openclaw"]?.label).toBe(
+      "Clawling Chat",
+    );
+    expect(pluginManifest.channelConfigs?.["clawchat-plugin-openclaw"]?.schema?.properties).toHaveProperty(
+      "token",
+    );
+    expect(packageJson.name).toBe("@clawling/clawchat-plugin-openclaw");
+    const pkg = packageJson as PackageJsonWithOpenclaw;
+    expect(pkg.openclaw.extensions).toContain("./index.ts");
+    expect(pkg.openclaw.install.npmSpec).toBe("@clawling/clawchat-plugin-openclaw");
+  });
+
+  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.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: "clawchat-plugin-openclaw",
+      label: "Clawling Chat",
+    });
+    expect(pkg.openclaw.channel).toEqual({
+      id: "clawchat-plugin-openclaw",
+      label: "Clawling Chat",
+      selectionLabel: "Clawling Chat",
+      docsPath: "/channels/clawchat-plugin-openclaw",
+      docsLabel: "clawchat-plugin-openclaw",
+      blurb: "ClawChat Protocol v2 over WebSocket.",
+      order: 110,
+      cliAddOptions: [
+        {
+          flags: "--token <invite-code>",
+          description: "ClawChat invite code",
+        },
+      ],
+    });
+  });
+
+  it("declares supported channel/command activation hints for plugin loading", () => {
+    expect(pluginManifest.activation).toEqual({
+      onStartup: true,
+      onChannels: ["clawchat-plugin-openclaw"],
+      onCommands: ["clawchat-activate"],
+    });
+    expect(pluginManifest.commandAliases).toEqual([
+      { name: "clawchat-activate", kind: "runtime-slash" },
+    ]);
+  });
+
+  it("declares env-driven ClawChat channel credentials for host setup/status surfaces", () => {
+    expect(pluginManifest.channelEnvVars).toEqual({
+      "clawchat-plugin-openclaw": [
+        "CLAWCHAT_TOKEN",
+        CLAWCHAT_AGENT_ID_ENV,
+        "CLAWCHAT_USER_ID",
+        CLAWCHAT_OWNER_USER_ID_ENV,
+        "CLAWCHAT_REFRESH_TOKEN",
+        "CLAWCHAT_BASE_URL",
+        "CLAWCHAT_WEBSOCKET_URL",
+      ],
+    });
+  });
+
+  it("keeps host manifest channel schemas aligned with runtime config schema", () => {
+    expect(pluginManifest.configSchema).toEqual(openclawClawlingConfigSchema);
+    expect(pluginManifest.channelConfigs?.["clawchat-plugin-openclaw"]?.schema).toEqual(
+      openclawClawlingConfigSchema,
+    );
+  });
+
+  it("does not publish stream tuning in manifest config schemas", () => {
+    expect(pluginManifest.configSchema.properties).not.toHaveProperty("stream");
+    expect(
+      pluginManifest.channelConfigs?.["clawchat-plugin-openclaw"]?.schema?.properties,
+    ).not.toHaveProperty("stream");
+  });
+
+  it("keeps setup entry on a lightweight setup surface", () => {
+    const pkg = packageJson as PackageJsonWithOpenclaw;
+    expect(pkg.files).not.toContain("setup-api.ts");
+    expect(fs.existsSync(new URL("../setup-api.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 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/clawchat-plugin-openclaw.md", import.meta.url), "utf8");
+    expect(readme).not.toMatch(/clawchat_activate/i);
+    expect(docs).not.toMatch(/clawchat_activate/i);
+    expect(readme).toMatch(/\/clawchat-activate A1B2C3/i);
+    expect(docs).toMatch(/\/clawchat-activate A1B2C3/i);
+    expect(readme).toMatch(/OpenClaw 2026\.5\.5/i);
+    expect(docs).toMatch(/OpenClaw 2026\.5\.5/i);
+    expect(readme).toMatch(/Unknown channel: clawchat-plugin-openclaw/i);
+    expect(docs).toMatch(/Unknown channel: clawchat-plugin-openclaw/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 lookup instead of direct HTTP calls, shell scripts, or handwritten clients\./,
+    );
+    expect(skill).toMatch(/clawchat_get_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(/clawchat_get_conversation/);
+    expect(skill).toMatch(/For conversations\/groups, use only `clawchat_get_conversation`/);
+    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_get_account_profile",
+      "clawchat_get_user_profile",
+      "clawchat_list_account_friends",
+      "clawchat_search_users",
+      "clawchat_mention_message",
+      "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",
+      "clawchat_memory_search",
+      "clawchat_memory_read",
+      "clawchat_memory_write",
+      "clawchat_memory_edit",
+      "clawchat_metadata_sync",
+      "clawchat_metadata_update",
+    ]);
+  });
+
+  it("declares exactly the six file-backed memory and metadata tools without old-prefix aliases", () => {
+    const memoryTools = (pluginManifest.contracts?.tools ?? []).filter((name) =>
+      /memory|metadata/.test(name),
+    );
+    expect(memoryTools).toEqual([
+      "clawchat_memory_search",
+      "clawchat_memory_read",
+      "clawchat_memory_write",
+      "clawchat_memory_edit",
+      "clawchat_metadata_sync",
+      "clawchat_metadata_update",
+    ]);
+    expect(pluginManifest.contracts?.tools ?? []).not.toContain("cc_memory_read");
+    expect(pluginManifest.contracts?.tools ?? []).not.toContain("cc_metadata_sync");
+  });
+
+  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("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/clawchat-plugin-openclaw.md", import.meta.url), "utf8");
+    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-activate A1B2C3/i);
+    expect(docs).toMatch(/\/clawchat-activate A1B2C3/i);
+    expect(readme).toMatch(/openclaw channels add --channel clawchat-plugin-openclaw --token "\$CLAWCHAT_INVITE_CODE"/i);
+    expect(docs).toMatch(/openclaw channels add --channel clawchat-plugin-openclaw --token "\$CLAWCHAT_INVITE_CODE"/i);
+    expect(readme).toMatch(/openclaw channels login --channel clawchat-plugin-openclaw/i);
+    expect(docs).toMatch(/openclaw channels login --channel clawchat-plugin-openclaw/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: clawchat-plugin-openclaw/i);
+    expect(docs).toMatch(/Unknown channel: clawchat-plugin-openclaw/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(/\/clawchat_activate\s+A1B2C3/i);
+    expect(docs).not.toMatch(/\/clawchat_activate\s+A1B2C3/i);
+    expect(readme).toMatch(/runtime slash command/i);
+    expect(docs).toMatch(/runtime slash command/i);
+  });
+
+  it("documents the numbered install restart step", () => {
+    const install = fs.readFileSync(new URL("../INSTALL.md", import.meta.url), "utf8");
+    const restart = install.indexOf("## 3. Restart");
+    const activate = install.indexOf("## 4. Activate");
+    const installSection = install.slice(restart, activate);
+
+    expect(installSection).toMatch(/openclaw gateway restart/);
+    expect(installSection).toMatch(/First restart completed/);
+    expect(installSection).not.toMatch(/kill -TERM 1/);
+    expect(installSection).not.toMatch(/docker restart <container>/);
+  });
+
+  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("## 4. Activate");
+    const verify = install.indexOf("## 5. Verify");
+    const activateSection = install.slice(activate, verify);
+
+    expect(activateSection).toMatch(/openclaw channels add --channel clawchat-plugin-openclaw --token "\$CLAWCHAT_INVITE_CODE"/);
+    expect(activateSection).toMatch(/Activation completed/);
+    expect(activateSection).not.toMatch(/openclaw channels status --probe/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(/restart OpenClaw/i);
+    expect(verifySection).toMatch(/installation flow is complete/i);
+  });
+});