@clawling/clawchat-plugin-openclaw 2026.10.9-1 → 2026.10.9-3

package/openclaw.plugin.json

@@ -132,6 +132,7 @@
       "note-cap-group": { "type": "integer" },
       "note-cap-turn": { "type": "integer" },
       "delta-budget-chars": { "type": "integer" },
+      "non-owner-host-tools": { "type": "string", "enum": ["off", "approve"] },
       "reconnect": {
         "type": "object",
         "additionalProperties": false,
@@ -210,6 +211,7 @@
             "note-cap-group": { "type": "integer" },
             "note-cap-turn": { "type": "integer" },
             "delta-budget-chars": { "type": "integer" },
+            "non-owner-host-tools": { "type": "string", "enum": ["off", "approve"] },
             "reconnect": {
               "type": "object",
               "additionalProperties": false,
@@ -294,6 +296,7 @@
           "note-cap-group": { "type": "integer" },
           "note-cap-turn": { "type": "integer" },
           "delta-budget-chars": { "type": "integer" },
+          "non-owner-host-tools": { "type": "string", "enum": ["off", "approve"] },
           "reconnect": {
             "type": "object",
             "additionalProperties": false,
@@ -372,6 +375,7 @@
                 "note-cap-group": { "type": "integer" },
                 "note-cap-turn": { "type": "integer" },
                 "delta-budget-chars": { "type": "integer" },
+                "non-owner-host-tools": { "type": "string", "enum": ["off", "approve"] },
                 "reconnect": {
                   "type": "object",
                   "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.10.9-1",
+  "version": "2026.10.9-3",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "author": "CLAWLING PTE. LTD.",
@@ -52,7 +52,7 @@
     "@sinclair/typebox": "0.34.48"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.5.4"
+    "openclaw": ">=2026.8.1"
   },
   "peerDependenciesMeta": {
     "openclaw": {
@@ -93,7 +93,7 @@
     "install": {
       "npmSpec": "@clawling/clawchat-plugin-openclaw",
       "defaultChoice": "npm",
-      "minHostVersion": ">=2026.5.4"
+      "minHostVersion": ">=2026.8.1"
     }
   }
 }

package/src/clawchat-memory.ts

@@ -34,6 +34,13 @@ export interface ClawChatMemorySearchResult {
   query: string;
   matches: ClawChatMemorySearchMatch[];
   truncated: boolean;
+  /** Set by callers whose conversation scope left notes out (never a count). */
+  scopeNote?: string;
+}
+
+export interface ClawChatMemorySearchOptions {
+  /** Targets this caller may see; others are skipped before any content read. */
+  readable?: (target: ClawChatMemoryTarget) => boolean;
 }
 
 const metadataStart = "<!-- clawchat:metadata:start -->";
@@ -434,6 +441,7 @@ function buildSearchMatch(
 export async function searchClawChatMemory(
   root: string,
   params: ClawChatMemorySearchParams,
+  options: ClawChatMemorySearchOptions = {},
 ): Promise<ClawChatMemorySearchResult> {
   const { query, queryLower, targetTypes, maxResults } = normalizeSearchParams(params);
   const rootPath = path.resolve(root);
@@ -443,6 +451,11 @@ export async function searchClawChatMemory(
   for (const targetType of targetTypes) {
     const targets = await listSafeMemoryFiles(rootPath, rootRealPath, targetType);
     for (const target of targets) {
+      // Filter before reading, matching and counting so unreadable notes
+      // leave no trace in matches or `truncated`.
+      if (options.readable && !options.readable(target)) {
+        continue;
+      }
       const file = await readClawChatMemoryFile(rootPath, target);
       if (!file.exists) {
         continue;

package/src/config.ts

@@ -125,6 +125,8 @@ export type OpenclawClawlingAccountConfig = {
   "note-cap-group"?: number;
   "note-cap-turn"?: number;
   "delta-budget-chars"?: number;
+  /** Host tools in turns the owner did not start: `off` | `approve` (approve currently behaves as off). */
+  "non-owner-host-tools"?: string;
   reconnect?: OpenclawClawlingReconnectConfig;
   heartbeat?: OpenclawClawlingHeartbeatConfig;
   ack?: OpenclawClawlingAckConfig;
@@ -190,6 +192,7 @@ export const openclawClawlingAccountConfigSchema = {
     "note-cap-group": { type: "integer" },
     "note-cap-turn": { type: "integer" },
     "delta-budget-chars": { type: "integer" },
+    "non-owner-host-tools": { type: "string", enum: ["off", "approve"] },
     reconnect: {
       type: "object",
       additionalProperties: false,
@@ -337,6 +340,8 @@ export type ResolvedOpenclawClawlingAccount = {
   noteCapTurn: number;
   /** `delta-budget-chars`: characters of unseen group messages an @-mention adds. */
   deltaBudgetChars: number;
+  /** `non-owner-host-tools`: parsed mode; `approve` is reserved and currently behaves like `off`. */
+  nonOwnerHostTools: "off" | "approve";
   allowFrom: string[];
   reconnect: Required<OpenclawClawlingReconnectConfig>;
   heartbeat: Required<OpenclawClawlingHeartbeatConfig>;
@@ -597,6 +602,11 @@ export const SESSION_INT_KEYS = {
   "delta-budget-chars": [8000, 2000, 32000],
 } as const satisfies Record<string, readonly [number, number, number]>;
 
+/** `approve` only when explicitly set; any other value (typo, `on`, boolean) means `off`. */
+export function parseNonOwnerHostTools(raw: unknown): "off" | "approve" {
+  return typeof raw === "string" && raw.trim().toLowerCase() === "approve" ? "approve" : "off";
+}
+
 function readSessionInt(channel: Record<string, unknown>, key: keyof typeof SESSION_INT_KEYS): number {
   const [factory, minimum, maximum] = SESSION_INT_KEYS[key];
   const raw = channel[key];
@@ -739,6 +749,7 @@ export function resolveOpenclawClawlingAccount(
     noteCapGroup: readSessionInt(channel, "note-cap-group"),
     noteCapTurn: readSessionInt(channel, "note-cap-turn"),
     deltaBudgetChars: readSessionInt(channel, "delta-budget-chars"),
+    nonOwnerHostTools: parseNonOwnerHostTools(channel["non-owner-host-tools"]),
     allowFrom: [],
     reconnect: readReconnect(channel.reconnect),
     heartbeat: readHeartbeat(channel.heartbeat),

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/host-tools-guard.ts

@@ -0,0 +1,186 @@
+// Layer 2 of the non-owner turn boundary: a fail-closed `before_tool_call`
+// hook. Dispatch (layer 1) already narrows the offered tools for turns the
+// owner did not start; this hook blocks anything else that still reaches
+// execution. Only calls whose session key carries the ClawChat prefix are
+// in scope (D8); everything else passes untouched. Tool arguments are never
+// logged.
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { CHANNEL_ID, normalizeOpenclawClawlingAccountId, resolveOpenclawClawlingAccount } from "./config.ts";
+import {
+  classifyChat,
+  clawChatSessionAccountId,
+  NON_OWNER_TOOL_ALLOWLIST,
+  parseClawChatSessionKey,
+} from "./turn-boundary.ts";
+import { clawChatDbPathForStateDir, getClawChatStore } from "./storage.ts";
+import { resolveOwnerIdentity } from "./owner-identity.ts";
+import { getRegisteredClawChatToolNames } from "./tools.ts";
+
+export const BLOCK_MESSAGE =
+  "This tool is not available here: only your owner's direct chat may use host tools on this machine. Do not try to reach them another way; answer without them, or tell the person to ask your owner.";
+
+export type HostToolDecision = { block: true; blockReason: string } | undefined;
+export type HostToolInput = {
+  toolName: string;
+  params: Record<string, unknown>;
+  sessionKey?: string;
+  ownerDirectConversationId?: string | null;
+  registeredTools: ReadonlySet<string>;
+};
+
+/**
+ * Host tool-search controls (OpenClaw 2026.9.6+). The host adds them to every
+ * run on its own and builds their catalog from the run's allowed tools, so in
+ * a non-owner turn they reach only the allowlisted tools; the host fires this
+ * hook again for the inner tool a `tool_call` runs, and that inner call gets
+ * every check below. They are not part of the dispatch allowlist.
+ */
+export const HOST_TOOL_SEARCH_CONTROLS: readonly string[] = Object.freeze(["tool_search", "tool_describe", "tool_call"]);
+const ACCOUNT_SCOPED_TOOLS: readonly string[] = ["clawchat_mention_message", "clawchat_react_message"];
+
+const block = (): HostToolDecision => ({ block: true, blockReason: BLOCK_MESSAGE });
+const CLAWCHAT_SESSION_PREFIX = new RegExp(`^agent:[^:]+:${CHANNEL_ID}:`, "i");
+const PATH_FIELD = /^(?:filePath|media|iconPath|path|attachments)$/i;
+
+/** D8: only the ClawChat session-key prefix ties a call to ClawChat; requester channel alone never does. */
+export function isClawChatToolCall(input: Pick<HostToolInput, "sessionKey">): boolean {
+  return CLAWCHAT_SESSION_PREFIX.test(input.sessionKey?.trim() ?? "");
+}
+
+/** True when any argument looks like a local file path; only http(s) URLs are allowed. */
+export function hasLocalPathArgument(value: unknown, field = ""): boolean {
+  if (typeof value === "string") {
+    const text = value.trim();
+    if (/^https?:\/\//i.test(text)) return false;
+    if (/^(?:\/|[a-z]:[\\/]|\\\\|file:|~|\.\.?[\\/])/i.test(text)) return true;
+    return PATH_FIELD.test(field) && text.length > 0;
+  }
+  if (Array.isArray(value)) return value.some(item => hasLocalPathArgument(item, field));
+  return Boolean(value && typeof value === "object" && Object.entries(value).some(
+    ([key, item]) => hasLocalPathArgument(item, PATH_FIELD.test(field) ? field : key),
+  ));
+}
+
+/** Pure decision for one tool call. `undefined` lets the call run. */
+export function decideHostToolCall(input: HostToolInput): HostToolDecision {
+  if (!isClawChatToolCall(input)) return undefined;
+  const parsed = parseClawChatSessionKey(input.sessionKey);
+  if (!parsed) return block();
+  if (classifyChat({ ...parsed, ownerDirectConversationId: input.ownerDirectConversationId }) === "owner") {
+    return undefined;
+  }
+  // Outer pre-check only. The inner tool call is checked again and that check
+  // is authoritative: the host also accepts dotted/flattened argument keys
+  // that this outer check may not recognise.
+  if (hasLocalPathArgument(input.params)) return block();
+  if (HOST_TOOL_SEARCH_CONTROLS.includes(input.toolName)) return undefined;
+  if (ACCOUNT_SCOPED_TOOLS.includes(input.toolName)) {
+    // D9: a non-owner turn may only act on its own chat, named explicitly.
+    const target = input.params.chatId;
+    if (typeof target !== "string" || !target.trim() || target.trim().toLowerCase() !== parsed.chatId) {
+      return {
+        block: true,
+        blockReason: input.toolName === "clawchat_react_message"
+          ? "Pass this chat's chatId to react here."
+          : "Pass this chat's chatId to mention here.",
+      };
+    }
+  }
+  if (NON_OWNER_TOOL_ALLOWLIST.includes(input.toolName)) {
+    return input.toolName.startsWith("clawchat_") && !input.registeredTools.has(input.toolName)
+      ? block()
+      : undefined;
+  }
+  return block(); // `off` and the reserved `approve` both block in this release.
+}
+
+type RequesterContext = { channel?: string; accountId?: string };
+
+export function registerHostToolsGuard(
+  api: OpenClawPluginApi,
+  options: { ownerConversation?: (accountId: string) => string | null } = {},
+): void {
+  const warned = new Set<string>();
+  const warn = (failure: string) => {
+    if (warned.has(failure)) return;
+    warned.add(failure);
+    try {
+      api.logger.warn(`clawchat-plugin-openclaw: host-tool guard ${failure}; enforcing non-owner policy`);
+    } catch {
+      // Logging cannot unlock a call.
+    }
+  };
+  const lookupOwnerConversation = (accountId: string): string | null => {
+    if (options.ownerConversation) return options.ownerConversation(accountId);
+    const account = resolveOpenclawClawlingAccount(api.config, accountId);
+    const stateDir = api.runtime.state?.resolveStateDir?.();
+    const store = getClawChatStore({
+      ...(stateDir ? { dbPath: clawChatDbPathForStateDir(stateDir) } : {}),
+      log: { error: message => api.logger.error?.(message) },
+    });
+    return resolveOwnerIdentity(store, accountId, account.ownerUserId).conversationId;
+  };
+
+  api.on("before_tool_call", (event, sdkCtx) => {
+    // `requester` is host 2026.8.1+ (the floor); the development SDK types predate it.
+    const ctx = sdkCtx as (typeof sdkCtx & { requester?: RequesterContext }) | undefined;
+    try {
+      if (!ctx) {
+        warn("missing-context");
+        return block();
+      }
+      const sessionKey = ctx.sessionKey;
+      if (!isClawChatToolCall({ sessionKey })) return undefined;
+      const requester = ctx.requester;
+      const parsed = parseClawChatSessionKey(sessionKey);
+      if (!parsed || (requester?.channel && requester.channel !== CHANNEL_ID)) {
+        warn("unknown-session");
+        return block();
+      }
+      // Direct keys carry their account; group keys do not. A group turn is
+      // non-owner whoever speaks, so a group call without the requester
+      // account (host tool-search controls and the inner calls they run get
+      // a run-level ctx without one) still gets the non-owner policy; only
+      // the tools that act as an account need it. Conflicting ids block.
+      const keyAccountId = clawChatSessionAccountId(sessionKey);
+      const requesterAccountId = requester?.accountId?.trim()
+        ? normalizeOpenclawClawlingAccountId(requester.accountId)
+        : undefined;
+      const accountId = requesterAccountId ?? keyAccountId;
+      if (keyAccountId && keyAccountId !== accountId) {
+        warn("account-identity");
+        return block();
+      }
+      if (!accountId) {
+        if (parsed.kind !== "group" || ACCOUNT_SCOPED_TOOLS.includes(event.toolName)) {
+          warn("account-identity");
+          return block();
+        }
+        return decideHostToolCall({
+          toolName: event.toolName,
+          params: event.params ?? {},
+          sessionKey,
+          ownerDirectConversationId: null,
+          registeredTools: getRegisteredClawChatToolNames(),
+        });
+      }
+      let ownerDirectConversationId: string | null = null;
+      try {
+        ownerDirectConversationId = lookupOwnerConversation(accountId);
+      } catch {
+        // Treated as missing below; the allowlist still applies.
+      }
+      if (!ownerDirectConversationId?.trim()) warn("missing-owner-conversation");
+      return decideHostToolCall({
+        toolName: event.toolName,
+        params: event.params ?? {},
+        sessionKey,
+        ownerDirectConversationId,
+        registeredTools: getRegisteredClawChatToolNames(),
+      });
+    } catch {
+      warn("handler-exception");
+      return block();
+    }
+  });
+}

package/src/host-version.ts

@@ -0,0 +1,35 @@
+export const HOST_FLOOR = "2026.8.1";
+
+function parse(v: string): [number, number, number] | null {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+/** Prerelease suffixes count as their base version (10.1-beta.2 ≥ 8.1). Unparseable ⇒ false. */
+export function hostAtLeast(version: string | undefined, min: string): boolean {
+  const a = version ? parse(version) : null;
+  const b = parse(min);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] > b[i];
+  return true;
+}
+
+/** First host release where tool search is on unless `tools.toolSearch` turns it off. */
+export const HOST_TOOL_SEARCH_DEFAULT_ON = "2026.9.6";
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/**
+ * Whether the host's `tools.toolSearch` setting leaves tool search on, read the
+ * way the host reads it (2026.9.6+): unset or `true` ⇒ on; `false` ⇒ off; an
+ * object ⇒ its `enabled` flag, else on only when it sets other options.
+ */
+export function hostToolSearchEnabled(config: unknown): boolean {
+  const tools = isRecord(config) ? config.tools : undefined;
+  const raw = isRecord(tools) ? tools.toolSearch : undefined;
+  if (raw === undefined || raw === true) return true;
+  if (!isRecord(raw)) return false;
+  if (typeof raw.enabled === "boolean") return raw.enabled;
+  return Object.keys(raw).some(key => key !== "enabled");
+}

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;