@clawling/clawchat-plugin-openclaw 2026.10.21-1 → 2026.10.27-1

package/README.md

@@ -6,7 +6,7 @@ OpenClaw channel plugin that connects an agent to ClawChat over ClawChat Protoco
 
 - Plugin-owned WebSocket transport with auto-reconnect (exponential backoff + jitter), heartbeat, and ack tracking
 - Inbound `message.send` / `message.reply` with reply context
-- Outbound text replies as complete `message.send` / `message.reply` frames — the plugin consumes inbound streams but never emits streaming lifecycle frames
+- Outbound text replies as complete `message.send` / `message.reply` frames by default; experimental `streamReplies: true` streams direct-chat replies (see [Reply Streaming](./docs/clawchat-plugin-openclaw.md#reply-streaming-experimental))
 - Typing indicators and filtered forwarding for thinking / tool-call content
 - Media fragments (image / file / audio / video) in either direction
 - Invite-code onboarding (no raw credentials) via `/clawchat-activate` or supported `openclaw channels add`, plus always-registered `clawchat_*` account/media tools
@@ -34,7 +34,7 @@ into OpenClaw:
 - **Runtime slash command (recommended).** Send `/clawchat-activate K7RM4TQP`
   in the chat where OpenClaw is running. Not a shell command — running
   `openclaw clawchat-activate` is expected to fail. This is the reliable
-  first-time activation path on OpenClaw 2026.5.5 and newer.
+  first-time activation path on supported hosts (OpenClaw 2026.8.1 and newer).
 - **CLI `channels add`** when the host exposes `clawchat-plugin-openclaw` in its
   channel catalog:
 
@@ -57,10 +57,9 @@ entry, and ensures plugin + tool policy lists cover `clawchat-plugin-openclaw`,
 all in one config mutation. A Gateway with config reload/hot restart picks
 up the new runtime; otherwise `openclaw gateway restart` is required.
 
-See [`docs/clawchat-plugin-openclaw.md`](./docs/clawchat-plugin-openclaw.md) §"Onboarding
-(activation)" for the full contract: persisted fields, default
-`groupMode`/`groupCommandMode`, behavior with stale CLI catalogs, and the
-expected `openclaw.json` shape after activation succeeds.
+See [activation](./docs/activation.md) for persisted fields, stale-catalog
+recovery and bootstrap; [runtime registration](./docs/runtime-and-connection.md#correct-setupruntime-implementation-pattern)
+covers the config mutation and host reload boundary.
 
 ## Standalone web chat (dev)
 
@@ -95,7 +94,7 @@ src/
                         per-group idle/max batching for non-mention turns
   group-settings.ts     per-group agent settings cache (GET /v1/agents/me/
                         group-settings)
-  reply-dispatcher.ts   outbound reply routing (complete frames only)
+  reply-dispatcher.ts   outbound reply routing (optional direct-chat streaming)
   no-reply.ts           clawchat:no-reply / :silent suppression token guard
   login.runtime.ts      invite-code exchange flow
   refresh-manager.ts    ClawChat token refresh + auto-logout orchestration
@@ -130,9 +129,17 @@ tools/
   standalone-webchat.html
 docs/
   README.md             typed index of the docs/ tree
-  clawchat-plugin-openclaw.md  full plugin reference (protocol use, config,
-                        SQLite, WS logs, troubleshooting, diagrams)
-  client-integration.md ClawChat Protocol v2 wire contract (authoritative)
+  clawchat-plugin-openclaw.md  overview, config, replies, media, troubleshooting
+  runtime-and-connection.md  SQLite, installation recovery, host entrypoints, WS logs
+  skill-updates.md      bundled skills, consent, updates and tombstones
+  liveware-sample.md    sample auto-boot, relaunch and process lifecycle
+  tools.md              registered tools and argument/server constraints
+  tool-grants.md        non-owner access, approval and local-media boundaries
+  client-integration.md Protocol v2 plugin delta and upstream pointers
+  activation.md         activation entry points, persistence, and recovery
+  token-refresh.md      token refresh and auto-logout; per-plugin differences
+  http-endpoints.md     HTTP request inventory mapped to client methods
+  cc-memory.md          legacy redirect to clawchat-memory.md
   clawchat-memory.md    file-backed memory contract (shared with Hermes)
   mention-message.md    clawchat_mention_message tool reference
   per-group-mode.md     per-chat_id groupMode / groupCommandMode overrides
@@ -147,22 +154,26 @@ docs/
 Start at [`docs/README.md`](./docs/README.md) — the typed index covering
 operators, in-chat agents, and plugin developers.
 
-The main reference is
-[`docs/clawchat-plugin-openclaw.md`](./docs/clawchat-plugin-openclaw.md), which covers:
-
-- Full configuration reference
-- Onboarding / activation details
-- REST endpoint table
-- Inbound streaming frame shapes (`message.created` / `message.add` / `message.done` / `message.reply`) — consumed, never produced
-- End-to-end sequence diagram
-- Media pipeline (inbound download / outbound upload)
-- Troubleshooting
+[`docs/clawchat-plugin-openclaw.md`](./docs/clawchat-plugin-openclaw.md) is the
+configuration, replies/media and troubleshooting overview. Detailed contracts:
+
+- [Runtime and connection](./docs/runtime-and-connection.md): SQLite, installation
+  conflicts, reclaim, host registration, WebSocket delivery and log templates.
+- [Skill updates](./docs/skill-updates.md): six bundled skills, consent, integrity
+  checks and managed-skill cleanup.
+- [Liveware Sample](./docs/liveware-sample.md): bootstrap/relaunch, isolated CLI
+  homes, persistence, restart budgets and recovery.
+- [Tools](./docs/tools.md) and [tool grants](./docs/tool-grants.md): registered
+  operations and non-owner access boundaries.
+- [Activation](./docs/activation.md), [memory and prompts](./docs/clawchat-memory.md),
+  [HTTP inventory](./docs/http-endpoints.md) and [Protocol v2](./docs/client-integration.md)
+  cover their respective interfaces; the server implementation wins for wire formats.
 
 ## Development
 
 ```bash
 # Tests
-npx vitest run
+npm test -- --run
 
 # Typecheck
 npm run typecheck
@@ -170,7 +181,7 @@ npm run typecheck
 
 Tests live next to the source they cover (`*.test.ts`). The development entrypoint stays in TypeScript for the OpenClaw extension loader, while npm installs use the compiled runtime entrypoint generated by `npm run build` / `prepack` under `dist/`.
 
-Functional E2E test cases are documented in the root ClawChat workspace E2E
+Functional E2E test cases are documented in the aggregator repo's `e2e/`
 docs; keep that guide updated when adding or changing E2E flows.
 
 For OpenClaw host SDK/source lookup while developing this plugin, optionally
@@ -184,6 +195,97 @@ npm run dev:openclaw-source
 This checkout is local-only. It is ignored by git and is not required to run the
 plugin tests or publish the package.
 
+## Branches and releasing
+
+Everything reaches `main` through a GitHub PR; nothing is pushed to `main`
+directly.
+
+- Day-to-day, non-urgent changes are merged into the `pre-release` branch, not
+  `main`, also through a GitHub PR (`--base pre-release`) that is
+  squash-merged. `main` only moves when a release is cut, so it always equals
+  the newest published version.
+- An urgent fix (security, widespread connection failure) may target `main`
+  directly with a squash-merged PR that includes the version bump; afterwards
+  merge `main` back into `pre-release`.
+
+A release runs in this fixed order — never publish first and merge later, and
+never tag a commit that is not on `main`:
+
+1. **Bump the version on `pre-release`.** Set `package.json` `version` to the
+   new `YYYY.M.D-N` (no zero padding, e.g. `2026.10.7-1`; `-N` counts releases
+   on the same day) in a commit titled `chore(release): openclaw <old> -> <new>`,
+   and run `npm test -- --run` and `npm run typecheck`.
+2. **Merge `pre-release` into `main` through a PR, with a merge commit:**
+
+   ```bash
+   (
+   set -e
+   gh pr create --base main --head pre-release --title "release: <version>"
+   gh pr merge <n> --merge          # merge commit, not squash
+   test "$(gh pr view <n> --json state --jq .state)" = MERGED
+   git fetch origin
+   git push origin origin/main:pre-release   # fast-forward pre-release to main (not a force push)
+   )
+   ```
+
+3. **Tag the merge commit on `main` and push the tag.** The tag name equals
+   the `package.json` version, without a `v`; `<n>` is the release PR from
+   step 2, whose merge commit is tagged (not whatever `main` points to now):
+
+   Use the PR's merge commit because the floating `origin/main` may already
+   contain a later merge.
+
+   ```bash
+   (
+   set -e
+   git fetch origin --tags
+   release_commit=$(gh pr view <n> --json mergeCommit --jq .mergeCommit.oid)
+   git merge-base --is-ancestor "$release_commit" origin/main
+   git tag -a <version> "$release_commit" -m "<version>: <one-line summary>"
+   git push origin <version>
+   )
+   ```
+
+4. **Publish to npm from a clean checkout of the tag:**
+
+   ```bash
+   (
+   set -e
+   git worktree add --detach .worktrees/release-<version> <version>
+   cd .worktrees/release-<version>
+   test -z "$(git status --porcelain)"   # must be clean
+   npm install                        # no lockfile is committed (package-lock.json is gitignored)
+   npm test -- --run
+   npm run release                    # npm publish --tag latest; guard, typecheck, then prepack builds dist/
+   )
+   ```
+
+   The subshell stops at the first failing command, so a failed install or
+   test never reaches `npm run release`.
+
+   Every `npm publish` runs the release guard through `prepublishOnly`, before
+   typecheck and before `prepack` changes the manifest. The guard requires a
+   local annotated tag named exactly after `package.json`'s version, HEAD at
+   that tag's commit, and a clean working tree (including non-ignored untracked
+   files). It checks that `origin` has the same tag object, fetches `origin/main`,
+   and requires the tag commit to be an ancestor of that refreshed branch.
+   Any Git error blocks publishing; there is no npm dist-tag exemption.
+   Run `npm publish --dry-run` from the tag checkout to exercise the guard.
+   Never skip the guard; fix the checkout instead.
+
+5. **Record the release.** Use the commit SHA tagged in step 3 as `<sha>`:
+
+   ```bash
+   gh release create <version> --verify-tag --title <version> --notes "commit: <sha>
+   npm: @clawling/clawchat-plugin-openclaw@<version>"
+   ```
+
+   Add later results with `gh release edit <version> --notes "<updated notes>"`,
+   keeping the commit and npm version in the notes; never move the tag.
+
+Tag messages, PR titles, PR bodies and release notes are public like commit
+messages.
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/dist/index.js

@@ -1,6 +1,6 @@
 import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
 import { openclawClawlingPlugin } from "./src/channel.js";
-import { registerOpenclawClawlingCommands } from "./src/commands.js";
+import { registerInstallationCli, registerInstallationGatewayMethods, registerOpenclawClawlingCommands, } from "./src/commands.js";
 import { openclawClawlingConfigSchema } from "./src/config.js";
 import { registerHostToolsGuard } from "./src/host-tools-guard.js";
 import { registerClawChatPromptInjection, } from "./src/prompt-injection.js";
@@ -29,7 +29,7 @@ const channelEntry = defineChannelPluginEntry({
     },
 });
 /**
- * Chat slash commands (`/clawchat-activate`, `/clawchat-output`) are registered
+ * Chat slash commands and installation gateway methods are registered
  * in EVERY registration mode except `cli-metadata`, not inside `registerFull`.
  *
  * The host loads the plugin more than once per process — a `full` load and,
@@ -59,8 +59,11 @@ export default {
     ...channelEntry,
     register: (api) => {
         channelEntry.register(api);
+        // Every mode, including cli-metadata: CLI discovery loads that mode.
+        registerInstallationCli(api);
         if (api.registrationMode !== "cli-metadata") {
             registerOpenclawClawlingCommands(api);
+            registerInstallationGatewayMethods(api);
             if (!FULL_REGISTRATION_MODES.has(String(api.registrationMode)))
                 registerHostToolsGuard(api);
         }

package/dist/src/api-client.js

@@ -1,3 +1,5 @@
+import { orchestrationOriginHeaders } from "./orchestration.js";
+export { orchestrationOriginHeaders } from "./orchestration.js";
 import { ClawlingApiError, } from "./api-types.js";
 import { CHANNEL_ID } from "./config.js";
 const ORCH = "/v1/agents/me/orchestration";
@@ -80,7 +82,8 @@ export const REFRESH_REQUEST_TIMEOUT_MS = 20_000;
  * Unauthenticated: the refresh token in the body IS the credential, so we send
  * NO `Authorization` header. `X-Device-Id` MUST equal the connect-time device
  * id (the backend rejects on `sess.DeviceID != X-Device-Id`). The endpoint is
- * always HTTP 200 — branch on the envelope `code`, NOT on HTTP status. This is
+ * HTTP 200 by contract — branch on the envelope `code`; numeric `10003` also
+ * proves invalid refresh credentials on non-200 responses. This is
  * a standalone function (not a method on the token-bearing client) precisely
  * because no bearer token participates.
  *
@@ -137,8 +140,22 @@ async function authRefreshAttempt(baseUrl, fetchImpl, params, signal) {
         };
     }
     if (res.status !== 200) {
-        // Any non-200 (500/LB/transport) — TRANSIENT, regardless of body.
+        // Explicit invalid-refresh credentials are PERMANENT regardless of HTTP
+        // status, matching Hermes; retries must not hide the backend's rejection.
         const text = await res.text().catch(() => "");
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed) &&
+                typeof parsed.code === "number" && parsed.code === CODE_INVALID_REFRESH) {
+                const message = (typeof parsed.msg === "string" && parsed.msg) ||
+                    (typeof parsed.message === "string" && parsed.message) ||
+                    `refresh http ${res.status} code=10003`;
+                return { kind: "permanent", code: CODE_INVALID_REFRESH, message };
+            }
+        }
+        catch {
+            // Unparseable bodies do not prove invalid credentials; keep them transient.
+        }
         return {
             kind: "transient",
             status: res.status,
@@ -316,8 +333,9 @@ export function createOpenclawClawlingApiClient(opts) {
      * build a raw client the same way. Proactive rotation is still picked up here for
      * free, since the token is read fresh from the account at call time.
      */
-    async function orchCall(method, path, init) {
-        const res = await doFetch(method, path, init);
+    async function orchCall(method, path, origin, init) {
+        const headers = orchestrationOriginHeaders(origin);
+        const res = await doFetch(method, path, { ...init, headers: { ...init?.headers, ...headers } });
         if (res.status === 401 || res.status === 403) {
             throw new ClawlingApiError("auth", `unauthorized (status ${res.status})`, {
                 status: res.status,
@@ -453,34 +471,34 @@ export function createOpenclawClawlingApiClient(opts) {
             assertNonBlankId(friendUserId, "removeFriend: friendUserId");
             return await call("DELETE", `/v1/friendships/${encodeURIComponent(friendUserId)}`);
         },
-        async orchListAgents() {
-            return await orchCall("GET", `${ORCH}/agents`);
+        async orchListAgents(origin) {
+            return await orchCall("GET", `${ORCH}/agents`, origin);
         },
-        async orchGetAgent(agentId) {
-            return await orchCall("GET", `${ORCH}/agents/${encodeURIComponent(agentId)}`);
+        async orchGetAgent(agentId, origin) {
+            return await orchCall("GET", `${ORCH}/agents/${encodeURIComponent(agentId)}`, origin);
         },
-        async orchSetAgentBehavior(agentId, behavior) {
-            return await orchCall("PATCH", `${ORCH}/agents/${encodeURIComponent(agentId)}`, orchJson({ behavior }));
+        async orchSetAgentBehavior(agentId, behavior, origin) {
+            return await orchCall("PATCH", `${ORCH}/agents/${encodeURIComponent(agentId)}`, origin, orchJson({ behavior }));
         },
-        async orchListGroups() {
-            return await orchCall("GET", `${ORCH}/groups`);
+        async orchListGroups(origin) {
+            return await orchCall("GET", `${ORCH}/groups`, origin);
         },
-        async orchGetGroup(cid) {
-            return await orchCall("GET", `${ORCH}/groups/${encodeURIComponent(cid)}`);
+        async orchGetGroup(cid, origin) {
+            return await orchCall("GET", `${ORCH}/groups/${encodeURIComponent(cid)}`, origin);
         },
-        async orchSetGroupPrompt(cid, description) {
-            return await orchCall("PATCH", `${ORCH}/groups/${encodeURIComponent(cid)}`, orchJson({ description }));
+        async orchSetGroupPrompt(cid, description, origin) {
+            return await orchCall("PATCH", `${ORCH}/groups/${encodeURIComponent(cid)}`, origin, orchJson({ description }));
         },
-        async orchCreateGroup(title, agentIds) {
-            return await orchCall("POST", `${ORCH}/groups`, orchJson({ title, agent_ids: agentIds }));
+        async orchCreateGroup(title, agentIds, origin) {
+            return await orchCall("POST", `${ORCH}/groups`, origin, orchJson({ title, agent_ids: agentIds }));
         },
-        async orchAddGroupMember(cid, agentId) {
-            return await orchCall("POST", `${ORCH}/groups/${encodeURIComponent(cid)}/members`, orchJson({ agent_id: agentId }));
+        async orchAddGroupMember(cid, agentId, origin) {
+            return await orchCall("POST", `${ORCH}/groups/${encodeURIComponent(cid)}/members`, origin, orchJson({ agent_id: agentId }));
         },
-        async orchRemoveGroupMember(cid, agentId) {
-            return await orchCall("DELETE", `${ORCH}/groups/${encodeURIComponent(cid)}/members/${encodeURIComponent(agentId)}`);
+        async orchRemoveGroupMember(cid, agentId, origin) {
+            return await orchCall("DELETE", `${ORCH}/groups/${encodeURIComponent(cid)}/members/${encodeURIComponent(agentId)}`, origin);
         },
-        async orchSetGroupAgentSettings(cid, agentId, patch) {
+        async orchSetGroupAgentSettings(cid, agentId, patch, origin) {
             // `!== undefined` rather than truthiness: `muted: false` is a real value
             // the backend must see; an absent key means "leave unchanged".
             const body = {};
@@ -490,13 +508,13 @@ export function createOpenclawClawlingApiClient(opts) {
                 body.reply_mode = patch.replyMode;
             if (patch.batchDelaySeconds !== undefined)
                 body.batch_delay_seconds = patch.batchDelaySeconds;
-            return await orchCall("PATCH", `${ORCH}/groups/${encodeURIComponent(cid)}/agents/${encodeURIComponent(agentId)}`, orchJson(body));
+            return await orchCall("PATCH", `${ORCH}/groups/${encodeURIComponent(cid)}/agents/${encodeURIComponent(agentId)}`, origin, orchJson(body));
         },
-        async orchCreateConnectCode() {
-            return await orchCall("POST", `${ORCH}/connect-codes`);
+        async orchCreateConnectCode(origin) {
+            return await orchCall("POST", `${ORCH}/connect-codes`, origin);
         },
-        async orchGetConnectCode(code) {
-            return await orchCall("GET", `${ORCH}/connect-codes/${encodeURIComponent(code)}`);
+        async orchGetConnectCode(code, origin) {
+            return await orchCall("GET", `${ORCH}/connect-codes/${encodeURIComponent(code)}`, origin);
         },
         async registerApp(params) {
             assertNonBlankId(params.appId, "registerApp: appId");

package/dist/src/cli.js

@@ -0,0 +1,74 @@
+import * as gatewayRuntime from "openclaw/plugin-sdk/gateway-runtime";
+/** Older SDKs have no public URL redactor. In that case omit error text entirely. */
+function safeRpcError(error, opts) {
+    const name = error instanceof Error && /^(?:Error|[A-Za-z][A-Za-z0-9]*Error)$/u.test(error.name)
+        ? error.name : "Error";
+    const redact = "redactSensitiveUrlLikeString" in gatewayRuntime ? gatewayRuntime.redactSensitiveUrlLikeString : undefined;
+    if (typeof redact === "function" && error instanceof Error) {
+        try {
+            let message = error.message;
+            // Never echo explicitly supplied gateway credentials, even outside URLs.
+            for (const secret of [opts.token, opts.password]) {
+                if (secret)
+                    message = message.replaceAll(secret, "[redacted]");
+            }
+            return redact(message).replace(/[\r\n]+/gu, " ").slice(0, 240);
+        }
+        catch {
+            return name;
+        }
+    }
+    return name;
+}
+export function registerClawChatCli(program, api) {
+    const root = program.command("clawchat").description("ClawChat installation conflict tools");
+    for (const action of ["reclaim", "status"]) {
+        const sub = root.command(action)
+            .description(action === "reclaim" ? "Reclaim this ClawChat installation" : "Show ClawChat installation status")
+            .option("--account <id>", "ClawChat account id (default: default)")
+            .option("--offline", "Operate on local storage; use only while the gateway is stopped (cannot clear a running gateway's memory stop)")
+            .option("--json", "Print the result as JSON");
+        gatewayRuntime.addGatewayClientOptions(sub);
+        sub.action(async (opts) => {
+            await runCliAction(action, opts, api);
+        });
+    }
+}
+async function runCliAction(action, opts, api) {
+    // The registrar builds only Commander metadata; storage/runtime work starts
+    // after a leaf command is invoked, and only offline calls open local storage.
+    const { resolveInstallationAccountId, runInstallationCommand } = await import("./commands.js");
+    let accountId;
+    try {
+        accountId = resolveInstallationAccountId(opts.account);
+    }
+    catch {
+        console.error("--account requires a valid non-empty account id");
+        process.exitCode = 1;
+        return;
+    }
+    let result;
+    try {
+        if (opts.offline) {
+            result = await runInstallationCommand(action, accountId, { stateDir: api.runtime.state?.resolveStateDir?.() });
+        }
+        else {
+            const response = await gatewayRuntime.callGatewayFromCli(`clawchat.${action}`, opts, { accountId });
+            if (typeof response.ok !== "boolean" || typeof response.text !== "string") {
+                throw new Error("Invalid gateway response");
+            }
+            result = { ok: response.ok, text: response.text };
+        }
+    }
+    catch (error) {
+        console.error(`ClawChat ${action} failed: ${safeRpcError(error, opts)}`);
+        if (!opts.offline) {
+            console.error(`If the OpenClaw gateway is not running, use \`openclaw clawchat ${action} --offline\` to operate on local storage directly.`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    console.log(opts.json ? JSON.stringify(result) : result.text);
+    if (!result.ok)
+        process.exitCode = 1;
+}

package/dist/src/commands.js

@@ -73,6 +73,100 @@ function extractActivationIntent(value) {
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
+const INSTALLATION_COMMAND_FAILED = "ClawChat installation conflict storage unavailable; command failed.";
+/**
+ * Reject malformed explicit IDs rather than accidentally targeting default.
+ * Validity follows the host's account-id normalizer: an ID is accepted only if
+ * it is already canonical (up to case), so IDs the host would rewrite or map
+ * to `default` are rejected.
+ */
+export function resolveInstallationAccountId(value) {
+    if (value === undefined)
+        return normalizeOpenclawClawlingAccountId(undefined);
+    const trimmed = typeof value === "string" ? value.trim() : "";
+    const normalized = normalizeOpenclawClawlingAccountId(trimmed);
+    if (!trimmed || normalized !== trimmed.toLowerCase()) {
+        throw new Error("accountId must be a valid non-empty account id");
+    }
+    return normalized;
+}
+/** One implementation for slash commands, gateway RPC and offline CLI. */
+export async function runInstallationCommand(action, accountId, deps = {}) {
+    try {
+        const store = getClawChatStore(deps.stateDir ? { dbPath: clawChatDbPathForStateDir(deps.stateDir) } : {});
+        const lookup = store.lookupSuperseded(accountId);
+        if (lookup.status === "unavailable")
+            return { ok: false, text: "ClawChat installation conflict storage unavailable; try again after storage recovers (a gateway restart also drops a stop that could not be saved)." };
+        if (action === "reclaim") {
+            if (lookup.status === "absent" && !hasReclaimWaiter(accountId) && !recalledSuperseded(accountId))
+                return { ok: true, text: "This ClawChat installation is not superseded; nothing to reclaim." };
+            if (!store.clearSuperseded(accountId))
+                return { ok: false, text: "Unable to clear ClawChat installation conflict; reclaim failed." };
+            rememberSuperseded(accountId, null);
+            return { ok: true, text: signalReclaim(accountId)
+                    ? "ClawChat reclaim requested; reconnecting this installation."
+                    : "ClawChat conflict cleared; restart the OpenClaw gateway to reconnect this installation." };
+        }
+        const fields = installationStatus(lookup.status === "row" ? lookup.row : recalledSuperseded(accountId), resolveInstallId(store));
+        const connection = fields.superseded ? "superseded" : deps.connectionState
+            ? await deps.connectionState(accountId) ?? "disconnected"
+            : "unknown (gateway not reachable; offline snapshot)";
+        return { ok: true, text: [
+                `ClawChat account: ${accountId}`, `install_id: ${fields.installId ?? "unavailable"}`,
+                `connection: ${connection}`, `superseded: ${fields.superseded}`,
+                `superseded_at: ${fields.supersededAt ? new Date(fields.supersededAt).toISOString() : "-"}`,
+                `by_client_version: ${fields.byClientVersion ?? "unknown"}`,
+                `owner_notified: ${Boolean(fields.ownerNotifiedAt)}`,
+            ].join("\n") };
+    }
+    catch {
+        return { ok: false, text: INSTALLATION_COMMAND_FAILED };
+    }
+}
+async function runLiveInstallationCommand(api, action, accountId) {
+    try {
+        return await runInstallationCommand(action, accountId, {
+            stateDir: api.runtime.state?.resolveStateDir?.(),
+            connectionState: async (id) => {
+                const { getOpenclawClawlingClient } = await import("./runtime.js");
+                return getOpenclawClawlingClient(id)?.state;
+            },
+        });
+    }
+    catch {
+        return { ok: false, text: INSTALLATION_COMMAND_FAILED };
+    }
+}
+export function registerInstallationGatewayMethods(api) {
+    for (const action of ["reclaim", "status"]) {
+        api.registerGatewayMethod(`clawchat.${action}`, async ({ params, respond }) => {
+            let accountId;
+            try {
+                accountId = resolveInstallationAccountId(params.accountId);
+            }
+            catch {
+                respond(false, undefined, { code: "INVALID_REQUEST", message: "accountId must be a valid non-empty account id" });
+                return;
+            }
+            respond(true, await runLiveInstallationCommand(api, action, accountId));
+        }, { scope: action === "reclaim" ? "operator.admin" : "operator.read" });
+    }
+}
+/**
+ * Register the `openclaw clawchat reclaim|status` CLI root. The implementation
+ * is imported lazily inside the registrar so registration never opens storage
+ * or starts a client. Keep this dynamic import in src/: tsc leaves the `.ts`
+ * extension of a dynamic import in the root index.ts unrewritten in dist.
+ */
+export function registerInstallationCli(api) {
+    api.registerCli(async ({ program }) => {
+        const { registerClawChatCli } = await import("./cli.js");
+        registerClawChatCli(program, api);
+    }, {
+        commands: ["clawchat"],
+        descriptors: [{ name: "clawchat", description: "ClawChat installation conflict tools", hasSubcommands: true }],
+    });
+}
 function readRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -212,36 +306,8 @@ export function registerOpenclawClawlingCommands(api) {
                 if (flag.error)
                     return { text: `${flag.error}. Usage: /clawchat-${action} [--account <id>]` };
                 const accountId = flag.accountId ?? normalizeOpenclawClawlingAccountId(ctx.accountId);
-                try {
-                    const stateDir = api.runtime.state?.resolveStateDir?.();
-                    const store = getClawChatStore(stateDir ? { dbPath: clawChatDbPathForStateDir(stateDir) } : {});
-                    const lookup = store.lookupSuperseded(accountId);
-                    if (lookup.status === "unavailable")
-                        return { text: "ClawChat installation conflict storage unavailable; try again after storage recovers (a gateway restart also drops a stop that could not be saved)." };
-                    if (action === "reclaim") {
-                        if (lookup.status === "absent" && !hasReclaimWaiter(accountId) && !recalledSuperseded(accountId))
-                            return { text: "This ClawChat installation is not superseded; nothing to reclaim." };
-                        if (!store.clearSuperseded(accountId))
-                            return { text: "Unable to clear ClawChat installation conflict; reclaim failed." };
-                        rememberSuperseded(accountId, null);
-                        return { text: signalReclaim(accountId)
-                                ? "ClawChat reclaim requested; reconnecting this installation."
-                                : "ClawChat conflict cleared; restart the OpenClaw gateway to reconnect this installation." };
-                    }
-                    const fields = installationStatus(lookup.status === "row" ? lookup.row : recalledSuperseded(accountId), resolveInstallId(store));
-                    const { getOpenclawClawlingClient } = await import("./runtime.js");
-                    const connection = fields.superseded ? "superseded" : getOpenclawClawlingClient(accountId)?.state ?? "disconnected";
-                    return { text: [
-                            `ClawChat account: ${accountId}`, `install_id: ${fields.installId ?? "unavailable"}`,
-                            `connection: ${connection}`, `superseded: ${fields.superseded}`,
-                            `superseded_at: ${fields.supersededAt ? new Date(fields.supersededAt).toISOString() : "-"}`,
-                            `by_client_version: ${fields.byClientVersion ?? "unknown"}`,
-                            `owner_notified: ${Boolean(fields.ownerNotifiedAt)}`,
-                        ].join("\n") };
-                }
-                catch {
-                    return { text: "ClawChat installation conflict storage unavailable; command failed." };
-                }
+                const result = await runLiveInstallationCommand(api, action, accountId);
+                return { text: result.text };
             },
         });
     }

package/dist/src/config.js

@@ -35,10 +35,10 @@ export const DEFAULT_HEARTBEAT = {
     timeout: 10_000,
 };
 export const DEFAULT_ACK = {
-    // 15s tolerates a slow server + one retry without false timeouts.
+    // Allow a slow server 15s before each same-frame timeout retry.
     timeout: 15_000,
-    // Keep false: auto-resend on timeout risks duplicate messages; the
-    // reconnect path re-queues via `queueWhileReconnecting` instead.
+    timeoutRetries: 2,
+    // Core ws-client policy; aligned sends use timeoutRetries.
     autoResendOnTimeout: false,
 };
 export const openclawClawlingAccountConfigSchema = {
@@ -116,6 +116,7 @@ export const openclawClawlingAccountConfigSchema = {
             additionalProperties: false,
             properties: {
                 timeout: { type: "integer", minimum: 100 },
+                timeoutRetries: { type: "integer", minimum: 0, maximum: 5 },
                 autoResendOnTimeout: { type: "boolean" },
             },
         },
@@ -396,7 +397,7 @@ export function effectiveOutputVisibility(account, chatId, chatType) {
  * `SESSION_INT_KEYS`). An out-of-range value is clamped to the nearest bound,
  * a non-number falls back to the factory value. Every key here has a reader;
  * the shared keys this plugin has no use for are listed in
- * docs/clawchat-plugin-openclaw.md with the reason.
+ * docs/clawchat-plugin-openclaw.md#session-and-note-keys with the reason.
  *   key -> [factory, minimum, maximum]
  */
 export const SESSION_INT_KEYS = {
@@ -439,6 +440,9 @@ function readAck(raw) {
     const s = raw && typeof raw === "object" ? raw : {};
     return {
         timeout: typeof s.timeout === "number" ? s.timeout : DEFAULT_ACK.timeout,
+        timeoutRetries: typeof s.timeoutRetries === "number" && Number.isFinite(s.timeoutRetries)
+            ? Math.max(0, Math.min(5, Math.trunc(s.timeoutRetries)))
+            : DEFAULT_ACK.timeoutRetries,
         autoResendOnTimeout: typeof s.autoResendOnTimeout === "boolean"
             ? s.autoResendOnTimeout
             : DEFAULT_ACK.autoResendOnTimeout,

package/dist/src/framework-error-copy.js

@@ -4,7 +4,7 @@
  *
  * The host hands the channel its own English failure text (rate limit, expired
  * provider login, context overflow, billing, timeouts — see
- * `docs/clawchat-plugin-openclaw.md` "Framework error replies"). Posting that
+ * `docs/clawchat-plugin-openclaw.md#framework-error-replies`). Posting that
  * raw leaves a non-English owner with a message they cannot act on. Instead we
  * lead with one sentence in the owner's language saying what happened and what
  * to do, then keep the original text at the end so it can still be reported.

package/dist/src/gate-outcome.js

@@ -1,13 +1,8 @@
-/**
- * Maps backend owner-approval gate codes to structured tool outcomes.
- *
- * Backend gate codes (confirmed live contract):
- *   21001 — pending owner approval (payload: { request_id, operation, expires_at })
- *   21003 — policy forbidden       (payload: { operation })
- *
- * Returns null for any other code so callers can fall through to normal handling.
- */
+import { ownerOnlyMessage } from "./orchestration.js";
 export function mapGateOutcome(code, data) {
+    if (code === 21007)
+        return { status: "owner_turn_only",
+            operation: typeof data.operation === "string" ? data.operation : "", instruction: ownerOnlyMessage(false) };
     if (code === 21001) {
         return {
             status: "pending_owner_approval",