@clawling/clawchat-plugin-openclaw 2026.8.14-1 → 2026.8.20-1

package/dist/src/api-client.js

@@ -153,8 +153,13 @@ export function createOpenclawClawlingApiClient(opts) {
         // `X-Device-Id` is sent on every request so the server can correlate
         // activity back to this plugin instance. Callers may override via
         // `extra` (e.g. tests) but the default is the channel id.
+        //
+        // A blank token gets NO Authorization header at all: `Bearer ` with an
+        // empty credential is a zero-segment JWT that the backend logs as
+        // malformed-token 401 noise (the unauthenticated plugin-report call sent
+        // one on every gateway entry).
         return {
-            authorization: `Bearer ${opts.token}`,
+            ...(opts.token.trim() ? { authorization: `Bearer ${opts.token}` } : {}),
             "x-device-id": CHANNEL_ID,
             ...extra,
         };

package/dist/src/config.js

@@ -221,6 +221,28 @@ function decodeJwtStringClaim(token, claim) {
  * wins; the mismatch is logged. Also derives userId from `sub` when nothing is
  * configured, mirroring the `oid` fallback above.
  */
+/**
+ * Reject an ownerUserId that is an unrendered provisioning-template
+ * placeholder — treat it as absent (fall through to the next source) instead
+ * of using it verbatim.
+ *
+ * 2026-08 production incident: a provisioner shipped the literal `usr_owner`
+ * (this repo's own test-fixture value) un-rendered; every affected agent
+ * passed the connect gate and hammered prod with `GET /v1/users/usr_owner`
+ * plus malformed-JWT retries for days. Dev/mock ids stay loose on purpose —
+ * only the known fixture literal and unmistakable template syntax
+ * ({{…}}, ${…}, <…>, %…%) are rejected.
+ */
+function rejectPlaceholderOwnerUserId(value, source) {
+    if (!value)
+        return "";
+    const looksUnrendered = value === "usr_owner" || /[{}<>%]|\$\{/.test(value);
+    if (looksUnrendered) {
+        console.warn(`clawchat ownerUserId from ${source} looks like an unrendered template placeholder ("${value}"); ignoring it. Fix the provisioning template — without a real owner id (or an oid claim in the token) the agent stays in activation-wait instead of hammering the backend.`);
+        return "";
+    }
+    return value;
+}
 function resolveUserId(token, configured) {
     const tokenSub = decodeJwtStringClaim(token, "sub");
     if (!tokenSub)
@@ -336,8 +358,8 @@ export function resolveOpenclawClawlingAccount(cfg, env = process.env) {
     const token = readOptionalString(channel.token) || readEnvString(env, CLAWCHAT_TOKEN_ENV);
     const agentId = readOptionalString(channel.agentId) || readEnvString(env, CLAWCHAT_AGENT_ID_ENV);
     const userId = resolveUserId(token, readOptionalString(channel.userId) || readEnvString(env, CLAWCHAT_USER_ID_ENV));
-    const ownerUserId = readOptionalString(channel.ownerUserId) ||
-        readEnvString(env, CLAWCHAT_OWNER_USER_ID_ENV) ||
+    const ownerUserId = rejectPlaceholderOwnerUserId(readOptionalString(channel.ownerUserId), "channel ownerUserId") ||
+        rejectPlaceholderOwnerUserId(readEnvString(env, CLAWCHAT_OWNER_USER_ID_ENV), CLAWCHAT_OWNER_USER_ID_ENV) ||
         // Fall back to the access token's `oid` (owner) claim. A provisioner may
         // inject token + userId but omit ownerUserId; without it the connect gate
         // (hasOpenclawClawlingConnectCredentials) never passes and the plugin sits

package/dist/src/media-runtime.js

@@ -1,4 +1,5 @@
 import { buildOutboundMediaLoadOptions, } from "openclaw/plugin-sdk/media-runtime";
+import { ClawlingApiError } from "./api-types.js";
 export function inferMediaKindFromMime(mime) {
     if (!mime)
         return "file";
@@ -10,7 +11,178 @@ export function inferMediaKindFromMime(mime) {
         return "video";
     return "file";
 }
-const DEFAULT_MEDIA_MAX_BYTES = 20 * 1024 * 1024;
+/**
+ * Single-file ceiling of the upstream msghub media service — its
+ * `media.max_size_bytes` is `104857600` in every shipped upstream config, and a
+ * larger body is rejected with HTTP 413 / business code `41301`. The plugin
+ * mirrors the server capability rather than under-reporting it: a lower local
+ * cap silently fails attachments the service would accept.
+ */
+export const CLAWCHAT_MEDIA_MAX_BYTES = 100 * 1024 * 1024;
+const DEFAULT_MEDIA_MAX_BYTES = CLAWCHAT_MEDIA_MAX_BYTES;
+/** Three attempts per attachment = the initial upload plus two backoff retries. */
+export const DEFAULT_UPLOAD_RETRY_POLICY = {
+    maxAttempts: 3,
+    baseDelayMs: 300,
+    maxDelayMs: 2_000,
+};
+/** Bounded exponential backoff for the wait AFTER 1-based `attempt`. */
+export function uploadRetryDelayMs(attempt, policy = DEFAULT_UPLOAD_RETRY_POLICY) {
+    return Math.min(policy.baseDelayMs * 2 ** Math.max(0, attempt - 1), policy.maxDelayMs);
+}
+/**
+ * Media-service business codes that reject THIS payload on its merits:
+ * missing file part, empty upload, bad token, too large, disallowed MIME.
+ * Re-sending identical bytes produces an identical rejection, so these never
+ * retry regardless of status.
+ */
+const PERMANENT_BUSINESS_CODES = new Set([40001, 40002, 40101, 41301, 41501]);
+/**
+ * Socket/DNS/timeout signatures for throws that never made it through the API
+ * client's own wrapping (e.g. an `AbortError` surfaced by the host fetch).
+ */
+const TRANSIENT_ERROR_PATTERN = /(econnreset|econnrefused|econnaborted|etimedout|epipe|ehostunreach|enetunreach|enetdown|eai_again|enotfound|socket hang up|network error|fetch failed|timed out|timeout|aborted)/i;
+function isRetryableHttpStatus(status) {
+    // 408 request timeout, 425 too early, 429 rate limited, plus every 5xx.
+    return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+const API_ERROR_KINDS = ["auth", "api", "transport", "validation"];
+function asClawlingApiError(err) {
+    if (err instanceof ClawlingApiError)
+        return err;
+    // Structural fallback: a duck-typed error from a mocked client still carries
+    // the diagnostics we must log, and misreading it as `unknown` would lose them.
+    if (err instanceof Error &&
+        API_ERROR_KINDS.includes(err.kind)) {
+        return err;
+    }
+    return undefined;
+}
+function isRetryableFailure(detail) {
+    // Local pre-flight failures and credential rejections do not get better by
+    // trying again with the same bytes and the same token.
+    if (detail.kind === "validation" || detail.kind === "auth")
+        return false;
+    if (typeof detail.code === "number" && PERMANENT_BUSINESS_CODES.has(detail.code))
+        return false;
+    if (typeof detail.status === "number")
+        return isRetryableHttpStatus(detail.status);
+    // `transport` without a status is a failure before any response existed —
+    // DNS, connection reset, timeout: the transient case this retry loop is for.
+    if (detail.kind === "transport")
+        return true;
+    // `api` without a status is a server-declared business rejection.
+    return false;
+}
+/** Classify a thrown upload error into structured diagnostics + a retry verdict. */
+export function classifyUploadError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const api = asClawlingApiError(err);
+    if (!api) {
+        return { kind: "unknown", message, retryable: TRANSIENT_ERROR_PATTERN.test(message) };
+    }
+    const detail = {
+        kind: api.kind,
+        message,
+        retryable: false,
+        ...(typeof api.meta?.status === "number" ? { status: api.meta.status } : {}),
+        ...(typeof api.meta?.code === "number" ? { code: api.meta.code } : {}),
+        ...(api.meta?.path ? { path: api.meta.path } : {}),
+        ...(api.meta?.data !== undefined ? { data: api.meta.data } : {}),
+    };
+    detail.retryable = isRetryableFailure(detail);
+    return detail;
+}
+const BEARER_PATTERN = /\b(bearer)\s+[A-Za-z0-9._~+/=-]+/gi;
+const JWT_PATTERN = /\beyJ[A-Za-z0-9._~+/=-]{10,}/g;
+const SECRET_FIELD_PATTERN = /("?\b(?:authorization|access[_-]?token|refresh[_-]?token|token|api[_-]?key|apikey|password|passwd|secret|signature|x-amz-signature|x-amz-credential)\b"?\s*[:=]\s*)"?[^"',\s&}]+"?/gi;
+/**
+ * Strip anything credential-shaped out of a diagnostic string. Upload failures
+ * are logged with the server's `msg`/`data` verbatim, and neither is under this
+ * plugin's control — a backend that echoes a header or a presigned URL must not
+ * turn a log line into a token leak.
+ */
+export function redactMediaDiagnostics(text) {
+    return text
+        .replace(BEARER_PATTERN, "$1 [redacted]")
+        .replace(SECRET_FIELD_PATTERN, '$1"[redacted]"')
+        .replace(JWT_PATTERN, "[redacted]");
+}
+/**
+ * Reduce an outbound media source to something safe to log: presigned HTTP(S)
+ * URLs carry their credential in the query string, so only origin + path
+ * survive. Local paths are kept (they are the only way to identify the
+ * attachment) but never their contents.
+ */
+export function sanitizeMediaSource(source) {
+    try {
+        const parsed = new URL(source);
+        if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+            const trimmed = `${parsed.origin}${parsed.pathname}`;
+            return parsed.search || parsed.hash ? `${trimmed} (query redacted)` : trimmed;
+        }
+    }
+    catch {
+        // Not a URL — a local path. Fall through to plain redaction.
+    }
+    return redactMediaDiagnostics(source);
+}
+function serializeDiagnosticValue(value, limit = 300) {
+    let text;
+    try {
+        text = typeof value === "string" ? value : (JSON.stringify(value) ?? String(value));
+    }
+    catch {
+        text = "[unserializable]";
+    }
+    const redacted = redactMediaDiagnostics(text);
+    return redacted.length > limit ? `${redacted.slice(0, limit)}…` : redacted;
+}
+/**
+ * Render a failure as `key=value` diagnostics: error kind, HTTP status,
+ * business code, request path, response data, plus file name / size / MIME.
+ * Everything passes through {@link redactMediaDiagnostics} first — no token,
+ * `Authorization` header, or local file content ever reaches a log line.
+ */
+export function formatOutboundMediaFailure(failure) {
+    const { detail } = failure;
+    return [
+        `source=${failure.source}`,
+        ...(failure.fileName ? [`file=${serializeDiagnosticValue(failure.fileName, 120)}`] : []),
+        ...(typeof failure.size === "number" ? [`size=${failure.size}`] : []),
+        ...(failure.mime ? [`mime=${failure.mime}`] : []),
+        `stage=${failure.stage}`,
+        `attempts=${failure.attempts}`,
+        `retryable=${detail.retryable}`,
+        `kind=${detail.kind}`,
+        ...(typeof detail.status === "number" ? [`status=${detail.status}`] : []),
+        ...(typeof detail.code === "number" ? [`code=${detail.code}`] : []),
+        ...(detail.path ? [`path=${detail.path}`] : []),
+        ...(detail.data !== undefined ? [`data=${serializeDiagnosticValue(detail.data)}`] : []),
+        `error=${serializeDiagnosticValue(detail.message)}`,
+    ].join(" ");
+}
+function buildFailure(input) {
+    const failure = { ...input, summary: "" };
+    failure.summary = formatOutboundMediaFailure(failure);
+    return failure;
+}
+/**
+ * Build the send-blocking error message for a batch that lost attachments.
+ *
+ * Both call sites (the `sendMedia` adapter and the reply dispatcher) reject the
+ * whole send on a shortfall, so this is the only text the agent sees: it must
+ * name every failed attachment with its reason instead of a generic
+ * "upload failed" that leaves the operator with nothing to act on.
+ */
+export function describeOutboundMediaShortfall(result, requested) {
+    const missing = Math.max(requested - result.fragments.length, result.failures.length);
+    const outcome = result.fragments.length > 0 ? "partial success" : "all failed";
+    const reasons = result.failures.map((f, i) => `[${i + 1}] ${f.summary}`).join(" | ");
+    return (`clawchat-plugin-openclaw failed to upload ${missing}/${requested} outbound media ` +
+        `attachment(s) (${outcome}, ${result.fragments.length}/${requested} uploaded); ` +
+        `message not sent${reasons ? `: ${reasons}` : ""}`);
+}
 /**
  * Fetch each remote URL via the shared media runtime, persist to a local
  * cache, and return the list of local paths.
@@ -33,53 +205,113 @@ export async function fetchInboundMedia(items, ctx) {
             paths.push(saved.path);
         }
         catch (err) {
-            ctx.log?.info?.(`clawchat-plugin-openclaw inbound media skipped: ${item.url} (${err instanceof Error ? err.message : String(err)})`);
+            ctx.log?.info?.(`clawchat-plugin-openclaw inbound media skipped: ${sanitizeMediaSource(item.url)} (${redactMediaDiagnostics(err instanceof Error ? err.message : String(err))})`);
         }
     }
     return paths;
 }
 /**
  * Upload each URL (remote or local path) to /media/upload via the api
- * client and return a fragment ready to splice into `body.fragments`.
+ * client and return fragments ready to splice into `body.fragments`, plus a
+ * structured failure record for every attachment that did not make it.
  *
  * Uses the host runtime's `runtime.media.loadWebMedia`, so local-root
  * enforcement and media-loading policy stay aligned with the current
  * OpenClaw runtime instead of a directly imported helper.
  *
- * Single-upload failures log at error and are dropped; the remaining
- * fragments still come back so a partially-failing batch still sends the
- * working media.
+ * Transient upload faults (network/timeout, HTTP 5xx, 429/408) are retried
+ * with bounded exponential backoff per {@link DEFAULT_UPLOAD_RETRY_POLICY};
+ * local validation, auth, and definitive business rejections fail on the first
+ * attempt. One attachment giving up never aborts the batch — every remaining
+ * URL is still loaded and uploaded, and its fragment comes back — so the
+ * caller can distinguish partial success from a total failure and report why.
  */
 export async function uploadOutboundMedia(urls, ctx) {
+    const result = { fragments: [], failures: [] };
     if (urls.length === 0)
-        return [];
+        return result;
     const maxBytes = ctx.maxBytes ?? DEFAULT_MEDIA_MAX_BYTES;
-    const out = [];
+    const policy = { ...DEFAULT_UPLOAD_RETRY_POLICY, ...(ctx.retry ?? {}) };
+    const sleep = ctx.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     for (const url of urls) {
+        const source = sanitizeMediaSource(url);
+        let loaded;
         try {
-            const loaded = await ctx.runtime.media.loadWebMedia(url, buildOutboundMediaLoadOptions({
+            loaded = await ctx.runtime.media.loadWebMedia(url, buildOutboundMediaLoadOptions({
                 maxBytes,
                 ...(ctx.mediaAccess ? { mediaAccess: ctx.mediaAccess } : {}),
                 ...(ctx.mediaLocalRoots ? { mediaLocalRoots: ctx.mediaLocalRoots } : {}),
                 ...(ctx.mediaReadFile ? { mediaReadFile: ctx.mediaReadFile } : {}),
             }));
-            const uploaded = await ctx.apiClient.uploadMedia({
-                buffer: loaded.buffer,
-                filename: loaded.fileName ?? "upload.bin",
-                mime: loaded.contentType,
-            });
-            const fragment = {
-                kind: uploaded.kind,
-                url: uploaded.url,
-                name: uploaded.name,
-                mime: uploaded.mime,
-                size: uploaded.size,
-            };
-            out.push(fragment);
         }
         catch (err) {
-            ctx.log?.error?.(`clawchat-plugin-openclaw outbound media upload failed: ${url} (${err instanceof Error ? err.message : String(err)})`);
+            // Loading is host policy plus a one-shot read (missing path, outside the
+            // allowed roots, over `maxBytes`). Nothing here is transient, so it is
+            // never retried — and the bytes never reached the media service.
+            const failure = buildFailure({
+                source,
+                stage: "load",
+                attempts: 1,
+                detail: { ...classifyUploadError(err), retryable: false },
+            });
+            result.failures.push(failure);
+            ctx.log?.error?.(`clawchat-plugin-openclaw outbound media load failed: ${failure.summary}`);
+            continue;
+        }
+        const fileName = loaded.fileName ?? "upload.bin";
+        const size = loaded.buffer.byteLength;
+        const mime = loaded.contentType;
+        let pending;
+        let attempts = 0;
+        for (let attempt = 1; attempt <= policy.maxAttempts; attempt += 1) {
+            attempts = attempt;
+            try {
+                const uploaded = await ctx.apiClient.uploadMedia({
+                    buffer: loaded.buffer,
+                    filename: fileName,
+                    ...(mime ? { mime } : {}),
+                });
+                result.fragments.push({
+                    kind: uploaded.kind,
+                    url: uploaded.url,
+                    name: uploaded.name,
+                    mime: uploaded.mime,
+                    size: uploaded.size,
+                });
+                pending = undefined;
+                break;
+            }
+            catch (err) {
+                pending = classifyUploadError(err);
+                if (!pending.retryable || attempt >= policy.maxAttempts)
+                    break;
+                const delayMs = uploadRetryDelayMs(attempt, policy);
+                const attemptFailure = buildFailure({
+                    source,
+                    stage: "upload",
+                    attempts: attempt,
+                    fileName,
+                    size,
+                    ...(mime ? { mime } : {}),
+                    detail: pending,
+                });
+                ctx.log?.info?.(`clawchat-plugin-openclaw outbound media upload retry ${attempt}/${policy.maxAttempts - 1} in ${delayMs}ms: ${attemptFailure.summary}`);
+                await sleep(delayMs);
+            }
+        }
+        if (pending) {
+            const failure = buildFailure({
+                source,
+                stage: "upload",
+                attempts,
+                fileName,
+                size,
+                ...(mime ? { mime } : {}),
+                detail: pending,
+            });
+            result.failures.push(failure);
+            ctx.log?.error?.(`clawchat-plugin-openclaw outbound media upload failed: ${failure.summary}`);
         }
     }
-    return out;
+    return result;
 }

package/dist/src/outbound.js

@@ -6,7 +6,7 @@ import { chunkMarkdownText } from "openclaw/plugin-sdk/reply-runtime";
 import { createOpenclawClawlingApiClient } from "./api-client.js";
 import { CHANNEL_ID, resolveOpenclawClawlingAccount } from "./config.js";
 import { applyTextMentionLabels, buildMentionMessageFragments, normalizeMentionTargets, textToFragments, } from "./message-mapper.js";
-import { uploadOutboundMedia } from "./media-runtime.js";
+import { describeOutboundMediaShortfall, uploadOutboundMedia, } from "./media-runtime.js";
 import { isClawChatNoopResponseText } from "./profile-prompt.js";
 import { stripNoReplyTokens } from "./no-reply.js";
 import { getOpenclawClawlingClient, getOpenclawClawlingRuntime, waitForOpenclawClawlingClient, } from "./runtime.js";
@@ -723,16 +723,20 @@ export const openclawClawlingOutbound = {
                 token: account.token,
                 userId: account.userId,
             });
-            const mediaFragments = await uploadOutboundMedia([mediaUrl.trim()], {
+            const uploadResult = await uploadOutboundMedia([mediaUrl.trim()], {
                 apiClient,
                 runtime,
                 ...(mediaAccess ? { mediaAccess } : {}),
                 ...(mediaLocalRoots ? { mediaLocalRoots } : {}),
                 ...(mediaReadFile ? { mediaReadFile } : {}),
             });
-            if (mediaFragments.length === 0) {
-                throw new Error(`clawchat-plugin-openclaw failed to upload media: ${mediaUrl}`);
+            // Single-attachment path, so "shortfall" is always a total failure here;
+            // the message still carries the structured, redacted reason instead of a
+            // bare "failed to upload" the operator cannot act on.
+            if (uploadResult.fragments.length === 0) {
+                throw new Error(describeOutboundMediaShortfall(uploadResult, 1));
             }
+            const mediaFragments = uploadResult.fragments;
             const target = parseOpenclawRecipient(to);
             const messageId = mintOutboundMessageId(account);
             const claimText = (text ?? "").trim();

package/dist/src/reply-dispatcher.js

@@ -2,7 +2,7 @@ import { interactiveReplyToPresentation, renderMessagePresentationFallbackText,
 import { resolveOutboundMediaUrls } from "openclaw/plugin-sdk/reply-payload";
 import { createOpenclawClawlingApiClient } from "./api-client.js";
 import { effectiveOutputVisibility, } from "./config.js";
-import { uploadOutboundMedia } from "./media-runtime.js";
+import { describeOutboundMediaShortfall, uploadOutboundMedia, } from "./media-runtime.js";
 import { mintMessageId, sendOpenclawClawlingText, } from "./outbound.js";
 import { isClawChatNoopResponseText } from "./profile-prompt.js";
 import { consumeTerminalClawChatSend } from "./terminal-send.js";
@@ -293,15 +293,19 @@ export function createOpenclawClawlingReplyDispatcher(options) {
             log?.info?.(`[${account.accountId}] clawchat-plugin-openclaw outbound media skipped: baseUrl not configured`);
             return [];
         }
-        const fragments = await uploadOutboundMedia(urls, { apiClient, runtime, log });
-        if (fragments.length < urls.length) {
-            // uploadOutboundMedia drops a failed item with only a log line. A shortfall
-            // means an attachment never reached the media service; surfacing it (parity
-            // with the adapter path in outbound.ts and with the Hermes plugin) stops a
-            // text-only frame from going out and reading as a successful send.
-            throw new Error(`clawchat-plugin-openclaw failed to upload ${urls.length - fragments.length}/${urls.length} outbound media attachment(s); message not sent`);
+        const result = await uploadOutboundMedia(urls, { apiClient, runtime, log });
+        if (result.fragments.length < urls.length) {
+            // uploadOutboundMedia never aborts the batch: every URL is attempted and
+            // the successful fragments still come back. A shortfall — partial success
+            // or total failure alike — means at least one attachment never reached
+            // the media service, so the whole send is rejected (parity with the
+            // adapter path in outbound.ts and with the Hermes plugin) rather than
+            // letting a text-only frame go out reading as a successful send. The
+            // thrown message carries each failure's structured, redacted diagnostics
+            // so the agent is not left with a reasonless generic error.
+            throw new Error(describeOutboundMediaShortfall(result, urls.length));
         }
-        return fragments;
+        return result.fragments;
     }
     // ----- Reply state ------------------------------------------------------
     let reasoningText = "";

package/dist/src/runtime.js

@@ -16,7 +16,7 @@ import { CHANNEL_ID, effectiveOutputVisibility, effectiveGroupCommandMode, effec
 import { isValidChatId } from "./ws-client.js";
 import { dispatchOpenclawClawlingInbound } from "./inbound.js";
 import { PendingConsentStore, cleanupTombstonedManagedSkills, handleOwnerConsentReply, managedSkillExists, readLocalSkillState, resolveBundledSkillsDir, resolveManagedSkillsDir, runSkillUpdateCheck, } from "./skill-update.js";
-import { fetchInboundMedia } from "./media-runtime.js";
+import { CLAWCHAT_MEDIA_MAX_BYTES, fetchInboundMedia } from "./media-runtime.js";
 import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.js";
 import { runWithTerminalClawChatSendScope } from "./terminal-send.js";
 import { flushAlignedOutboundQueue, getAlignedOutboundQueueSize, sendOpenclawClawlingText, setAlignedOutboundLogContext, } from "./outbound.js";
@@ -2440,7 +2440,7 @@ export async function startOpenclawClawlingGateway(params) {
             ? await fetchInboundMedia(turn.mediaItems, {
                 runtime,
                 log,
-                maxBytes: 20 * 1024 * 1024,
+                maxBytes: CLAWCHAT_MEDIA_MAX_BYTES,
             })
             : [];
         if (inboundPaths.length > 0) {

package/package.json

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

package/src/api-client.ts

@@ -337,8 +337,13 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
     // `X-Device-Id` is sent on every request so the server can correlate
     // activity back to this plugin instance. Callers may override via
     // `extra` (e.g. tests) but the default is the channel id.
+    //
+    // A blank token gets NO Authorization header at all: `Bearer ` with an
+    // empty credential is a zero-segment JWT that the backend logs as
+    // malformed-token 401 noise (the unauthenticated plugin-report call sent
+    // one on every gateway entry).
     return {
-      authorization: `Bearer ${opts.token}`,
+      ...(opts.token.trim() ? { authorization: `Bearer ${opts.token}` } : {}),
       "x-device-id": CHANNEL_ID,
       ...extra,
     };

package/src/config.ts

@@ -349,6 +349,30 @@ function decodeJwtStringClaim(token: string, claim: string): string {
  * wins; the mismatch is logged. Also derives userId from `sub` when nothing is
  * configured, mirroring the `oid` fallback above.
  */
+/**
+ * Reject an ownerUserId that is an unrendered provisioning-template
+ * placeholder — treat it as absent (fall through to the next source) instead
+ * of using it verbatim.
+ *
+ * 2026-08 production incident: a provisioner shipped the literal `usr_owner`
+ * (this repo's own test-fixture value) un-rendered; every affected agent
+ * passed the connect gate and hammered prod with `GET /v1/users/usr_owner`
+ * plus malformed-JWT retries for days. Dev/mock ids stay loose on purpose —
+ * only the known fixture literal and unmistakable template syntax
+ * ({{…}}, ${…}, <…>, %…%) are rejected.
+ */
+function rejectPlaceholderOwnerUserId(value: string, source: string): string {
+  if (!value) return "";
+  const looksUnrendered = value === "usr_owner" || /[{}<>%]|\$\{/.test(value);
+  if (looksUnrendered) {
+    console.warn(
+      `clawchat ownerUserId from ${source} looks like an unrendered template placeholder ("${value}"); ignoring it. Fix the provisioning template — without a real owner id (or an oid claim in the token) the agent stays in activation-wait instead of hammering the backend.`,
+    );
+    return "";
+  }
+  return value;
+}
+
 function resolveUserId(token: string, configured: string): string {
   const tokenSub = decodeJwtStringClaim(token, "sub");
   if (!tokenSub) return configured;
@@ -498,8 +522,11 @@ export function resolveOpenclawClawlingAccount(
     readOptionalString(channel.userId) || readEnvString(env, CLAWCHAT_USER_ID_ENV),
   );
   const ownerUserId =
-    readOptionalString(channel.ownerUserId) ||
-    readEnvString(env, CLAWCHAT_OWNER_USER_ID_ENV) ||
+    rejectPlaceholderOwnerUserId(readOptionalString(channel.ownerUserId), "channel ownerUserId") ||
+    rejectPlaceholderOwnerUserId(
+      readEnvString(env, CLAWCHAT_OWNER_USER_ID_ENV),
+      CLAWCHAT_OWNER_USER_ID_ENV,
+    ) ||
     // Fall back to the access token's `oid` (owner) claim. A provisioner may
     // inject token + userId but omit ownerUserId; without it the connect gate
     // (hasOpenclawClawlingConnectCredentials) never passes and the plugin sits

package/src/media-runtime.ts

@@ -5,6 +5,7 @@ import {
   type OutboundMediaReadFile,
 } from "openclaw/plugin-sdk/media-runtime";
 import type { OpenclawClawlingApiClient } from "./api-client.ts";
+import { ClawlingApiError, type ClawlingApiErrorKind } from "./api-types.ts";
 
 /**
  * Local structural superset of the protocol media fragment narrow types.
@@ -50,6 +51,10 @@ export interface UploadOutboundCtx {
   mediaLocalRoots?: readonly string[] | "any";
   /** Host-provided read bridge for sandbox/allowed local media paths. */
   mediaReadFile?: OutboundMediaReadFile;
+  /** Overrides for the transient-failure retry budget. Merged over the default policy. */
+  retry?: Partial<UploadRetryPolicy>;
+  /** Test seam for the backoff wait. Defaults to `setTimeout`. */
+  sleep?: (ms: number) => Promise<void>;
 }
 
 export function inferMediaKindFromMime(mime: string | undefined): MediaItem["kind"] {
@@ -60,7 +65,250 @@ export function inferMediaKindFromMime(mime: string | undefined): MediaItem["kin
   return "file";
 }
 
-const DEFAULT_MEDIA_MAX_BYTES = 20 * 1024 * 1024;
+/**
+ * Single-file ceiling of the upstream msghub media service — its
+ * `media.max_size_bytes` is `104857600` in every shipped upstream config, and a
+ * larger body is rejected with HTTP 413 / business code `41301`. The plugin
+ * mirrors the server capability rather than under-reporting it: a lower local
+ * cap silently fails attachments the service would accept.
+ */
+export const CLAWCHAT_MEDIA_MAX_BYTES = 100 * 1024 * 1024;
+
+const DEFAULT_MEDIA_MAX_BYTES = CLAWCHAT_MEDIA_MAX_BYTES;
+
+export interface UploadRetryPolicy {
+  /** Total attempts per attachment, including the first one. */
+  maxAttempts: number;
+  /** Wait after the first failed attempt; doubled per further attempt. */
+  baseDelayMs: number;
+  /** Upper bound on any single wait, so the backoff stays bounded. */
+  maxDelayMs: number;
+}
+
+/** Three attempts per attachment = the initial upload plus two backoff retries. */
+export const DEFAULT_UPLOAD_RETRY_POLICY: UploadRetryPolicy = {
+  maxAttempts: 3,
+  baseDelayMs: 300,
+  maxDelayMs: 2_000,
+};
+
+/** Bounded exponential backoff for the wait AFTER 1-based `attempt`. */
+export function uploadRetryDelayMs(
+  attempt: number,
+  policy: UploadRetryPolicy = DEFAULT_UPLOAD_RETRY_POLICY,
+): number {
+  return Math.min(policy.baseDelayMs * 2 ** Math.max(0, attempt - 1), policy.maxDelayMs);
+}
+
+/** Structured, credential-free diagnostics for one failed upload attempt. */
+export interface UploadErrorDetail {
+  /** `ClawlingApiError.kind`, or `"unknown"` for a non-API throw. */
+  kind: ClawlingApiErrorKind | "unknown";
+  /** HTTP status, when the failure carried a response. */
+  status?: number;
+  /** Business `code` from the `{ code, msg, data }` envelope. */
+  code?: number;
+  /** Request path the failure came from (e.g. `/media/upload`). */
+  path?: string;
+  /** Response `data` payload, when the envelope carried one. */
+  data?: unknown;
+  message: string;
+  retryable: boolean;
+}
+
+/**
+ * Media-service business codes that reject THIS payload on its merits:
+ * missing file part, empty upload, bad token, too large, disallowed MIME.
+ * Re-sending identical bytes produces an identical rejection, so these never
+ * retry regardless of status.
+ */
+const PERMANENT_BUSINESS_CODES = new Set([40001, 40002, 40101, 41301, 41501]);
+
+/**
+ * Socket/DNS/timeout signatures for throws that never made it through the API
+ * client's own wrapping (e.g. an `AbortError` surfaced by the host fetch).
+ */
+const TRANSIENT_ERROR_PATTERN =
+  /(econnreset|econnrefused|econnaborted|etimedout|epipe|ehostunreach|enetunreach|enetdown|eai_again|enotfound|socket hang up|network error|fetch failed|timed out|timeout|aborted)/i;
+
+function isRetryableHttpStatus(status: number): boolean {
+  // 408 request timeout, 425 too early, 429 rate limited, plus every 5xx.
+  return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+
+const API_ERROR_KINDS: readonly string[] = ["auth", "api", "transport", "validation"];
+
+function asClawlingApiError(err: unknown): ClawlingApiError | undefined {
+  if (err instanceof ClawlingApiError) return err;
+  // Structural fallback: a duck-typed error from a mocked client still carries
+  // the diagnostics we must log, and misreading it as `unknown` would lose them.
+  if (
+    err instanceof Error &&
+    API_ERROR_KINDS.includes((err as { kind?: unknown }).kind as string)
+  ) {
+    return err as ClawlingApiError;
+  }
+  return undefined;
+}
+
+function isRetryableFailure(detail: UploadErrorDetail): boolean {
+  // Local pre-flight failures and credential rejections do not get better by
+  // trying again with the same bytes and the same token.
+  if (detail.kind === "validation" || detail.kind === "auth") return false;
+  if (typeof detail.code === "number" && PERMANENT_BUSINESS_CODES.has(detail.code)) return false;
+  if (typeof detail.status === "number") return isRetryableHttpStatus(detail.status);
+  // `transport` without a status is a failure before any response existed —
+  // DNS, connection reset, timeout: the transient case this retry loop is for.
+  if (detail.kind === "transport") return true;
+  // `api` without a status is a server-declared business rejection.
+  return false;
+}
+
+/** Classify a thrown upload error into structured diagnostics + a retry verdict. */
+export function classifyUploadError(err: unknown): UploadErrorDetail {
+  const message = err instanceof Error ? err.message : String(err);
+  const api = asClawlingApiError(err);
+  if (!api) {
+    return { kind: "unknown", message, retryable: TRANSIENT_ERROR_PATTERN.test(message) };
+  }
+  const detail: UploadErrorDetail = {
+    kind: api.kind,
+    message,
+    retryable: false,
+    ...(typeof api.meta?.status === "number" ? { status: api.meta.status } : {}),
+    ...(typeof api.meta?.code === "number" ? { code: api.meta.code } : {}),
+    ...(api.meta?.path ? { path: api.meta.path } : {}),
+    ...(api.meta?.data !== undefined ? { data: api.meta.data } : {}),
+  };
+  detail.retryable = isRetryableFailure(detail);
+  return detail;
+}
+
+const BEARER_PATTERN = /\b(bearer)\s+[A-Za-z0-9._~+/=-]+/gi;
+const JWT_PATTERN = /\beyJ[A-Za-z0-9._~+/=-]{10,}/g;
+const SECRET_FIELD_PATTERN =
+  /("?\b(?:authorization|access[_-]?token|refresh[_-]?token|token|api[_-]?key|apikey|password|passwd|secret|signature|x-amz-signature|x-amz-credential)\b"?\s*[:=]\s*)"?[^"',\s&}]+"?/gi;
+
+/**
+ * Strip anything credential-shaped out of a diagnostic string. Upload failures
+ * are logged with the server's `msg`/`data` verbatim, and neither is under this
+ * plugin's control — a backend that echoes a header or a presigned URL must not
+ * turn a log line into a token leak.
+ */
+export function redactMediaDiagnostics(text: string): string {
+  return text
+    .replace(BEARER_PATTERN, "$1 [redacted]")
+    .replace(SECRET_FIELD_PATTERN, '$1"[redacted]"')
+    .replace(JWT_PATTERN, "[redacted]");
+}
+
+/**
+ * Reduce an outbound media source to something safe to log: presigned HTTP(S)
+ * URLs carry their credential in the query string, so only origin + path
+ * survive. Local paths are kept (they are the only way to identify the
+ * attachment) but never their contents.
+ */
+export function sanitizeMediaSource(source: string): string {
+  try {
+    const parsed = new URL(source);
+    if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+      const trimmed = `${parsed.origin}${parsed.pathname}`;
+      return parsed.search || parsed.hash ? `${trimmed} (query redacted)` : trimmed;
+    }
+  } catch {
+    // Not a URL — a local path. Fall through to plain redaction.
+  }
+  return redactMediaDiagnostics(source);
+}
+
+function serializeDiagnosticValue(value: unknown, limit = 300): string {
+  let text: string;
+  try {
+    text = typeof value === "string" ? value : (JSON.stringify(value) ?? String(value));
+  } catch {
+    text = "[unserializable]";
+  }
+  const redacted = redactMediaDiagnostics(text);
+  return redacted.length > limit ? `${redacted.slice(0, limit)}…` : redacted;
+}
+
+/** Which step of the outbound pipeline gave up on this attachment. */
+export type OutboundMediaFailureStage = "load" | "upload";
+
+export interface OutboundMediaFailure {
+  /** Redacted source URL / local path the attachment came from. */
+  source: string;
+  stage: OutboundMediaFailureStage;
+  /** Attempts actually made, including the first. */
+  attempts: number;
+  fileName?: string;
+  /** Byte length of the loaded payload. */
+  size?: number;
+  mime?: string;
+  detail: UploadErrorDetail;
+  /** One-line redacted diagnostic — the same text written to the error log. */
+  summary: string;
+}
+
+export interface OutboundMediaUploadResult {
+  /** Fragments for every attachment that uploaded successfully. */
+  fragments: ClawlingMediaFragment[];
+  /** One entry per attachment that did not, in request order. */
+  failures: OutboundMediaFailure[];
+}
+
+/**
+ * Render a failure as `key=value` diagnostics: error kind, HTTP status,
+ * business code, request path, response data, plus file name / size / MIME.
+ * Everything passes through {@link redactMediaDiagnostics} first — no token,
+ * `Authorization` header, or local file content ever reaches a log line.
+ */
+export function formatOutboundMediaFailure(failure: OutboundMediaFailure): string {
+  const { detail } = failure;
+  return [
+    `source=${failure.source}`,
+    ...(failure.fileName ? [`file=${serializeDiagnosticValue(failure.fileName, 120)}`] : []),
+    ...(typeof failure.size === "number" ? [`size=${failure.size}`] : []),
+    ...(failure.mime ? [`mime=${failure.mime}`] : []),
+    `stage=${failure.stage}`,
+    `attempts=${failure.attempts}`,
+    `retryable=${detail.retryable}`,
+    `kind=${detail.kind}`,
+    ...(typeof detail.status === "number" ? [`status=${detail.status}`] : []),
+    ...(typeof detail.code === "number" ? [`code=${detail.code}`] : []),
+    ...(detail.path ? [`path=${detail.path}`] : []),
+    ...(detail.data !== undefined ? [`data=${serializeDiagnosticValue(detail.data)}`] : []),
+    `error=${serializeDiagnosticValue(detail.message)}`,
+  ].join(" ");
+}
+
+function buildFailure(input: Omit<OutboundMediaFailure, "summary">): OutboundMediaFailure {
+  const failure: OutboundMediaFailure = { ...input, summary: "" };
+  failure.summary = formatOutboundMediaFailure(failure);
+  return failure;
+}
+
+/**
+ * Build the send-blocking error message for a batch that lost attachments.
+ *
+ * Both call sites (the `sendMedia` adapter and the reply dispatcher) reject the
+ * whole send on a shortfall, so this is the only text the agent sees: it must
+ * name every failed attachment with its reason instead of a generic
+ * "upload failed" that leaves the operator with nothing to act on.
+ */
+export function describeOutboundMediaShortfall(
+  result: OutboundMediaUploadResult,
+  requested: number,
+): string {
+  const missing = Math.max(requested - result.fragments.length, result.failures.length);
+  const outcome = result.fragments.length > 0 ? "partial success" : "all failed";
+  const reasons = result.failures.map((f, i) => `[${i + 1}] ${f.summary}`).join(" | ");
+  return (
+    `clawchat-plugin-openclaw failed to upload ${missing}/${requested} outbound media ` +
+    `attachment(s) (${outcome}, ${result.fragments.length}/${requested} uploaded); ` +
+    `message not sent${reasons ? `: ${reasons}` : ""}`
+  );
+}
 
 /**
  * Fetch each remote URL via the shared media runtime, persist to a local
@@ -92,7 +340,7 @@ export async function fetchInboundMedia(
       paths.push(saved.path);
     } catch (err) {
       ctx.log?.info?.(
-        `clawchat-plugin-openclaw inbound media skipped: ${item.url} (${err instanceof Error ? err.message : String(err)})`,
+        `clawchat-plugin-openclaw inbound media skipped: ${sanitizeMediaSource(item.url)} (${redactMediaDiagnostics(err instanceof Error ? err.message : String(err))})`,
       );
     }
   }
@@ -101,26 +349,34 @@ export async function fetchInboundMedia(
 
 /**
  * Upload each URL (remote or local path) to /media/upload via the api
- * client and return a fragment ready to splice into `body.fragments`.
+ * client and return fragments ready to splice into `body.fragments`, plus a
+ * structured failure record for every attachment that did not make it.
  *
  * Uses the host runtime's `runtime.media.loadWebMedia`, so local-root
  * enforcement and media-loading policy stay aligned with the current
  * OpenClaw runtime instead of a directly imported helper.
  *
- * Single-upload failures log at error and are dropped; the remaining
- * fragments still come back so a partially-failing batch still sends the
- * working media.
+ * Transient upload faults (network/timeout, HTTP 5xx, 429/408) are retried
+ * with bounded exponential backoff per {@link DEFAULT_UPLOAD_RETRY_POLICY};
+ * local validation, auth, and definitive business rejections fail on the first
+ * attempt. One attachment giving up never aborts the batch — every remaining
+ * URL is still loaded and uploaded, and its fragment comes back — so the
+ * caller can distinguish partial success from a total failure and report why.
  */
 export async function uploadOutboundMedia(
   urls: string[],
   ctx: UploadOutboundCtx,
-): Promise<ClawlingMediaFragment[]> {
-  if (urls.length === 0) return [];
+): Promise<OutboundMediaUploadResult> {
+  const result: OutboundMediaUploadResult = { fragments: [], failures: [] };
+  if (urls.length === 0) return result;
   const maxBytes = ctx.maxBytes ?? DEFAULT_MEDIA_MAX_BYTES;
-  const out: ClawlingMediaFragment[] = [];
+  const policy: UploadRetryPolicy = { ...DEFAULT_UPLOAD_RETRY_POLICY, ...(ctx.retry ?? {}) };
+  const sleep = ctx.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
   for (const url of urls) {
+    const source = sanitizeMediaSource(url);
+    let loaded: Awaited<ReturnType<PluginRuntime["media"]["loadWebMedia"]>>;
     try {
-      const loaded = await ctx.runtime.media.loadWebMedia(
+      loaded = await ctx.runtime.media.loadWebMedia(
         url,
         buildOutboundMediaLoadOptions({
           maxBytes,
@@ -129,24 +385,74 @@ export async function uploadOutboundMedia(
           ...(ctx.mediaReadFile ? { mediaReadFile: ctx.mediaReadFile } : {}),
         }),
       );
-      const uploaded = await ctx.apiClient.uploadMedia({
-        buffer: loaded.buffer,
-        filename: loaded.fileName ?? "upload.bin",
-        mime: loaded.contentType,
-      });
-      const fragment: ClawlingMediaFragment = {
-        kind: uploaded.kind,
-        url: uploaded.url,
-        name: uploaded.name,
-        mime: uploaded.mime,
-        size: uploaded.size,
-      };
-      out.push(fragment);
     } catch (err) {
-      ctx.log?.error?.(
-        `clawchat-plugin-openclaw outbound media upload failed: ${url} (${err instanceof Error ? err.message : String(err)})`,
-      );
+      // Loading is host policy plus a one-shot read (missing path, outside the
+      // allowed roots, over `maxBytes`). Nothing here is transient, so it is
+      // never retried — and the bytes never reached the media service.
+      const failure = buildFailure({
+        source,
+        stage: "load",
+        attempts: 1,
+        detail: { ...classifyUploadError(err), retryable: false },
+      });
+      result.failures.push(failure);
+      ctx.log?.error?.(`clawchat-plugin-openclaw outbound media load failed: ${failure.summary}`);
+      continue;
+    }
+    const fileName = loaded.fileName ?? "upload.bin";
+    const size = loaded.buffer.byteLength;
+    const mime = loaded.contentType;
+    let pending: UploadErrorDetail | undefined;
+    let attempts = 0;
+    for (let attempt = 1; attempt <= policy.maxAttempts; attempt += 1) {
+      attempts = attempt;
+      try {
+        const uploaded = await ctx.apiClient.uploadMedia({
+          buffer: loaded.buffer,
+          filename: fileName,
+          ...(mime ? { mime } : {}),
+        });
+        result.fragments.push({
+          kind: uploaded.kind,
+          url: uploaded.url,
+          name: uploaded.name,
+          mime: uploaded.mime,
+          size: uploaded.size,
+        });
+        pending = undefined;
+        break;
+      } catch (err) {
+        pending = classifyUploadError(err);
+        if (!pending.retryable || attempt >= policy.maxAttempts) break;
+        const delayMs = uploadRetryDelayMs(attempt, policy);
+        const attemptFailure = buildFailure({
+          source,
+          stage: "upload",
+          attempts: attempt,
+          fileName,
+          size,
+          ...(mime ? { mime } : {}),
+          detail: pending,
+        });
+        ctx.log?.info?.(
+          `clawchat-plugin-openclaw outbound media upload retry ${attempt}/${policy.maxAttempts - 1} in ${delayMs}ms: ${attemptFailure.summary}`,
+        );
+        await sleep(delayMs);
+      }
+    }
+    if (pending) {
+      const failure = buildFailure({
+        source,
+        stage: "upload",
+        attempts,
+        fileName,
+        size,
+        ...(mime ? { mime } : {}),
+        detail: pending,
+      });
+      result.failures.push(failure);
+      ctx.log?.error?.(`clawchat-plugin-openclaw outbound media upload failed: ${failure.summary}`);
     }
   }
-  return out;
+  return result;
 }

package/src/outbound.ts

@@ -16,7 +16,11 @@ import {
   textToFragments,
   type MentionTarget,
 } from "./message-mapper.ts";
-import { uploadOutboundMedia, type ClawlingMediaFragment } from "./media-runtime.ts";
+import {
+  describeOutboundMediaShortfall,
+  uploadOutboundMedia,
+  type ClawlingMediaFragment,
+} from "./media-runtime.ts";
 import { isClawChatNoopResponseText } from "./profile-prompt.ts";
 import { stripNoReplyTokens } from "./no-reply.ts";
 import {
@@ -947,16 +951,20 @@ export const openclawClawlingOutbound: ChannelOutboundAdapter = {
         token: account.token,
         userId: account.userId,
       });
-      const mediaFragments = await uploadOutboundMedia([mediaUrl.trim()], {
+      const uploadResult = await uploadOutboundMedia([mediaUrl.trim()], {
         apiClient,
         runtime,
         ...(mediaAccess ? { mediaAccess } : {}),
         ...(mediaLocalRoots ? { mediaLocalRoots } : {}),
         ...(mediaReadFile ? { mediaReadFile } : {}),
       });
-      if (mediaFragments.length === 0) {
-        throw new Error(`clawchat-plugin-openclaw failed to upload media: ${mediaUrl}`);
+      // Single-attachment path, so "shortfall" is always a total failure here;
+      // the message still carries the structured, redacted reason instead of a
+      // bare "failed to upload" the operator cannot act on.
+      if (uploadResult.fragments.length === 0) {
+        throw new Error(describeOutboundMediaShortfall(uploadResult, 1));
       }
+      const mediaFragments = uploadResult.fragments;
       const target = parseOpenclawRecipient(to);
       const messageId = mintOutboundMessageId(account);
       const claimText = (text ?? "").trim();

package/src/reply-dispatcher.ts

@@ -17,7 +17,11 @@ import {
   effectiveOutputVisibility,
   type ResolvedOpenclawClawlingAccount,
 } from "./config.ts";
-import { uploadOutboundMedia, type ClawlingMediaFragment } from "./media-runtime.ts";
+import {
+  describeOutboundMediaShortfall,
+  uploadOutboundMedia,
+  type ClawlingMediaFragment,
+} from "./media-runtime.ts";
 import {
   mintMessageId,
   sendOpenclawClawlingText,
@@ -439,17 +443,19 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
       );
       return [];
     }
-    const fragments = await uploadOutboundMedia(urls, { apiClient, runtime, log });
-    if (fragments.length < urls.length) {
-      // uploadOutboundMedia drops a failed item with only a log line. A shortfall
-      // means an attachment never reached the media service; surfacing it (parity
-      // with the adapter path in outbound.ts and with the Hermes plugin) stops a
-      // text-only frame from going out and reading as a successful send.
-      throw new Error(
-        `clawchat-plugin-openclaw failed to upload ${urls.length - fragments.length}/${urls.length} outbound media attachment(s); message not sent`,
-      );
+    const result = await uploadOutboundMedia(urls, { apiClient, runtime, log });
+    if (result.fragments.length < urls.length) {
+      // uploadOutboundMedia never aborts the batch: every URL is attempted and
+      // the successful fragments still come back. A shortfall — partial success
+      // or total failure alike — means at least one attachment never reached
+      // the media service, so the whole send is rejected (parity with the
+      // adapter path in outbound.ts and with the Hermes plugin) rather than
+      // letting a text-only frame go out reading as a successful send. The
+      // thrown message carries each failure's structured, redacted diagnostics
+      // so the agent is not left with a reasonless generic error.
+      throw new Error(describeOutboundMediaShortfall(result, urls.length));
     }
-    return fragments;
+    return result.fragments;
   }
 
   // ----- Reply state ------------------------------------------------------

package/src/runtime.ts

@@ -52,7 +52,7 @@ import {
   resolveManagedSkillsDir,
   runSkillUpdateCheck,
 } from "./skill-update.ts";
-import { fetchInboundMedia } from "./media-runtime.ts";
+import { CLAWCHAT_MEDIA_MAX_BYTES, fetchInboundMedia } from "./media-runtime.ts";
 import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.ts";
 import { runWithTerminalClawChatSendScope } from "./terminal-send.ts";
 import {
@@ -2907,7 +2907,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         ? await fetchInboundMedia(turn.mediaItems, {
             runtime,
             log,
-            maxBytes: 20 * 1024 * 1024,
+            maxBytes: CLAWCHAT_MEDIA_MAX_BYTES,
           })
         : [];
     if (inboundPaths.length > 0) {

package/dist/src/friend-request-turn.js

@@ -1,83 +0,0 @@
-/**
- * Synthetic reasoning-turn builder for `friend.request` notify.signal events.
- *
- * When the server fires a `friend.request` signal the runtime dispatches one
- * deduped synthetic `message.send` envelope so the agent can reason about the
- * pending request. The prompt text varies by the current "friend.add" permission
- * policy state: a deny policy yields a decline/inform prompt; ask or allow
- * yields a prompt that instructs the agent to review the request via the
- * `clawchat_list_friend_requests` tool.
- */
-import { EVENT } from "./protocol-types.js";
-/**
- * Returns canned prompt text for a friend-request reasoning turn based on the
- * current "friend.add" permission policy state.
- *
- * - `deny`  → inform the agent it should decline; no accept instruction.
- * - `ask` / `allow` → instruct the agent to review the pending request.
- *
- * The requester's user id is embedded so the agent does not go looking up the
- * synthetic sender ("clawchat-friend-request" is not a real user).
- */
-export function friendRequestPromptFor(state, requesterUserId) {
-    const arrived = requesterUserId
-        ? `A new friend request has arrived from user ${requesterUserId}.`
-        : "A new friend request has arrived.";
-    if (state === "deny") {
-        return [
-            arrived,
-            "Your current friend-add policy is set to deny.",
-            "Do not add this contact.",
-            "You may inform the requester that you cannot add them at this time.",
-        ].join(" ");
-    }
-    return [
-        arrived,
-        "Please review the pending request by calling `clawchat_list_friend_requests`",
-        "and decide whether to accept it.",
-    ].join(" ");
-}
-/**
- * Builds a synthetic `message.send` envelope that triggers one agent reasoning
- * turn for a pending friend request. The envelope shape mirrors the
- * activation-bootstrap envelope; it targets the owner's direct conversation so
- * the agent has context about who it is reasoning for.
- */
-export function buildFriendRequestEnvelope(params) {
-    const { account, state, entityId, ownerConversationId } = params;
-    const text = friendRequestPromptFor(state, entityId);
-    const now = Date.now();
-    // Fall back to ownerUserId only when no activation conversation is recorded:
-    // the turn still runs (the agent can act via tools, e.g. accept the request),
-    // but its in-chat replies will not be deliverable until activation records
-    // the owner conversation.
-    return {
-        version: "2",
-        event: EVENT.MESSAGE_SEND,
-        trace_id: `clawchat-plugin-openclaw-friend-request-${entityId}-${now}`,
-        emitted_at: now,
-        chat_id: ownerConversationId ?? account.ownerUserId,
-        chat_type: "direct",
-        to: { id: account.userId, type: "direct" },
-        sender: {
-            id: "clawchat-friend-request",
-            type: "direct",
-            nick_name: "ClawChat",
-        },
-        payload: {
-            message_id: `clawchat-plugin-openclaw-friend-request-${entityId}-${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,
-                },
-            },
-        },
-    };
-}