@clawling/clawchat-plugin-openclaw 2026.9.16-1 → 2026.9.17-1

package/dist/src/api-client.js

@@ -1,7 +1,7 @@
 import { ClawlingApiError, } from "./api-types.js";
 import { CHANNEL_ID } from "./config.js";
 export function buildPluginReportBody(input) {
-    return {
+    const body = {
         device_id: input.deviceId,
         platform: input.platform,
         plugin_version: input.pluginVersion,
@@ -9,6 +9,16 @@ export function buildPluginReportBody(input) {
         runtime_name: input.runtimeName,
         runtime_version: input.runtimeVersion,
     };
+    const ob = input.onboarding;
+    if (ob?.wiki_report_id !== undefined)
+        body.wiki_report_id = ob.wiki_report_id;
+    if (ob?.capability_tier !== undefined)
+        body.capability_tier = ob.capability_tier;
+    if (ob?.capability_ceiling !== undefined)
+        body.capability_ceiling = ob.capability_ceiling;
+    if (ob?.capabilities !== undefined)
+        body.capabilities = ob.capabilities;
+    return body;
 }
 /**
  * §A.0 — decode the access token's `exp` claim locally (base64url-decode the
@@ -472,7 +482,24 @@ export function createOpenclawClawlingApiClient(opts) {
                 headers: { "content-type": "application/json" },
             });
         },
-        async agentsConnect({ code: inviteCode, platform, type, user_id: userId }) {
+        async agentsConnectCheck({ code, platform, user_id: userId, context }) {
+            if (!code?.trim()) {
+                throw new ClawlingApiError("validation", "agentsConnectCheck: code is required");
+            }
+            const body = { code: code.trim(), platform: platform.trim() };
+            if (userId?.trim())
+                body.user_id = userId.trim();
+            if (opts.pluginVersion?.trim())
+                body.plugin_version = opts.pluginVersion.trim();
+            for (const [k, v] of Object.entries(context ?? {}))
+                if (v)
+                    body[k] = v;
+            return await call("POST", "/v1/agents/connect/check", {
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(body),
+            });
+        },
+        async agentsConnect({ code: inviteCode, platform, type, user_id: userId, context }) {
             if (!inviteCode?.trim()) {
                 throw new ClawlingApiError("validation", "agentsConnect: inviteCode is required");
             }
@@ -493,6 +520,9 @@ export function createOpenclawClawlingApiClient(opts) {
             if (opts.pluginVersion?.trim()) {
                 body.plugin_version = opts.pluginVersion.trim();
             }
+            for (const [k, v] of Object.entries(context ?? {}))
+                if (v)
+                    body[k] = v;
             return await call("POST", "/v1/agents/connect", {
                 // `X-Device-Id` is added globally via `authHeaders` on every request.
                 headers: { "content-type": "application/json" },

package/dist/src/connect-check.js

@@ -0,0 +1,74 @@
+import { ClawlingApiError } from "./api-types.js";
+import { AGENTS_CONNECT_PLATFORM, RECONNECT_GUIDE_URL } from "./onboarding-context.js";
+/**
+ * Non-consuming pre-check of a connect code. Records the "checked" funnel
+ * stage server-side and tells us whether the code is bound to an existing
+ * agent (the reconnect prompt). Any transport-level failure — older backend,
+ * rate limit, network — degrades to `null`: the pre-check is telemetry plus a
+ * courtesy, never a gate in front of `/connect`.
+ */
+export async function preCheckConnectCode(client, input, log) {
+    try {
+        const res = await client.agentsConnectCheck({
+            code: input.code,
+            platform: AGENTS_CONNECT_PLATFORM,
+            ...(input.userId ? { user_id: input.userId } : {}),
+            ...(input.context ? { context: input.context } : {}),
+        });
+        // A 200 with no data says nothing about the code: degrade exactly like an
+        // unreachable endpoint (Hermes' `evaluate_precheck({})` does the same).
+        if (!res || typeof res !== "object" || Object.keys(res).length === 0) {
+            log("Connect-code pre-check returned no data; continuing without it.");
+            return null;
+        }
+        return {
+            pairable: res.pairable === true,
+            status: typeof res.status === "string" ? res.status : "",
+            boundAgent: res.bound_agent === true,
+            userIdStatus: typeof res.user_id_status === "string" ? res.user_id_status : "",
+        };
+    }
+    catch (err) {
+        const kind = err instanceof ClawlingApiError ? err.kind : "error";
+        log(`Connect-code pre-check unavailable (${kind}); continuing without it.`);
+        return null;
+    }
+}
+/** Owner-facing explanation for `pairable: false`. No flags, no minutes, one URL. */
+export function unpairableMessage(pre) {
+    if (pre.userIdStatus === "owner_mismatch" && pre.boundAgent) {
+        // The server cannot tell us whether the bound agent shares this identity's
+        // owner, only that it is a different agent — so say exactly that.
+        return ("This connect code is the reconnect prompt for a different agent than the identity stored here. " +
+            "Ask your owner to send the reconnect prompt from THIS agent's chat in the ClawChat app.");
+    }
+    if (pre.userIdStatus === "invalid") {
+        return ("The identity stored here is not a valid ClawChat user id, so it cannot be restored. " +
+            "Activate as a brand-new agent with --new-account.");
+    }
+    if (pre.userIdStatus === "owner_mismatch") {
+        return ("This connect code belongs to a different ClawChat account than the identity stored here. " +
+            "Ask the owner of THIS agent for a code, or activate as a brand-new agent with --new-account.");
+    }
+    switch (pre.status) {
+        case "paired":
+            return ("This connect code was already redeemed. If this agent lost its connection, ask your owner " +
+                `to send you the reconnect prompt from the ClawChat app and follow ${RECONNECT_GUIDE_URL}; ` +
+                "otherwise ask for a fresh code.");
+        case "expired":
+        case "invalid":
+            return `This connect code is ${pre.status}. Ask your owner for a fresh code from the ClawChat app.`;
+        default:
+            return `This connect code is not pairable (status=${pre.status || "unknown"}). Ask your owner for a fresh code from the ClawChat app.`;
+    }
+}
+/**
+ * Refusal for a new-identity intent (`--new-account` or the interactive
+ * choice) on a bound code: without a user_id, `/connect` restores the bound
+ * agent instead of creating one. No flags, no minutes, no URL.
+ */
+export function boundCodeNewIdentityMessage() {
+    return ("This is a reconnect code bound to an existing agent, so it cannot create a new agent. " +
+        "Ask your owner for a normal connect code from the ClawChat app, or use this reconnect prompt " +
+        "on the agent it belongs to.");
+}

package/dist/src/login.runtime.js

@@ -6,23 +6,12 @@ import { openclawClawlingAccountSlotPath, patchOpenclawClawlingAccountSection }
 import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
 import { CHANNEL_ID, mergeOpenclawClawchatRuntimePluginActivation, mergeOpenclawClawchatToolAllow, normalizeOpenclawClawlingAccountId, readOpenclawClawlingAccountSection, resolveOpenclawClawlingAccount, } from "./config.js";
 import { getClawChatStore } from "./storage.js";
-/**
- * Platform tag sent to `/v1/agents/connect`. Identifies the host of this
- * agent runtime — openclaw's bundled clawchat channel.
- */
-export const AGENTS_CONNECT_PLATFORM = "openclaw";
-/**
- * Agent type tag sent to `/v1/agents/connect`. The clawchat channel is
- * always a bot; humans don't log in through this flow.
- */
-export const AGENTS_CONNECT_TYPE = "clawbot";
-/**
- * `/v1/agents/connect` envelope code for "the supplied user_id matches no
- * agent". Servers that predate the server-side stale-user_id fallback return
- * this instead of degrading to a fresh pairing, so the client sheds the id and
- * retries once.
- */
-export const AGENT_NOT_FOUND_CODE = 16001;
+import { buildOnboardingContext, RECONNECT_GUIDE_URL } from "./onboarding-context.js";
+import { boundCodeNewIdentityMessage, preCheckConnectCode, unpairableMessage } from "./connect-check.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 };
 /**
  * Thrown when redeeming an invite code would silently replace a live activation.
  *
@@ -43,9 +32,11 @@ export class ExistingActivationError extends Error {
             "spent. Re-run stating the intent:\n" +
             "  - Pair as a BRAND-NEW agent (this instance stops using the identity " +
             "above): /clawchat-activate <CODE> --new-account\n" +
-            "  - RESTORE the identity above (re-pairs that same agent; if it was " +
-            "deleted this brings it back with its history): " +
-            "/clawchat-activate <CODE> --repair\n" +
+            "  - RESTORE the identity above: do not spend a fresh code on it. Ask your " +
+            "owner to send you the reconnect prompt from the ClawChat app — its code is " +
+            "bound to this identity and usually restores it on its own; if activation " +
+            "still reports it as already paired, run it again with --repair " +
+            `(/clawchat-activate <CODE> --repair) — and follow ${RECONNECT_GUIDE_URL}\n` +
             "  - To run a SECOND agent alongside this one instead, activate it as a " +
             "named account: /clawchat-activate <CODE> --account <name>  (or: openclaw " +
             "channels add --channel clawchat-plugin-openclaw --account <name> --token <CODE>)");
@@ -197,7 +188,50 @@ export async function runOpenclawClawlingLogin(params) {
     // `DEFAULT_BASE_URL` / `DEFAULT_WEBSOCKET_URL` when the operator has not
     // overridden them, so login works without a prior `openclaw channels setup --channel clawchat-plugin-openclaw`.
     const account = resolveOpenclawClawlingAccount(cfg, accountId);
-    // Fork before the invite code is even read, so neither branch spends the code
+    const inviteCode = (await (params.readInviteCode ?? (() => promptInviteCodeFromStdin(runtime)))()).trim();
+    if (!inviteCode) {
+        throw new Error("Login aborted: invite code is required.");
+    }
+    const apiClient = (params.apiClientFactory ?? createOpenclawClawlingApiClient)({
+        baseUrl: account.baseUrl,
+        mediaBaseUrl: account.mediaBaseUrl,
+        // Pre-login we may not have a token yet. Send the current one (or empty)
+        // — the server should accept an unauthenticated invite-code exchange.
+        token: account.token || "",
+        pluginVersion: resolvePluginVersion(),
+    });
+    // Telemetry the backend joins with wiki field reports; ignored by older servers.
+    const onboarding = buildOnboardingContext();
+    // Non-consuming pre-check. `null` = endpoint unavailable, carry on. A bound
+    // code (the owner's reconnect prompt) is the owner's own proof of intent, so
+    // it settles the "new agent or restore?" question below without a flag.
+    //
+    // The pre-check only carries the `user_id` that `/connect` would replay. An
+    // explicit `newAccount` never replays it, so it must not be judged against
+    // it either: the server marks `pairable:false` for an `owner_mismatch` /
+    // `invalid` id, and that would block the very escape the refusal recommends.
+    const storedUserId = account.userId.trim();
+    const precheckUserId = params.newAccount ? "" : storedUserId;
+    runtime.log("Checking the invite code …");
+    let precheck = await preCheckConnectCode(apiClient, { code: inviteCode, userId: precheckUserId || undefined, context: onboarding }, runtime.log);
+    // Whether the operator will be asked "new agent or restore?" below. When
+    // they will, a refusal caused only by the stored identity (not by the code)
+    // is deferred: choosing a brand-new identity drops that id, so the verdict
+    // on it no longer applies.
+    const identityUnsettled = storedUserId !== "" && account.token.trim() !== "" && !params.newAccount && !params.repair;
+    const refusedForIdentity = precheck !== null &&
+        !precheck.pairable &&
+        precheckUserId !== "" &&
+        // Only a live code: a dead one (expired / paired / invalid) refuses on its
+        // own account whatever identity is chosen, so there is nothing to defer.
+        precheck.status === "pending" &&
+        (precheck.userIdStatus === "owner_mismatch" || precheck.userIdStatus === "invalid");
+    const deferredRefusal = identityUnsettled && refusedForIdentity ? precheck : null;
+    if (precheck && !precheck.pairable && !deferredRefusal) {
+        throw new Error(unpairableMessage(precheck));
+    }
+    const boundToIncumbent = precheck?.pairable === true && precheck.boundAgent === true && precheckUserId !== "";
+    // Fork before the invite code is spent, so neither branch spends the code
     // before the outcome is settled. "Live" is decided by whether a usable token
     // remains: auto-logout (§C) blanks the tokens but preserves the identity, so a
     // logged-out instance still re-pairs with no flag at all, which is the flow
@@ -207,46 +241,56 @@ export async function runOpenclawClawlingLogin(params) {
     // ambiguous, because redeeming a code here can either mint a new agent or
     // re-pair the incumbent one. Ask which, and only refuse when nobody answers.
     // An explicit `newAccount` / `repair` from the caller has already settled it,
-    // so no prompt.
+    // so no prompt. Nor is one needed when the pre-check proved the code is the
+    // owner's own reconnect prompt for this very agent (`boundToIncumbent`) — a
+    // bound code can only ever restore the incumbent identity.
     let newAccount = params.newAccount;
-    if (account.userId.trim() && account.token.trim() && !newAccount && !params.repair) {
+    if (identityUnsettled && !boundToIncumbent) {
         const identity = account.agentId.trim()
-            ? `agent ${account.agentId.trim()} (shadow user ${account.userId.trim()})`
-            : `agent ${account.userId.trim()}`;
+            ? `agent ${account.agentId.trim()} (shadow user ${storedUserId})`
+            : `agent ${storedUserId}`;
         const intent = await (params.readActivationIntent ??
             (() => promptActivationIntentFromStdin(runtime, identity)))();
         // Only "new-account" changes what gets sent. Restoring needs no flag:
         // replaying the stored `user_id` IS the re-pair, and that is already the
         // default below — so choosing it simply means "don't refuse".
-        if (intent === "new-account")
+        if (intent === "new-account") {
             newAccount = true;
+            if (deferredRefusal) {
+                // The first verdict judged the id we are now dropping; re-check the
+                // code on its own before spending it.
+                precheck = await preCheckConnectCode(apiClient, { code: inviteCode, context: onboarding }, runtime.log);
+                if (precheck && !precheck.pairable) {
+                    throw new Error(unpairableMessage(precheck));
+                }
+            }
+        }
+        else if (deferredRefusal) {
+            // Restoring (or nobody to ask) replays the id the server already refused.
+            throw new Error(unpairableMessage(deferredRefusal));
+        }
         else if (intent === null) {
-            throw new ExistingActivationError(account.userId.trim(), account.agentId.trim());
+            throw new ExistingActivationError(storedUserId, account.agentId.trim());
         }
     }
-    const inviteCode = (await (params.readInviteCode ?? (() => promptInviteCodeFromStdin(runtime)))()).trim();
-    if (!inviteCode) {
-        throw new Error("Login aborted: invite code is required.");
+    // A new identity (flag or interactive choice) sends no user_id, and /connect
+    // without one on a bound code silently RESTORES the bound agent and spends
+    // the code. A reconnect code can never mint an agent, so refuse first.
+    if (newAccount && precheck?.boundAgent === true) {
+        throw new Error(boundCodeNewIdentityMessage());
     }
-    const apiClient = (params.apiClientFactory ?? createOpenclawClawlingApiClient)({
-        baseUrl: account.baseUrl,
-        mediaBaseUrl: account.mediaBaseUrl,
-        // Pre-login we may not have a token yet. Send the current one (or empty)
-        // — the server should accept an unauthenticated invite-code exchange.
-        token: account.token || "",
-        pluginVersion: resolvePluginVersion(),
-    });
     runtime.log("Verifying invite code …");
     let result;
     // A brand-new identity is precisely "do not replay" — the replay is the only
     // thing that would bind this code to the incumbent agent.
-    const existingUserId = newAccount ? "" : account.userId.trim();
+    const existingUserId = newAccount ? "" : storedUserId;
     try {
         result = await apiClient.agentsConnect({
             code: inviteCode,
             platform: AGENTS_CONNECT_PLATFORM,
             type: AGENTS_CONNECT_TYPE,
             ...(existingUserId ? { user_id: existingUserId } : {}),
+            context: onboarding,
         });
     }
     catch (err) {
@@ -266,6 +310,7 @@ export async function runOpenclawClawlingLogin(params) {
                         code: inviteCode,
                         platform: AGENTS_CONNECT_PLATFORM,
                         type: AGENTS_CONNECT_TYPE,
+                        context: onboarding,
                     });
                 }
                 catch (retryErr) {

package/dist/src/onboarding-context.js

@@ -0,0 +1,70 @@
+/**
+ * Onboarding telemetry the plugin attaches to `/v1/agents/connect` and
+ * `/v1/agents/connect/check` (all optional, all ignored by older backends).
+ *
+ * Values mirror the connection wiki's manifest vocabulary so the backend can
+ * join plugin activations with wiki field reports without an alias table:
+ *   - `agent_kind` = the wiki `match.agent` name for this host
+ *   - `lane`       = "self": this plugin holds its own WebSocket + token
+ *   - `matched_install` = the wiki page slug that routes to this plugin
+ * Nothing here is a credential and nothing here gates activation.
+ */
+export const AGENT_KIND = "openclaw";
+export const LANE = "self";
+export const MATCHED_INSTALL = "install/official-openclaw";
+/** Public connection wiki. `/start.md` is the entry page; `/reconnect.md` the re-pair page. */
+export const START_GUIDE_URL = "https://agent-connection.clawling.com/start.md";
+export const RECONNECT_GUIDE_URL = "https://agent-connection.clawling.com/reconnect.md";
+const WIKI_VERSION_MAX = 40;
+/** Wiki `os` enum (windows | macos | linux); "" for anything else so callers omit it. */
+export function hostOs(plat = process.platform) {
+    switch (plat) {
+        case "win32":
+            return "windows";
+        case "darwin":
+            return "macos";
+        case "linux":
+            return "linux";
+        default:
+            return "";
+    }
+}
+/**
+ * The wiki build stamp the agent saw on the install page. The official install
+ * page tells the agent to export `CLAWCHAT_WIKI_VERSION` before activating; a
+ * hand-run `openclaw channels add` simply has none.
+ */
+export function wikiVersion(env = process.env) {
+    return (env.CLAWCHAT_WIKI_VERSION ?? "").trim().slice(0, WIKI_VERSION_MAX);
+}
+export function buildOnboardingContext(opts = {}) {
+    const out = {
+        agent_kind: AGENT_KIND,
+        lane: LANE,
+        matched_install: MATCHED_INSTALL,
+    };
+    const os = hostOs(opts.platform);
+    if (os)
+        out.os = os;
+    const wiki = wikiVersion(opts.env);
+    if (wiki)
+        out.wiki_version = wiki;
+    return out;
+}
+/**
+ * Platform tag sent to `/v1/agents/connect`. Identifies the host of this
+ * agent runtime — openclaw's bundled clawchat channel.
+ */
+export const AGENTS_CONNECT_PLATFORM = "openclaw";
+/**
+ * Agent type tag sent to `/v1/agents/connect`. The clawchat channel is
+ * always a bot; humans don't log in through this flow.
+ */
+export const AGENTS_CONNECT_TYPE = "clawbot";
+/**
+ * `/v1/agents/connect` envelope code for "the supplied user_id matches no
+ * agent". Servers that predate the server-side stale-user_id fallback return
+ * this instead of degrading to a fresh pairing, so the client sheds the id and
+ * retries once.
+ */
+export const AGENT_NOT_FOUND_CODE = 16001;

package/dist/src/onboarding-report.js

@@ -0,0 +1,50 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const REPORT_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const CAP_KEYS = ["headless", "mcp", "permission_hook", "session_line"];
+function tier(v) {
+    return Number.isInteger(v) && v >= 1 && v <= 4 ? v : undefined;
+}
+/**
+ * Read + validate `~/clawchat/onboarding.json`. Never throws: an unresolvable
+ * home directory, an absent/unreadable file, or malformed JSON all fall
+ * through to `null`, same as a file with no valid fields — this must be safe
+ * to call unconditionally from a best-effort report path.
+ */
+export function readOnboardingReport(homeDir) {
+    try {
+        const base = homeDir ?? os.homedir();
+        const file = path.join(base, "clawchat", "onboarding.json");
+        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            return null;
+        const o = raw;
+        const out = {};
+        if (typeof o.wiki_report_id === "string" && REPORT_ID_RE.test(o.wiki_report_id))
+            out.wiki_report_id = o.wiki_report_id;
+        const t = tier(o.capability_tier);
+        if (t !== undefined)
+            out.capability_tier = t;
+        const c = tier(o.capability_ceiling);
+        // The backend rejects the WHOLE report (22004) when ceiling < tier, which
+        // would silently stop the version row updating. Keep the tier, drop the
+        // inconsistent ceiling.
+        if (c !== undefined && (t === undefined || c >= t))
+            out.capability_ceiling = c;
+        if (o.capabilities && typeof o.capabilities === "object") {
+            const caps = {};
+            for (const k of CAP_KEYS) {
+                const v = o.capabilities[k];
+                if (typeof v === "boolean")
+                    caps[k] = v;
+            }
+            if (Object.keys(caps).length > 0)
+                out.capabilities = caps;
+        }
+        return Object.keys(out).length > 0 ? out : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/plugin-report.js

@@ -56,6 +56,7 @@ export async function reportPluginVersionSafe(p) {
             agentVersion: p.agentVersion,
             runtimeName: "node",
             runtimeVersion: process.version,
+            onboarding: p.onboarding ?? null,
         }, { authenticated: p.authenticated });
     }
     catch (err) {

package/dist/src/runtime.js

@@ -7,10 +7,12 @@ import { createOpenclawClawlingApiClient } from "./api-client.js";
 import { buildActivationBootstrapText } from "./activation-greeting.js";
 import { buildFriendGreetingEnvelope } from "./friend-greeting.js";
 import { reportPluginVersionSafe, resolvePluginVersion } from "./plugin-report.js";
+import { readOnboardingReport } from "./onboarding-report.js";
 import { ensureLivewareCli, livewareCliHomeDir, livewareSampleRootDir, resolveLivewarePath, } from "./liveware-cli.js";
 import { LivewareSampleSupervisor, } from "./liveware-sample.js";
 import { ClawlingApiError } from "./api-types.js";
 import { RefreshManager } from "./refresh-manager.js";
+import { RECONNECT_GUIDE_URL } from "./onboarding-context.js";
 import { runOpenclawClawlingLogin, } from "./login.runtime.js";
 import { CHANNEL_ID, effectiveOutputVisibility, effectiveGroupCommandMode, effectiveGroupMode, hasOpenclawClawlingConnectCredentials, normalizeOpenclawClawlingAccountId, readOpenclawClawlingAccountSection, resolveOpenclawClawlingAccount, CLAWCHAT_REFRESH_TOKEN_ENV, } from "./config.js";
 import { patchOpenclawClawlingAccountSection } from "./account-config-writes.js";
@@ -102,8 +104,12 @@ const OPENCLAW_CONFIRM_SLASH_COMMANDS = new Set([
 ]);
 const GROUP_OWNER_ATTENTION_TITLE = "requires owner attention";
 // §C.1 — user-visible message emitted on permanent token expiry. Kept
-// byte-identical to the Hermes plugin (parity spec §C.1.4).
-const CLAWCHAT_TOKEN_EXPIRED_MESSAGE = "ClawChat token expired and could not be refreshed. Re-pair with `/clawchat-activate <code>`.";
+// byte-identical to the Hermes plugin (parity spec §C.1.4). Points the owner
+// at the reconnect prompt (a code bound to this identity) rather than at a
+// slash command: a fresh create code spent here would mint a second agent.
+export const CLAWCHAT_TOKEN_EXPIRED_MESSAGE = "ClawChat token expired and could not be refreshed. Ask your owner to send you the reconnect prompt from the ClawChat app, then follow " +
+    RECONNECT_GUIDE_URL +
+    ".";
 const CLAWCHAT_TOKEN_EXPIRED_LAST_ERROR = "token expired — re-pair required";
 function isRecord(value) {
     return Boolean(value && typeof value === "object" && !Array.isArray(value));
@@ -724,6 +730,7 @@ export async function startOpenclawClawlingGateway(params) {
         pluginVersion,
         agentVersion,
         authenticated: false,
+        onboarding: readOnboardingReport(),
         log,
     });
     // Ensure the liveware CLI is installed (async, never blocks startup).
@@ -796,6 +803,7 @@ export async function startOpenclawClawlingGateway(params) {
         pluginVersion,
         agentVersion,
         authenticated: true,
+        onboarding: readOnboardingReport(),
         log,
     });
     // §A.0 — fallback expiry source. Prefer the SQLite `activated_at`; null for a

package/dist/src/skill-update.js

@@ -66,7 +66,7 @@ export const OFFICIAL_SKILLS_BASE = "https://raw.githubusercontent.com/clawling/
  * in the install-cli repo, bump this constant, ship it. `liveware-sample.ts`
  * imports the same ref, so the `livewares` tree at that tag is pinned too.
  */
-export const DEFAULT_SKILLS_REF = "skills-v1.9.0";
+export const DEFAULT_SKILLS_REF = "skills-v1.10.0";
 /** Refuse to treat an absurdly large response as a skill file (defence in depth). */
 export const MAX_SKILL_BYTES = 256 * 1024;
 /** This adapter's host target inside `skills/manifest.json`. */

package/package.json

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

package/skills/clawchat-core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clawchat-core
-version: 1.3.0
+version: 1.4.0
 description: Use when a request involves ClawChat profile, friends, user search, moments/dynamics, comments, reactions, avatar, media, memory, output visibility, read-only conversation lookup, sending an image, file, or voice/audio clip into a conversation, or plugin install/update/activation.
 ---
 
@@ -44,7 +44,14 @@ If `channels add` reports `Unknown channel: clawchat-plugin-openclaw`, use the r
 
 ### What a connect code is
 
-A connect code is issued by the owner inside the ClawChat app (注册 Agent → OpenClaw, or a service's 创建新身份 page). It is a short single-use string that expires on its own. Use it **exactly as provided** — do not lowercase, normalize, add prefixes, invent, reuse, or retry a code, and never assume a length or a digits-only shape: an older note here called it a six-digit "invite code"; that was the legacy pairing flow and no longer holds. If activation fails with a non-zero exit or API error, report the error verbatim and ask for a fresh code.
+A connect code is issued by the owner in the ClawChat app's add-agent card and
+usually reaches you inside the connection prompt the app produces, which points
+you at https://agent-connection.clawling.com/start.md. It is a short single-use
+string that expires on its own. Use it **exactly as provided** — do not lowercase,
+normalize, add prefixes, invent, reuse, or retry a code, and never assume a length
+or a digits-only shape: an older note here called it a six-digit "invite code";
+that was the legacy pairing flow and no longer holds. If activation fails with a
+non-zero exit or API error, report the error verbatim and ask for a fresh code.
 
 ### When this OpenClaw is already connected
 
@@ -57,6 +64,27 @@ A fresh connect code always means **one more identity**. If the owner hands you
 
 Never pick a flag by matching words in an error message, and never re-run activation with a flag you chose to get past one.
 
+### Lost the connection (token expired, auto-logout, or an "already paired" refusal)
+
+Do not spend a fresh create code on the identity you already hold — that mints a
+second agent. Ask your owner to send you the **reconnect prompt** from the ClawChat
+app (the agent's own page) and follow
+https://agent-connection.clawling.com/reconnect.md. The code in that prompt is
+bound to your identity: activation usually restores it on its own, and if it
+still reports the identity as already paired, run it again with `--repair`
+(`/clawchat-activate CODE --repair`).
+
+### After onboarding: the field report
+
+If your owner sent you here from the ClawChat app, file the structured field
+report described in https://agent-connection.clawling.com/start.md Appendix B once
+you have exchanged one real message with your owner in both directions. Keep the
+returned `id` and write it to `~/clawchat/onboarding.json` as
+`{"wiki_report_id": "<id>"}` (plain JSON, no other keys required); the plugin
+forwards it to ClawChat on its next connection so the owner's app can show that
+the report exists. Never put a ClawChat user, agent, or conversation id in the
+report itself.
+
 ## Output Visibility
 
 When the user asks to change ClawChat output verbosity, use the runtime slash command for the current conversation. Treat natural-language wording as aliases for the three supported modes:

package/skills/manifest.json

@@ -3,10 +3,10 @@
   "skills": {
     "openclaw": {
       "clawchat-core": {
-        "version": "1.3.0",
+        "version": "1.4.0",
         "path": "openclaw/clawchat-core/SKILL.md",
-        "sha256": "38468122ef085f652fbcffd6241803019e0242086d2a9c039152591c8d306976",
-        "bytes": 11650
+        "sha256": "c0cd2a83d6b48b6f4778a2127b5f4f7dd1ba33ea093972e714eee4bc0af6ed67",
+        "bytes": 12893
       },
       "clawchat-liveware": {
         "version": "1.2.2",
@@ -35,10 +35,10 @@
     },
     "hermes": {
       "clawchat-core": {
-        "version": "1.9.0",
+        "version": "1.10.0",
         "path": "hermes/clawchat-core/SKILL.md",
-        "sha256": "fd00ff36b58385c774a9268229136523a73a16c258d9af046aaa5bfa7d30a90f",
-        "bytes": 18632
+        "sha256": "6130e98e426f5d51392fd5bd7d75932d859b0531ea4216ef9a0a50526b99dfb6",
+        "bytes": 20124
       },
       "clawchat-liveware": {
         "version": "1.2.2",

package/src/api-client.ts

@@ -1,6 +1,8 @@
 import {
   ClawlingApiError,
   type AgentAppView,
+  type AgentConnectCheckInput,
+  type AgentConnectCheckResult,
   type AgentMetadataPatch,
   type AgentProfile,
   type AgentConnectResult,
@@ -17,9 +19,24 @@ import {
   type UserSearchHit,
 } from "./api-types.ts";
 import type { GroupSettings, GroupSettingsFetchResult } from "./group-settings.ts";
+import type { OnboardingReportFields } from "./onboarding-report.ts";
 import type { PermissionPolicy, PermState } from "./permissions.ts";
 import { CHANNEL_ID } from "./config.ts";
 
+/** Params for `agentsConnect` — exchange an invite code for an agent token. */
+export interface AgentsConnectInput {
+  /** The invite code entered by the operator. */
+  code: string;
+  /** Platform the agent is attaching from (e.g. "openclaw"). */
+  platform: string;
+  /** Agent type tag (e.g. "bot"). */
+  type: string;
+  /** Existing configured ClawChat user id, when re-activating an account. */
+  user_id?: string;
+  /** agent_kind / os / lane / wiki_version / matched_install — see onboarding-context.ts */
+  context?: Record<string, string>;
+}
+
 export interface PluginReportInput {
   deviceId: string;
   platform: string;
@@ -27,10 +44,12 @@ export interface PluginReportInput {
   agentVersion: string;
   runtimeName: string;
   runtimeVersion: string;
+  /** Agent-written onboarding facts (`~/clawchat/onboarding.json`); optional. */
+  onboarding?: OnboardingReportFields | null;
 }
 
-export function buildPluginReportBody(input: PluginReportInput): Record<string, string> {
-  return {
+export function buildPluginReportBody(input: PluginReportInput): Record<string, unknown> {
+  const body: Record<string, unknown> = {
     device_id: input.deviceId,
     platform: input.platform,
     plugin_version: input.pluginVersion,
@@ -38,6 +57,12 @@ export function buildPluginReportBody(input: PluginReportInput): Record<string,
     runtime_name: input.runtimeName,
     runtime_version: input.runtimeVersion,
   };
+  const ob = input.onboarding;
+  if (ob?.wiki_report_id !== undefined) body.wiki_report_id = ob.wiki_report_id;
+  if (ob?.capability_tier !== undefined) body.capability_tier = ob.capability_tier;
+  if (ob?.capability_ceiling !== undefined) body.capability_ceiling = ob.capability_ceiling;
+  if (ob?.capabilities !== undefined) body.capabilities = ob.capabilities;
+  return body;
 }
 
 export interface ApiClientOptions {
@@ -149,19 +174,16 @@ export interface OpenclawClawlingApiClient {
   uploadMedia(params: { buffer: Buffer; filename: string; mime?: string }): Promise<UploadResult>;
   /**
    * Exchange an invite code for an agent token.
-   * Request body shape: `{ code, platform, type, user_id?, plugin_version? }`.
-   * `plugin_version` is included when `ApiClientOptions.pluginVersion` is set.
+   * Request body shape: `{ code, platform, type, user_id?, plugin_version?, agent_kind?, os?, lane?, wiki_version?, matched_install? }`.
+   * `plugin_version` is included when `ApiClientOptions.pluginVersion` is set;
+   * `context` is flattened onto the top-level body (see `onboarding-context.ts`).
+   */
+  agentsConnect(params: AgentsConnectInput): Promise<AgentConnectResult>;
+  /**
+   * POST /v1/agents/connect/check — non-consuming pairability pre-check. Same
+   * `X-Device-Id` as `agentsConnect` so the funnel row is keyed identically.
    */
-  agentsConnect(params: {
-    /** The invite code entered by the operator. */
-    code: string;
-    /** Platform the agent is attaching from (e.g. "openclaw"). */
-    platform: string;
-    /** Agent type tag (e.g. "bot"). */
-    type: string;
-    /** Existing configured ClawChat user id, when re-activating an account. */
-    user_id?: string;
-  }): Promise<AgentConnectResult>;
+  agentsConnectCheck(input: AgentConnectCheckInput): Promise<AgentConnectCheckResult>;
   /**
    * Upload an avatar image via `POST /v1/files/upload-url`. The resulting
    * `url` is what you then pass to `updateMyProfile({ avatar_url: url })`.
@@ -755,7 +777,20 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
         },
       );
     },
-    async agentsConnect({ code: inviteCode, platform, type, user_id: userId }): Promise<AgentConnectResult> {
+    async agentsConnectCheck({ code, platform, user_id: userId, context }): Promise<AgentConnectCheckResult> {
+      if (!code?.trim()) {
+        throw new ClawlingApiError("validation", "agentsConnectCheck: code is required");
+      }
+      const body: Record<string, string> = { code: code.trim(), platform: platform.trim() };
+      if (userId?.trim()) body.user_id = userId.trim();
+      if (opts.pluginVersion?.trim()) body.plugin_version = opts.pluginVersion.trim();
+      for (const [k, v] of Object.entries(context ?? {})) if (v) body[k] = v;
+      return await call<AgentConnectCheckResult>("POST", "/v1/agents/connect/check", {
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+      });
+    },
+    async agentsConnect({ code: inviteCode, platform, type, user_id: userId, context }): Promise<AgentConnectResult> {
       if (!inviteCode?.trim()) {
         throw new ClawlingApiError("validation", "agentsConnect: inviteCode is required");
       }
@@ -776,6 +811,7 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
       if (opts.pluginVersion?.trim()) {
         body.plugin_version = opts.pluginVersion.trim();
       }
+      for (const [k, v] of Object.entries(context ?? {})) if (v) body[k] = v;
       return await call<AgentConnectResult>("POST", "/v1/agents/connect", {
         // `X-Device-Id` is added globally via `authHeaders` on every request.
         headers: { "content-type": "application/json" },

package/src/api-types.ts

@@ -146,6 +146,24 @@ export interface AgentConnectResult {
   conversation?: AgentConnectConversation;
 }
 
+/** Body of POST /v1/agents/connect/check. Same optional telemetry as /connect. */
+export interface AgentConnectCheckInput {
+  code: string;
+  platform: string;
+  user_id?: string;
+  /** agent_kind / os / lane / wiki_version / matched_install — see onboarding-context.ts */
+  context?: Record<string, string>;
+}
+
+/** data of POST /v1/agents/connect/check. Older backends omit `bound_agent`. */
+export interface AgentConnectCheckResult {
+  pairable: boolean;
+  status: string;
+  expires_at?: string;
+  user_id_status?: string;
+  bound_agent?: boolean;
+}
+
 export type AgentAppView = { id: string; app_id?: string; name: string; url: string };
 
 export type ClawlingApiErrorKind =

package/src/connect-check.ts

@@ -0,0 +1,98 @@
+import { ClawlingApiError } from "./api-types.ts";
+import type { OpenclawClawlingApiClient } from "./api-client.ts";
+import { AGENTS_CONNECT_PLATFORM, RECONNECT_GUIDE_URL } from "./onboarding-context.ts";
+
+export interface ConnectPreCheck {
+  pairable: boolean;
+  status: string;
+  boundAgent: boolean;
+  userIdStatus: string;
+}
+
+/**
+ * Non-consuming pre-check of a connect code. Records the "checked" funnel
+ * stage server-side and tells us whether the code is bound to an existing
+ * agent (the reconnect prompt). Any transport-level failure — older backend,
+ * rate limit, network — degrades to `null`: the pre-check is telemetry plus a
+ * courtesy, never a gate in front of `/connect`.
+ */
+export async function preCheckConnectCode(
+  client: Pick<OpenclawClawlingApiClient, "agentsConnectCheck">,
+  input: { code: string; userId?: string; context?: Record<string, string> },
+  log: (message: string) => void,
+): Promise<ConnectPreCheck | null> {
+  try {
+    const res = await client.agentsConnectCheck({
+      code: input.code,
+      platform: AGENTS_CONNECT_PLATFORM,
+      ...(input.userId ? { user_id: input.userId } : {}),
+      ...(input.context ? { context: input.context } : {}),
+    });
+    // A 200 with no data says nothing about the code: degrade exactly like an
+    // unreachable endpoint (Hermes' `evaluate_precheck({})` does the same).
+    if (!res || typeof res !== "object" || Object.keys(res).length === 0) {
+      log("Connect-code pre-check returned no data; continuing without it.");
+      return null;
+    }
+    return {
+      pairable: res.pairable === true,
+      status: typeof res.status === "string" ? res.status : "",
+      boundAgent: res.bound_agent === true,
+      userIdStatus: typeof res.user_id_status === "string" ? res.user_id_status : "",
+    };
+  } catch (err) {
+    const kind = err instanceof ClawlingApiError ? err.kind : "error";
+    log(`Connect-code pre-check unavailable (${kind}); continuing without it.`);
+    return null;
+  }
+}
+
+/** Owner-facing explanation for `pairable: false`. No flags, no minutes, one URL. */
+export function unpairableMessage(pre: ConnectPreCheck): string {
+  if (pre.userIdStatus === "owner_mismatch" && pre.boundAgent) {
+    // The server cannot tell us whether the bound agent shares this identity's
+    // owner, only that it is a different agent — so say exactly that.
+    return (
+      "This connect code is the reconnect prompt for a different agent than the identity stored here. " +
+      "Ask your owner to send the reconnect prompt from THIS agent's chat in the ClawChat app."
+    );
+  }
+  if (pre.userIdStatus === "invalid") {
+    return (
+      "The identity stored here is not a valid ClawChat user id, so it cannot be restored. " +
+      "Activate as a brand-new agent with --new-account."
+    );
+  }
+  if (pre.userIdStatus === "owner_mismatch") {
+    return (
+      "This connect code belongs to a different ClawChat account than the identity stored here. " +
+      "Ask the owner of THIS agent for a code, or activate as a brand-new agent with --new-account."
+    );
+  }
+  switch (pre.status) {
+    case "paired":
+      return (
+        "This connect code was already redeemed. If this agent lost its connection, ask your owner " +
+        `to send you the reconnect prompt from the ClawChat app and follow ${RECONNECT_GUIDE_URL}; ` +
+        "otherwise ask for a fresh code."
+      );
+    case "expired":
+    case "invalid":
+      return `This connect code is ${pre.status}. Ask your owner for a fresh code from the ClawChat app.`;
+    default:
+      return `This connect code is not pairable (status=${pre.status || "unknown"}). Ask your owner for a fresh code from the ClawChat app.`;
+  }
+}
+
+/**
+ * Refusal for a new-identity intent (`--new-account` or the interactive
+ * choice) on a bound code: without a user_id, `/connect` restores the bound
+ * agent instead of creating one. No flags, no minutes, no URL.
+ */
+export function boundCodeNewIdentityMessage(): string {
+  return (
+    "This is a reconnect code bound to an existing agent, so it cannot create a new agent. " +
+    "Ask your owner for a normal connect code from the ClawChat app, or use this reconnect prompt " +
+    "on the agent it belongs to."
+  );
+}

package/src/login.runtime.ts

@@ -14,24 +14,16 @@ import {
   resolveOpenclawClawlingAccount,
 } from "./config.ts";
 import { getClawChatStore, type ClawChatStore } from "./storage.ts";
-
-/**
- * Platform tag sent to `/v1/agents/connect`. Identifies the host of this
- * agent runtime — openclaw's bundled clawchat channel.
- */
-export const AGENTS_CONNECT_PLATFORM = "openclaw" as const;
-/**
- * Agent type tag sent to `/v1/agents/connect`. The clawchat channel is
- * always a bot; humans don't log in through this flow.
- */
-export const AGENTS_CONNECT_TYPE = "clawbot" as const;
-/**
- * `/v1/agents/connect` envelope code for "the supplied user_id matches no
- * agent". Servers that predate the server-side stale-user_id fallback return
- * this instead of degrading to a fresh pairing, so the client sheds the id and
- * retries once.
- */
-export const AGENT_NOT_FOUND_CODE = 16001 as const;
+import { buildOnboardingContext, RECONNECT_GUIDE_URL } from "./onboarding-context.ts";
+import { boundCodeNewIdentityMessage, preCheckConnectCode, unpairableMessage } from "./connect-check.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 {
+  AGENTS_CONNECT_PLATFORM,
+  AGENTS_CONNECT_TYPE,
+  AGENT_NOT_FOUND_CODE,
+} from "./onboarding-context.ts";
+export { AGENTS_CONNECT_PLATFORM, AGENTS_CONNECT_TYPE, AGENT_NOT_FOUND_CODE };
 
 export type OpenclawClawchatMutateConfigFile = <T = void>(params: {
   afterWrite: { mode: "auto" } | { mode: "none" | "restart"; reason: string };
@@ -103,9 +95,11 @@ export class ExistingActivationError extends Error {
         "spent. Re-run stating the intent:\n" +
         "  - Pair as a BRAND-NEW agent (this instance stops using the identity " +
         "above): /clawchat-activate <CODE> --new-account\n" +
-        "  - RESTORE the identity above (re-pairs that same agent; if it was " +
-        "deleted this brings it back with its history): " +
-        "/clawchat-activate <CODE> --repair\n" +
+        "  - RESTORE the identity above: do not spend a fresh code on it. Ask your " +
+        "owner to send you the reconnect prompt from the ClawChat app — its code is " +
+        "bound to this identity and usually restores it on its own; if activation " +
+        "still reports it as already paired, run it again with --repair " +
+        `(/clawchat-activate <CODE> --repair) — and follow ${RECONNECT_GUIDE_URL}\n` +
         "  - To run a SECOND agent alongside this one instead, activate it as a " +
         "named account: /clawchat-activate <CODE> --account <name>  (or: openclaw " +
         "channels add --channel clawchat-plugin-openclaw --account <name> --token <CODE>)",
@@ -289,7 +283,63 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
   // overridden them, so login works without a prior `openclaw channels setup --channel clawchat-plugin-openclaw`.
   const account = resolveOpenclawClawlingAccount(cfg, accountId);
 
-  // Fork before the invite code is even read, so neither branch spends the code
+  const inviteCode = (
+    await (params.readInviteCode ?? (() => promptInviteCodeFromStdin(runtime)))()
+  ).trim();
+  if (!inviteCode) {
+    throw new Error("Login aborted: invite code is required.");
+  }
+
+  const apiClient = (params.apiClientFactory ?? createOpenclawClawlingApiClient)({
+    baseUrl: account.baseUrl,
+    mediaBaseUrl: account.mediaBaseUrl,
+    // Pre-login we may not have a token yet. Send the current one (or empty)
+    // — the server should accept an unauthenticated invite-code exchange.
+    token: account.token || "",
+    pluginVersion: resolvePluginVersion(),
+  });
+
+  // Telemetry the backend joins with wiki field reports; ignored by older servers.
+  const onboarding = buildOnboardingContext();
+
+  // Non-consuming pre-check. `null` = endpoint unavailable, carry on. A bound
+  // code (the owner's reconnect prompt) is the owner's own proof of intent, so
+  // it settles the "new agent or restore?" question below without a flag.
+  //
+  // The pre-check only carries the `user_id` that `/connect` would replay. An
+  // explicit `newAccount` never replays it, so it must not be judged against
+  // it either: the server marks `pairable:false` for an `owner_mismatch` /
+  // `invalid` id, and that would block the very escape the refusal recommends.
+  const storedUserId = account.userId.trim();
+  const precheckUserId = params.newAccount ? "" : storedUserId;
+  runtime.log("Checking the invite code …");
+  let precheck = await preCheckConnectCode(
+    apiClient,
+    { code: inviteCode, userId: precheckUserId || undefined, context: onboarding },
+    runtime.log,
+  );
+  // Whether the operator will be asked "new agent or restore?" below. When
+  // they will, a refusal caused only by the stored identity (not by the code)
+  // is deferred: choosing a brand-new identity drops that id, so the verdict
+  // on it no longer applies.
+  const identityUnsettled =
+    storedUserId !== "" && account.token.trim() !== "" && !params.newAccount && !params.repair;
+  const refusedForIdentity =
+    precheck !== null &&
+    !precheck.pairable &&
+    precheckUserId !== "" &&
+    // Only a live code: a dead one (expired / paired / invalid) refuses on its
+    // own account whatever identity is chosen, so there is nothing to defer.
+    precheck.status === "pending" &&
+    (precheck.userIdStatus === "owner_mismatch" || precheck.userIdStatus === "invalid");
+  const deferredRefusal = identityUnsettled && refusedForIdentity ? precheck : null;
+  if (precheck && !precheck.pairable && !deferredRefusal) {
+    throw new Error(unpairableMessage(precheck));
+  }
+  const boundToIncumbent =
+    precheck?.pairable === true && precheck.boundAgent === true && precheckUserId !== "";
+
+  // Fork before the invite code is spent, so neither branch spends the code
   // before the outcome is settled. "Live" is decided by whether a usable token
   // remains: auto-logout (§C) blanks the tokens but preserves the identity, so a
   // logged-out instance still re-pairs with no flag at all, which is the flow
@@ -299,50 +349,60 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
   // ambiguous, because redeeming a code here can either mint a new agent or
   // re-pair the incumbent one. Ask which, and only refuse when nobody answers.
   // An explicit `newAccount` / `repair` from the caller has already settled it,
-  // so no prompt.
+  // so no prompt. Nor is one needed when the pre-check proved the code is the
+  // owner's own reconnect prompt for this very agent (`boundToIncumbent`) — a
+  // bound code can only ever restore the incumbent identity.
   let newAccount = params.newAccount;
-  if (account.userId.trim() && account.token.trim() && !newAccount && !params.repair) {
+  if (identityUnsettled && !boundToIncumbent) {
     const identity = account.agentId.trim()
-      ? `agent ${account.agentId.trim()} (shadow user ${account.userId.trim()})`
-      : `agent ${account.userId.trim()}`;
+      ? `agent ${account.agentId.trim()} (shadow user ${storedUserId})`
+      : `agent ${storedUserId}`;
     const intent = await (params.readActivationIntent ??
       (() => promptActivationIntentFromStdin(runtime, identity)))();
     // Only "new-account" changes what gets sent. Restoring needs no flag:
     // replaying the stored `user_id` IS the re-pair, and that is already the
     // default below — so choosing it simply means "don't refuse".
-    if (intent === "new-account") newAccount = true;
-    else if (intent === null) {
-      throw new ExistingActivationError(account.userId.trim(), account.agentId.trim());
+    if (intent === "new-account") {
+      newAccount = true;
+      if (deferredRefusal) {
+        // The first verdict judged the id we are now dropping; re-check the
+        // code on its own before spending it.
+        precheck = await preCheckConnectCode(
+          apiClient,
+          { code: inviteCode, context: onboarding },
+          runtime.log,
+        );
+        if (precheck && !precheck.pairable) {
+          throw new Error(unpairableMessage(precheck));
+        }
+      }
+    } else if (deferredRefusal) {
+      // Restoring (or nobody to ask) replays the id the server already refused.
+      throw new Error(unpairableMessage(deferredRefusal));
+    } else if (intent === null) {
+      throw new ExistingActivationError(storedUserId, account.agentId.trim());
     }
   }
 
-  const inviteCode = (
-    await (params.readInviteCode ?? (() => promptInviteCodeFromStdin(runtime)))()
-  ).trim();
-  if (!inviteCode) {
-    throw new Error("Login aborted: invite code is required.");
+  // A new identity (flag or interactive choice) sends no user_id, and /connect
+  // without one on a bound code silently RESTORES the bound agent and spends
+  // the code. A reconnect code can never mint an agent, so refuse first.
+  if (newAccount && precheck?.boundAgent === true) {
+    throw new Error(boundCodeNewIdentityMessage());
   }
 
-  const apiClient = (params.apiClientFactory ?? createOpenclawClawlingApiClient)({
-    baseUrl: account.baseUrl,
-    mediaBaseUrl: account.mediaBaseUrl,
-    // Pre-login we may not have a token yet. Send the current one (or empty)
-    // — the server should accept an unauthenticated invite-code exchange.
-    token: account.token || "",
-    pluginVersion: resolvePluginVersion(),
-  });
-
   runtime.log("Verifying invite code …");
   let result;
   // A brand-new identity is precisely "do not replay" — the replay is the only
   // thing that would bind this code to the incumbent agent.
-  const existingUserId = newAccount ? "" : account.userId.trim();
+  const existingUserId = newAccount ? "" : storedUserId;
   try {
     result = await apiClient.agentsConnect({
       code: inviteCode,
       platform: AGENTS_CONNECT_PLATFORM,
       type: AGENTS_CONNECT_TYPE,
       ...(existingUserId ? { user_id: existingUserId } : {}),
+      context: onboarding,
     });
   } catch (err) {
     if (err instanceof ClawlingApiError) {
@@ -363,6 +423,7 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
             code: inviteCode,
             platform: AGENTS_CONNECT_PLATFORM,
             type: AGENTS_CONNECT_TYPE,
+            context: onboarding,
           });
         } catch (retryErr) {
           if (retryErr instanceof ClawlingApiError) {

package/src/onboarding-context.ts

@@ -0,0 +1,77 @@
+/**
+ * Onboarding telemetry the plugin attaches to `/v1/agents/connect` and
+ * `/v1/agents/connect/check` (all optional, all ignored by older backends).
+ *
+ * Values mirror the connection wiki's manifest vocabulary so the backend can
+ * join plugin activations with wiki field reports without an alias table:
+ *   - `agent_kind` = the wiki `match.agent` name for this host
+ *   - `lane`       = "self": this plugin holds its own WebSocket + token
+ *   - `matched_install` = the wiki page slug that routes to this plugin
+ * Nothing here is a credential and nothing here gates activation.
+ */
+
+export const AGENT_KIND = "openclaw" as const;
+export const LANE = "self" as const;
+export const MATCHED_INSTALL = "install/official-openclaw" as const;
+
+/** Public connection wiki. `/start.md` is the entry page; `/reconnect.md` the re-pair page. */
+export const START_GUIDE_URL = "https://agent-connection.clawling.com/start.md" as const;
+export const RECONNECT_GUIDE_URL = "https://agent-connection.clawling.com/reconnect.md" as const;
+
+const WIKI_VERSION_MAX = 40;
+
+/** Wiki `os` enum (windows | macos | linux); "" for anything else so callers omit it. */
+export function hostOs(plat: string = process.platform): "windows" | "macos" | "linux" | "" {
+  switch (plat) {
+    case "win32":
+      return "windows";
+    case "darwin":
+      return "macos";
+    case "linux":
+      return "linux";
+    default:
+      return "";
+  }
+}
+
+/**
+ * The wiki build stamp the agent saw on the install page. The official install
+ * page tells the agent to export `CLAWCHAT_WIKI_VERSION` before activating; a
+ * hand-run `openclaw channels add` simply has none.
+ */
+export function wikiVersion(env: NodeJS.ProcessEnv = process.env): string {
+  return (env.CLAWCHAT_WIKI_VERSION ?? "").trim().slice(0, WIKI_VERSION_MAX);
+}
+
+export function buildOnboardingContext(
+  opts: { platform?: string; env?: NodeJS.ProcessEnv } = {},
+): Record<string, string> {
+  const out: Record<string, string> = {
+    agent_kind: AGENT_KIND,
+    lane: LANE,
+    matched_install: MATCHED_INSTALL,
+  };
+  const os = hostOs(opts.platform);
+  if (os) out.os = os;
+  const wiki = wikiVersion(opts.env);
+  if (wiki) out.wiki_version = wiki;
+  return out;
+}
+
+/**
+ * Platform tag sent to `/v1/agents/connect`. Identifies the host of this
+ * agent runtime — openclaw's bundled clawchat channel.
+ */
+export const AGENTS_CONNECT_PLATFORM = "openclaw" as const;
+/**
+ * Agent type tag sent to `/v1/agents/connect`. The clawchat channel is
+ * always a bot; humans don't log in through this flow.
+ */
+export const AGENTS_CONNECT_TYPE = "clawbot" as const;
+/**
+ * `/v1/agents/connect` envelope code for "the supplied user_id matches no
+ * agent". Servers that predate the server-side stale-user_id fallback return
+ * this instead of degrading to a fresh pairing, so the client sheds the id and
+ * retries once.
+ */
+export const AGENT_NOT_FOUND_CODE = 16001 as const;

package/src/onboarding-report.ts

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * Optional onboarding facts the AGENT writes after following the connection
+ * wiki: the id of the field report it filed there, and its self-assessed
+ * capability tier. The plugin only relays them on the plugin-report call; it
+ * never files a wiki report itself. Same directory as the greeting override
+ * (`~/clawchat/`), so the agent already knows the place.
+ */
+export interface OnboardingReportFields {
+  wiki_report_id?: string;
+  capability_tier?: number;
+  capability_ceiling?: number;
+  capabilities?: { headless?: boolean; mcp?: boolean; permission_hook?: boolean; session_line?: boolean };
+}
+
+const REPORT_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const CAP_KEYS = ["headless", "mcp", "permission_hook", "session_line"] as const;
+
+function tier(v: unknown): number | undefined {
+  return Number.isInteger(v) && (v as number) >= 1 && (v as number) <= 4 ? (v as number) : undefined;
+}
+
+/**
+ * Read + validate `~/clawchat/onboarding.json`. Never throws: an unresolvable
+ * home directory, an absent/unreadable file, or malformed JSON all fall
+ * through to `null`, same as a file with no valid fields — this must be safe
+ * to call unconditionally from a best-effort report path.
+ */
+export function readOnboardingReport(homeDir?: string): OnboardingReportFields | null {
+  try {
+    const base = homeDir ?? os.homedir();
+    const file = path.join(base, "clawchat", "onboarding.json");
+    const raw: unknown = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+    const o = raw as Record<string, unknown>;
+    const out: OnboardingReportFields = {};
+    if (typeof o.wiki_report_id === "string" && REPORT_ID_RE.test(o.wiki_report_id)) out.wiki_report_id = o.wiki_report_id;
+    const t = tier(o.capability_tier);
+    if (t !== undefined) out.capability_tier = t;
+    const c = tier(o.capability_ceiling);
+    // The backend rejects the WHOLE report (22004) when ceiling < tier, which
+    // would silently stop the version row updating. Keep the tier, drop the
+    // inconsistent ceiling.
+    if (c !== undefined && (t === undefined || c >= t)) out.capability_ceiling = c;
+    if (o.capabilities && typeof o.capabilities === "object") {
+      const caps: NonNullable<OnboardingReportFields["capabilities"]> = {};
+      for (const k of CAP_KEYS) {
+        const v = (o.capabilities as Record<string, unknown>)[k];
+        if (typeof v === "boolean") caps[k] = v;
+      }
+      if (Object.keys(caps).length > 0) out.capabilities = caps;
+    }
+    return Object.keys(out).length > 0 ? out : null;
+  } catch {
+    return null;
+  }
+}

package/src/plugin-report.ts

@@ -2,6 +2,7 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createOpenclawClawlingApiClient } from "./api-client.ts";
+import type { OnboardingReportFields } from "./onboarding-report.ts";
 
 const PACKAGE_NAME = "@clawling/clawchat-plugin-openclaw";
 
@@ -48,6 +49,8 @@ export interface ReportParams {
   pluginVersion: string;
   agentVersion: string;
   authenticated: boolean;
+  /** Agent-written onboarding facts (`~/clawchat/onboarding.json`); optional. */
+  onboarding?: OnboardingReportFields | null;
   log?: { debug?: (msg: string) => void };
 }
 
@@ -70,6 +73,7 @@ export async function reportPluginVersionSafe(p: ReportParams): Promise<void> {
         agentVersion: p.agentVersion,
         runtimeName: "node",
         runtimeVersion: process.version,
+        onboarding: p.onboarding ?? null,
       },
       { authenticated: p.authenticated },
     );

package/src/runtime.ts

@@ -19,6 +19,7 @@ import { createOpenclawClawlingApiClient } from "./api-client.ts";
 import { buildActivationBootstrapText } from "./activation-greeting.ts";
 import { buildFriendGreetingEnvelope } from "./friend-greeting.ts";
 import { reportPluginVersionSafe, resolvePluginVersion } from "./plugin-report.ts";
+import { readOnboardingReport } from "./onboarding-report.ts";
 import path from "node:path";
 import {
   ensureLivewareCli,
@@ -33,6 +34,7 @@ import {
 } from "./liveware-sample.ts";
 import { ClawlingApiError } from "./api-types.ts";
 import { RefreshManager } from "./refresh-manager.ts";
+import { RECONNECT_GUIDE_URL } from "./onboarding-context.ts";
 import {
   runOpenclawClawlingLogin,
   type LoginParams,
@@ -210,9 +212,13 @@ const OPENCLAW_CONFIRM_SLASH_COMMANDS = new Set([
 ]);
 const GROUP_OWNER_ATTENTION_TITLE = "requires owner attention";
 // §C.1 — user-visible message emitted on permanent token expiry. Kept
-// byte-identical to the Hermes plugin (parity spec §C.1.4).
-const CLAWCHAT_TOKEN_EXPIRED_MESSAGE =
-  "ClawChat token expired and could not be refreshed. Re-pair with `/clawchat-activate <code>`.";
+// byte-identical to the Hermes plugin (parity spec §C.1.4). Points the owner
+// at the reconnect prompt (a code bound to this identity) rather than at a
+// slash command: a fresh create code spent here would mint a second agent.
+export const CLAWCHAT_TOKEN_EXPIRED_MESSAGE =
+  "ClawChat token expired and could not be refreshed. Ask your owner to send you the reconnect prompt from the ClawChat app, then follow " +
+  RECONNECT_GUIDE_URL +
+  ".";
 const CLAWCHAT_TOKEN_EXPIRED_LAST_ERROR = "token expired — re-pair required";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -1067,6 +1073,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     pluginVersion,
     agentVersion,
     authenticated: false,
+    onboarding: readOnboardingReport(),
     log,
   });
   // Ensure the liveware CLI is installed (async, never blocks startup).
@@ -1139,6 +1146,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     pluginVersion,
     agentVersion,
     authenticated: true,
+    onboarding: readOnboardingReport(),
     log,
   });
   // §A.0 — fallback expiry source. Prefer the SQLite `activated_at`; null for a

package/src/skill-update.ts

@@ -71,7 +71,7 @@ export const OFFICIAL_SKILLS_BASE =
  * in the install-cli repo, bump this constant, ship it. `liveware-sample.ts`
  * imports the same ref, so the `livewares` tree at that tag is pinned too.
  */
-export const DEFAULT_SKILLS_REF = "skills-v1.9.0";
+export const DEFAULT_SKILLS_REF = "skills-v1.10.0";
 
 /** Refuse to treat an absurdly large response as a skill file (defence in depth). */
 export const MAX_SKILL_BYTES = 256 * 1024;