@clawling/clawchat-plugin-openclaw 2026.5.14-3 → 2026.6.16-1

package/dist/src/api-client.js

@@ -39,7 +39,15 @@ export function decodeJwtExp(token) {
 const CODE_OK = 0;
 const CODE_INTERNAL = 1; // CodeInternal — transient.
 const CODE_BAD_REQUEST = 400; // bad body / device id — permanent (client bug).
-const CODE_INVALID_REFRESH = 10003; // CodeInvalidRefresh — permanent.
+/**
+ * CodeInvalidRefresh — returned for BOTH a genuinely revoked/invalid refresh
+ * token AND a single-use refresh token that was already CONSUMED by a prior
+ * successful rotation (a duplicate-supervisor / concurrent-refresh / stale-store
+ * race). The stateless `authRefresh` cannot tell the two apart, so it reports
+ * `permanent`; the stateful `RefreshManager` re-classifies a consumed-rotation
+ * race back to transient (see §B race) before any auto-logout.
+ */
+export const CODE_INVALID_REFRESH = 10003;
 /**
  * §0/§B — call `POST /v1/auth/refresh` to rotate the access+refresh token.
  *

package/dist/src/refresh-manager.js

@@ -1,4 +1,4 @@
-import { authRefresh, decodeJwtExp, } from "./api-client.js";
+import { authRefresh, CODE_INVALID_REFRESH, decodeJwtExp, } from "./api-client.js";
 /**
  * §A–§D — ClawChat token refresh + auto-logout orchestration for the OpenClaw
  * plugin.
@@ -54,6 +54,12 @@ export class RefreshManager {
     inFlight = null;
     /** §A.3 — the access token a refresh was last attempted for. */
     rejectedToken = null;
+    /**
+     * §B race — the refresh token we last successfully rotated AWAY from (now
+     * consumed server-side). A subsequent `code:10003` for this exact token is a
+     * consumed-rotation race, NOT a revocation, so it must not auto-logout.
+     */
+    lastRotatedFromToken = null;
     /** §A.3 — epoch-ms of the last refresh attempt (any token). */
     lastAttemptAt = 0;
     proactiveTimer = null;
@@ -138,12 +144,33 @@ export class RefreshManager {
                 accessToken: result.accessToken,
                 refreshToken: result.refreshToken,
             });
+            // §B race — record the now-consumed refresh token so a later `10003` for it
+            // is recognized as a rotation race rather than a revocation.
+            this.lastRotatedFromToken = refreshToken;
             // Clear the latch; the access token has actually changed.
             this.rejectedToken = null;
             this.ports.log?.info?.("clawchat-plugin-openclaw refresh success (token rotated)");
             return { kind: "success", accessToken: result.accessToken, refreshToken: result.refreshToken };
         }
         if (result.kind === "permanent") {
+            // §B race — a `code:10003` is also returned for a single-use refresh token
+            // already CONSUMED by a prior successful rotation. Before auto-logging-out
+            // (which wipes credentials and bricks the agent), distinguish that race
+            // from a genuine revocation. It is a race when EITHER the submitted token
+            // is one we already rotated away from, OR the live store refresh token has
+            // moved on since we read it (another worker rotated underneath us). In
+            // either case the credential chain is still alive — report transient (no
+            // latch, no logout) so the next attempt proceeds with the live token. A
+            // `code:400` (client bug) is never a race.
+            if (result.code === CODE_INVALID_REFRESH) {
+                const liveRefresh = this.ports.getRefreshToken();
+                const rotatedByUs = this.lastRotatedFromToken !== null && refreshToken === this.lastRotatedFromToken;
+                const rotatedUnderneath = !!liveRefresh && liveRefresh.trim().length > 0 && liveRefresh !== refreshToken;
+                if (rotatedByUs || rotatedUnderneath) {
+                    this.ports.log?.info?.(`clawchat-plugin-openclaw refresh 10003 treated as consumed-rotation race (rotatedByUs=${rotatedByUs} rotatedUnderneath=${rotatedUnderneath}); recovering with live token`);
+                    return { kind: "transient", message: "refresh token already rotated (race); retrying with current token" };
+                }
+            }
             // §A.3 — latch the dead token so reconnect storms don't re-fire refresh.
             this.rejectedToken = accessToken;
             this.ports.log?.error?.(`clawchat-plugin-openclaw refresh permanent failure code=${result.code}: ${result.message}`);
@@ -249,12 +276,17 @@ export class RefreshManager {
      * the guards would not bound a cross-reconnect loop).
      */
     exportState() {
-        return { rejectedToken: this.rejectedToken, lastAttemptAt: this.lastAttemptAt };
+        return {
+            rejectedToken: this.rejectedToken,
+            lastAttemptAt: this.lastAttemptAt,
+            lastRotatedFromToken: this.lastRotatedFromToken,
+        };
     }
     /** §A.3/§A.4 — restore guard state from a prior manager (see `exportState`). */
     restoreState(state) {
         this.rejectedToken = state.rejectedToken;
         this.lastAttemptAt = state.lastAttemptAt;
+        this.lastRotatedFromToken = state.lastRotatedFromToken ?? null;
     }
 }
 function decodeJwtIat(token) {

package/dist/src/runtime.js

@@ -7,7 +7,8 @@ import { createOpenclawClawlingApiClient } from "./api-client.js";
 import { reportPluginVersionSafe, resolvePluginVersion } from "./plugin-report.js";
 import { ClawlingApiError } from "./api-types.js";
 import { RefreshManager } from "./refresh-manager.js";
-import { CHANNEL_ID, effectiveOutputVisibility, effectiveGroupCommandMode, hasOpenclawClawlingConnectCredentials, } from "./config.js";
+import { runOpenclawClawlingLogin, } from "./login.runtime.js";
+import { CHANNEL_ID, effectiveOutputVisibility, effectiveGroupCommandMode, hasOpenclawClawlingConnectCredentials, resolveOpenclawClawlingAccount, } from "./config.js";
 import { dispatchOpenclawClawlingInbound } from "./inbound.js";
 import { fetchInboundMedia } from "./media-runtime.js";
 import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.js";
@@ -339,6 +340,72 @@ function resolveConnectionStore(params, runtime) {
 function accountHasConnectCredentials(account) {
     return hasOpenclawClawlingConnectCredentials(account);
 }
+/**
+ * §B self-heal — env var carrying a one-shot connect code for non-interactive
+ * (re)activation. Containers / orchestrators set this so a plugin that lost its
+ * token (e.g. a consumed-rotation auto-logout, or a wiped/rotated env) can
+ * recover WITHOUT the openclaw CLI channel registry (which cannot reach this
+ * plugin pre-config) and without an in-chat `/clawchat-activate` (which needs the
+ * agent already online — a chicken/egg). Declared in `openclaw.plugin.json`
+ * `channelEnvVars` so the host forwards it.
+ */
+export const CONNECT_CODE_ENV = "CLAWCHAT_CONNECT_CODE";
+/**
+ * §B self-heal — process-scoped record of connect codes we have already tried to
+ * redeem, so a repeated `startAccount` (reconnect / re-enter) does not hammer the
+ * server with the same (often single-use) code. The real guard against
+ * re-redeeming a SUCCESSFUL code is `accountHasConnectCredentials`; this set only
+ * bounds retries of a code that has not yet produced credentials this process.
+ */
+const consumedAutoActivationCodes = new Set();
+/** Test seam — clear the process-scoped consumed-code set between cases. */
+export function resetAutoActivationStateForTests() {
+    consumedAutoActivationCodes.clear();
+}
+/**
+ * §B self-heal — if a connect code is present in the environment and the account
+ * is NOT already credentialed, redeem it via the shared invite-code exchange
+ * (`runOpenclawClawlingLogin`, which also persists the activation row to SQLite),
+ * then return the re-resolved account. Credentials are written into the in-memory
+ * `cfg` (no host restart); durability comes from the SQLite activation row. All
+ * failures are swallowed — a bad/expired code must not crash startup; the gateway
+ * falls through to the normal wait-for-activation loop.
+ */
+export async function maybeAutoActivateFromEnv(params) {
+    const code = (params.connectCode ?? "").trim();
+    if (!code)
+        return params.account;
+    if (accountHasConnectCredentials(params.account))
+        return params.account;
+    if (consumedAutoActivationCodes.has(code))
+        return params.account;
+    consumedAutoActivationCodes.add(code);
+    const runLogin = params.runLogin ?? runOpenclawClawlingLogin;
+    const resolveAccount = params.resolveAccount ?? resolveOpenclawClawlingAccount;
+    const accountId = params.account.accountId;
+    params.log?.info?.(`[${accountId}] clawchat-plugin-openclaw ${CONNECT_CODE_ENV} present; attempting non-interactive activation`);
+    try {
+        await runLogin({
+            cfg: params.cfg,
+            accountId: params.accountId,
+            runtime: { log: (m) => params.log?.info?.(m) },
+            readInviteCode: async () => code,
+            // Update the IN-MEMORY config so this process re-resolves to a configured
+            // account immediately (no host restart). Durable persistence is the SQLite
+            // activations row that runOpenclawClawlingLogin writes alongside this.
+            persistConfig: (next) => {
+                Object.assign(params.cfg, next);
+            },
+        });
+    }
+    catch (err) {
+        params.log?.error?.(`[${accountId}] clawchat-plugin-openclaw ${CONNECT_CODE_ENV} activation failed: ${err instanceof Error ? err.message : String(err)}`);
+        return params.account;
+    }
+    const next = resolveAccount(params.cfg);
+    params.log?.info?.(`[${accountId}] clawchat-plugin-openclaw ${CONNECT_CODE_ENV} activation succeeded hasToken=${Boolean(next.token)}`);
+    return next;
+}
 function waitForActivationPoll(abortSignal, ms) {
     if (abortSignal.aborted)
         return Promise.resolve(false);
@@ -439,6 +506,21 @@ export async function startOpenclawClawlingGateway(params) {
         authenticated: false,
         log,
     });
+    // §B self-heal — non-interactive env connect-code activation BEFORE blocking on
+    // the wait-for-activation loop. Gated so the common path (no env code, or an
+    // already-credentialed account) adds NO async work: on success it credentials
+    // the in-memory account (and persists the SQLite activation row) so the loop
+    // below returns immediately.
+    const envConnectCode = process.env[CONNECT_CODE_ENV];
+    if (envConnectCode && envConnectCode.trim() && !accountHasConnectCredentials(account)) {
+        account = await maybeAutoActivateFromEnv({
+            cfg,
+            account,
+            accountId,
+            connectCode: envConnectCode,
+            log,
+        });
+    }
     const activationAccount = await waitForActivationCredentials({
         account,
         abortSignal,

package/openclaw.plugin.json

@@ -22,6 +22,7 @@
       "CLAWCHAT_USER_ID",
       "CLAWCHAT_OWNER_USER_ID",
       "CLAWCHAT_REFRESH_TOKEN",
+      "CLAWCHAT_CONNECT_CODE",
       "CLAWCHAT_BASE_URL",
       "CLAWCHAT_WEBSOCKET_URL",
       "CLAWCHAT_MEDIA_BASE_URL"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.5.14-3",
+  "version": "2026.6.16-1",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "files": [

package/src/api-client.ts

@@ -164,7 +164,15 @@ export interface OpenclawClawlingApiClient {
 const CODE_OK = 0;
 const CODE_INTERNAL = 1; // CodeInternal — transient.
 const CODE_BAD_REQUEST = 400; // bad body / device id — permanent (client bug).
-const CODE_INVALID_REFRESH = 10003; // CodeInvalidRefresh — permanent.
+/**
+ * CodeInvalidRefresh — returned for BOTH a genuinely revoked/invalid refresh
+ * token AND a single-use refresh token that was already CONSUMED by a prior
+ * successful rotation (a duplicate-supervisor / concurrent-refresh / stale-store
+ * race). The stateless `authRefresh` cannot tell the two apart, so it reports
+ * `permanent`; the stateful `RefreshManager` re-classifies a consumed-rotation
+ * race back to transient (see §B race) before any auto-logout.
+ */
+export const CODE_INVALID_REFRESH = 10003;
 
 /**
  * §0/§B — call `POST /v1/auth/refresh` to rotate the access+refresh token.

package/src/refresh-manager.ts

@@ -1,5 +1,6 @@
 import {
   authRefresh,
+  CODE_INVALID_REFRESH,
   decodeJwtExp,
   type AuthRefreshResult,
 } from "./api-client.ts";
@@ -119,6 +120,12 @@ export class RefreshManager {
   private inFlight: Promise<RefreshOutcome> | null = null;
   /** §A.3 — the access token a refresh was last attempted for. */
   private rejectedToken: string | null = null;
+  /**
+   * §B race — the refresh token we last successfully rotated AWAY from (now
+   * consumed server-side). A subsequent `code:10003` for this exact token is a
+   * consumed-rotation race, NOT a revocation, so it must not auto-logout.
+   */
+  private lastRotatedFromToken: string | null = null;
   /** §A.3 — epoch-ms of the last refresh attempt (any token). */
   private lastAttemptAt = 0;
   private proactiveTimer: TimerHandle | null = null;
@@ -219,6 +226,9 @@ export class RefreshManager {
         accessToken: result.accessToken,
         refreshToken: result.refreshToken,
       });
+      // §B race — record the now-consumed refresh token so a later `10003` for it
+      // is recognized as a rotation race rather than a revocation.
+      this.lastRotatedFromToken = refreshToken;
       // Clear the latch; the access token has actually changed.
       this.rejectedToken = null;
       this.ports.log?.info?.("clawchat-plugin-openclaw refresh success (token rotated)");
@@ -226,6 +236,28 @@ export class RefreshManager {
     }
 
     if (result.kind === "permanent") {
+      // §B race — a `code:10003` is also returned for a single-use refresh token
+      // already CONSUMED by a prior successful rotation. Before auto-logging-out
+      // (which wipes credentials and bricks the agent), distinguish that race
+      // from a genuine revocation. It is a race when EITHER the submitted token
+      // is one we already rotated away from, OR the live store refresh token has
+      // moved on since we read it (another worker rotated underneath us). In
+      // either case the credential chain is still alive — report transient (no
+      // latch, no logout) so the next attempt proceeds with the live token. A
+      // `code:400` (client bug) is never a race.
+      if (result.code === CODE_INVALID_REFRESH) {
+        const liveRefresh = this.ports.getRefreshToken();
+        const rotatedByUs =
+          this.lastRotatedFromToken !== null && refreshToken === this.lastRotatedFromToken;
+        const rotatedUnderneath =
+          !!liveRefresh && liveRefresh.trim().length > 0 && liveRefresh !== refreshToken;
+        if (rotatedByUs || rotatedUnderneath) {
+          this.ports.log?.info?.(
+            `clawchat-plugin-openclaw refresh 10003 treated as consumed-rotation race (rotatedByUs=${rotatedByUs} rotatedUnderneath=${rotatedUnderneath}); recovering with live token`,
+          );
+          return { kind: "transient", message: "refresh token already rotated (race); retrying with current token" };
+        }
+      }
       // §A.3 — latch the dead token so reconnect storms don't re-fire refresh.
       this.rejectedToken = accessToken;
       this.ports.log?.error?.(
@@ -341,14 +373,27 @@ export class RefreshManager {
    * restoring this state the rejected-token latch + min-interval would reset and
    * the guards would not bound a cross-reconnect loop).
    */
-  exportState(): { rejectedToken: string | null; lastAttemptAt: number } {
-    return { rejectedToken: this.rejectedToken, lastAttemptAt: this.lastAttemptAt };
+  exportState(): {
+    rejectedToken: string | null;
+    lastAttemptAt: number;
+    lastRotatedFromToken: string | null;
+  } {
+    return {
+      rejectedToken: this.rejectedToken,
+      lastAttemptAt: this.lastAttemptAt,
+      lastRotatedFromToken: this.lastRotatedFromToken,
+    };
   }
 
   /** §A.3/§A.4 — restore guard state from a prior manager (see `exportState`). */
-  restoreState(state: { rejectedToken: string | null; lastAttemptAt: number }): void {
+  restoreState(state: {
+    rejectedToken: string | null;
+    lastAttemptAt: number;
+    lastRotatedFromToken?: string | null;
+  }): void {
     this.rejectedToken = state.rejectedToken;
     this.lastAttemptAt = state.lastAttemptAt;
+    this.lastRotatedFromToken = state.lastRotatedFromToken ?? null;
   }
 }
 

package/src/runtime.ts

@@ -18,12 +18,17 @@ import { createOpenclawClawlingApiClient } from "./api-client.ts";
 import { reportPluginVersionSafe, resolvePluginVersion } from "./plugin-report.ts";
 import { ClawlingApiError } from "./api-types.ts";
 import { RefreshManager } from "./refresh-manager.ts";
-import type { OpenclawClawchatMutateConfigFile } from "./login.runtime.ts";
+import {
+  runOpenclawClawlingLogin,
+  type LoginParams,
+  type OpenclawClawchatMutateConfigFile,
+} from "./login.runtime.ts";
 import {
   CHANNEL_ID,
   effectiveOutputVisibility,
   effectiveGroupCommandMode,
   hasOpenclawClawlingConnectCredentials,
+  resolveOpenclawClawlingAccount,
   type ResolvedOpenclawClawlingAccount,
 } from "./config.ts";
 import type { ClawlingChatClient } from "./ws-client.ts";
@@ -548,6 +553,94 @@ function accountHasConnectCredentials(account: ResolvedOpenclawClawlingAccount):
   return hasOpenclawClawlingConnectCredentials(account);
 }
 
+/**
+ * §B self-heal — env var carrying a one-shot connect code for non-interactive
+ * (re)activation. Containers / orchestrators set this so a plugin that lost its
+ * token (e.g. a consumed-rotation auto-logout, or a wiped/rotated env) can
+ * recover WITHOUT the openclaw CLI channel registry (which cannot reach this
+ * plugin pre-config) and without an in-chat `/clawchat-activate` (which needs the
+ * agent already online — a chicken/egg). Declared in `openclaw.plugin.json`
+ * `channelEnvVars` so the host forwards it.
+ */
+export const CONNECT_CODE_ENV = "CLAWCHAT_CONNECT_CODE";
+
+/**
+ * §B self-heal — process-scoped record of connect codes we have already tried to
+ * redeem, so a repeated `startAccount` (reconnect / re-enter) does not hammer the
+ * server with the same (often single-use) code. The real guard against
+ * re-redeeming a SUCCESSFUL code is `accountHasConnectCredentials`; this set only
+ * bounds retries of a code that has not yet produced credentials this process.
+ */
+const consumedAutoActivationCodes = new Set<string>();
+
+/** Test seam — clear the process-scoped consumed-code set between cases. */
+export function resetAutoActivationStateForTests(): void {
+  consumedAutoActivationCodes.clear();
+}
+
+export interface AutoActivateFromEnvParams {
+  cfg: OpenClawConfig;
+  account: ResolvedOpenclawClawlingAccount;
+  accountId: string | null;
+  /** The connect code (production: `process.env[CONNECT_CODE_ENV]`). */
+  connectCode: string | undefined;
+  log?: Log;
+  /** Test seam — login implementation. */
+  runLogin?: (params: LoginParams) => Promise<void>;
+  /** Test seam — account resolver applied to the (mutated) cfg after login. */
+  resolveAccount?: (cfg: OpenClawConfig) => ResolvedOpenclawClawlingAccount;
+}
+
+/**
+ * §B self-heal — if a connect code is present in the environment and the account
+ * is NOT already credentialed, redeem it via the shared invite-code exchange
+ * (`runOpenclawClawlingLogin`, which also persists the activation row to SQLite),
+ * then return the re-resolved account. Credentials are written into the in-memory
+ * `cfg` (no host restart); durability comes from the SQLite activation row. All
+ * failures are swallowed — a bad/expired code must not crash startup; the gateway
+ * falls through to the normal wait-for-activation loop.
+ */
+export async function maybeAutoActivateFromEnv(
+  params: AutoActivateFromEnvParams,
+): Promise<ResolvedOpenclawClawlingAccount> {
+  const code = (params.connectCode ?? "").trim();
+  if (!code) return params.account;
+  if (accountHasConnectCredentials(params.account)) return params.account;
+  if (consumedAutoActivationCodes.has(code)) return params.account;
+  consumedAutoActivationCodes.add(code);
+
+  const runLogin = params.runLogin ?? runOpenclawClawlingLogin;
+  const resolveAccount = params.resolveAccount ?? resolveOpenclawClawlingAccount;
+  const accountId = params.account.accountId;
+  params.log?.info?.(
+    `[${accountId}] clawchat-plugin-openclaw ${CONNECT_CODE_ENV} present; attempting non-interactive activation`,
+  );
+  try {
+    await runLogin({
+      cfg: params.cfg,
+      accountId: params.accountId,
+      runtime: { log: (m: string) => params.log?.info?.(m) },
+      readInviteCode: async () => code,
+      // Update the IN-MEMORY config so this process re-resolves to a configured
+      // account immediately (no host restart). Durable persistence is the SQLite
+      // activations row that runOpenclawClawlingLogin writes alongside this.
+      persistConfig: (next) => {
+        Object.assign(params.cfg, next);
+      },
+    });
+  } catch (err) {
+    params.log?.error?.(
+      `[${accountId}] clawchat-plugin-openclaw ${CONNECT_CODE_ENV} activation failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return params.account;
+  }
+  const next = resolveAccount(params.cfg);
+  params.log?.info?.(
+    `[${accountId}] clawchat-plugin-openclaw ${CONNECT_CODE_ENV} activation succeeded hasToken=${Boolean(next.token)}`,
+  );
+  return next;
+}
+
 function waitForActivationPoll(abortSignal: AbortSignal, ms: number): Promise<boolean> {
   if (abortSignal.aborted) return Promise.resolve(false);
   return new Promise((resolve) => {
@@ -669,6 +762,21 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     authenticated: false,
     log,
   });
+  // §B self-heal — non-interactive env connect-code activation BEFORE blocking on
+  // the wait-for-activation loop. Gated so the common path (no env code, or an
+  // already-credentialed account) adds NO async work: on success it credentials
+  // the in-memory account (and persists the SQLite activation row) so the loop
+  // below returns immediately.
+  const envConnectCode = process.env[CONNECT_CODE_ENV];
+  if (envConnectCode && envConnectCode.trim() && !accountHasConnectCredentials(account)) {
+    account = await maybeAutoActivateFromEnv({
+      cfg,
+      account,
+      accountId,
+      connectCode: envConnectCode,
+      log,
+    });
+  }
   const activationAccount = await waitForActivationCredentials({
     account,
     abortSignal,