@newbase-clawchat/openclaw-clawchat 2026.4.30 → 2026.5.4

package/README.md

@@ -10,7 +10,7 @@ OpenClaw channel plugin that connects an agent to ClawChat over the ClawChat Pro
 - Outbound text replies in `static` or `stream` mode, with a consolidated final `message.reply`
 - Typing indicators and filtered forwarding for thinking / tool-call content
 - Media fragments (image / file / audio / video) in either direction
-- Invite-code onboarding via `clawchat_activate` or channel login, plus always-registered `clawchat_*` account/media tools
+- Invite-code onboarding via `clawchat_activate` or `channels add --token`, plus always-registered `clawchat_*` account/media tools
 
 ## Install
 
@@ -19,7 +19,7 @@ OpenClaw channel plugin that connects an agent to ClawChat over the ClawChat Pro
 npm i @newbase-clawchat/openclaw-clawchat
 ```
 
-Requires `openclaw >= 2026.4.29` as a peer host.
+Requires `openclaw >= 2026.5.4` as a peer host.
 
 For the OpenClaw plugin install/update flow, see [`INSTALL.md`](./INSTALL.md).
 
@@ -39,11 +39,12 @@ activate ClawChat with invite code A1B2C3
 
 If the plugin is already loaded by the Gateway, the activation skill calls the
 `clawchat_activate` tool and OpenClaw hot-reloads the updated `channels.*`
-credentials. If the tool is not available yet, use channel login as the CLI
-fallback:
+credentials. If the tool is not available yet, use `channels add` as the
+first-time CLI activation path:
 
 ```bash
-openclaw channels login --channel openclaw-clawchat
+CLAWCHAT_INVITE_CODE="A1B2C3"
+openclaw channels add --channel openclaw-clawchat --token "$CLAWCHAT_INVITE_CODE"
 openclaw channels status --probe
 ```
 
@@ -55,15 +56,17 @@ openclaw gateway restart
 ```
 
 If you run the gateway manually instead of as a service and it is not already
-running, start it after login:
+running, start it after activation:
 
 ```bash
 openclaw gateway run
 ```
 
-The invite code is not a token; token fields are written only after login. The
+The `--token` value above is the ClawChat invite code for OpenClaw's generic
+`channels add` CLI surface; persisted token fields are written only after the
+invite code exchange succeeds. The
 plugin registers `clawchat_activate` and the six account/media tools at plugin
-load time so they stay visible before activation. Before login, account/media
+load time so they stay visible before activation. Before activation, account/media
 tools return a config error instead of disappearing; after activation/login, the
 channel is enabled and the same tools read the hot-reloaded token/userId.
 

package/dist/src/channel.js

@@ -32,9 +32,9 @@ const configAdapter = createTopLevelChannelConfigAdapter({
  * one-shot setup metadata because current hosts do not discover channels from
  * `plugins.load.paths`.
  *
- * Setup takes exactly ONE input: `code` (an invite code). URL + token +
- * userId come from the login flow which is triggered automatically in
- * `afterAccountConfigWritten`.
+ * Setup takes an invite code from `code` or from OpenClaw's generic
+ * `channels add --token` input. URL + token + userId come from the login flow
+ * which is triggered automatically in `afterAccountConfigWritten`.
  *
  * `applyAccountConfig` itself only marks the section `enabled: true`;
  * credentials are written by `runOpenclawClawlingLogin` via the runtime config
@@ -43,7 +43,12 @@ const configAdapter = createTopLevelChannelConfigAdapter({
 const setupAdapter = {
     resolveAccountId: () => DEFAULT_ACCOUNT_ID,
     validateInput: ({ input }) => {
-        if (!input.code?.trim()) {
+        const inviteCode = typeof input.code === "string" && input.code.trim()
+            ? input.code.trim()
+            : typeof input.token === "string"
+                ? input.token.trim()
+                : "";
+        if (!inviteCode) {
             return "ClawChat invite code is required.";
         }
         return null;
@@ -62,7 +67,11 @@ const setupAdapter = {
         });
     },
     afterAccountConfigWritten: async ({ cfg, input, runtime, }) => {
-        const code = input.code?.trim();
+        const code = typeof input.code === "string" && input.code.trim()
+            ? input.code.trim()
+            : typeof input.token === "string"
+                ? input.token.trim()
+                : "";
         if (!code)
             return;
         // Lazy-import the login runtime to keep @clack/prompts / readline /

package/dist/src/config.js

@@ -1,5 +1,10 @@
 import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
 export const CHANNEL_ID = "openclaw-clawchat";
+export const CLAWCHAT_TOKEN_ENV = "CLAWCHAT_TOKEN";
+export const CLAWCHAT_USER_ID_ENV = "CLAWCHAT_USER_ID";
+export const CLAWCHAT_REFRESH_TOKEN_ENV = "CLAWCHAT_REFRESH_TOKEN";
+export const CLAWCHAT_BASE_URL_ENV = "CLAWCHAT_BASE_URL";
+export const CLAWCHAT_WEBSOCKET_URL_ENV = "CLAWCHAT_WEBSOCKET_URL";
 /**
  * Built-in defaults for the Clawling Chat endpoints so `openclaw channel
  * login` works out of the box without requiring a prior `openclaw channel
@@ -134,6 +139,9 @@ function readChannelSection(cfg) {
 function readOptionalString(value) {
     return typeof value === "string" ? value.trim() : "";
 }
+function readEnvString(env, key) {
+    return readOptionalString(env[key]);
+}
 function readReplyMode(value) {
     return value === "stream" ? "stream" : "static";
 }
@@ -175,13 +183,17 @@ function readAck(raw) {
             : DEFAULT_ACK.autoResendOnTimeout,
     };
 }
-export function resolveOpenclawClawlingAccount(cfg) {
+export function resolveOpenclawClawlingAccount(cfg, env = process.env) {
     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);

package/dist/src/login.runtime.js

@@ -69,7 +69,9 @@ async function persistLoginConfig(params, result) {
     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.

package/dist/src/tools.js

@@ -118,8 +118,8 @@ export function registerOpenclawClawlingTools(api) {
     function buildClient() {
         const acct = resolveCurrent();
         // `baseUrl` always resolves via the built-in default in config.ts, so we
-        // only need to gate on `token` here (which is populated by `openclaw
-        // channel login`).
+        // only need to gate on `token` here (which is populated by ClawChat
+        // activation/login).
         if (!acct.token) {
             return { ok: false, error: configError("openclaw-clawchat: token is required") };
         }

package/openclaw.plugin.json

@@ -7,6 +7,15 @@
     "onChannels": ["openclaw-clawchat"],
     "onCommands": ["clawchat-login"]
   },
+  "channelEnvVars": {
+    "openclaw-clawchat": [
+      "CLAWCHAT_TOKEN",
+      "CLAWCHAT_USER_ID",
+      "CLAWCHAT_REFRESH_TOKEN",
+      "CLAWCHAT_BASE_URL",
+      "CLAWCHAT_WEBSOCKET_URL"
+    ]
+  },
   "commandAliases": [
     { "name": "clawchat-login", "kind": "runtime-slash" }
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newbase-clawchat/openclaw-clawchat",
-  "version": "2026.4.30",
+  "version": "2026.5.4",
   "description": "OpenClaw ClawChat channel plugin",
   "files": [
     "dist",
@@ -15,6 +15,8 @@
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest",
     "test:e2e:install-clawchat-plugin": "bash .e2e/run-install-clawchat-plugin-e2e.sh",
+    "test:e2e:install-clawchat-plugin:agent": "bash .e2e/run-install-clawchat-plugin-agent-e2e.sh",
+    "test:e2e:install-clawchat-plugin:agent:smoke": "node --test .e2e/run-install-clawchat-plugin-agent-e2e.test.mjs",
     "test:e2e:install-clawchat-plugin:smoke": "node --test .e2e/run-install-clawchat-plugin-e2e.test.mjs",
     "dev:openclaw-source": "test -d tmp/openclaw || git clone --depth=1 https://github.com/openclaw/openclaw.git tmp/openclaw",
     "prepack": "npm run build",
@@ -28,12 +30,12 @@
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
-    "openclaw": "2026.4.29",
+    "openclaw": "2026.5.4",
     "typescript": "^5.4.0",
     "vitest": "^4.1.5"
   },
   "peerDependencies": {
-    "openclaw": "^2026.4.29"
+    "openclaw": ">=2026.5.4"
   },
   "peerDependenciesMeta": {
     "openclaw": {
@@ -62,7 +64,7 @@
     "install": {
       "npmSpec": "@newbase-clawchat/openclaw-clawchat",
       "defaultChoice": "npm",
-      "minHostVersion": ">=2026.4.29"
+      "minHostVersion": ">=2026.5.4"
     }
   }
 }

package/skills/clawchat-activate/SKILL.md

@@ -8,20 +8,20 @@ description: |
 
 Activation should use the `clawchat_activate` tool when that tool is available. The tool runs the same invite-code login runtime as OpenClaw channel login and persists credentials into `channels.openclaw-clawchat`.
 
-If the tool is not available because the Gateway has not loaded this plugin yet, fall back to OpenClaw channel login. Do not edit config files manually and do not try to execute slash commands from this skill.
+If the tool is not available because the Gateway has not loaded this plugin yet, fall back to OpenClaw channel add for first-time CLI activation. Do not edit config files manually and do not try to execute slash commands from this skill.
 
 ## Workflow
 
 1. Check whether the user is trying to activate or log in ClawChat.
 2. If `clawchat_activate` is available and the invite code is known, call it with the invite code.
 3. If the invite code is not known, ask the user for it before calling `clawchat_activate`.
-4. If `clawchat_activate` is not available, execute the channel login command:
+4. If `clawchat_activate` is not available, execute the channel add command with the invite code:
 
 ```bash
-openclaw channels login --channel openclaw-clawchat
+openclaw channels add --channel openclaw-clawchat --token "$CLAWCHAT_INVITE_CODE"
 ```
-5. Do not append the invite code to the command; `openclaw channels login` has no code argument.
-6. When the command prompts for an invite code, provide the user's invite code if one was already present, otherwise ask the user for it.
+5. `channels add --token` is the first-time CLI activation path; the token argument is the ClawChat invite code on this setup path.
+6. Use `openclaw channels login --channel openclaw-clawchat` only to refresh credentials later after the channel already exists.
 7. After activation succeeds, rely on OpenClaw's `channels.*` config hot reload when the plugin is already loaded. Verify channel status if available:
 
 ```bash
@@ -32,7 +32,7 @@ openclaw channels status --probe
 ```bash
 openclaw gateway restart
 ```
-9. Tell the user activation completes after login succeeds and either config hot reload/probe succeeds or Gateway restart succeeds.
+9. Tell the user activation completes after channel add/login succeeds and either config hot reload/probe succeeds or Gateway restart succeeds.
 
 ## Trigger Examples
 
@@ -42,6 +42,6 @@ openclaw gateway restart
 - `绑定 ClawChat，邀请码 A1B2C3`
 - `激活 ClawChat`
 
-Do not ask the user to enter a bare ClawChat command. If activation is requested and `clawchat_activate` is available, call that tool yourself. If the tool is unavailable, execute `openclaw channels login --channel openclaw-clawchat` yourself, then probe channel status and restart the Gateway only when needed.
+Do not ask the user to enter a bare ClawChat command. If activation is requested and `clawchat_activate` is available, call that tool yourself. If the tool is unavailable, execute `openclaw channels add --channel openclaw-clawchat --token "$CLAWCHAT_INVITE_CODE"` yourself, then probe channel status and restart the Gateway only when needed.
 
-When the user asks to activate ClawChat without including a code, ask for the invite code before calling `clawchat_activate`; if falling back to channel login, provide the code when the command needs it.
+When the user asks to activate ClawChat without including a code, ask for the invite code before calling `clawchat_activate` or falling back to channel add.

package/src/channel.test.ts

@@ -28,9 +28,12 @@ describe("openclaw-clawchat plugin", () => {
     expect(
       validate!({ cfg: {}, accountId: "default", input: { code: "  " } }),
     ).toMatch(/invite code is required/i);
+    expect(
+      validate!({ cfg: {}, accountId: "default", input: { token: "  " } }),
+    ).toMatch(/invite code is required/i);
   });
 
-  it("setup.validateInput passes when code is present", () => {
+  it("setup.validateInput passes when code or token is present", () => {
     const validate = openclawClawlingPlugin.setup?.validateInput as (args: {
       cfg: unknown;
       accountId: string;
@@ -39,6 +42,9 @@ describe("openclaw-clawchat plugin", () => {
     expect(
       validate({ cfg: {}, accountId: "default", input: { code: "INV-XXXX" } }),
     ).toBeNull();
+    expect(
+      validate({ cfg: {}, accountId: "default", input: { token: "INV-XXXX" } }),
+    ).toBeNull();
   });
 
   it("setup.applyAccountConfig marks the channel enabled without touching credentials", () => {

package/src/channel.ts

@@ -50,9 +50,9 @@ const configAdapter = createTopLevelChannelConfigAdapter<ResolvedOpenclawClawlin
  * one-shot setup metadata because current hosts do not discover channels from
  * `plugins.load.paths`.
  *
- * Setup takes exactly ONE input: `code` (an invite code). URL + token +
- * userId come from the login flow which is triggered automatically in
- * `afterAccountConfigWritten`.
+ * Setup takes an invite code from `code` or from OpenClaw's generic
+ * `channels add --token` input. URL + token + userId come from the login flow
+ * which is triggered automatically in `afterAccountConfigWritten`.
  *
  * `applyAccountConfig` itself only marks the section `enabled: true`;
  * credentials are written by `runOpenclawClawlingLogin` via the runtime config
@@ -61,7 +61,13 @@ const configAdapter = createTopLevelChannelConfigAdapter<ResolvedOpenclawClawlin
 const setupAdapter = {
   resolveAccountId: () => DEFAULT_ACCOUNT_ID,
   validateInput: ({ input }: { cfg: unknown; accountId: string; input: ChannelSetupInput }) => {
-    if (!input.code?.trim()) {
+    const inviteCode =
+      typeof input.code === "string" && input.code.trim()
+        ? input.code.trim()
+        : typeof input.token === "string"
+          ? input.token.trim()
+          : "";
+    if (!inviteCode) {
       return "ClawChat invite code is required.";
     }
     return null;
@@ -96,7 +102,12 @@ const setupAdapter = {
     runtime: { log: (message: string) => void };
     previousCfg: OpenClawConfig;
   }) => {
-    const code = input.code?.trim();
+    const code =
+      typeof input.code === "string" && input.code.trim()
+        ? input.code.trim()
+        : typeof input.token === "string"
+          ? input.token.trim()
+          : "";
     if (!code) return;
     // Lazy-import the login runtime to keep @clack/prompts / readline /
     // config-runtime off the plugin's cold-start path. `readInviteCode`

package/src/config.test.ts

@@ -56,6 +56,50 @@ describe("openclaw-clawchat config", () => {
     expect(account.stream.maxBufferChars).toBe(3000);
   });
 
+  it("resolves credentials from ClawChat environment variables when config omits them", () => {
+    const account = resolveOpenclawClawlingAccount(
+      {},
+      {
+        CLAWCHAT_TOKEN: "env-token",
+        CLAWCHAT_USER_ID: "env-user",
+        CLAWCHAT_BASE_URL: "https://api.env.example",
+        CLAWCHAT_WEBSOCKET_URL: "wss://ws.env.example/ws",
+      },
+    );
+
+    expect(account.configured).toBe(true);
+    expect(account.token).toBe("env-token");
+    expect(account.userId).toBe("env-user");
+    expect(account.baseUrl).toBe("https://api.env.example");
+    expect(account.websocketUrl).toBe("wss://ws.env.example/ws");
+  });
+
+  it("prefers explicit channel config over ClawChat environment variables", () => {
+    const account = resolveOpenclawClawlingAccount(
+      {
+        channels: {
+          "openclaw-clawchat": {
+            token: "config-token",
+            userId: "config-user",
+            baseUrl: "https://api.config.example",
+            websocketUrl: "wss://ws.config.example/ws",
+          },
+        },
+      },
+      {
+        CLAWCHAT_TOKEN: "env-token",
+        CLAWCHAT_USER_ID: "env-user",
+        CLAWCHAT_BASE_URL: "https://api.env.example",
+        CLAWCHAT_WEBSOCKET_URL: "wss://ws.env.example/ws",
+      },
+    );
+
+    expect(account.token).toBe("config-token");
+    expect(account.userId).toBe("config-user");
+    expect(account.baseUrl).toBe("https://api.config.example");
+    expect(account.websocketUrl).toBe("wss://ws.config.example/ws");
+  });
+
   it("falls back to static replyMode for unknown values", () => {
     const cfg = {
       channels: {

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,7 +89,7 @@ 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;
@@ -234,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";
 }
@@ -289,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);

package/src/login.runtime.ts

@@ -110,7 +110,9 @@ async function persistLoginConfig(
 }
 
 /**
- * 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.

package/src/manifest.test.ts

@@ -46,9 +46,9 @@ describe("openclaw-clawchat manifest", () => {
 
   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");
+    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", () => {
@@ -85,6 +85,18 @@ describe("openclaw-clawchat manifest", () => {
     ]);
   });
 
+  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");
@@ -94,11 +106,11 @@ describe("openclaw-clawchat manifest", () => {
     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", () => {
@@ -155,7 +167,7 @@ describe("openclaw-clawchat manifest", () => {
     expect(config).toMatch(/"\.e2e\/\*\*"/);
   });
 
-  it("keeps the activation skill on clawchat_activate with channel-login fallback", () => {
+  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/);
@@ -164,9 +176,9 @@ describe("openclaw-clawchat manifest", () => {
     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/);
@@ -175,13 +187,13 @@ describe("openclaw-clawchat manifest", () => {
     expect(skill).toMatch(/restart[^\n]+only when/i);
   });
 
-  it("documents clawchat_activate as the natural-language activation path with CLI fallback", () => {
+  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(/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 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);
@@ -197,4 +209,42 @@ describe("openclaw-clawchat manifest", () => {
     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/plugin-entry.test.ts

@@ -3,9 +3,14 @@ import pluginEntry from "../index.ts";
 
 describe("openclaw-clawchat plugin entry", () => {
   it("registers the channel/tools and native activation command without bootstrap migration", () => {
+    const mutateConfigFile = vi.fn();
     const api = {
       config: {},
-      runtime: {},
+      runtime: {
+        config: {
+          mutateConfigFile,
+        },
+      },
       logger: { debug: vi.fn(), info: vi.fn(), error: vi.fn() },
       registerChannel: vi.fn(),
       registerCommand: vi.fn(),
@@ -23,5 +28,6 @@ describe("openclaw-clawchat plugin entry", () => {
         name: "clawchat-login",
       }),
     );
+    expect(mutateConfigFile).not.toHaveBeenCalled();
   });
 });

package/src/tools.ts

@@ -155,8 +155,8 @@ export function registerOpenclawClawlingTools(api: OpenClawPluginApi): void {
   function buildClient(): ClientResult {
     const acct = resolveCurrent();
     // `baseUrl` always resolves via the built-in default in config.ts, so we
-    // only need to gate on `token` here (which is populated by `openclaw
-    // channel login`).
+    // only need to gate on `token` here (which is populated by ClawChat
+    // activation/login).
     if (!acct.token) {
       return { ok: false, error: configError("openclaw-clawchat: token is required") };
     }