@clawling/clawchat-plugin-openclaw 2026.9.14-2 → 2026.9.17-1

package/dist/src/protocol-types.js

@@ -17,6 +17,7 @@ export const EVENT = {
     CHAT_METADATA_INVALIDATED: "chat.metadata.invalidated",
     NOTIFY_SIGNAL: "notify.signal",
     REPLAY_DONE: "replay.done",
+    HISTORY_TRUNCATED: "history.truncated",
     OFFLINE_BATCH: "offline.batch",
     OFFLINE_ACK: "offline.ack",
     OFFLINE_DONE: "offline.done",

package/dist/src/refresh-manager.js

@@ -22,6 +22,15 @@ const HOUR_MS = 60 * MINUTE_MS;
 export const MIN_REFRESH_INTERVAL_MS = 30_000;
 /** §A.1 — proactive jitter (±5min). */
 export const PROACTIVE_JITTER_MS = 5 * MINUTE_MS;
+/**
+ * §B retry within the grace window — jitter bounds for the one-shot retry after
+ * a transient proactive refresh. The retry is due `MIN_REFRESH_INTERVAL_MS` +
+ * [1s, 5s] after the failed attempt BEGAN (31–35s): far above the backend's
+ * minimum replay age, inside its 90s replay window, and never faster than the
+ * min-interval floor (which would skip it).
+ */
+export const PROACTIVE_RETRY_JITTER_MIN_MS = 1_000;
+export const PROACTIVE_RETRY_JITTER_MAX_MS = 5_000;
 /** §A.0 — fallback access-token TTL when `exp` is unparseable. */
 export const ACCESS_TOKEN_TTL_MS = 24 * HOUR_MS;
 /**
@@ -70,6 +79,8 @@ export class RefreshManager {
     /** §A.3 — epoch-ms of the last refresh attempt (any token). */
     lastAttemptAt = 0;
     proactiveTimer = null;
+    /** §B — the pending one-shot retry after a transient proactive refresh. */
+    proactiveRetryTimer = null;
     stopped = false;
     constructor(ports) {
         this.ports = ports;
@@ -133,9 +144,10 @@ export class RefreshManager {
             // sqlite-sourced agent must not keep a now-dead refresh token in its row
             // while running on the rotated token. Treat as transient so the WS stays
             // in backoff with the CURRENT tokens and the next attempt retries. The
-            // server already rotated, so the next attempt may return `code:10003`
-            // (which escalates to permanent per §B) — that is the accepted hazard, not
-            // a silent brick.
+            // server already rotated: inside the backend grace window the retry
+            // redeems the old token again; after it the retry returns `code:10003`
+            // (which escalates to permanent per §B) — the accepted hazard, not a
+            // silent brick.
             try {
                 await this.ports.persistRotatedTokens({
                     accessToken: result.accessToken,
@@ -160,8 +172,9 @@ export class RefreshManager {
             return { kind: "success", accessToken: result.accessToken, refreshToken: result.refreshToken };
         }
         if (result.kind === "permanent") {
-            // §B race — a `code:10003` is also returned for a single-use refresh token
-            // already CONSUMED by a prior successful rotation. Before auto-logging-out
+            // §B race — a `code:10003` is also returned for a refresh token already
+            // CONSUMED by a prior successful rotation (once the backend grace window
+            // no longer covers it). Before auto-logging-out
             // (which wipes credentials and bricks the agent), distinguish that race
             // from a genuine revocation. It is a race when EITHER the submitted token
             // is one we already rotated away from, OR the live store refresh token has
@@ -234,13 +247,26 @@ export class RefreshManager {
      * success, hands the rotated token to the runtime's `onProactiveRefreshed` port
      * so the live WS is closed and reconnected with the new token (the in-memory
      * swap alone does NOT reach the running socket, which captured the old token at
-     * `connect` time). Transient/skipped outcomes leave the WS untouched — the next
-     * proactive arm (or a reactive hello-fail) handles it.
+     * `connect` time). Transient/skipped outcomes leave the WS untouched.
+     *
+     * §B retry within the grace window — a TRANSIENT outcome (e.g. the attempt
+     * deadline hit after the server may already have rotated) arms ONE retry, due
+     * 31–35s after that attempt began, so a replay of the same refresh token lands
+     * inside the backend grace window instead of waiting for the next arm /
+     * hello-fail / 401, possibly hours later. The retry itself never arms another.
+     * Success, permanent and skipped outcomes arm nothing (skipped means another
+     * in-flight attempt or a latch already owns the token).
      */
-    async runProactiveRefresh() {
-        const outcome = await this.refresh("proactive-timer");
+    async runProactiveRefresh(isRetry = false) {
+        const accessTokenAtAttempt = this.ports.getAccessToken();
+        const outcome = await this.refresh(isRetry ? "proactive-retry" : "proactive-timer");
         if (this.stopped)
             return;
+        if (outcome.kind === "transient") {
+            if (!isRetry)
+                this.armProactiveRetry(accessTokenAtAttempt);
+            return;
+        }
         if (outcome.kind !== "success")
             return;
         if (this.ports.onProactiveRefreshed) {
@@ -255,6 +281,42 @@ export class RefreshManager {
             }
         }
     }
+    /**
+     * §B — arm the one-shot retry, measured from the failed attempt's start
+     * (`lastAttemptAt`). It runs through `refresh()`, so single-flight dedupe, the
+     * rejected-token latch and the min-interval floor all still apply. It is
+     * skipped when the access token changed meanwhile (someone else rotated).
+     */
+    armProactiveRetry(accessTokenAtAttempt) {
+        this.clearProactiveRetry();
+        const rawJitter = (this.ports.proactiveRetryJitter ?? defaultProactiveRetryJitter)();
+        const jitterMs = Math.min(PROACTIVE_RETRY_JITTER_MAX_MS, Math.max(PROACTIVE_RETRY_JITTER_MIN_MS, rawJitter));
+        const dueAtMs = this.lastAttemptAt + MIN_REFRESH_INTERVAL_MS + jitterMs;
+        const delayMs = Math.max(0, dueAtMs - this.now());
+        this.ports.log?.info?.(`clawchat-plugin-openclaw proactive refresh transient; one-shot retry in ${delayMs}ms`);
+        this.proactiveRetryTimer = this.setTimer(() => {
+            this.proactiveRetryTimer = null;
+            if (this.stopped)
+                return;
+            if (this.ports.getAccessToken() !== accessTokenAtAttempt) {
+                this.ports.log?.debug?.("clawchat-plugin-openclaw proactive retry skipped (access token already changed)");
+                return;
+            }
+            void this.runProactiveRefresh(true);
+        }, delayMs);
+    }
+    clearProactiveRetry() {
+        if (this.proactiveRetryTimer != null) {
+            this.clearTimer(this.proactiveRetryTimer);
+            this.proactiveRetryTimer = null;
+        }
+    }
+    /**
+     * Clear the proactive `refresh_at` timer (called on WS disconnect). The §B
+     * one-shot retry is deliberately NOT cleared here: a refresh timeout usually
+     * coincides with the network drop that also closes the socket, and refresh
+     * does not need the socket. `stop()` clears both.
+     */
     disarmProactiveTimer() {
         if (this.proactiveTimer != null) {
             this.clearTimer(this.proactiveTimer);
@@ -279,10 +341,11 @@ export class RefreshManager {
         });
         return this.now() >= refreshAtMs;
     }
-    /** Stop the manager — clears the proactive timer; no further refreshes arm. */
+    /** Stop the manager — clears the proactive + retry timers; nothing further arms. */
     stop() {
         this.stopped = true;
         this.disarmProactiveTimer();
+        this.clearProactiveRetry();
     }
     /** Test/inspection seam — the latched (rejected) access token, if any. */
     getRejectedToken() {
@@ -327,3 +390,7 @@ function decodeJwtIat(token) {
 function defaultJitter() {
     return (Math.random() * 2 - 1) * PROACTIVE_JITTER_MS;
 }
+function defaultProactiveRetryJitter() {
+    return (PROACTIVE_RETRY_JITTER_MIN_MS +
+        Math.random() * (PROACTIVE_RETRY_JITTER_MAX_MS - PROACTIVE_RETRY_JITTER_MIN_MS));
+}

package/dist/src/runtime.js

@@ -5,11 +5,14 @@ import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
 import { createOpenclawClawlingClient, resolveOpenclawClawlingDeviceId } from "./client.js";
 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";
@@ -101,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));
@@ -723,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).
@@ -795,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
@@ -1941,6 +1950,38 @@ export async function startOpenclawClawlingGateway(params) {
                     ],
                 }));
             }
+            else if (env.event === "history.truncated") {
+                // Replay-start boundary frame (docs/client-integration.md §11.7): part
+                // of the retained history will not be replayed to this device. This
+                // plugin advertises no reliable-delivery flag, so the server does not
+                // send it today; if one arrives it is logged explicitly. Never acked (no
+                // seq/dseq), never dispatched, no user-visible action. An absent or
+                // unrecognised `reason` means "pruned"; `oldest_seq` is an opaque token.
+                const current = wsLogContext();
+                const truncatedPayload = env.payload && typeof env.payload === "object"
+                    ? env.payload
+                    : undefined;
+                const rawReason = truncatedPayload?.reason;
+                const knownReason = rawReason === "pruned" || rawReason === "cursor_started_above_zero";
+                const fields = [
+                    ["event_name", env.event],
+                    ["trace_id", env.trace_id],
+                    ["oldest_seq", typeof truncatedPayload?.oldest_seq === "number" ? truncatedPayload.oldest_seq : "-"],
+                    ["reason", knownReason ? rawReason : "pruned"],
+                ];
+                if (!knownReason && typeof rawReason === "string" && rawReason) {
+                    fields.push(["raw_reason", rawReason]);
+                }
+                log?.info?.(formatWsLog({
+                    event: "inbound_control",
+                    accountId,
+                    attempt: current.attempt,
+                    reconnectCount: current.reconnectCount,
+                    state: "ready",
+                    action: "history_truncated",
+                    fields,
+                }));
+            }
             else if (env.event !== "ping" && env.event !== "pong") {
                 const current = wsLogContext();
                 log?.info?.(formatWsLog({
@@ -2088,6 +2129,77 @@ export async function startOpenclawClawlingGateway(params) {
     // A single queueMicrotask coalesces all awareness signals that arrive in
     // the same synchronous turn into exactly one handleInboundEnvelope call.
     let pendingAwarenessNote = false;
+    /**
+     * First message to a newly added NON-owner friend (`friend.added`).
+     *
+     * The signal only names the counterparty; the direct conversation the
+     * server created inside the accept transaction is resolved through
+     * `POST /v1/conversations/direct` and ONE synthetic greeting turn runs in
+     * it. Dedupe is persisted through the message ledger keyed on the signal's
+     * `event_id` (`message_id` is `notify:friend.added:<userId>` and would
+     * collide on remove + re-add, so it is only the fallback key) — a
+     * reconnect replay of the same signal cannot greet twice. The claim uses
+     * kind "message" because the ledger's once-only unique index is partial on
+     * kind = 'message'; chat_id stays null so the row never feeds a transcript.
+     * The owner's own `friend.added` is skipped: the activation bootstrap greets
+     * the owner.
+     */
+    const scheduleFriendGreeting = (payload) => {
+        if (!account.friendGreeting)
+            return;
+        const friendUserId = typeof payload?.entity_id === "string" ? payload.entity_id.trim() : "";
+        if (!friendUserId)
+            return;
+        const ownerUserId = account.ownerUserId?.trim();
+        if (ownerUserId && friendUserId === ownerUserId)
+            return;
+        const eventId = typeof payload?.event_id === "string" ? payload.event_id.trim() : "";
+        const messageId = typeof payload?.message_id === "string" ? payload.message_id.trim() : "";
+        const dedupeKey = eventId || messageId;
+        if (!dedupeKey) {
+            log?.info?.(`[${accountId}] clawchat-plugin-openclaw friend greeting skipped friend=${friendUserId} reason=no_dedupe_key`);
+            return;
+        }
+        if (store?.claimMessageOnce) {
+            const claimed = recordConnection("friend greeting claim", () => store.claimMessageOnce?.({
+                platform: "openclaw",
+                accountId,
+                kind: "message",
+                direction: "inbound",
+                eventType: "friend.greeting",
+                traceId: null,
+                chatId: null,
+                messageId: `friend.greeting:${dedupeKey}`,
+                text: null,
+                raw: { friend_user_id: friendUserId },
+            }));
+            if (claimed !== true) {
+                // false = already greeted (replay); null = ledger undecided — fail
+                // closed rather than risk a duplicate unsolicited message.
+                log?.info?.(`[${accountId}] clawchat-plugin-openclaw friend greeting skipped friend=${friendUserId} key=${dedupeKey} claimed=${String(claimed)}`);
+                return;
+            }
+        }
+        void (async () => {
+            let conversationId = "";
+            try {
+                const result = await getConversationApiClient().getDirectConversation(friendUserId);
+                conversationId = result?.conversation?.id?.trim() ?? "";
+            }
+            catch (err) {
+                log?.error?.(`[${accountId}] clawchat-plugin-openclaw friend greeting conversation lookup failed friend=${friendUserId}: ${err instanceof Error ? err.message : String(err)}`);
+                return;
+            }
+            if (!isValidChatId(conversationId)) {
+                log?.error?.(`[${accountId}] clawchat-plugin-openclaw friend greeting skipped friend=${friendUserId} reason=no_conversation_id`);
+                return;
+            }
+            log?.info?.(`[${accountId}] clawchat-plugin-openclaw friend greeting dispatch friend=${friendUserId} chat_id=${conversationId}`);
+            await handleInboundEnvelope(buildFriendGreetingEnvelope({ account, conversationId, friendUserId }));
+        })().catch((err) => {
+            log?.error?.(`[${accountId}] clawchat-plugin-openclaw friend greeting failed friend=${friendUserId}: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    };
     client.on("notify:signal", (env) => {
         // §9.4 reliable system notification. The plugin holds no friend/roster
         // cache (friends are fetched on demand via REST tools), so there is nothing
@@ -2177,6 +2289,9 @@ export async function startOpenclawClawlingGateway(params) {
                         void handleInboundEnvelope(buildAwarenessNoteEnvelope({ account, ownerConversationId }));
                     });
                 }
+                if (type === "friend.added") {
+                    scheduleFriendGreeting(payload);
+                }
             }
         }
     });

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.8.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/dist/src/tools-schema.js

@@ -123,6 +123,12 @@ export const ClawchatGetConversationSchema = Type.Object({
         description: "Concrete ClawChat conversation id to fetch",
     }),
 });
+export const ClawchatGetDirectConversationSchema = Type.Object({
+    userId: Type.String({
+        minLength: 1,
+        description: "Concrete ClawChat user id (usr_...) of the friend",
+    }),
+});
 export const ClawchatLeaveGroupSchema = Type.Object({
     conversationId: Type.String({
         description: "Concrete ClawChat group conversation id to leave",

package/dist/src/tools.js

@@ -12,7 +12,7 @@ import { getOpenclawClawlingClient, } from "./runtime.js";
 import { markTerminalClawChatSend, getCurrentTerminalSendScope } from "./terminal-send.js";
 import { editClawChatMemoryBody, readClawChatMemoryFile, resolveClawChatMemoryPath, searchClawChatMemory, writeClawChatMemoryBody, } from "./clawchat-memory.js";
 import { pullGroupMetadata, pullOwnerMetadata, pullUserMetadata, pushMetadata, updateMetadata, } from "./clawchat-metadata.js";
-import { ClawchatGetAccountProfileSchema, ClawchatGetConversationSchema, ClawchatGetMomentSchema, ClawchatGetUserProfileSchema, ClawchatLeaveGroupSchema, ClawchatAddGroupMemberSchema, ClawchatAcceptFriendRequestSchema, ClawchatMemoryEditSchema, ClawchatMemoryReadSchema, ClawchatMemorySearchSchema, ClawchatMemoryWriteSchema, ClawchatMetadataSyncSchema, ClawchatMetadataUpdateSchema, ClawchatCreateMomentCommentSchema, ClawchatCreateMomentSchema, ClawchatDeleteMomentCommentSchema, ClawchatDeleteMomentSchema, ClawchatListAccountFriendsSchema, ClawchatListFriendRequestsSchema, ClawchatListMomentsSchema, ClawchatMentionMessageSchema, ClawchatReactMessageSchema, ClawchatReplyMomentCommentSchema, ClawchatRejectFriendRequestSchema, ClawchatRemoveFriendSchema, ClawchatSearchUsersSchema, ClawchatSendFriendRequestSchema, ClawchatToggleMomentReactionSchema, ClawchatUpdateAccountProfileSchema, ClawchatUploadAvatarImageSchema, ClawchatRegisterAppSchema, ClawchatListAppsSchema, ClawchatUnregisterAppSchema, ClawchatLivewareLoginSchema, } from "./tools-schema.js";
+import { ClawchatGetAccountProfileSchema, ClawchatGetConversationSchema, ClawchatGetDirectConversationSchema, ClawchatGetMomentSchema, ClawchatGetUserProfileSchema, ClawchatLeaveGroupSchema, ClawchatAddGroupMemberSchema, ClawchatAcceptFriendRequestSchema, ClawchatMemoryEditSchema, ClawchatMemoryReadSchema, ClawchatMemorySearchSchema, ClawchatMemoryWriteSchema, ClawchatMetadataSyncSchema, ClawchatMetadataUpdateSchema, ClawchatCreateMomentCommentSchema, ClawchatCreateMomentSchema, ClawchatDeleteMomentCommentSchema, ClawchatDeleteMomentSchema, ClawchatListAccountFriendsSchema, ClawchatListFriendRequestsSchema, ClawchatListMomentsSchema, ClawchatMentionMessageSchema, ClawchatReactMessageSchema, ClawchatReplyMomentCommentSchema, ClawchatRejectFriendRequestSchema, ClawchatRemoveFriendSchema, ClawchatSearchUsersSchema, ClawchatSendFriendRequestSchema, ClawchatToggleMomentReactionSchema, ClawchatUpdateAccountProfileSchema, ClawchatUploadAvatarImageSchema, ClawchatRegisterAppSchema, ClawchatListAppsSchema, ClawchatUnregisterAppSchema, ClawchatLivewareLoginSchema, } from "./tools-schema.js";
 const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
 // Owner-approval gate business codes (must match the ClawChat backend's owner-approval codes).
 const CODE_PENDING_APPROVAL = 21001;
@@ -840,6 +840,37 @@ export function registerOpenclawClawlingTools(api, options = {}) {
             },
         };
     }, { name: "clawchat_get_conversation" });
+    api.registerTool((ctx) => {
+        const accountId = resolveOpenclawClawlingToolAccountId(ctx);
+        return {
+            name: "clawchat_get_direct_conversation",
+            label: "Get ClawChat Direct Conversation With User",
+            description: toolDescription("Resolve the direct (1:1) ClawChat conversation with a specific user to its conversation id (cnv_...), creating it if needed. " +
+                "TRIGGER - invoke when you need to send a message to a ClawChat user and only know their userId (usr_...), for example to start a conversation with a newly added friend. " +
+                "The user must already be your friend; otherwise the server rejects the call. " +
+                "Use the returned conversation.id as chatId for clawchat_mention_message. " +
+                "Never pass a userId or a name as a chatId."),
+            parameters: ClawchatGetDirectConversationSchema,
+            async execute(_callId, params) {
+                return await recordClawchatToolCall(accountId, "clawchat_get_direct_conversation", params, async () => {
+                    const p = params;
+                    const built = buildClient(accountId);
+                    if (!built.ok)
+                        return built.error;
+                    try {
+                        const data = await built.client.getDirectConversation(p.userId);
+                        return jsonResponse(data);
+                    }
+                    catch (err) {
+                        if (err instanceof ClawlingApiError) {
+                            return apiError(err);
+                        }
+                        return genericError(err);
+                    }
+                });
+            },
+        };
+    }, { name: "clawchat_get_direct_conversation" });
     api.registerTool((ctx) => {
         const accountId = resolveOpenclawClawlingToolAccountId(ctx);
         return {

package/dist/src/ws-client.js

@@ -643,6 +643,11 @@ export class ClawChatClient extends EventEmitter {
             this.emit("notify:signal", env);
         if (env.event === EVENT.REPLAY_DONE)
             this.emit("replay:done", env);
+        // Replay-start boundary frame (docs/client-integration.md §11.7). Control
+        // only: it carries no seq/dseq, so it is never acked and never becomes a
+        // `message`. Its own emitter keeps it out of the unknown-event path.
+        if (env.event === EVENT.HISTORY_TRUNCATED)
+            this.emit("history:truncated", env);
         if (env.event === EVENT.OFFLINE_DONE)
             this.emit("offline:done");
     }

package/openclaw.plugin.json

@@ -46,6 +46,7 @@
       "clawchat_mention_message",
       "clawchat_react_message",
       "clawchat_get_conversation",
+      "clawchat_get_direct_conversation",
       "clawchat_leave_group",
       "clawchat_add_group_member",
       "clawchat_list_moments",
@@ -112,6 +113,7 @@
       "forwardToolCalls": { "type": "boolean" },
       "richInteractions": { "type": "boolean" },
       "awarenessNote": { "type": "boolean" },
+      "friendGreeting": { "type": "boolean" },
       "livewareSample": { "type": "boolean" },
       "reconnect": {
         "type": "object",
@@ -184,6 +186,7 @@
             "forwardToolCalls": { "type": "boolean" },
             "richInteractions": { "type": "boolean" },
             "awarenessNote": { "type": "boolean" },
+            "friendGreeting": { "type": "boolean" },
             "livewareSample": { "type": "boolean" },
             "reconnect": {
               "type": "object",
@@ -262,6 +265,7 @@
           "forwardToolCalls": { "type": "boolean" },
           "richInteractions": { "type": "boolean" },
           "awarenessNote": { "type": "boolean" },
+          "friendGreeting": { "type": "boolean" },
           "livewareSample": { "type": "boolean" },
           "reconnect": {
             "type": "object",
@@ -334,6 +338,7 @@
                 "forwardToolCalls": { "type": "boolean" },
                 "richInteractions": { "type": "boolean" },
                 "awarenessNote": { "type": "boolean" },
+                "friendGreeting": { "type": "boolean" },
                 "livewareSample": { "type": "boolean" },
                 "reconnect": {
                   "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.9.14-2",
+  "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.2.2
+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:
@@ -88,6 +116,7 @@ Tool descriptions are authoritative. These routing hints resolve common ambiguit
 | Accept/reject a friend request | `clawchat_accept_friend_request` or `clawchat_reject_friend_request` with exact `requestId`; list incoming requests first when ambiguous |
 | Remove/unfriend contact | `clawchat_remove_friend` with exact `friendUserId`; list friends first when ambiguous |
 | Inspect one conversation or group by exact id | `clawchat_get_conversation` |
+| Message a ClawChat user you only know by `userId` (e.g. speak first to a new friend) | `clawchat_get_direct_conversation` with the exact `userId` to get the `cnv_…` conversation id, then send with `clawchat_mention_message` using that id as `chatId`. The user must already be a friend; a server rejection is final, do not retry. Never pass a `userId` or a name as `chatId` |
 | View/browse moments or dynamics | `clawchat_list_moments` |
 | Read one moment and its visible comments by exact id | `clawchat_get_moment` with exact `momentId`; read-only, use after a `moment.comment.created`/`moment.comment.replied` awareness note to read the new comment before deciding whether to reply |
 | Create a moment/dynamic | `clawchat_create_moment`; upload local images first and pass URLs |
@@ -129,6 +158,6 @@ For avatar changes, save the returned `avatar_url` back to the identity file aft
 
 For moments/dynamics, list first when the user refers to "this", "latest", "that post", "the one from earlier", or another ambiguous target. Use exact ids returned by the tools. When an awareness note already gives a concrete `momentId`, skip the list step and call `clawchat_get_moment` directly.
 
-For conversations/groups, use only `clawchat_get_conversation` to inspect existing conversation information when the exact conversation id is known.
+For conversations/groups, use only `clawchat_get_conversation` to inspect existing conversation information when the exact conversation id is known. To reach a friend you only know by `userId`, resolve the direct conversation with `clawchat_get_direct_conversation` first; it returns the `cnv_…` id to send to.
 
 Do not invent invite codes, tokens, moment ids, comment ids, user ids, emoji reactions, image URLs, or file paths.

package/skills/clawchat-set-greeting/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: clawchat-set-greeting
-version: 1.0.0
-description: Use when the user wants to customize, change, set, or reset this agent's first-load / activation greeting — what the agent says the first time it connects to a ClawChat conversation. Writes the greeting instruction to ~/clawchat/greeting.md.
+version: 1.1.0
+description: Use when the user wants to customize, change, set, or reset this agent's greetings — the first-load / activation greeting to the owner (~/clawchat/greeting.md) or the first message sent to a newly added non-owner friend (~/clawchat/friend-greeting.md).
 ---
 
 # Set the ClawChat first-load greeting
@@ -38,7 +38,26 @@ one sentence." — not the finished greeting sentence itself.
 To restore the built-in greeting, delete `~/clawchat/greeting.md` (or empty it). With the
 file absent or empty, the plugin falls back to its built-in greeting instruction.
 
+## The other greeting: first message to a new friend
+
+When someone who is **not** the owner becomes this agent's ClawChat friend (either side
+sent the request), the plugin speaks first in the new direct conversation using a second,
+separate instruction. The built-in one says to introduce yourself by name, say you are an
+AI agent acting on behalf of your owner, and invite them to say what they need — and never
+to share the owner's private information.
+
+Override it the same way with **`~/clawchat/friend-greeting.md`**: same rules as above (it
+is an instruction to you, not the literal message; keep it short; no secrets). Delete or
+empty the file to restore the built-in instruction. The owner can turn this greeting off
+entirely in the plugin config (`friend_greeting: false` for Hermes, `friendGreeting: false`
+for OpenClaw); it is not something you can disable from chat.
+
+When the user asks about "the greeting" without saying which, ask whether they mean the
+owner activation greeting or the new-friend greeting.
+
 ## Notes
 
-- This affects only the **first-load** activation greeting, not later replies.
-- The same file is honored by both ClawChat agent runtimes (Hermes and OpenClaw).
+- `greeting.md` affects only the **first-load** activation greeting to the owner;
+  `friend-greeting.md` affects only the first message to a newly added non-owner friend.
+  Neither changes later replies.
+- Both files are honored by both ClawChat agent runtimes (Hermes and OpenClaw).

package/skills/manifest.json

@@ -3,10 +3,10 @@
   "skills": {
     "openclaw": {
       "clawchat-core": {
-        "version": "1.2.2",
+        "version": "1.4.0",
         "path": "openclaw/clawchat-core/SKILL.md",
-        "sha256": "99eb816d3dd52b2135540214a2830108dcae8b182280dbcf4d32d0633e8a9b66",
-        "bytes": 11107
+        "sha256": "c0cd2a83d6b48b6f4778a2127b5f4f7dd1ba33ea093972e714eee4bc0af6ed67",
+        "bytes": 12893
       },
       "clawchat-liveware": {
         "version": "1.2.2",
@@ -21,10 +21,10 @@
         "bytes": 8892
       },
       "clawchat-set-greeting": {
-        "version": "1.0.0",
+        "version": "1.1.0",
         "path": "shared/clawchat-set-greeting/SKILL.md",
-        "sha256": "435470becd56ae25dcee58f626afe1e2aadecc6252af9b93a761e31de7467816",
-        "bytes": 2316
+        "sha256": "cf21e94513e3de5bfe882e55be639ce37a6db5d874d988b8e1e18a908a46252d",
+        "bytes": 3475
       },
       "clawchat-liveware-sample": {
         "version": "2.0.0",
@@ -35,10 +35,10 @@
     },
     "hermes": {
       "clawchat-core": {
-        "version": "1.8.0",
+        "version": "1.10.0",
         "path": "hermes/clawchat-core/SKILL.md",
-        "sha256": "3488cb84c05527d4a8ce25ecbc0d698764628ddccb89fcd25ee0ce18c434c167",
-        "bytes": 18195
+        "sha256": "6130e98e426f5d51392fd5bd7d75932d859b0531ea4216ef9a0a50526b99dfb6",
+        "bytes": 20124
       },
       "clawchat-liveware": {
         "version": "1.2.2",
@@ -53,10 +53,10 @@
         "bytes": 8892
       },
       "clawchat-set-greeting": {
-        "version": "1.0.0",
+        "version": "1.1.0",
         "path": "shared/clawchat-set-greeting/SKILL.md",
-        "sha256": "435470becd56ae25dcee58f626afe1e2aadecc6252af9b93a761e31de7467816",
-        "bytes": 2316
+        "sha256": "cf21e94513e3de5bfe882e55be639ce37a6db5d874d988b8e1e18a908a46252d",
+        "bytes": 3475
       },
       "clawchat-liveware-sample": {
         "version": "2.0.0",