@clawling/clawchat-plugin-openclaw 2026.9.14-2 → 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
@@ -42,13 +52,23 @@ const CODE_INTERNAL = 1; // CodeInternal — transient.
 const CODE_BAD_REQUEST = 400; // bad body / device id — permanent (client bug).
 /**
  * CodeInvalidRefresh — returned for BOTH a genuinely revoked/invalid refresh
- * token AND a single-use refresh token that was already CONSUMED by a prior
- * successful rotation (a duplicate-supervisor / concurrent-refresh / stale-store
- * race). The stateless `authRefresh` cannot tell the two apart, so it reports
- * `permanent`; the stateful `RefreshManager` re-classifies a consumed-rotation
- * race back to transient (see §B race) before any auto-logout.
+ * token AND a refresh token that was already CONSUMED by a prior successful
+ * rotation (a duplicate-supervisor / concurrent-refresh / stale-store race), once
+ * the backend's short replay grace window no longer covers it. The stateless
+ * `authRefresh` cannot tell the two apart, so it reports `permanent`; the
+ * stateful `RefreshManager` re-classifies a consumed-rotation race back to
+ * transient (see §B race) before any auto-logout.
  */
 export const CODE_INVALID_REFRESH = 10003;
+/**
+ * §B attempt deadline — total wall clock for one refresh attempt (request AND
+ * response body). A hit aborts the request and is TRANSIENT. Kept below
+ * `MIN_REFRESH_INTERVAL_MS` (30s) so the min-interval floor, not the deadline,
+ * sets the retry cadence: a retry of the same refresh token then lands inside
+ * the backend refresh grace window if the server rotated but the response was
+ * lost.
+ */
+export const REFRESH_REQUEST_TIMEOUT_MS = 20_000;
 /**
  * §0/§B — call `POST /v1/auth/refresh` to rotate the access+refresh token.
  *
@@ -58,6 +78,11 @@ export const CODE_INVALID_REFRESH = 10003;
  * always HTTP 200 — branch on the envelope `code`, NOT on HTTP status. This is
  * a standalone function (not a method on the token-bearing client) precisely
  * because no bearer token participates.
+ *
+ * The whole attempt is bounded by `REFRESH_REQUEST_TIMEOUT_MS` (§B attempt
+ * deadline): the request is aborted via its signal, and the deadline is also
+ * raced against the attempt so a fetch implementation that ignores the signal
+ * cannot hang the caller.
  */
 export async function authRefresh(opts, params) {
     const baseUrl = opts.baseUrl.replace(/\/+$/, "");
@@ -65,6 +90,26 @@ export async function authRefresh(opts, params) {
     if (!params.refreshToken?.trim()) {
         return { kind: "permanent", code: CODE_INVALID_REFRESH, message: "missing refresh token" };
     }
+    const timeoutMs = opts.timeoutMs ?? REFRESH_REQUEST_TIMEOUT_MS;
+    const controller = new AbortController();
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            controller.abort(new Error("refresh request timed out"));
+            resolve({ kind: "transient", message: `refresh request timed out after ${timeoutMs}ms` });
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([
+            authRefreshAttempt(baseUrl, fetchImpl, params, controller.signal),
+            deadline,
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function authRefreshAttempt(baseUrl, fetchImpl, params, signal) {
     let res;
     try {
         res = await fetchImpl(`${baseUrl}/v1/auth/refresh`, {
@@ -75,6 +120,8 @@ export async function authRefresh(opts, params) {
                 "x-device-id": params.deviceId,
             },
             body: JSON.stringify({ refresh_token: params.refreshToken.trim() }),
+            // Still in effect while the body is read below.
+            signal,
         });
     }
     catch (err) {
@@ -117,8 +164,9 @@ export async function authRefresh(opts, params) {
         const refreshToken = typeof data.refresh_token === "string" ? data.refresh_token : "";
         if (!accessToken || !refreshToken) {
             // Rotation succeeded server-side but the body is malformed — transient so
-            // we retry; the next attempt will return 10003 (rotation single-use) and
-            // escalate to permanent (§B transient→permanent).
+            // we retry; inside the backend grace window the retry redeems the old
+            // token again, after it the retry returns 10003 and escalates to
+            // permanent (§B transient→permanent).
             return { kind: "transient", status: 200, message: "refresh: rotation body incomplete" };
         }
         return { kind: "success", accessToken, refreshToken };
@@ -396,6 +444,13 @@ export function createOpenclawClawlingApiClient(opts) {
         async deleteMomentComment(params) {
             return await call("DELETE", `/v1/moments/${encodeURIComponent(String(params.momentId))}/comments/${encodeURIComponent(String(params.commentId))}`);
         },
+        async getDirectConversation(peerId) {
+            assertNonBlankId(peerId, "getDirectConversation: peerId");
+            return await call("POST", "/v1/conversations/direct", {
+                body: JSON.stringify({ peer_id: peerId.trim() }),
+                headers: { "content-type": "application/json" },
+            });
+        },
         async getConversation(conversationId) {
             return await call("GET", `/v1/conversations/${encodeURIComponent(conversationId)}`);
         },
@@ -427,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");
             }
@@ -448,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/config.js

@@ -83,6 +83,7 @@ export const openclawClawlingAccountConfigSchema = {
         forwardToolCalls: { type: "boolean" },
         richInteractions: { type: "boolean" },
         awarenessNote: { type: "boolean" },
+        friendGreeting: { type: "boolean" },
         livewareSample: { type: "boolean" },
         reconnect: {
             type: "object",
@@ -448,6 +449,7 @@ export function resolveOpenclawClawlingAccount(cfg, accountId, env = process.env
     const forwardToolCalls = typeof channel.forwardToolCalls === "boolean" ? channel.forwardToolCalls : false;
     const richInteractions = typeof channel.richInteractions === "boolean" ? channel.richInteractions : false;
     const awarenessNote = typeof channel.awarenessNote === "boolean" ? channel.awarenessNote : false;
+    const friendGreeting = typeof channel.friendGreeting === "boolean" ? channel.friendGreeting : true;
     const livewareSample = typeof channel.livewareSample === "boolean" ? channel.livewareSample : true;
     return {
         accountId: resolvedAccountId,
@@ -475,6 +477,7 @@ export function resolveOpenclawClawlingAccount(cfg, accountId, env = process.env
         forwardToolCalls,
         richInteractions,
         awarenessNote,
+        friendGreeting,
         livewareSample,
         allowFrom: [],
         reconnect: readReconnect(channel.reconnect),

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/friend-greeting.js

@@ -0,0 +1,80 @@
+/**
+ * First message to a newly added NON-owner friend.
+ *
+ * `friend.added` used to be a pure awareness event. The server creates the
+ * direct conversation inside the friend-accept transaction, but the signal
+ * only carries the counterparty `usr_…` — so the runtime resolves the
+ * conversation through `POST /v1/conversations/direct` and then feeds ONE
+ * synthetic inbound turn (built here) into the normal dispatch path, the same
+ * way the activation bootstrap greets the owner.
+ *
+ * The prompt is deliberately distinct from the owner activation prompt: this
+ * reader is a stranger, so "you are connected and ready" makes no sense and
+ * the agent must say whose agent it is instead.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { EVENT } from "./protocol-types.js";
+export const FRIEND_GREETING_FALLBACK = [
+    "A ClawChat user has just become your friend. You are now in a direct conversation with them; they are not your owner.",
+    "Reply now with one short, friendly greeting message in this conversation: introduce yourself by name, say you are an AI agent acting on behalf of your owner, and invite them to tell you what they need.",
+    "Send it as a normal chat reply. Do not write or create any files or notes, and do not call tools just to greet.",
+    "Do not share your owner's private information, and do not ask the user for personal information.",
+].join("\n");
+// Cross-plugin, user-editable override read lazily so edits apply on the next
+// friend without a restart. Any read failure falls back to the built-in text.
+// Mirrors `buildActivationBootstrapText` (`~/clawchat/greeting.md`).
+export function buildFriendGreetingText(homeDir = os.homedir()) {
+    const greetingPath = path.join(homeDir, "clawchat", "friend-greeting.md");
+    try {
+        const raw = fs.readFileSync(greetingPath);
+        const override = new TextDecoder("utf-8", { fatal: true }).decode(raw).trim();
+        if (override.length > 0) {
+            return override;
+        }
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "ENOENT") {
+            console.warn(`clawchat.friend-greeting failed to read override ${greetingPath}:`, error);
+        }
+    }
+    return FRIEND_GREETING_FALLBACK;
+}
+/**
+ * Synthetic inbound envelope for the friend greeting turn. Same invariant as
+ * `buildActivationBootstrapEnvelope`: `conversationId` MUST be a conversation
+ * idcode — the agent's reply inherits this chat_id, and anything else is
+ * refused at the outbound boundary after a full LLM turn has been spent.
+ */
+export function buildFriendGreetingEnvelope(params) {
+    const { account, conversationId, friendUserId } = params;
+    const text = buildFriendGreetingText();
+    const now = Date.now();
+    return {
+        version: "2",
+        event: EVENT.MESSAGE_SEND,
+        trace_id: `clawchat-plugin-openclaw-friend-greeting-${now}`,
+        emitted_at: now,
+        chat_id: conversationId,
+        chat_type: "direct",
+        to: { id: account.userId, type: "direct" },
+        sender: { id: friendUserId, type: "direct", nick_name: "" },
+        payload: {
+            message_id: `clawchat-plugin-openclaw-friend-greeting-${conversationId}-${now}`,
+            message_mode: "normal",
+            message: {
+                body: { fragments: [{ kind: "text", text }] },
+                context: { mentions: [], reply: null },
+                streaming: {
+                    status: "static",
+                    sequence: 0,
+                    mutation_policy: "sealed",
+                    started_at: null,
+                    completed_at: null,
+                },
+            },
+        },
+    };
+}

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) {