@clawling/clawchat-plugin-openclaw 2026.10.8-2 → 2026.10.9-2

package/dist/src/connect-check.js

@@ -1,4 +1,5 @@
 import { ClawlingApiError } from "./api-types.js";
+import { readConnectFailureGuidance } from "./connect-failure.js";
 import { AGENTS_CONNECT_PLATFORM, RECONNECT_GUIDE_URL } from "./onboarding-context.js";
 /**
  * Non-consuming pre-check of a connect code. Records the "checked" funnel
@@ -29,8 +30,14 @@ export async function preCheckConnectCode(client, input, log) {
         };
     }
     catch (err) {
+        // Still a degrade, never a gate: `/connect` re-evaluates the code and
+        // surfaces the same guidance on the error it throws. The guidance is only
+        // logged here so a rate-limit or dead code is visible early.
         const kind = err instanceof ClawlingApiError ? err.kind : "error";
-        log(`Connect-code pre-check unavailable (${kind}); continuing without it.`);
+        const guidance = err instanceof ClawlingApiError ? readConnectFailureGuidance(err.meta?.data) : {};
+        const action = guidance.nextAction ? `; next_action: ${guidance.nextAction}` : "";
+        const hint = guidance.hint ? `. ${guidance.hint}` : "";
+        log(`Connect-code pre-check unavailable (${kind}${action})${hint}; continuing without it.`);
         return null;
     }
 }

package/dist/src/connect-failure.js

@@ -0,0 +1,78 @@
+/** Default wait for `wait_retry` when the server omits / garbles the delay. */
+export const WAIT_RETRY_DEFAULT_SECONDS = 60;
+/** Upper bound on any `wait_retry` wait, whatever the server asks for. */
+export const WAIT_RETRY_MAX_SECONDS = 120;
+function readNonBlankString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
+export function readConnectFailureGuidance(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return {};
+    const record = data;
+    const out = {};
+    const hint = readNonBlankString(record.hint);
+    if (hint)
+        out.hint = hint;
+    const nextAction = readNonBlankString(record.next_action);
+    if (nextAction)
+        out.nextAction = nextAction;
+    const retryAfter = record.retry_after_seconds;
+    if (typeof retryAfter === "number" && Number.isFinite(retryAfter)) {
+        out.retryAfterSeconds = retryAfter;
+    }
+    return out;
+}
+/** Delay before the single `wait_retry` retry: server value, capped, with a default. */
+export function waitRetryDelayMs(retryAfterSeconds) {
+    const seconds = typeof retryAfterSeconds === "number" && Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0
+        ? Math.min(retryAfterSeconds, WAIT_RETRY_MAX_SECONDS)
+        : WAIT_RETRY_DEFAULT_SECONDS;
+    return Math.round(seconds * 1000);
+}
+/**
+ * Error thrown by the invite-code login when `/v1/agents/connect` fails.
+ * The message keeps the historical `agents/connect failed (<kind>): <msg>`
+ * prefix; when the server sent guidance it is appended so an agent reading
+ * the CLI / chat-command output knows what to do next.
+ */
+export class ConnectFailedError extends Error {
+    kind;
+    code;
+    status;
+    hint;
+    nextAction;
+    retryAfterSeconds;
+    constructor(kind, serverMessage, meta = {}) {
+        super(formatConnectFailureMessage(kind, serverMessage, meta));
+        this.name = "ConnectFailedError";
+        this.kind = kind;
+        if (meta.code !== undefined)
+            this.code = meta.code;
+        if (meta.status !== undefined)
+            this.status = meta.status;
+        if (meta.hint !== undefined)
+            this.hint = meta.hint;
+        if (meta.nextAction !== undefined)
+            this.nextAction = meta.nextAction;
+        if (meta.retryAfterSeconds !== undefined)
+            this.retryAfterSeconds = meta.retryAfterSeconds;
+    }
+}
+function formatConnectFailureMessage(kind, serverMessage, guidance) {
+    let text = `agents/connect failed (${kind}): ${serverMessage}`;
+    if (guidance.nextAction)
+        text += ` (next_action: ${guidance.nextAction})`;
+    if (guidance.hint)
+        text += `. ${guidance.hint}`;
+    return text;
+}
+export function connectFailedError(err) {
+    return new ConnectFailedError(err.kind, err.message, {
+        ...(err.meta?.code !== undefined ? { code: err.meta.code } : {}),
+        ...(err.meta?.status !== undefined ? { status: err.meta.status } : {}),
+        ...readConnectFailureGuidance(err.meta?.data),
+    });
+}

package/dist/src/dm-recall-default.js

@@ -0,0 +1,179 @@
+/**
+ * Turn off OpenClaw's cross-conversation recall for the agent ClawChat routes
+ * to, once, unless the owner already decided.
+ *
+ * OpenClaw >= 2026.8.1 has `memory.search.rememberAcrossConversations`. When it
+ * is not written anywhere, OpenClaw turns it on unless `session.dmScope` or a
+ * binding isolates DMs (`resolveRememberAcrossConversations`,
+ * packages/memory-host-sdk/src/host/config-utils.ts). The plugin isolates
+ * ClawChat DMs only in memory (`withClawChatSessionScope`), which OpenClaw
+ * cannot see, so recall stays on and a friend's DM can recall the owner's.
+ * Active Memory reads the live gateway config each turn, so a per-turn
+ * override does not reach it: the setting has to be in the config file.
+ *
+ * Where it is read (2026.8.1 / 2026.9.x): the agent's `agents.entries.<id>`
+ * or, when the roster is the legacy array, its `agents.list[]` entry (matched
+ * by `id`); then the global `memory.search`. With no roster in the file there
+ * is one implicit agent, so the global layer IS that agent's.
+ *
+ * Rules (relay openclaw-dm-recall, 10-08):
+ * - only on hosts >= 2026.8.1 (older ones have neither the key nor the recall);
+ * - only when neither layer sets it; an explicit `true` is the owner's choice:
+ *   kept, warned once; an explicit `false` is kept silently;
+ * - only once per agent: a marker in the plugin's state dir records it, so
+ *   whatever the owner changes later is never touched again.
+ */
+import fs from "node:fs";
+import path from "node:path";
+export const DM_RECALL_MARKER_FILENAME = "clawchat-dm-recall-default.json";
+export const DM_RECALL_MIN_HOST = [2026, 8, 1];
+function isRec(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeId(id) {
+    return typeof id === "string" ? id.trim().toLowerCase() : "";
+}
+/** True for a release host >= 2026.8.1. Pre-releases and unknown strings are false. */
+export function hostHasRememberAcrossConversations(version) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec((version ?? "").trim());
+    if (!m)
+        return false;
+    const parts = [Number(m[1]), Number(m[2]), Number(m[3])];
+    for (let i = 0; i < 3; i += 1) {
+        if (parts[i] !== DM_RECALL_MIN_HOST[i])
+            return parts[i] > DM_RECALL_MIN_HOST[i];
+    }
+    return true;
+}
+function findAgentSlot(cfg, agentId) {
+    const agents = isRec(cfg.agents) ? cfg.agents : undefined;
+    const id = normalizeId(agentId);
+    if (agents && Object.hasOwn(agents, "entries") && agents.entries !== undefined) {
+        if (!isRec(agents.entries))
+            return { kind: "missing" };
+        for (const key of Object.keys(agents.entries)) {
+            const entry = agents.entries[key];
+            if (normalizeId(key) === id && isRec(entry))
+                return { kind: "entries", key, entry };
+        }
+        return { kind: "missing" };
+    }
+    if (agents && Object.hasOwn(agents, "list") && agents.list !== undefined) {
+        if (!Array.isArray(agents.list))
+            return { kind: "missing" };
+        const index = agents.list.findIndex((e) => isRec(e) && normalizeId(e.id) === id);
+        return index >= 0 ? { kind: "list", index, entry: agents.list[index] } : { kind: "missing" };
+    }
+    return { kind: "no-roster" };
+}
+function readFlag(holder) {
+    if (!isRec(holder) || !isRec(holder.memory) || !isRec(holder.memory.search))
+        return undefined;
+    const v = holder.memory.search.rememberAcrossConversations;
+    return typeof v === "boolean" ? v : undefined;
+}
+/** The value written at each layer, `undefined` where it is not written. */
+export function readRememberAcrossConversations(cfg, agentId) {
+    const slot = findAgentSlot(cfg, agentId);
+    const agent = slot.kind === "entries" || slot.kind === "list" ? readFlag(slot.entry) : undefined;
+    return { agent, global: readFlag(cfg) };
+}
+function setFlagFalse(holder) {
+    const memory = isRec(holder.memory) ? holder.memory : {};
+    const search = isRec(memory.search) ? memory.search : {};
+    holder.memory = { ...memory, search: { ...search, rememberAcrossConversations: false } };
+}
+/**
+ * Write `rememberAcrossConversations: false` at the agent's own layer of
+ * `cfg` (mutated in place). Returns the dotted path written, or `null` when a
+ * roster exists but does not list the agent (nothing written).
+ */
+export function setAgentRememberAcrossConversationsFalse(cfg, agentId) {
+    const slot = findAgentSlot(cfg, agentId);
+    if (slot.kind === "entries") {
+        setFlagFalse(slot.entry);
+        return `agents.entries.${slot.key}.memory.search`;
+    }
+    if (slot.kind === "list") {
+        setFlagFalse(slot.entry);
+        return `agents.list[${slot.index}].memory.search`;
+    }
+    if (slot.kind === "no-roster") {
+        setFlagFalse(cfg);
+        return "memory.search";
+    }
+    return null;
+}
+function readMarker(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        return isRec(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeMarker(file, agentId, outcome) {
+    const marker = readMarker(file);
+    const agents = isRec(marker.agents) ? marker.agents : {};
+    agents[normalizeId(agentId)] = { outcome, at: new Date().toISOString() };
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify({ ...marker, agents }, null, 2)}\n`);
+}
+/** Apply the one-time default. Never throws. */
+export async function applyDmRecallDefault(params) {
+    const { agentId, log } = params;
+    const markerFile = path.join(params.stateDir, DM_RECALL_MARKER_FILENAME);
+    try {
+        if (readMarker(markerFile).agents?.[normalizeId(agentId)])
+            return "already-handled";
+        if (!hostHasRememberAcrossConversations(params.hostVersion))
+            return "unsupported-host";
+        const cfg = params.readConfig();
+        const current = readRememberAcrossConversations(isRec(cfg) ? cfg : {}, agentId);
+        const explicit = current.agent ?? current.global;
+        if (explicit === true) {
+            log?.warn?.(`clawchat-plugin-openclaw: memory.search.rememberAcrossConversations is true for agent '${agentId}', so a ` +
+                "friend's ClawChat direct chat can recall what the owner said in theirs. Kept as set. To turn it off: " +
+                `openclaw config set memory.search.rememberAcrossConversations false (or set it to false on agent '${agentId}'), then restart the gateway.`);
+            writeMarker(markerFile, agentId, "kept-true");
+            return "kept-true";
+        }
+        if (explicit === false) {
+            writeMarker(markerFile, agentId, "kept-false");
+            return "kept-false";
+        }
+        if (findAgentSlot(isRec(cfg) ? cfg : {}, agentId).kind === "missing") {
+            log?.info?.(`clawchat-plugin-openclaw: agent '${agentId}' is not in the agents roster; rememberAcrossConversations left unset`);
+            return "agent-not-in-roster";
+        }
+        let written = null;
+        let raced;
+        await params.mutateConfigFile({
+            afterWrite: { mode: "none", reason: "clawchat-plugin-openclaw: no recall across ClawChat direct chats" },
+            mutate(draft) {
+                // Re-check on the locked, current file: someone may have set it meanwhile.
+                const now = readRememberAcrossConversations(draft, agentId);
+                raced = now.agent ?? now.global;
+                if (raced !== undefined)
+                    return;
+                written = setAgentRememberAcrossConversationsFalse(draft, agentId);
+            },
+        });
+        if (written === null) {
+            if (raced === undefined)
+                return "agent-not-in-roster";
+            const outcome = raced ? "kept-true" : "kept-false";
+            writeMarker(markerFile, agentId, outcome);
+            return outcome;
+        }
+        writeMarker(markerFile, agentId, "wrote-false");
+        log?.info?.(`clawchat-plugin-openclaw: set ${written}.rememberAcrossConversations=false for agent '${agentId}' ` +
+            "(ClawChat direct chats with different people no longer recall each other)");
+        return "wrote-false";
+    }
+    catch (err) {
+        log?.error?.(`clawchat-plugin-openclaw: could not apply the rememberAcrossConversations default for agent '${agentId}': ${err instanceof Error ? err.message : String(err)}`);
+        return "write-failed";
+    }
+}

package/dist/src/login.runtime.js

@@ -8,10 +8,14 @@ import { CHANNEL_ID, mergeOpenclawClawchatRuntimePluginActivation, mergeOpenclaw
 import { getClawChatStore } from "./storage.js";
 import { buildOnboardingContext, RECONNECT_GUIDE_URL } from "./onboarding-context.js";
 import { boundCodeNewIdentityMessage, preCheckConnectCode, unpairableMessage } from "./connect-check.js";
+import { connectFailedError, readConnectFailureGuidance, waitRetryDelayMs } from "./connect-failure.js";
 // Re-exported: `src/login.runtime.test.ts` and `src/commands.ts` import these
 // from here, so the historical import path keeps working after the move.
 import { AGENTS_CONNECT_PLATFORM, AGENTS_CONNECT_TYPE, AGENT_NOT_FOUND_CODE, } from "./onboarding-context.js";
 export { AGENTS_CONNECT_PLATFORM, AGENTS_CONNECT_TYPE, AGENT_NOT_FOUND_CODE };
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 /**
  * Thrown when redeeming an invite code would silently replace a live activation.
  *
@@ -284,8 +288,31 @@ export async function runOpenclawClawlingLogin(params) {
     // 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 = newAccount ? "" : storedUserId;
+    // Rate-limit (`next_action: wait_retry`) budget: one wait-and-retry per
+    // activation, shared across both requests below.
+    let waitRetryUsed = false;
+    const sleep = params.sleep ?? defaultSleep;
+    const redeem = async (body) => {
+        try {
+            return await apiClient.agentsConnect(body);
+        }
+        catch (err) {
+            if (!(err instanceof ClawlingApiError) || waitRetryUsed)
+                throw err;
+            const guidance = readConnectFailureGuidance(err.meta?.data);
+            // Only wait_retry is retried: a rate-limited request did not consume the
+            // code. Every other next_action (and any unknown one) is final.
+            if (guidance.nextAction !== "wait_retry")
+                throw err;
+            waitRetryUsed = true;
+            const delayMs = waitRetryDelayMs(guidance.retryAfterSeconds);
+            runtime.log(`Connect code redeem rate limited — retrying once in ${Math.round(delayMs / 1000)}s …`);
+            await sleep(delayMs);
+            return await apiClient.agentsConnect(body);
+        }
+    };
     try {
-        result = await apiClient.agentsConnect({
+        result = await redeem({
             code: inviteCode,
             platform: AGENTS_CONNECT_PLATFORM,
             type: AGENTS_CONNECT_TYPE,
@@ -306,7 +333,7 @@ export async function runOpenclawClawlingLogin(params) {
             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({
+                    result = await redeem({
                         code: inviteCode,
                         platform: AGENTS_CONNECT_PLATFORM,
                         type: AGENTS_CONNECT_TYPE,
@@ -315,13 +342,13 @@ export async function runOpenclawClawlingLogin(params) {
                 }
                 catch (retryErr) {
                     if (retryErr instanceof ClawlingApiError) {
-                        throw new Error(`agents/connect failed (${retryErr.kind}): ${retryErr.message}`);
+                        throw connectFailedError(retryErr);
                     }
                     throw retryErr;
                 }
             }
             else {
-                throw new Error(`agents/connect failed (${err.kind}): ${err.message}`);
+                throw connectFailedError(err);
             }
         }
         else {

package/dist/src/runtime.js

@@ -1,3 +1,4 @@
+import { applyDmRecallDefault } from "./dm-recall-default.js";
 import { AckTimeoutError, AuthError, ProtocolError, StateError, TransportError, EVENT, recallTargetMessageId, } from "./protocol-types.js";
 import { waitUntilAbort } from "openclaw/plugin-sdk/channel-lifecycle";
 import { hasControlCommand } from "openclaw/plugin-sdk/command-detection";
@@ -937,6 +938,48 @@ export async function startOpenclawClawlingGateway(params) {
             ? runtimeConfig.mutateConfigFile
             : undefined;
     };
+    // OpenClaw >= 2026.8.1 recalls across a single agent's DMs unless DM isolation
+    // is visible in the gateway config; ours is in-memory only. Write the agent's
+    // `rememberAcrossConversations: false` once, unless the owner set it
+    // (dm-recall-default.ts). Fire-and-forget: never blocks or fails startup.
+    void (async () => {
+        const stateDir = runtime.state?.resolveStateDir?.();
+        const mutateConfigFile = resolveMutateConfigFile();
+        const readConfig = runtime.config?.current;
+        if (!stateDir || !mutateConfigFile || typeof readConfig !== "function")
+            return;
+        let agentId;
+        try {
+            agentId = runtime.channel.routing.resolveAgentRoute({
+                cfg: withClawChatSessionScope(cfg),
+                channel: CHANNEL_ID,
+                accountId,
+                peer: { kind: "direct", id: account.ownerUserId || "owner" },
+            }).agentId;
+        }
+        catch (err) {
+            log?.info?.(`[${accountId}] clawchat-plugin-openclaw rememberAcrossConversations default skipped: agent route unavailable (${err instanceof Error ? err.message : String(err)})`);
+            return;
+        }
+        await applyDmRecallDefault({
+            agentId,
+            hostVersion: runtime.version,
+            stateDir,
+            readConfig: () => readConfig.call(runtime.config),
+            mutateConfigFile: mutateConfigFile,
+            log: {
+                info: (m) => log?.info?.(`[${accountId}] ${m}`),
+                warn: (m) => {
+                    const warn = log?.warn;
+                    if (warn)
+                        warn(`[${accountId}] ${m}`);
+                    else
+                        log?.info?.(`[${accountId}] WARNING ${m}`);
+                },
+                error: (m) => log?.error?.(`[${accountId}] ${m}`),
+            },
+        });
+    })();
     // §0/§C.1 — write the account slot's `token`/`refreshToken` keys. `tokens=null`
     // blanks them (auto-logout); otherwise persists the rotated pair.
     const persistConfigTokens = async (tokens) => {

package/package.json

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

package/src/connect-check.ts

@@ -1,5 +1,6 @@
 import { ClawlingApiError } from "./api-types.ts";
 import type { OpenclawClawlingApiClient } from "./api-client.ts";
+import { readConnectFailureGuidance } from "./connect-failure.ts";
 import { AGENTS_CONNECT_PLATFORM, RECONNECT_GUIDE_URL } from "./onboarding-context.ts";
 
 export interface ConnectPreCheck {
@@ -41,8 +42,14 @@ export async function preCheckConnectCode(
       userIdStatus: typeof res.user_id_status === "string" ? res.user_id_status : "",
     };
   } catch (err) {
+    // Still a degrade, never a gate: `/connect` re-evaluates the code and
+    // surfaces the same guidance on the error it throws. The guidance is only
+    // logged here so a rate-limit or dead code is visible early.
     const kind = err instanceof ClawlingApiError ? err.kind : "error";
-    log(`Connect-code pre-check unavailable (${kind}); continuing without it.`);
+    const guidance = err instanceof ClawlingApiError ? readConnectFailureGuidance(err.meta?.data) : {};
+    const action = guidance.nextAction ? `; next_action: ${guidance.nextAction}` : "";
+    const hint = guidance.hint ? `. ${guidance.hint}` : "";
+    log(`Connect-code pre-check unavailable (${kind}${action})${hint}; continuing without it.`);
     return null;
   }
 }

package/src/connect-failure.ts

@@ -0,0 +1,109 @@
+import type { ClawlingApiError, ClawlingApiErrorKind } from "./api-types.ts";
+
+/**
+ * Machine-readable guidance the backend attaches to the error envelope's
+ * `data` on a failed `POST /v1/agents/connect` (and `/connect/check`). Every
+ * field is optional: older servers send none of them, and then the plugin
+ * behaves exactly as before.
+ *
+ * Known `next_action` values (closed enum on the server; any other value is
+ * surfaced verbatim and never retried):
+ * - `ask_owner_new_code` — the code is dead (unknown / expired); never retry.
+ * - `wait_retry`         — rate limited; the code was NOT consumed. Wait
+ *                          `retry_after_seconds`, then retry once.
+ * - `reconnect`          — redeemed from another device; the owner must send
+ *                          a reconnect prompt.
+ * - `stop`               — an unchanged retry fails the same way.
+ */
+export type ConnectNextAction = "ask_owner_new_code" | "wait_retry" | "reconnect" | "stop";
+
+export interface ConnectFailureGuidance {
+  hint?: string;
+  /** A `ConnectNextAction`, or an unknown value passed through verbatim. */
+  nextAction?: ConnectNextAction | (string & {});
+  retryAfterSeconds?: number;
+}
+
+/** Default wait for `wait_retry` when the server omits / garbles the delay. */
+export const WAIT_RETRY_DEFAULT_SECONDS = 60;
+/** Upper bound on any `wait_retry` wait, whatever the server asks for. */
+export const WAIT_RETRY_MAX_SECONDS = 120;
+
+function readNonBlankString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export function readConnectFailureGuidance(data: unknown): ConnectFailureGuidance {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return {};
+  const record = data as Record<string, unknown>;
+  const out: ConnectFailureGuidance = {};
+  const hint = readNonBlankString(record.hint);
+  if (hint) out.hint = hint;
+  const nextAction = readNonBlankString(record.next_action);
+  if (nextAction) out.nextAction = nextAction;
+  const retryAfter = record.retry_after_seconds;
+  if (typeof retryAfter === "number" && Number.isFinite(retryAfter)) {
+    out.retryAfterSeconds = retryAfter;
+  }
+  return out;
+}
+
+/** Delay before the single `wait_retry` retry: server value, capped, with a default. */
+export function waitRetryDelayMs(retryAfterSeconds: number | undefined): number {
+  const seconds =
+    typeof retryAfterSeconds === "number" && Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0
+      ? Math.min(retryAfterSeconds, WAIT_RETRY_MAX_SECONDS)
+      : WAIT_RETRY_DEFAULT_SECONDS;
+  return Math.round(seconds * 1000);
+}
+
+/**
+ * Error thrown by the invite-code login when `/v1/agents/connect` fails.
+ * The message keeps the historical `agents/connect failed (<kind>): <msg>`
+ * prefix; when the server sent guidance it is appended so an agent reading
+ * the CLI / chat-command output knows what to do next.
+ */
+export class ConnectFailedError extends Error {
+  readonly kind: ClawlingApiErrorKind;
+  readonly code?: number;
+  readonly status?: number;
+  readonly hint?: string;
+  readonly nextAction?: ConnectFailureGuidance["nextAction"];
+  readonly retryAfterSeconds?: number;
+
+  constructor(
+    kind: ClawlingApiErrorKind,
+    serverMessage: string,
+    meta: { code?: number; status?: number } & ConnectFailureGuidance = {},
+  ) {
+    super(formatConnectFailureMessage(kind, serverMessage, meta));
+    this.name = "ConnectFailedError";
+    this.kind = kind;
+    if (meta.code !== undefined) this.code = meta.code;
+    if (meta.status !== undefined) this.status = meta.status;
+    if (meta.hint !== undefined) this.hint = meta.hint;
+    if (meta.nextAction !== undefined) this.nextAction = meta.nextAction;
+    if (meta.retryAfterSeconds !== undefined) this.retryAfterSeconds = meta.retryAfterSeconds;
+  }
+}
+
+function formatConnectFailureMessage(
+  kind: ClawlingApiErrorKind,
+  serverMessage: string,
+  guidance: ConnectFailureGuidance,
+): string {
+  let text = `agents/connect failed (${kind}): ${serverMessage}`;
+  if (guidance.nextAction) text += ` (next_action: ${guidance.nextAction})`;
+  if (guidance.hint) text += `. ${guidance.hint}`;
+  return text;
+}
+
+export function connectFailedError(err: ClawlingApiError): ConnectFailedError {
+  return new ConnectFailedError(err.kind, err.message, {
+    ...(err.meta?.code !== undefined ? { code: err.meta.code } : {}),
+    ...(err.meta?.status !== undefined ? { status: err.meta.status } : {}),
+    ...readConnectFailureGuidance(err.meta?.data),
+  });
+}

package/src/dm-recall-default.ts

@@ -0,0 +1,230 @@
+/**
+ * Turn off OpenClaw's cross-conversation recall for the agent ClawChat routes
+ * to, once, unless the owner already decided.
+ *
+ * OpenClaw >= 2026.8.1 has `memory.search.rememberAcrossConversations`. When it
+ * is not written anywhere, OpenClaw turns it on unless `session.dmScope` or a
+ * binding isolates DMs (`resolveRememberAcrossConversations`,
+ * packages/memory-host-sdk/src/host/config-utils.ts). The plugin isolates
+ * ClawChat DMs only in memory (`withClawChatSessionScope`), which OpenClaw
+ * cannot see, so recall stays on and a friend's DM can recall the owner's.
+ * Active Memory reads the live gateway config each turn, so a per-turn
+ * override does not reach it: the setting has to be in the config file.
+ *
+ * Where it is read (2026.8.1 / 2026.9.x): the agent's `agents.entries.<id>`
+ * or, when the roster is the legacy array, its `agents.list[]` entry (matched
+ * by `id`); then the global `memory.search`. With no roster in the file there
+ * is one implicit agent, so the global layer IS that agent's.
+ *
+ * Rules (relay openclaw-dm-recall, 10-08):
+ * - only on hosts >= 2026.8.1 (older ones have neither the key nor the recall);
+ * - only when neither layer sets it; an explicit `true` is the owner's choice:
+ *   kept, warned once; an explicit `false` is kept silently;
+ * - only once per agent: a marker in the plugin's state dir records it, so
+ *   whatever the owner changes later is never touched again.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+export const DM_RECALL_MARKER_FILENAME = "clawchat-dm-recall-default.json";
+export const DM_RECALL_MIN_HOST: readonly [number, number, number] = [2026, 8, 1];
+
+export type DmRecallOutcome =
+  | "wrote-false"
+  | "kept-true"
+  | "kept-false"
+  | "already-handled"
+  | "unsupported-host"
+  | "agent-not-in-roster"
+  | "write-failed";
+
+type Rec = Record<string, unknown>;
+
+type MutateConfigFile = (params: {
+  afterWrite: { mode: "none"; reason: string };
+  mutate: (draft: Rec) => void;
+}) => Promise<unknown>;
+
+type Log = {
+  info?: (msg: string) => void;
+  warn?: (msg: string) => void;
+  error?: (msg: string) => void;
+};
+
+function isRec(value: unknown): value is Rec {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function normalizeId(id: unknown): string {
+  return typeof id === "string" ? id.trim().toLowerCase() : "";
+}
+
+/** True for a release host >= 2026.8.1. Pre-releases and unknown strings are false. */
+export function hostHasRememberAcrossConversations(version: string | undefined | null): boolean {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec((version ?? "").trim());
+  if (!m) return false;
+  const parts = [Number(m[1]), Number(m[2]), Number(m[3])];
+  for (let i = 0; i < 3; i += 1) {
+    if (parts[i] !== DM_RECALL_MIN_HOST[i]) return parts[i] > DM_RECALL_MIN_HOST[i];
+  }
+  return true;
+}
+
+type AgentSlot =
+  | { kind: "entries"; key: string; entry: Rec }
+  | { kind: "list"; index: number; entry: Rec }
+  | { kind: "no-roster" }
+  | { kind: "missing" };
+
+function findAgentSlot(cfg: Rec, agentId: string): AgentSlot {
+  const agents = isRec(cfg.agents) ? cfg.agents : undefined;
+  const id = normalizeId(agentId);
+  if (agents && Object.hasOwn(agents, "entries") && agents.entries !== undefined) {
+    if (!isRec(agents.entries)) return { kind: "missing" };
+    for (const key of Object.keys(agents.entries)) {
+      const entry = agents.entries[key];
+      if (normalizeId(key) === id && isRec(entry)) return { kind: "entries", key, entry };
+    }
+    return { kind: "missing" };
+  }
+  if (agents && Object.hasOwn(agents, "list") && agents.list !== undefined) {
+    if (!Array.isArray(agents.list)) return { kind: "missing" };
+    const index = agents.list.findIndex((e) => isRec(e) && normalizeId(e.id) === id);
+    return index >= 0 ? { kind: "list", index, entry: agents.list[index] as Rec } : { kind: "missing" };
+  }
+  return { kind: "no-roster" };
+}
+
+function readFlag(holder: unknown): boolean | undefined {
+  if (!isRec(holder) || !isRec(holder.memory) || !isRec(holder.memory.search)) return undefined;
+  const v = holder.memory.search.rememberAcrossConversations;
+  return typeof v === "boolean" ? v : undefined;
+}
+
+/** The value written at each layer, `undefined` where it is not written. */
+export function readRememberAcrossConversations(
+  cfg: Rec,
+  agentId: string,
+): { agent: boolean | undefined; global: boolean | undefined } {
+  const slot = findAgentSlot(cfg, agentId);
+  const agent = slot.kind === "entries" || slot.kind === "list" ? readFlag(slot.entry) : undefined;
+  return { agent, global: readFlag(cfg) };
+}
+
+function setFlagFalse(holder: Rec): void {
+  const memory = isRec(holder.memory) ? holder.memory : {};
+  const search = isRec(memory.search) ? memory.search : {};
+  holder.memory = { ...memory, search: { ...search, rememberAcrossConversations: false } };
+}
+
+/**
+ * Write `rememberAcrossConversations: false` at the agent's own layer of
+ * `cfg` (mutated in place). Returns the dotted path written, or `null` when a
+ * roster exists but does not list the agent (nothing written).
+ */
+export function setAgentRememberAcrossConversationsFalse(cfg: Rec, agentId: string): string | null {
+  const slot = findAgentSlot(cfg, agentId);
+  if (slot.kind === "entries") {
+    setFlagFalse(slot.entry);
+    return `agents.entries.${slot.key}.memory.search`;
+  }
+  if (slot.kind === "list") {
+    setFlagFalse(slot.entry);
+    return `agents.list[${slot.index}].memory.search`;
+  }
+  if (slot.kind === "no-roster") {
+    setFlagFalse(cfg);
+    return "memory.search";
+  }
+  return null;
+}
+
+type Marker = { agents?: Record<string, { outcome: DmRecallOutcome; at: string }> };
+
+function readMarker(file: string): Marker {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8")) as unknown;
+    return isRec(parsed) ? (parsed as Marker) : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeMarker(file: string, agentId: string, outcome: DmRecallOutcome): void {
+  const marker = readMarker(file);
+  const agents = isRec(marker.agents) ? marker.agents : {};
+  agents[normalizeId(agentId)] = { outcome, at: new Date().toISOString() };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify({ ...marker, agents }, null, 2)}\n`);
+}
+
+/** Apply the one-time default. Never throws. */
+export async function applyDmRecallDefault(params: {
+  agentId: string;
+  hostVersion: string | undefined | null;
+  stateDir: string;
+  readConfig: () => unknown;
+  mutateConfigFile: MutateConfigFile;
+  log?: Log;
+}): Promise<DmRecallOutcome> {
+  const { agentId, log } = params;
+  const markerFile = path.join(params.stateDir, DM_RECALL_MARKER_FILENAME);
+  try {
+    if (readMarker(markerFile).agents?.[normalizeId(agentId)]) return "already-handled";
+    if (!hostHasRememberAcrossConversations(params.hostVersion)) return "unsupported-host";
+
+    const cfg = params.readConfig();
+    const current = readRememberAcrossConversations(isRec(cfg) ? cfg : {}, agentId);
+    const explicit = current.agent ?? current.global;
+    if (explicit === true) {
+      log?.warn?.(
+        `clawchat-plugin-openclaw: memory.search.rememberAcrossConversations is true for agent '${agentId}', so a ` +
+          "friend's ClawChat direct chat can recall what the owner said in theirs. Kept as set. To turn it off: " +
+          `openclaw config set memory.search.rememberAcrossConversations false (or set it to false on agent '${agentId}'), then restart the gateway.`,
+      );
+      writeMarker(markerFile, agentId, "kept-true");
+      return "kept-true";
+    }
+    if (explicit === false) {
+      writeMarker(markerFile, agentId, "kept-false");
+      return "kept-false";
+    }
+
+    if (findAgentSlot(isRec(cfg) ? cfg : {}, agentId).kind === "missing") {
+      log?.info?.(
+        `clawchat-plugin-openclaw: agent '${agentId}' is not in the agents roster; rememberAcrossConversations left unset`,
+      );
+      return "agent-not-in-roster";
+    }
+
+    let written: string | null = null;
+    let raced: boolean | undefined;
+    await params.mutateConfigFile({
+      afterWrite: { mode: "none", reason: "clawchat-plugin-openclaw: no recall across ClawChat direct chats" },
+      mutate(draft) {
+        // Re-check on the locked, current file: someone may have set it meanwhile.
+        const now = readRememberAcrossConversations(draft, agentId);
+        raced = now.agent ?? now.global;
+        if (raced !== undefined) return;
+        written = setAgentRememberAcrossConversationsFalse(draft, agentId);
+      },
+    });
+    if (written === null) {
+      if (raced === undefined) return "agent-not-in-roster";
+      const outcome: DmRecallOutcome = raced ? "kept-true" : "kept-false";
+      writeMarker(markerFile, agentId, outcome);
+      return outcome;
+    }
+    writeMarker(markerFile, agentId, "wrote-false");
+    log?.info?.(
+      `clawchat-plugin-openclaw: set ${written}.rememberAcrossConversations=false for agent '${agentId}' ` +
+        "(ClawChat direct chats with different people no longer recall each other)",
+    );
+    return "wrote-false";
+  } catch (err) {
+    log?.error?.(
+      `clawchat-plugin-openclaw: could not apply the rememberAcrossConversations default for agent '${agentId}': ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return "write-failed";
+  }
+}

package/src/login.runtime.ts

@@ -16,6 +16,7 @@ import {
 import { getClawChatStore, type ClawChatStore } from "./storage.ts";
 import { buildOnboardingContext, RECONNECT_GUIDE_URL } from "./onboarding-context.ts";
 import { boundCodeNewIdentityMessage, preCheckConnectCode, unpairableMessage } from "./connect-check.ts";
+import { connectFailedError, readConnectFailureGuidance, waitRetryDelayMs } from "./connect-failure.ts";
 // Re-exported: `src/login.runtime.test.ts` and `src/commands.ts` import these
 // from here, so the historical import path keeps working after the move.
 import {
@@ -68,6 +69,15 @@ export interface LoginParams {
    * `promptActivationIntentFromStdin`; overridden by tests.
    */
   readActivationIntent?: () => Promise<ActivationIntent | null>;
+  /**
+   * Wait used before the single `next_action: wait_retry` retry of
+   * `/v1/agents/connect`. Defaults to a `setTimeout`; overridden by tests.
+   */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
 /** The two outcomes available once an identity is already stored. */
@@ -396,8 +406,30 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
   // 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 = newAccount ? "" : storedUserId;
+  // Rate-limit (`next_action: wait_retry`) budget: one wait-and-retry per
+  // activation, shared across both requests below.
+  let waitRetryUsed = false;
+  const sleep = params.sleep ?? defaultSleep;
+  const redeem = async (body: Parameters<typeof apiClient.agentsConnect>[0]) => {
+    try {
+      return await apiClient.agentsConnect(body);
+    } catch (err) {
+      if (!(err instanceof ClawlingApiError) || waitRetryUsed) throw err;
+      const guidance = readConnectFailureGuidance(err.meta?.data);
+      // Only wait_retry is retried: a rate-limited request did not consume the
+      // code. Every other next_action (and any unknown one) is final.
+      if (guidance.nextAction !== "wait_retry") throw err;
+      waitRetryUsed = true;
+      const delayMs = waitRetryDelayMs(guidance.retryAfterSeconds);
+      runtime.log(
+        `Connect code redeem rate limited — retrying once in ${Math.round(delayMs / 1000)}s …`,
+      );
+      await sleep(delayMs);
+      return await apiClient.agentsConnect(body);
+    }
+  };
   try {
-    result = await apiClient.agentsConnect({
+    result = await redeem({
       code: inviteCode,
       platform: AGENTS_CONNECT_PLATFORM,
       type: AGENTS_CONNECT_TYPE,
@@ -419,7 +451,7 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
           `Stored userId ${existingUserId} no longer exists on this server — retrying as a fresh pairing …`,
         );
         try {
-          result = await apiClient.agentsConnect({
+          result = await redeem({
             code: inviteCode,
             platform: AGENTS_CONNECT_PLATFORM,
             type: AGENTS_CONNECT_TYPE,
@@ -427,12 +459,12 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
           });
         } catch (retryErr) {
           if (retryErr instanceof ClawlingApiError) {
-            throw new Error(`agents/connect failed (${retryErr.kind}): ${retryErr.message}`);
+            throw connectFailedError(retryErr);
           }
           throw retryErr;
         }
       } else {
-        throw new Error(`agents/connect failed (${err.kind}): ${err.message}`);
+        throw connectFailedError(err);
       }
     } else {
       throw err;

package/src/runtime.ts

@@ -1,3 +1,4 @@
+import { applyDmRecallDefault } from "./dm-recall-default.ts";
 import {
   AckTimeoutError,
   AuthError,
@@ -1293,6 +1294,47 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       : undefined;
   };
 
+  // OpenClaw >= 2026.8.1 recalls across a single agent's DMs unless DM isolation
+  // is visible in the gateway config; ours is in-memory only. Write the agent's
+  // `rememberAcrossConversations: false` once, unless the owner set it
+  // (dm-recall-default.ts). Fire-and-forget: never blocks or fails startup.
+  void (async () => {
+    const stateDir = runtime.state?.resolveStateDir?.();
+    const mutateConfigFile = resolveMutateConfigFile();
+    const readConfig = (runtime.config as { current?: () => unknown } | undefined)?.current;
+    if (!stateDir || !mutateConfigFile || typeof readConfig !== "function") return;
+    let agentId: string;
+    try {
+      agentId = runtime.channel.routing.resolveAgentRoute({
+        cfg: withClawChatSessionScope(cfg),
+        channel: CHANNEL_ID,
+        accountId,
+        peer: { kind: "direct", id: account.ownerUserId || "owner" },
+      }).agentId;
+    } catch (err) {
+      log?.info?.(
+        `[${accountId}] clawchat-plugin-openclaw rememberAcrossConversations default skipped: agent route unavailable (${err instanceof Error ? err.message : String(err)})`,
+      );
+      return;
+    }
+    await applyDmRecallDefault({
+      agentId,
+      hostVersion: runtime.version,
+      stateDir,
+      readConfig: () => readConfig.call(runtime.config),
+      mutateConfigFile: mutateConfigFile as never,
+      log: {
+        info: (m) => log?.info?.(`[${accountId}] ${m}`),
+        warn: (m) => {
+          const warn = (log as { warn?: (msg: string) => void } | undefined)?.warn;
+          if (warn) warn(`[${accountId}] ${m}`);
+          else log?.info?.(`[${accountId}] WARNING ${m}`);
+        },
+        error: (m) => log?.error?.(`[${accountId}] ${m}`),
+      },
+    });
+  })();
+
   // §0/§C.1 — write the account slot's `token`/`refreshToken` keys. `tokens=null`
   // blanks them (auto-logout); otherwise persists the rotated pair.
   const persistConfigTokens = async (