@clawling/clawchat-plugin-openclaw 2026.7.25-1 → 2026.7.27-1

package/dist/src/commands.js

@@ -1,7 +1,28 @@
 import { CHANNEL_ID } from "./config.js";
+/** Activation intent flags — the two escape hatches out of the live-activation guard. */
+const ACTIVATION_FLAGS = ["--new-account", "--repair"];
+function stripActivationFlags(raw) {
+    return ACTIVATION_FLAGS.reduce((acc, flag) => acc.split(flag).join(" "), raw);
+}
 function extractInviteCode(value) {
     const raw = typeof value === "string" ? value.trim() : "";
-    return raw.match(/\b[A-Z0-9]{6}\b/u)?.[0] ?? "";
+    return stripActivationFlags(raw).match(/\b[A-Z0-9]{6}\b/u)?.[0] ?? "";
+}
+/**
+ * Read the activation intent from the command args.
+ *
+ * Redeeming a code while this instance holds a live activation is refused by
+ * `runOpenclawClawlingLogin` (it would re-bind the code to the incumbent agent
+ * rather than add a second one). `/clawchat-activate` is the only activation
+ * surface whose arguments this plugin parses, so it carries the two intents:
+ * `--new-account` replaces the identity, `--repair` re-pairs the current one.
+ */
+function extractActivationIntent(value) {
+    const raw = typeof value === "string" ? value : "";
+    return {
+        newAccount: raw.includes("--new-account"),
+        repair: raw.includes("--repair"),
+    };
 }
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
@@ -85,10 +106,12 @@ export function registerOpenclawClawlingCommands(api) {
         acceptsArgs: true,
         requireAuth: true,
         async handler(ctx) {
-            const code = extractInviteCode(ctx.args ?? ctx.commandBody);
+            const rawArgs = ctx.args ?? ctx.commandBody;
+            const code = extractInviteCode(rawArgs);
             if (!code) {
                 return { text: "ClawChat invite code is required. Usage: /clawchat-activate A1B2C3" };
             }
+            const intent = extractActivationIntent(rawArgs);
             try {
                 const { runOpenclawClawlingLogin } = await import("./login.runtime.js");
                 await runOpenclawClawlingLogin({
@@ -97,6 +120,8 @@ export function registerOpenclawClawlingCommands(api) {
                     runtime: { log: (message) => api.logger?.info?.(message) },
                     readInviteCode: async () => code,
                     mutateConfigFile: api.runtime.config.mutateConfigFile,
+                    newAccount: intent.newAccount,
+                    repair: intent.repair,
                 });
                 return { text: "✅ ClawChat activated successfully." };
             }

package/dist/src/login.runtime.js

@@ -14,6 +14,45 @@ export const AGENTS_CONNECT_PLATFORM = "openclaw";
  * always a bot; humans don't log in through this flow.
  */
 export const AGENTS_CONNECT_TYPE = "clawbot";
+/**
+ * `/v1/agents/connect` envelope code for "the supplied user_id matches no
+ * agent". Servers that predate the server-side stale-user_id fallback return
+ * this instead of degrading to a fresh pairing, so the client sheds the id and
+ * retries once.
+ */
+export const AGENT_NOT_FOUND_CODE = 16001;
+/**
+ * Thrown when redeeming an invite code would silently replace a live activation.
+ *
+ * This channel holds exactly one ClawChat identity — `channels.<id>` is a single
+ * slot and `listOpenclawClawlingAccountIds()` returns a single account. Because
+ * the stored `user_id` is replayed as a re-pair hint, redeeming a *new* invite
+ * code here cannot produce a second agent: the server binds the code to the
+ * existing agent, consumes it, creates no second agent and no second contact
+ * entry, and the local credentials are overwritten in place — losing the first
+ * agent with no error and no warning. Refuse instead, and name the real intents.
+ */
+export class ExistingActivationError extends Error {
+    userId;
+    agentId;
+    constructor(userId, agentId = "") {
+        const who = agentId ? `agent ${agentId} (shadow user ${userId})` : `agent ${userId}`;
+        super(`this OpenClaw instance is already paired to ClawChat ${who}. ` +
+            "Redeeming another invite code here would re-bind that code to the SAME " +
+            "agent — no second agent is created, and this instance's credentials are " +
+            "overwritten.\n" +
+            "  - To run a SECOND agent alongside this one, give it its own OpenClaw " +
+            "home:\n" +
+            "      OPENCLAW_HOME=<path> openclaw channels login --channel clawchat-plugin-openclaw\n" +
+            "  - To REPLACE this instance's agent with a brand-new identity: " +
+            "/clawchat-activate <CODE> --new-account\n" +
+            "  - To re-pair THIS agent (e.g. after losing its token): " +
+            "/clawchat-activate <CODE> --repair");
+        this.name = "ExistingActivationError";
+        this.userId = userId;
+        this.agentId = agentId;
+    }
+}
 /**
  * Prompt the operator for an invite code.
  *
@@ -126,6 +165,14 @@ export async function runOpenclawClawlingLogin(params) {
     // `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);
+    // Guard before the invite code is even read, so a refused activation never
+    // spends the code — the operator can still redeem it the right way. "Live" is
+    // decided by whether a usable token remains: auto-logout (§C) blanks the
+    // tokens but preserves the identity, so a logged-out instance still re-pairs
+    // with no flag at all, which is the flow the replay exists for.
+    if (account.userId.trim() && account.token.trim() && !params.newAccount && !params.repair) {
+        throw new ExistingActivationError(account.userId.trim(), account.agentId.trim());
+    }
     const inviteCode = (await (params.readInviteCode ?? (() => promptInviteCodeFromStdin(runtime)))()).trim();
     if (!inviteCode) {
         throw new Error("Login aborted: invite code is required.");
@@ -140,8 +187,10 @@ export async function runOpenclawClawlingLogin(params) {
     });
     runtime.log("Verifying invite code …");
     let result;
+    // A brand-new identity is precisely "do not replay" — the replay is the only
+    // thing that would bind this code to the incumbent agent.
+    const existingUserId = params.newAccount ? "" : account.userId.trim();
     try {
-        const existingUserId = account.userId.trim();
         result = await apiClient.agentsConnect({
             code: inviteCode,
             platform: AGENTS_CONNECT_PLATFORM,
@@ -151,9 +200,37 @@ export async function runOpenclawClawlingLogin(params) {
     }
     catch (err) {
         if (err instanceof ClawlingApiError) {
-            throw new Error(`agents/connect failed (${err.kind}): ${err.message}`);
+            // The stored userId is a re-pair hint, not a credential — the invite
+            // code alone decides ownership. AGENT_NOT_FOUND means it names an agent
+            // this server has never had (owner account deleted, or the config was
+            // repointed at another deployment), so replaying it would fail
+            // identically for every future invite code. A 16001 leaves the code
+            // `pending` server-side, so shedding the id and retrying once cannot
+            // double-spend it. Nothing else is retried: an owner mismatch is a real
+            // rejection, and a request that sent no id has no stale state to shed.
+            if (existingUserId && err.meta?.code === AGENT_NOT_FOUND_CODE) {
+                runtime.log(`Stored userId ${existingUserId} no longer exists on this server — retrying as a fresh pairing …`);
+                try {
+                    result = await apiClient.agentsConnect({
+                        code: inviteCode,
+                        platform: AGENTS_CONNECT_PLATFORM,
+                        type: AGENTS_CONNECT_TYPE,
+                    });
+                }
+                catch (retryErr) {
+                    if (retryErr instanceof ClawlingApiError) {
+                        throw new Error(`agents/connect failed (${retryErr.kind}): ${retryErr.message}`);
+                    }
+                    throw retryErr;
+                }
+            }
+            else {
+                throw new Error(`agents/connect failed (${err.kind}): ${err.message}`);
+            }
+        }
+        else {
+            throw err;
         }
-        throw err;
     }
     const accessToken = requireConnectString(result?.access_token, "access_token");
     const agentUserId = requireConnectString(result?.agent?.user_id, "agent.user_id");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.7.25-1",
+  "version": "2026.7.27-1",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "author": "CLAWLING PTE. LTD.",

package/src/commands.ts

@@ -3,9 +3,33 @@ import type { OpenClawConfig, PluginCommandContext } from "openclaw/plugin-sdk/c
 import { CHANNEL_ID, type OutputVisibility } from "./config.ts";
 import type { OpenclawClawchatMutateConfigFile } from "./login.runtime.ts";
 
+/** Activation intent flags — the two escape hatches out of the live-activation guard. */
+const ACTIVATION_FLAGS = ["--new-account", "--repair"] as const;
+
+function stripActivationFlags(raw: string): string {
+  return ACTIVATION_FLAGS.reduce((acc, flag) => acc.split(flag).join(" "), raw);
+}
+
 function extractInviteCode(value: unknown): string {
   const raw = typeof value === "string" ? value.trim() : "";
-  return raw.match(/\b[A-Z0-9]{6}\b/u)?.[0] ?? "";
+  return stripActivationFlags(raw).match(/\b[A-Z0-9]{6}\b/u)?.[0] ?? "";
+}
+
+/**
+ * Read the activation intent from the command args.
+ *
+ * Redeeming a code while this instance holds a live activation is refused by
+ * `runOpenclawClawlingLogin` (it would re-bind the code to the incumbent agent
+ * rather than add a second one). `/clawchat-activate` is the only activation
+ * surface whose arguments this plugin parses, so it carries the two intents:
+ * `--new-account` replaces the identity, `--repair` re-pairs the current one.
+ */
+function extractActivationIntent(value: unknown): { newAccount: boolean; repair: boolean } {
+  const raw = typeof value === "string" ? value : "";
+  return {
+    newAccount: raw.includes("--new-account"),
+    repair: raw.includes("--repair"),
+  };
 }
 
 function errorMessage(err: unknown): string {
@@ -98,10 +122,12 @@ export function registerOpenclawClawlingCommands(api: Pick<OpenClawPluginApi, "r
     acceptsArgs: true,
     requireAuth: true,
     async handler(ctx) {
-      const code = extractInviteCode(ctx.args ?? ctx.commandBody);
+      const rawArgs = ctx.args ?? ctx.commandBody;
+      const code = extractInviteCode(rawArgs);
       if (!code) {
         return { text: "ClawChat invite code is required. Usage: /clawchat-activate A1B2C3" };
       }
+      const intent = extractActivationIntent(rawArgs);
       try {
         const { runOpenclawClawlingLogin } = await import("./login.runtime.ts");
         await runOpenclawClawlingLogin({
@@ -112,6 +138,8 @@ export function registerOpenclawClawlingCommands(api: Pick<OpenClawPluginApi, "r
           mutateConfigFile: (api.runtime.config as unknown as {
             mutateConfigFile: OpenclawClawchatMutateConfigFile;
           }).mutateConfigFile,
+          newAccount: intent.newAccount,
+          repair: intent.repair,
         });
         return { text: "✅ ClawChat activated successfully." };
       } catch (err) {

package/src/login.runtime.ts

@@ -21,6 +21,13 @@ export const AGENTS_CONNECT_PLATFORM = "openclaw" as const;
  * always a bot; humans don't log in through this flow.
  */
 export const AGENTS_CONNECT_TYPE = "clawbot" as const;
+/**
+ * `/v1/agents/connect` envelope code for "the supplied user_id matches no
+ * agent". Servers that predate the server-side stale-user_id fallback return
+ * this instead of degrading to a fresh pairing, so the client sheds the id and
+ * retries once.
+ */
+export const AGENT_NOT_FOUND_CODE = 16001 as const;
 
 export type OpenclawClawchatMutateConfigFile = <T = void>(params: {
   afterWrite: { mode: "auto" } | { mode: "none" | "restart"; reason: string };
@@ -49,6 +56,49 @@ export interface LoginParams {
   store?: Pick<ClawChatStore, "upsertActivation">;
   /** Optional database path resolved by the host runtime. */
   dbPath?: string;
+  /**
+   * Replace this instance's ClawChat identity with a brand-new agent: drop the
+   * stored `user_id` so the server mints one for this invite code.
+   */
+  newAccount?: boolean;
+  /** Re-pair the agent this instance already holds (keeps its identity). */
+  repair?: boolean;
+}
+
+/**
+ * Thrown when redeeming an invite code would silently replace a live activation.
+ *
+ * This channel holds exactly one ClawChat identity — `channels.<id>` is a single
+ * slot and `listOpenclawClawlingAccountIds()` returns a single account. Because
+ * the stored `user_id` is replayed as a re-pair hint, redeeming a *new* invite
+ * code here cannot produce a second agent: the server binds the code to the
+ * existing agent, consumes it, creates no second agent and no second contact
+ * entry, and the local credentials are overwritten in place — losing the first
+ * agent with no error and no warning. Refuse instead, and name the real intents.
+ */
+export class ExistingActivationError extends Error {
+  readonly userId: string;
+  readonly agentId: string;
+
+  constructor(userId: string, agentId = "") {
+    const who = agentId ? `agent ${agentId} (shadow user ${userId})` : `agent ${userId}`;
+    super(
+      `this OpenClaw instance is already paired to ClawChat ${who}. ` +
+        "Redeeming another invite code here would re-bind that code to the SAME " +
+        "agent — no second agent is created, and this instance's credentials are " +
+        "overwritten.\n" +
+        "  - To run a SECOND agent alongside this one, give it its own OpenClaw " +
+        "home:\n" +
+        "      OPENCLAW_HOME=<path> openclaw channels login --channel clawchat-plugin-openclaw\n" +
+        "  - To REPLACE this instance's agent with a brand-new identity: " +
+        "/clawchat-activate <CODE> --new-account\n" +
+        "  - To re-pair THIS agent (e.g. after losing its token): " +
+        "/clawchat-activate <CODE> --repair",
+    );
+    this.name = "ExistingActivationError";
+    this.userId = userId;
+    this.agentId = agentId;
+  }
 }
 
 /**
@@ -185,6 +235,15 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
   // overridden them, so login works without a prior `openclaw channels setup --channel clawchat-plugin-openclaw`.
   const account = resolveOpenclawClawlingAccount(cfg);
 
+  // Guard before the invite code is even read, so a refused activation never
+  // spends the code — the operator can still redeem it the right way. "Live" is
+  // decided by whether a usable token remains: auto-logout (§C) blanks the
+  // tokens but preserves the identity, so a logged-out instance still re-pairs
+  // with no flag at all, which is the flow the replay exists for.
+  if (account.userId.trim() && account.token.trim() && !params.newAccount && !params.repair) {
+    throw new ExistingActivationError(account.userId.trim(), account.agentId.trim());
+  }
+
   const inviteCode = (
     await (params.readInviteCode ?? (() => promptInviteCodeFromStdin(runtime)))()
   ).trim();
@@ -203,8 +262,10 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
 
   runtime.log("Verifying invite code …");
   let result;
+  // A brand-new identity is precisely "do not replay" — the replay is the only
+  // thing that would bind this code to the incumbent agent.
+  const existingUserId = params.newAccount ? "" : account.userId.trim();
   try {
-    const existingUserId = account.userId.trim();
     result = await apiClient.agentsConnect({
       code: inviteCode,
       platform: AGENTS_CONNECT_PLATFORM,
@@ -213,9 +274,36 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
     });
   } catch (err) {
     if (err instanceof ClawlingApiError) {
-      throw new Error(`agents/connect failed (${err.kind}): ${err.message}`);
+      // The stored userId is a re-pair hint, not a credential — the invite
+      // code alone decides ownership. AGENT_NOT_FOUND means it names an agent
+      // this server has never had (owner account deleted, or the config was
+      // repointed at another deployment), so replaying it would fail
+      // identically for every future invite code. A 16001 leaves the code
+      // `pending` server-side, so shedding the id and retrying once cannot
+      // double-spend it. Nothing else is retried: an owner mismatch is a real
+      // rejection, and a request that sent no id has no stale state to shed.
+      if (existingUserId && err.meta?.code === AGENT_NOT_FOUND_CODE) {
+        runtime.log(
+          `Stored userId ${existingUserId} no longer exists on this server — retrying as a fresh pairing …`,
+        );
+        try {
+          result = await apiClient.agentsConnect({
+            code: inviteCode,
+            platform: AGENTS_CONNECT_PLATFORM,
+            type: AGENTS_CONNECT_TYPE,
+          });
+        } catch (retryErr) {
+          if (retryErr instanceof ClawlingApiError) {
+            throw new Error(`agents/connect failed (${retryErr.kind}): ${retryErr.message}`);
+          }
+          throw retryErr;
+        }
+      } else {
+        throw new Error(`agents/connect failed (${err.kind}): ${err.message}`);
+      }
+    } else {
+      throw err;
     }
-    throw err;
   }
 
   const accessToken = requireConnectString(result?.access_token, "access_token");