@clawling/clawchat-plugin-openclaw 2026.5.12-39 → 2026.5.13-1

package/src/api-client.ts

@@ -17,6 +17,24 @@ import {
 } from "./api-types.ts";
 import { CHANNEL_ID } from "./config.ts";
 
+export interface PluginReportInput {
+  deviceId: string;
+  platform: string;
+  pluginVersion: string;
+  runtimeName: string;
+  runtimeVersion: string;
+}
+
+export function buildPluginReportBody(input: PluginReportInput): Record<string, string> {
+  return {
+    device_id: input.deviceId,
+    platform: input.platform,
+    plugin_version: input.pluginVersion,
+    runtime_name: input.runtimeName,
+    runtime_version: input.runtimeVersion,
+  };
+}
+
 export interface ApiClientOptions {
   baseUrl: string;
   token: string;
@@ -28,6 +46,47 @@ export interface ApiClientOptions {
   fetchImpl?: typeof fetch;
 }
 
+/**
+ * §A.0 — decode the access token's `exp` claim locally (base64url-decode the
+ * JWT payload segment, read `exp` as epoch seconds). Returns `null` when the
+ * token is not a parseable JWT or carries no numeric `exp`, in which case the
+ * caller falls back to `activated_at + 24h`. We never persist a separate
+ * expiry column; this is derived from the token on every load.
+ */
+export function decodeJwtExp(token: string): number | null {
+  if (typeof token !== "string") return null;
+  const segments = token.split(".");
+  if (segments.length < 2) return null;
+  const payloadSegment = segments[1];
+  if (!payloadSegment) return null;
+  try {
+    const json = Buffer.from(payloadSegment, "base64url").toString("utf8");
+    const parsed = JSON.parse(json) as { exp?: unknown };
+    const exp = parsed?.exp;
+    return typeof exp === "number" && Number.isFinite(exp) ? exp : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * §0/§B — outcome classes for `POST /v1/auth/refresh`. The endpoint is
+ * always HTTP 200; callers branch on the envelope `code`. Distinct kinds keep
+ * the permanent/transient decision (and auto-logout vs. backoff) explicit.
+ */
+export type AuthRefreshResult =
+  | { kind: "success"; accessToken: string; refreshToken: string }
+  // `code:10003` invalid refresh OR `code:400` bad request — PERMANENT.
+  | { kind: "permanent"; code: number; message: string }
+  // `code:1` internal, any non-200, or a network error — TRANSIENT.
+  | { kind: "transient"; message: string; status?: number; code?: number };
+
+export interface AuthRefreshParams {
+  refreshToken: string;
+  /** The connect-time `X-Device-Id` (OpenClaw: `CHANNEL_ID`). */
+  deviceId: string;
+}
+
 export interface OpenclawClawlingApiClient {
   getMyProfile(): Promise<Profile>;
   getAgentProfile(agentId: string): Promise<{ agent: AgentProfile }>;
@@ -90,6 +149,111 @@ export interface OpenclawClawlingApiClient {
     filename: string;
     mime?: string;
   }): Promise<AvatarUploadResult>;
+  /**
+   * Report this plugin's version + runtime to member-backend. When
+   * `authenticated`, posts to the agent-JWT self-report endpoint (links the row
+   * to the caller's agent/owner); otherwise the public unpaired endpoint.
+   */
+  reportPlugin(
+    input: PluginReportInput,
+    opts?: { authenticated?: boolean },
+  ): Promise<void>;
+}
+
+/** Backend envelope codes for `POST /v1/auth/refresh` (§0). */
+const CODE_OK = 0;
+const CODE_INTERNAL = 1; // CodeInternal — transient.
+const CODE_BAD_REQUEST = 400; // bad body / device id — permanent (client bug).
+const CODE_INVALID_REFRESH = 10003; // CodeInvalidRefresh — permanent.
+
+/**
+ * §0/§B — call `POST /v1/auth/refresh` to rotate the access+refresh token.
+ *
+ * Unauthenticated: the refresh token in the body IS the credential, so we send
+ * NO `Authorization` header. `X-Device-Id` MUST equal the connect-time device
+ * id (the backend rejects on `sess.DeviceID != X-Device-Id`). The endpoint is
+ * always HTTP 200 — branch on the envelope `code`, NOT on HTTP status. This is
+ * a standalone function (not a method on the token-bearing client) precisely
+ * because no bearer token participates.
+ */
+export async function authRefresh(
+  opts: { baseUrl: string; fetchImpl?: typeof fetch },
+  params: AuthRefreshParams,
+): Promise<AuthRefreshResult> {
+  const baseUrl = opts.baseUrl.replace(/\/+$/, "");
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+  if (!params.refreshToken?.trim()) {
+    return { kind: "permanent", code: CODE_INVALID_REFRESH, message: "missing refresh token" };
+  }
+  let res: Response;
+  try {
+    res = await fetchImpl(`${baseUrl}/v1/auth/refresh`, {
+      method: "POST",
+      // No `Authorization` header — refresh is unauthenticated by design.
+      headers: {
+        "content-type": "application/json",
+        "x-device-id": params.deviceId,
+      },
+      body: JSON.stringify({ refresh_token: params.refreshToken.trim() }),
+    });
+  } catch (err) {
+    // Network error / timeout / DNS — TRANSIENT (no rotation committed).
+    return {
+      kind: "transient",
+      message: `refresh fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  if (res.status !== 200) {
+    // Any non-200 (500/LB/transport) — TRANSIENT, regardless of body.
+    const text = await res.text().catch(() => "");
+    return {
+      kind: "transient",
+      status: res.status,
+      message: `refresh http ${res.status} ${text.slice(0, 200)}`,
+    };
+  }
+
+  const text = await res.text().catch(() => "");
+  let parsed: { code?: unknown; msg?: unknown; message?: unknown; data?: unknown } | undefined;
+  try {
+    parsed = text ? (JSON.parse(text) as typeof parsed) : undefined;
+  } catch {
+    parsed = undefined;
+  }
+  const code = typeof parsed?.code === "number" ? parsed.code : Number.NaN;
+  const message =
+    (typeof parsed?.msg === "string" && parsed.msg) ||
+    (typeof parsed?.message === "string" && parsed.message) ||
+    `code=${code}`;
+
+  if (!Number.isFinite(code)) {
+    // 200 with no usable envelope — treat as transient (do not auto-logout).
+    return { kind: "transient", status: 200, message: "refresh: missing numeric code" };
+  }
+  if (code === CODE_OK) {
+    const data = parsed?.data && typeof parsed.data === "object"
+      ? (parsed.data as { access_token?: unknown; refresh_token?: unknown })
+      : {};
+    const accessToken = typeof data.access_token === "string" ? data.access_token : "";
+    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).
+      return { kind: "transient", status: 200, message: "refresh: rotation body incomplete" };
+    }
+    return { kind: "success", accessToken, refreshToken };
+  }
+  if (code === CODE_INVALID_REFRESH || code === CODE_BAD_REQUEST) {
+    return { kind: "permanent", code, message };
+  }
+  if (code === CODE_INTERNAL) {
+    return { kind: "transient", status: 200, code, message };
+  }
+  // Unknown non-zero code — conservatively transient (never auto-logout on an
+  // unrecognized code; only 10003/400 are permanent per §0).
+  return { kind: "transient", status: 200, code, message };
 }
 
 export function createOpenclawClawlingApiClient(opts: ApiClientOptions): OpenclawClawlingApiClient {
@@ -134,48 +298,54 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
         path,
       });
     }
-    if (!res.ok) {
-      const snippet = await res.text().catch(() => "");
-      throw new ClawlingApiError("transport", `http ${res.status} ${snippet.slice(0, 200)}`, {
-        status: res.status,
-        path,
-      });
-    }
+    // §15.3: HTTP status stays meaningful for proxies, but application code
+    // should branch on the business `code`, not the HTTP status. Parse the body
+    // FIRST — even on a non-2xx — so callers receive the precise business code
+    // (e.g. 41301 vs 41501) rather than a generic transport error. Only fall
+    // back to the HTTP status when no structured envelope is present.
+    const text = await res.text().catch(() => "");
     let parsed: unknown;
     try {
-      parsed = await res.json();
-    } catch (err) {
-      throw new ClawlingApiError(
-        "transport",
-        `non-JSON response: ${err instanceof Error ? err.message : String(err)}`,
-        { status: res.status, path },
-      );
+      parsed = text ? JSON.parse(text) : undefined;
+    } catch {
+      parsed = undefined;
     }
     // Unified envelope: `{ code: number, msg: string, data: T }`.
     // `code === 0` means success; any other value is a business error whose
     // `msg` is surfaced to callers and `code` is preserved on the error meta.
-    const env = parsed as { code?: unknown; msg?: unknown; message?: unknown; data?: T };
-    const code = typeof env.code === "number" ? env.code : Number.NaN;
-    const msg =
-      typeof env.msg === "string"
-        ? env.msg
-        : typeof env.message === "string"
-          ? env.message
-          : "";
-    if (!Number.isFinite(code)) {
-      throw new ClawlingApiError("transport", "invalid envelope: missing numeric `code`", {
-        status: res.status,
-        path,
-      });
+    const env =
+      parsed && typeof parsed === "object"
+        ? (parsed as { code?: unknown; msg?: unknown; message?: unknown; data?: T })
+        : undefined;
+    const code = typeof env?.code === "number" ? env.code : Number.NaN;
+    if (env && Number.isFinite(code)) {
+      const msg =
+        typeof env.msg === "string"
+          ? env.msg
+          : typeof env.message === "string"
+            ? env.message
+            : "";
+      if (code !== 0) {
+        throw new ClawlingApiError("api", msg || `code=${code}`, {
+          code,
+          status: res.status,
+          path,
+        });
+      }
+      return env.data as T;
     }
-    if (code !== 0) {
-      throw new ClawlingApiError("api", msg || `code=${code}`, {
-        code,
+    // No usable envelope — fall back to the HTTP status signal.
+    if (!res.ok) {
+      throw new ClawlingApiError("transport", `http ${res.status} ${text.slice(0, 200)}`, {
         status: res.status,
         path,
       });
     }
-    return env.data as T;
+    throw new ClawlingApiError(
+      "transport",
+      text ? "invalid envelope: missing numeric `code`" : "non-JSON response: empty body",
+      { status: res.status, path },
+    );
   }
 
   async function call<T>(
@@ -472,5 +642,14 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
       fd.set("file", file);
       return await call<AvatarUploadResult>("POST", "/v1/files/upload-url", { body: fd });
     },
+    async reportPlugin(input, opts): Promise<void> {
+      const path = opts?.authenticated
+        ? "/v1/agents/me/plugin-report"
+        : "/v1/agents/plugin-report";
+      await call<unknown>("POST", path, {
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(buildPluginReportBody(input)),
+      });
+    },
   };
 }

package/src/client.ts

@@ -9,6 +9,13 @@ export type { ChatType } from "./protocol-types.ts";
 export interface CreateClientOverrides {
   /** Transport override — only intended for tests (e.g. MockTransport). */
   transport?: Transport;
+  /**
+   * Device id to present on `connect`, overriding the hostname-derived default.
+   * Supplied with a previously server-resolved `device_id` (persisted from an
+   * earlier `hello-ok`) so a pod restart reuses the same device identity
+   * instead of minting a new one and forcing a full inbox replay.
+   */
+  deviceIdOverride?: string;
   wsLifecycle?: {
     onConnectFrameSent?: (env: {
       trace_id?: unknown;
@@ -27,10 +34,14 @@ export function createOpenclawClawlingClient(
   account: ResolvedOpenclawClawlingAccount,
   overrides: CreateClientOverrides = {},
 ): ClawlingChatClient {
+  const deviceId =
+    overrides.deviceIdOverride && overrides.deviceIdOverride.trim()
+      ? overrides.deviceIdOverride.trim()
+      : resolveOpenclawClawlingDeviceId(account);
   const client = createClawChatClient({
     url: account.websocketUrl,
     token: account.token,
-    deviceId: resolveOpenclawClawlingDeviceId(account),
+    deviceId,
     ...(overrides.transport ? { transport: overrides.transport } : {}),
     reconnect: {
       enabled: true,

package/src/config-compat.ts

@@ -0,0 +1,154 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+import { CHANNEL_ID } from "./config.ts";
+
+/**
+ * Compatibility migration for the plugin rename (commit 260044f): the plugin
+ * `id` and channel key changed from the OLD `openclaw-clawchat` to the NEW
+ * `clawchat-plugin-openclaw` (= {@link CHANNEL_ID}).
+ *
+ * Users upgrading from the old version have all their state — channel block
+ * (token/userId/ownerUserId/refreshToken/…), `plugins.allow`,
+ * `plugins.entries`, and `tools.allow`/`tools.alsoAllow` — keyed under the old
+ * id. The new code only reads the new id, so the channel silently fails to
+ * load. This migration moves the old-keyed state onto the new id.
+ *
+ * The function is PURE: it clones the input via `structuredClone` and never
+ * mutates its argument. It is IDEMPOTENT: a config with no old id anywhere
+ * returns an equivalent config with `changes: []`.
+ */
+
+export const LEGACY_CHANNEL_ID = "openclaw-clawchat" as const;
+export const TARGET_CHANNEL_ID = CHANNEL_ID;
+
+const BLOCKED_OBJECT_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+
+function isBlockedObjectKey(key: string): boolean {
+  return BLOCKED_OBJECT_KEYS.has(key);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyRecord(value: unknown): value is Record<string, unknown> {
+  return isRecord(value) && Object.keys(value).length > 0;
+}
+
+/**
+ * Copy keys from `source` into `target` only when they are absent/undefined in
+ * `target` (target is more current — never overwrite an existing value).
+ * Recurses into nested records. Skips prototype-pollution keys.
+ */
+function mergeMissing(
+  target: Record<string, unknown>,
+  source: Record<string, unknown>,
+): void {
+  for (const [key, value] of Object.entries(source)) {
+    if (value === undefined || isBlockedObjectKey(key)) continue;
+    const existing = target[key];
+    if (existing === undefined) {
+      target[key] = value;
+      continue;
+    }
+    if (isRecord(existing) && isRecord(value)) mergeMissing(existing, value);
+  }
+}
+
+/** Replace `from` → `to` in a string array, preserving order and deduping. */
+function replaceAndDedup(list: string[], from: string, to: string): string[] {
+  const out: string[] = [];
+  for (const raw of list) {
+    const value = raw === from ? to : raw;
+    if (!out.includes(value)) out.push(value);
+  }
+  return out;
+}
+
+export function migrateLegacyClawChatChannelConfig(config: OpenClawConfig): {
+  config: OpenClawConfig;
+  changes: string[];
+} {
+  const changes: string[] = [];
+  if (!isRecord(config)) return { config, changes };
+
+  const next = structuredClone(config) as Record<string, unknown>;
+
+  // 1. channels — move/merge the old channel block onto the new id.
+  const channels = next.channels;
+  if (isRecord(channels)) {
+    const oldChannel = channels[LEGACY_CHANNEL_ID];
+    if (isNonEmptyRecord(oldChannel)) {
+      const newChannel = channels[TARGET_CHANNEL_ID];
+      if (!isNonEmptyRecord(newChannel)) {
+        channels[TARGET_CHANNEL_ID] = oldChannel;
+        changes.push(
+          `Moved channel "${LEGACY_CHANNEL_ID}" → "${TARGET_CHANNEL_ID}".`,
+        );
+      } else {
+        mergeMissing(newChannel, oldChannel);
+        changes.push(
+          `Merged channel "${LEGACY_CHANNEL_ID}" → "${TARGET_CHANNEL_ID}" (filled missing fields; kept existing values).`,
+        );
+      }
+      delete channels[LEGACY_CHANNEL_ID];
+    }
+  }
+
+  // plugins.* live under a single `plugins` record.
+  const plugins = next.plugins;
+  if (isRecord(plugins)) {
+    // 2. plugins.allow — replace old id with new id (append if missing), dedup.
+    const allow = plugins.allow;
+    if (Array.isArray(allow) && allow.includes(LEGACY_CHANNEL_ID)) {
+      const replaced = replaceAndDedup(
+        allow.filter((v): v is string => typeof v === "string"),
+        LEGACY_CHANNEL_ID,
+        TARGET_CHANNEL_ID,
+      );
+      plugins.allow = replaced;
+      changes.push(
+        `Updated plugins.allow: "${LEGACY_CHANNEL_ID}" → "${TARGET_CHANNEL_ID}".`,
+      );
+    }
+
+    // 3. plugins.entries — merge-missing the old entry into the new one.
+    const entries = plugins.entries;
+    if (isRecord(entries)) {
+      const oldEntry = entries[LEGACY_CHANNEL_ID];
+      if (oldEntry !== undefined) {
+        if (isRecord(oldEntry)) {
+          const newEntry = entries[TARGET_CHANNEL_ID];
+          if (!isRecord(newEntry)) {
+            entries[TARGET_CHANNEL_ID] = oldEntry;
+          } else {
+            mergeMissing(newEntry, oldEntry);
+          }
+        }
+        delete entries[LEGACY_CHANNEL_ID];
+        changes.push(
+          `Merged plugins.entries["${LEGACY_CHANNEL_ID}"] → plugins.entries["${TARGET_CHANNEL_ID}"].`,
+        );
+      }
+    }
+  }
+
+  // 4. tools.allow + tools.alsoAllow — replace old id with new id, dedup.
+  const tools = next.tools;
+  if (isRecord(tools)) {
+    for (const key of ["allow", "alsoAllow"] as const) {
+      const list = tools[key];
+      if (Array.isArray(list) && list.includes(LEGACY_CHANNEL_ID)) {
+        tools[key] = replaceAndDedup(
+          list.filter((v): v is string => typeof v === "string"),
+          LEGACY_CHANNEL_ID,
+          TARGET_CHANNEL_ID,
+        );
+        changes.push(
+          `Updated tools.${key}: "${LEGACY_CHANNEL_ID}" → "${TARGET_CHANNEL_ID}".`,
+        );
+      }
+    }
+  }
+
+  return { config: next as OpenClawConfig, changes };
+}

package/src/inbound.ts

@@ -72,14 +72,16 @@ type SenderLike = {
   type?: unknown;
 };
 
-function normalizeSender(sender: unknown): { id: string; nickName: string; profileType: string | null } | null {
+function normalizeSender(sender: unknown): { id: string; nickName: string } | null {
   if (!sender || typeof sender !== "object") return null;
   const s = sender as SenderLike;
   const id = typeof s.id === "string" ? s.id : "";
   if (!id) return null;
   const nickName = typeof s.nick_name === "string" ? s.nick_name : id;
-  const profileType = s.type === "agent" || s.type === "user" ? s.type : null;
-  return { id, nickName, profileType };
+  // §4.1: `sender.type` is the server-stamped routing type and is always
+  // "direct" — it never carries the human/agent distinction. The sender's
+  // profile_type is resolved downstream from chat metadata, not from the wire.
+  return { id, nickName };
 }
 
 function requireChatId(envelope: Envelope<unknown>): string | null {
@@ -166,6 +168,20 @@ export async function dispatchOpenclawClawlingInbound(
     );
     return;
   }
+  // Fail-closed self-echo guard: the self-echo check below
+  // (`sender.id === account.userId`) is only meaningful when `account.userId`
+  // is known. A reactivation auth failure can leave `account.userId` as an
+  // empty string (see runtime.ts reactivation edge); with an empty userId the
+  // `account.userId && …` short-circuit would silently treat EVERY frame —
+  // including our own echoed messages — as non-self and feed it back into the
+  // LLM pipeline (self-reply loop). Refuse to process materialized messages in
+  // that state rather than risk echoing our own output.
+  if (!account.userId) {
+    log?.error?.(
+      `[${account.accountId}] clawchat-plugin-openclaw skip (fail-closed): empty account.userId, cannot apply self-echo guard event=${envelope.event} trace=${envelope.trace_id}`,
+    );
+    return;
+  }
   if (isMaterializedMessage && !isInboundMessagePayload(envelope.payload)) {
     log?.info?.(
       `[${account.accountId}] clawchat-plugin-openclaw skip: invalid payload trace=${envelope.trace_id}`,
@@ -214,7 +230,11 @@ export async function dispatchOpenclawClawlingInbound(
   }
   const chatType: ChatType = envelope.chat_type === "group" ? "group" : "direct";
   const isGroup = chatType === "group";
-  if (isMaterializedMessage && payload.message_mode !== "normal") {
+  // §7.5: the server does not default message_mode — an omitted field arrives
+  // as "" on the downlink. Empty/absent is equivalent to "normal", so only
+  // skip genuinely non-normal modes (e.g. "thinking").
+  const messageMode = payload.message_mode ?? "";
+  if (isMaterializedMessage && messageMode !== "normal" && messageMode !== "") {
     log?.info?.(
       `[${account.accountId}] clawchat-plugin-openclaw skip non-normal mode=${payload.message_mode}`,
     );
@@ -271,7 +291,6 @@ export async function dispatchOpenclawClawlingInbound(
     peer: { kind: isGroup ? "group" : "direct", id: chatId },
     senderId: sender.id,
     senderNickName: sender.nickName,
-    ...(sender.profileType ? { senderProfileType: sender.profileType } : {}),
     rawBody,
     messageId: payload.message_id,
     traceId: envelope.trace_id,

package/src/login.runtime.ts

@@ -268,6 +268,10 @@ export async function runOpenclawClawlingLogin(params: LoginParams): Promise<voi
       refreshToken: normalizedResult.refresh_token || null,
       conversationId: normalizedResult.conversation?.id ?? null,
       loginMethod: "login",
+      // §E — record the exact `X-Device-Id` sent at connect (the constant
+      // `CHANNEL_ID`, see `authHeaders` in api-client.ts), so a later refresh
+      // sends the same device id the backend baked into the session.
+      deviceId: CHANNEL_ID,
     });
   } catch {
     runtime.log("clawchat-plugin-openclaw sqlite activation persistence failed; login continues.");

package/src/outbound.ts

@@ -1,3 +1,4 @@
+import { randomInt } from "node:crypto";
 import { MessageSendError, type Envelope, type Fragment, type MentionFragment, type MessageAckPayload, type MessageErrorPayload } from "./protocol-types.ts";
 import type { ClawlingChatClient } from "./ws-client.ts";
 import {
@@ -321,10 +322,15 @@ async function sendAlignedAckableEnvelope(params: {
       if (ack.trace_id !== traceId) return;
       if (ack.event === "message.error") {
         if (state === "acked" || state === "failed") return;
-        const payload = ack.payload as Partial<MessageErrorPayload>;
+        const payload = ack.payload as Partial<MessageErrorPayload> & { message?: unknown };
         const code = typeof payload.code === "string" && payload.code ? payload.code : "unknown";
-        const message = typeof payload.message === "string" && payload.message ? payload.message : "message send failed";
-        fail(new MessageSendError(traceId, code, message, ack.chat_id));
+        // §14.3: the human-readable hint is `reason` (fall back to legacy `message`).
+        const hint = typeof payload.reason === "string" && payload.reason
+          ? payload.reason
+          : typeof payload.message === "string" && payload.message
+            ? payload.message
+            : "message send failed";
+        fail(new MessageSendError(traceId, code, hint, ack.chat_id));
         return;
       }
       if (ack.event !== "message.ack") return;
@@ -491,14 +497,19 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
       && params.replyCtx.replyPreviewNickName
       && params.replyCtx.replyPreviewText,
   );
-  const messageId = params.messageId;
+  // Outbound message_id is ALWAYS present (at-least-once delivery, protocol
+  // §3.1.9): the server's inbox UNIQUE(recipient, message_id) absorbs a
+  // bounded resend of the same frame as one coalesced row. A bounded resend
+  // (non-terminal socket close → re-enqueue of the same captured wire) reuses
+  // this exact id, so a duplicate write is deduped rather than fanned out.
+  const messageId = params.messageId ?? mintMessageId();
 
   let ack: Envelope<MessageAckPayload>;
   let mode: "send" | "reply";
   if (useReply && params.replyCtx) {
     mode = "reply";
     const payload = {
-      ...(messageId ? { message_id: messageId } : {}),
+      message_id: messageId,
       message_mode: "normal",
       message: {
         body: { fragments },
@@ -532,7 +543,7 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
         }
       : null;
     const payload = {
-      ...(messageId ? { message_id: messageId } : {}),
+      message_id: messageId,
       message_mode: "normal",
       message: {
         body: { fragments },
@@ -548,7 +559,7 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
       ...(params.log ? { log: params.log } : {}),
     });
   }
-  if (messageId && ack.payload.message_id !== messageId) {
+  if (ack.payload.message_id !== messageId) {
     throw new Error(
       `ack message_id mismatch: expected ${messageId} got ${ack.payload.message_id}`,
     );
@@ -638,8 +649,35 @@ export async function sendOpenclawClawlingMedia(
 
 type OutboundClaimStore = Pick<ClawChatStore, "claimMessageOnce" | "markMessageAcknowledged">;
 
-function mintOutboundMessageId(account: ResolvedOpenclawClawlingAccount): string {
-  return `${account.userId}-msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+// Crockford base32 alphabet (ULID spec).
+const ULID_ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+/**
+ * Generate a Canonical ULID: 10 chars of millisecond timestamp + 16 chars of
+ * randomness, Crockford base32, 26 chars total. Implemented locally (no extra
+ * dependency) because this repo has no ULID dep and only needs minting, not
+ * monotonic ordering or decoding.
+ */
+function ulid(now: number = Date.now()): string {
+  let time = now;
+  const out = new Array<string>(26);
+  for (let i = 9; i >= 0; i--) {
+    out[i] = ULID_ENCODING[time % 32]!;
+    time = Math.floor(time / 32);
+  }
+  for (let i = 10; i < 26; i++) {
+    out[i] = ULID_ENCODING[randomInt(0, 32)]!;
+  }
+  return out.join("");
+}
+
+/** Client-minted message id: `msg-` + ULID (protocol §7.6 format contract). */
+export function mintMessageId(): string {
+  return `msg-${ulid()}`;
+}
+
+function mintOutboundMessageId(_account: ResolvedOpenclawClawlingAccount): string {
+  return mintMessageId();
 }
 
 function resolveChannelOutboundStore(): OutboundClaimStore | null {