@clawling/clawchat-plugin-openclaw 2026.10.7-1 → 2026.10.8-1

package/dist/src/reply-dispatcher.js

@@ -1,12 +1,13 @@
 import { interactiveReplyToPresentation, renderMessagePresentationFallbackText, } from "openclaw/plugin-sdk/interactive-runtime";
 import { resolveOutboundMediaUrls } from "openclaw/plugin-sdk/reply-payload";
+import { classifyFrameworkError, formatFrameworkErrorForOwner, isFrameworkErrorReply, } from "./framework-error-copy.js";
 import { createOpenclawClawlingApiClient } from "./api-client.js";
 import { effectiveOutputVisibility, } from "./config.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";
-import { createReplyStream } from "./reply-stream.js";
+import { createReplyStream, streamableText } from "./reply-stream.js";
 import { openclawLlmContextDebug } from "./llm-context-debug.js";
 /**
  * Re-send cadence for `typing.update {is_typing:true}` while a reply is in
@@ -265,7 +266,7 @@ function formatApprovalSummary(payload) {
  * as separate ClawChat messages.
  */
 export function createOpenclawClawlingReplyDispatcher(options) {
-    const { cfg, runtime, account, client, target, replyCtx, inboundMessageId, store, resolveOwnerConversationId, log, } = options;
+    const { cfg, runtime, account, client, target, replyCtx, inboundMessageId, store, resolveOwnerConversationId, resolveOwnerLocale, log, } = options;
     const isGroupTarget = target.chatType === "group";
     const outputVisibility = effectiveOutputVisibility(account, target.chatId, target.chatType);
     const splitFullOutput = outputVisibility === "full";
@@ -344,7 +345,10 @@ export function createOpenclawClawlingReplyDispatcher(options) {
     // send, or an idle run with nothing delivered fails it. Host partials are snapshots of
     // the current assistant message that may be rewritten, so a snapshot that no
     // longer extends the preview fails the old stream and starts a new one.
-    const streamEnabled = account.streamReplies === true;
+    // Direct chats only, same as Hermes. In a group the server's merged stream
+    // copy carries no @, and a receiver that dedupes by message_id keeps
+    // whichever copy lands first, so an @-only agent would never wake up.
+    const streamEnabled = account.streamReplies === true && !isGroupTarget;
     let replyStream = null;
     const failStream = (reason) => {
         replyStream?.fail(reason);
@@ -355,11 +359,19 @@ export function createOpenclawClawlingReplyDispatcher(options) {
         replyStream = null;
         return id;
     };
+    // Latest host snapshot of the current assistant message, including any tail
+    // the add throttle held back, so a boundary can close the preview whole.
+    let streamPartialText = "";
+    // Texts already delivered as their own message at a message boundary; a
+    // final that only repeats one of them is not sent again.
+    const finalizedPreviewTexts = new Set();
     const onStreamPartial = (text) => {
         if (runDone || terminalReplySuppressed)
             return;
-        if (replyStream?.diverges(text))
-            failStream("superseded");
+        // A snapshot that no longer extends the preview without a message
+        // boundary is a host rewrite: the stream stops growing and the final
+        // replaces it in place (same id). It is never retracted.
+        streamPartialText = text;
         replyStream ??= createReplyStream({
             client,
             chatId: target.chatId,
@@ -555,6 +567,36 @@ export function createOpenclawClawlingReplyDispatcher(options) {
             log,
         });
     };
+    // ----- Stream message boundary -----------------------------------------
+    //
+    // A new assistant message (after a tool call or a thinking block) means the
+    // previewed one is complete. Close it as its own message — `message.done` +
+    // `message.reply` under the same id — instead of letting the next snapshot
+    // supersede it, so text the recipient already saw stays. A preview still
+    // held back (never shown) is just dropped.
+    const finalizeStreamAtBoundary = async (reason) => {
+        if (!replyStream)
+            return;
+        if (!replyStream.isOpen()) {
+            replyStream = null;
+            streamPartialText = "";
+            return;
+        }
+        const decision = streamableText(streamPartialText);
+        const text = decision.kind === "ok"
+            ? decision.text
+            : decision.kind === "poisoned"
+                ? streamPartialText
+                : replyStream.shownText();
+        streamPartialText = "";
+        log?.info?.(`[${account.accountId}] clawchat-plugin-openclaw stream boundary reason=${reason} text_len=${text.length} to=${target.chatId}`);
+        const result = await sendStatic(text, [], [], { recordMessage: true });
+        if (result)
+            finalizedPreviewTexts.add(text.trim());
+        // Whatever sendStatic did (sent, suppressed as no-reply, skipped after a
+        // terminal tool send), the stream is closed now.
+        replyStream = null;
+    };
     // ----- Static send ------------------------------------------------------
     const sendStatic = async (text, mediaFragments = [], richFragments = [], options = {}) => {
         const messageMode = options.messageMode ?? "normal";
@@ -753,7 +795,16 @@ export function createOpenclawClawlingReplyDispatcher(options) {
                     });
                     return;
                 }
-                const finalText = richFragment && account.richInteractions ? mergeFinalText("") : mergeFinalText(text);
+                // OpenClaw's own failure copy (isError, or a leading ⚠️) is English
+                // and often operator-facing; lead it with an owner-language sentence
+                // and keep the original at the end.
+                const deliveredText = isFrameworkErrorReply(payload, text)
+                    ? formatFrameworkErrorForOwner(text, resolveOwnerLocale?.() ?? null)
+                    : text;
+                if (deliveredText !== text) {
+                    log?.info?.(`[${account.accountId}] clawchat-plugin-openclaw final framework error localized category=${classifyFrameworkError(text)}`);
+                }
+                const finalText = richFragment && account.richInteractions ? mergeFinalText("") : mergeFinalText(deliveredText);
                 const finalUrls = mergeFinalUrls(urls);
                 if (isClawChatNoopResponseText(finalText) &&
                     !richFragment &&
@@ -762,6 +813,13 @@ export function createOpenclawClawlingReplyDispatcher(options) {
                     failStream("no-reply");
                     return;
                 }
+                if (!replyStream?.isOpen() &&
+                    finalizedPreviewTexts.has(finalText.trim()) &&
+                    !richFragment &&
+                    finalUrls.length === 0) {
+                    log?.info?.(`[${account.accountId}] clawchat-plugin-openclaw final skipped: already delivered at a message boundary`);
+                    return;
+                }
                 const mediaFragments = await uploadMediaUrls(finalUrls);
                 const result = await sendStatic(finalText, mediaFragments, richFragment && account.richInteractions ? [richFragment] : [], { recordMessage: true });
                 if (result?.messageId)
@@ -786,16 +844,31 @@ export function createOpenclawClawlingReplyDispatcher(options) {
                     return;
                 const fallbackText = bufferedOutputText.trim();
                 const fallbackUrls = bufferedOutputUrls.slice();
-                if (!fallbackText && fallbackUrls.length === 0)
+                if (!fallbackText && fallbackUrls.length === 0) {
+                    // No final came, but a preview was shown: keep it as the reply
+                    // rather than retracting text the recipient already read.
+                    if (replyStream?.isOpen())
+                        await finalizeStreamAtBoundary("idle");
                     return;
+                }
                 const mediaFragments = await uploadMediaUrls(fallbackUrls);
                 const result = await sendStatic(fallbackText, mediaFragments, [], { recordMessage: true });
                 if (result?.messageId)
                     recordThinkingIfLinked(result.messageId);
             }
             finally {
-                // A preview nothing materialized must not linger as an open stream.
-                failStream("undelivered");
+                // Safety net: nothing above claimed or closed an open stream (e.g. the
+                // finalize send threw). It must not linger open, and text already
+                // shown must not vanish: close it with what was shown (the server
+                // materializes that from message.done). Only a preview whose snapshot
+                // turned out to be a no-reply is retracted.
+                if (replyStream?.isOpen()) {
+                    if (streamableText(streamPartialText).kind === "poisoned")
+                        failStream("no-reply");
+                    else
+                        claimStreamMessageId(replyStream.shownText());
+                }
+                replyStream = null;
             }
         },
         onCleanup: () => {
@@ -830,13 +903,22 @@ export function createOpenclawClawlingReplyDispatcher(options) {
                         reasoningText = reasoningText ? `${reasoningText}\n${trimmed}` : trimmed;
                 }
                 : undefined,
-            onToolStart: splitFullOutput
+            onToolStart: splitFullOutput || streamEnabled
                 ? async (payload) => {
+                    if (streamEnabled)
+                        await finalizeStreamAtBoundary("tool-start");
+                    if (!splitFullOutput)
+                        return;
                     if (consumeTerminalSend("tool-start"))
                         return;
                     await emitProcessSegment(formatToolStartSummary(payload));
                 }
                 : undefined,
+            onAssistantMessageStart: streamEnabled
+                ? async () => {
+                    await finalizeStreamAtBoundary("assistant-message-start");
+                }
+                : undefined,
             onToolResult: splitFullOutput
                 ? async (payload) => {
                     if (consumeTerminalSend("tool-result"))

package/dist/src/reply-stream.js

@@ -11,12 +11,13 @@
  * and the server materializes its merged reply from the stream. `finish`
  * therefore takes the final text, sends whatever tail of it the throttle held
  * back as one last add, and closes with the whole text. A final that does not
- * extend what was shown cannot be appended (§8.2) — the stream is failed and
- * the final goes out under its own id.
+ * extend what was shown cannot be appended (§8.2): `message.done` then closes
+ * with the shown text and the final reply, under the same id, replaces it in
+ * place, so text the recipient already saw never vanishes.
  *
- * or, when the reply turns out not to be sendable (no-reply token, run
- * aborted, nothing delivered): message.created(M) → … → message.failed(M),
- * which aborts the stream without materializing anything.
+ * or, when the preview must not stay (a no-reply, or the reply went out
+ * through a ClawChat tool instead): message.created(M) → … → message.failed(M),
+ * which retracts the preview — the recipient keeps nothing of it.
  *
  * Streaming frames get no ack (§8.5) and no server-side mention repair, so the
  * stream only ever carries plain text; mentions, media and rich fragments ride
@@ -184,23 +185,24 @@ export function createReplyStream(options) {
                 return null;
             }
             // Trailing whitespace a partial carried may be trimmed off the final.
-            if (!finalText.startsWith(sent.trimEnd())) {
-                fail("superseded");
-                return null;
-            }
-            if (finalText.length > sent.length && finalText.startsWith(sent)) {
+            const extendsShown = finalText.startsWith(sent.trimEnd());
+            if (extendsShown && finalText.length > sent.length && finalText.startsWith(sent)) {
                 // Past the throttle: this is the last frame before done.
                 sendAdd(finalText, now());
             }
+            // A final that rewrites the preview cannot be appended (§8.2), but the
+            // shown text must not vanish: close the stream with what was shown and
+            // let the final reply under this same id replace it in place.
+            const doneText = extendsShown ? finalText : sent;
             closed = true;
             const at = now();
             emit(EVENT.MESSAGE_DONE, {
                 message_id: messageId,
-                fragments: [{ kind: "text", text: finalText }],
+                fragments: [{ kind: "text", text: doneText }],
                 streaming: streamingState("done", at),
                 completed_at: at,
             });
-            options.log?.info?.(`${prefix} stream done msg=${messageId} text_len=${finalText.length}`);
+            options.log?.info?.(`${prefix} stream done msg=${messageId} text_len=${finalText.length}${extendsShown ? "" : " replaced_in_place=true"}`);
             return messageId;
         },
         fail,

package/dist/src/runtime.js

@@ -859,6 +859,10 @@ export async function startOpenclawClawlingGateway(params) {
     // `sendOwnerSkillMessage` below) — both live in this same function closure, so
     // the forward reference here just resolves to the fresh value at call time.
     let livewareSampleNotify = async () => false;
+    // The supervisor this gateway call shares (new or adopted). The abort cleanup
+    // below awaits its stop() so the host's channel stop (which waits on this
+    // task) does not return while liveware children are still being killed.
+    let livewareSampleForShutdown = null;
     if (store) {
         const stateDirForSample = runtime.state?.resolveStateDir?.();
         const livewareSampleDeps = {
@@ -901,6 +905,7 @@ export async function startOpenclawClawlingGateway(params) {
         livewareSampleSupervisors.set(abortSignal, supervisorsForSignal);
         const supervisorKey = `openclaw:${accountId}`;
         const runningSupervisor = supervisorsForSignal.get(supervisorKey);
+        livewareSampleForShutdown = runningSupervisor ?? null;
         if (runningSupervisor) {
             // A gateway re-entry (refresh/backoff reconnect), not a fresh channel start:
             // hand the live supervisor this closure's token + REST client + notify path
@@ -910,9 +915,12 @@ export async function startOpenclawClawlingGateway(params) {
         }
         else {
             const livewareSampleSupervisor = new LivewareSampleSupervisor(livewareSampleDeps);
+            livewareSampleForShutdown = livewareSampleSupervisor;
             supervisorsForSignal.set(supervisorKey, livewareSampleSupervisor);
             abortSignal.addEventListener("abort", () => {
-                livewareSampleSupervisor.stop();
+                // Starts the SIGTERM → SIGKILL teardown at once; the gateway's own
+                // abort cleanup awaits the same (idempotent) stop() promise.
+                void livewareSampleSupervisor.stop();
                 if (supervisorsForSignal.get(supervisorKey) === livewareSampleSupervisor) {
                     supervisorsForSignal.delete(supervisorKey);
                 }
@@ -1188,6 +1196,25 @@ export async function startOpenclawClawlingGateway(params) {
     const persistOwnerProfile = upsertOwnerProfile
         ? makeOwnerProfilePersister({ upsertOwnerProfile }, { accountId })
         : undefined;
+    // The owner_profile row is where owner-language copy reads its locale
+    // (framework errors, greetings, liveware intros). It was only refreshed on
+    // owner metadata pulls, so an owner who switched app language kept getting
+    // the old one. friend.profile_updated also reaches the agent when the
+    // owner edits their profile; refetch just the owner row then.
+    const refreshOwnerProfileOnUpdate = (entityId) => {
+        const subject = typeof entityId === "string" ? entityId.trim() : "";
+        if (!persistOwnerProfile || !subject || subject !== account.ownerUserId)
+            return;
+        void (async () => {
+            try {
+                const owner = await getConversationApiClient().getAgentOwner();
+                persistOwnerProfile(owner);
+            }
+            catch (err) {
+                log?.error?.(`[${accountId}] clawchat-plugin-openclaw owner profile refresh failed source=friend.profile_updated: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        })();
+    };
     const refreshAgentBehavior = async (options) => {
         try {
             await pullOwnerMetadata({
@@ -2305,6 +2332,9 @@ export async function startOpenclawClawlingGateway(params) {
                 if (type === "friend.added") {
                     scheduleFriendGreeting(payload);
                 }
+                if (type === "friend.profile_updated") {
+                    refreshOwnerProfileOnUpdate(payload?.entity_id);
+                }
             }
         }
     });
@@ -2409,6 +2439,8 @@ export async function startOpenclawClawlingGateway(params) {
                         ? groupFile.metadata.group_owner_nickname ?? metadata?.nickname ?? userId
                         : metadata?.nickname ?? userId;
             const profileType = metadata?.profile_type ?? (userId === account.userId ? "agent" : "user");
+            if (name !== userId)
+                knownNicknames.set(userId, name);
             participants.push({ id: userId, name, profileType, isAgentOwner, isGroupOwner });
         }
         return participants;
@@ -2444,6 +2476,7 @@ export async function startOpenclawClawlingGateway(params) {
             basePrompt: turn.peer.kind === "group" ? getClawChatGroupPrompt() : getClawChatUserPrompt(),
             ...promptMetadata,
             ownerIdFallback: account.ownerUserId,
+            currentAgentIdFallback: account.userId,
             groupParticipants,
             turn: {
                 chatType: promptChatType,
@@ -2463,9 +2496,105 @@ export async function startOpenclawClawlingGateway(params) {
             },
         });
     };
+    // Group frames often carry the sender's id as nick_name. Prefer the nickname
+    // already cached in ClawChat memory (owner.md for the owner and this agent,
+    // users/<id>.md for everyone else, the group's group_owner_nickname for its
+    // owner); keep the id when nothing is cached.
+    const cachedNicknameFor = async (memoryRoot, userId) => {
+        try {
+            if (userId === account.ownerUserId || userId === account.userId) {
+                const ownerFile = await readClawChatMemoryFile(memoryRoot, { targetType: "owner", targetId: "owner" });
+                const nickname = userId === account.userId
+                    ? ownerFile.metadata.agent_nickname
+                    : ownerFile.metadata.agent_owner_nickname;
+                if (nickname)
+                    return nickname;
+            }
+            const userFile = await readClawChatMemoryFile(memoryRoot, { targetType: "user", targetId: userId });
+            return userFile.exists && userFile.metadata.nickname ? userFile.metadata.nickname : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    // Nicknames seen while building group prompts, so ingest can label a
+    // coalesced batch's transcript ("Alice:" rather than "usr_…:") without
+    // touching disk.
+    const knownNicknames = new Map();
+    const withCachedGroupSenderNames = async (turn, memoryRoot) => {
+        if (turn.peer.kind !== "group" || !memoryRoot)
+            return turn;
+        const isBareId = (name, id) => !name || name === id;
+        const cache = new Map();
+        let groupOwner = null;
+        const lookup = async (userId) => {
+            if (!cache.has(userId)) {
+                let nickname = await cachedNicknameFor(memoryRoot, userId);
+                if (!nickname) {
+                    if (!groupOwner) {
+                        try {
+                            const groupFile = await readClawChatMemoryFile(memoryRoot, { targetType: "group", targetId: turn.peer.id });
+                            groupOwner = { id: groupFile.metadata.group_owner_id, nickname: groupFile.metadata.group_owner_nickname };
+                        }
+                        catch {
+                            groupOwner = {};
+                        }
+                    }
+                    if (groupOwner.id === userId && groupOwner.nickname)
+                        nickname = groupOwner.nickname;
+                }
+                cache.set(userId, nickname);
+                if (nickname)
+                    knownNicknames.set(userId, nickname);
+            }
+            return cache.get(userId) ?? null;
+        };
+        const senderNickName = isBareId(turn.senderNickName, turn.senderId)
+            ? (await lookup(turn.senderId)) ?? turn.senderNickName
+            : turn.senderNickName;
+        // The wire carries no sender type, so a batch message from another agent
+        // (Hermes, a second OpenClaw…) would read as a person. users/<id>.md holds
+        // the backend's user type; this agent is always an agent.
+        const typeCache = new Map();
+        const lookupProfileType = async (userId) => {
+            if (userId === account.userId)
+                return "agent";
+            if (!typeCache.has(userId)) {
+                let profileType = null;
+                try {
+                    const userFile = await readClawChatMemoryFile(memoryRoot, { targetType: "user", targetId: userId });
+                    profileType = userFile.exists && userFile.metadata.profile_type ? userFile.metadata.profile_type : null;
+                }
+                catch {
+                    profileType = null;
+                }
+                typeCache.set(userId, profileType);
+            }
+            return typeCache.get(userId) ?? null;
+        };
+        const groupMessages = turn.groupMessages
+            ? await Promise.all(turn.groupMessages.map(async (message) => {
+                const named = isBareId(message.senderName, message.senderId)
+                    ? { ...message, senderName: (await lookup(message.senderId)) ?? message.senderName }
+                    : message;
+                const profileType = await lookupProfileType(message.senderId);
+                if (!profileType || profileType === named.senderProfileType)
+                    return named;
+                const senderRelation = profileType === "agent" && named.senderRelation === "peer_user"
+                    ? "peer_agent"
+                    : named.senderRelation;
+                return { ...named, senderProfileType: profileType, senderRelation };
+            }))
+            : turn.groupMessages;
+        return { ...turn, senderNickName, ...(groupMessages ? { groupMessages } : {}) };
+    };
     const resolveSenderNickNameForTurn = (turn) => {
         if (turn.senderNickName && turn.senderNickName !== turn.senderId)
             return turn.senderNickName;
+        // Synchronous on purpose: an await here would reorder same-group frames.
+        const known = turn.peer.kind === "group" ? knownNicknames.get(turn.senderId) : undefined;
+        if (known)
+            return known;
         return turn.senderNickName || turn.senderId;
     };
     const resolveSenderBatchIdentityForTurn = (turn) => {
@@ -2480,7 +2609,9 @@ export async function startOpenclawClawlingGateway(params) {
             senderProfileType: turn.senderProfileType ??
                 (senderRelation === "self_agent" || senderRelation === "peer_agent" ? "agent" : "user"),
             senderIsOwner: senderRelation === "owner",
-            senderIsGroupOwner: turn.senderIsGroupOwner ?? false,
+            // Left undefined when the frame does not say, so the prompt falls back
+            // to the group metadata's group_owner_id instead of a forced false.
+            ...(turn.senderIsGroupOwner !== undefined ? { senderIsGroupOwner: turn.senderIsGroupOwner } : {}),
         };
     };
     const claimInboundTurn = (turn) => {
@@ -2550,6 +2681,7 @@ export async function startOpenclawClawlingGateway(params) {
         catch (err) {
             log?.error?.(`[${accountId}] clawchat-plugin-openclaw message metadata refresh failed: ${err instanceof Error ? err.message : String(err)}`);
         }
+        turn = await withCachedGroupSenderNames(turn, memoryRoot);
         const conversationTarget = `${CHANNEL_ID}:${formatConversationSubject(turn.peer)}`;
         const turnPrompt = await buildPromptForTurn(turn, memoryRoot);
         const senderIsOwner = turn.senderIsOwner === true || turn.senderId === account.ownerUserId;
@@ -2680,6 +2812,7 @@ export async function startOpenclawClawlingGateway(params) {
                 runtime,
                 account,
                 client,
+                resolveOwnerLocale: () => store?.getOwnerProfile?.({ platform: "openclaw", accountId })?.locale ?? null,
                 target: { chatId: turn.peer.id, chatType: turn.peer.kind },
                 ...(replyCtx ? { replyCtx } : {}),
                 inboundMessageId: turn.messageId,
@@ -3270,6 +3403,16 @@ export async function startOpenclawClawlingGateway(params) {
             closeReason: "client close",
         });
         client.close();
+        if (livewareSampleForShutdown) {
+            // SIGTERM, then SIGKILL after KILL_GRACE_MS (3 s): inside the host's
+            // 5 s wait for this task, so a stuck child no longer outlives the stop.
+            try {
+                await livewareSampleForShutdown.stop();
+            }
+            catch (err) {
+                log?.error?.(`[${accountId}] clawchat-plugin-openclaw liveware-sample stop failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
         setStatus({
             ...getStatus(),
             connected: false,

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.16.0";
+export const DEFAULT_SKILLS_REF = "skills-v1.17.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

@@ -205,7 +205,7 @@ export const ClawchatCreateMomentSchema = Type.Object({
         description: "Moment text. At least one of text or images is required.",
     })),
     images: Type.Optional(Type.Array(Type.String({
-        description: "Image URL for the moment. Upload local files first; do not pass local paths.",
+        description: "An http(s) image URL, or an absolute local image path (the tool uploads it and uses the hosted URL).",
     }))),
 });
 export const ClawchatDeleteMomentSchema = Type.Object({

package/dist/src/tools.js

@@ -28,6 +28,15 @@ function extractRequestId(err) {
     }
     return undefined;
 }
+/**
+ * What the agent must do with the later `permission_result` receipt
+ * (agent-protocol §2.8): on approval the SERVER executes the gated call, so a
+ * second call would duplicate it or raise a fresh card. Only `approved_retry`
+ * (reads, which are never replayed) asks for exactly one more call.
+ */
+const PERMISSION_RECEIPT_RULE = "When the result arrives: outcome \"approved\" (or \"auto_allowed\") means the server has already done it for you — do not call this tool again; " +
+    "only outcome \"approved_retry\" means call this same tool once more with the same arguments. " +
+    "Anything the server produced (a new id, a code, read data) comes in that message's Result line.";
 function permissionGateResult(err) {
     const code = err.meta?.code;
     const requestId = extractRequestId(err);
@@ -38,7 +47,8 @@ function permissionGateResult(err) {
             "This operation requires the owner's approval and has been submitted for review" +
                 (requestId ? ` (request_id=${requestId})` : "") +
                 ". It has NOT failed. Do not retry — the result will arrive later as a normal " +
-                "chat message; wait for it instead of calling this tool again.";
+                "chat message; wait for it instead of calling this tool again. " +
+                PERMISSION_RECEIPT_RULE;
         status = "pending";
     }
     else {
@@ -120,6 +130,46 @@ function inferMimeFromPath(filePath) {
     const ext = path.extname(filePath).toLowerCase();
     return MIME_BY_EXT[ext] ?? "application/octet-stream";
 }
+/**
+ * Classify `clawchat_create_moment` image entries: http(s) URLs pass through;
+ * an existing absolute local regular file (≤ 20MB) is marked for upload; any
+ * other value is a validation error naming the offending index.
+ */
+function planMomentImages(images) {
+    const entries = [];
+    for (const [i, raw] of images.entries()) {
+        const where = `clawchat-plugin-openclaw: images[${i}]`;
+        const value = typeof raw === "string" ? raw.trim() : "";
+        if (!value) {
+            return { ok: false, message: `${where} must be an http(s) image URL or an absolute local image path` };
+        }
+        if (/^https?:\/\/\S+$/i.test(value)) {
+            entries.push({ kind: "url", url: value });
+            continue;
+        }
+        if (!path.isAbsolute(value)) {
+            return {
+                ok: false,
+                message: `${where} (${JSON.stringify(value)}) is neither an http(s) URL nor an absolute local file path; no moment was created`,
+            };
+        }
+        let stat;
+        try {
+            stat = fs.statSync(value);
+        }
+        catch {
+            return { ok: false, message: `${where}: local file ${value} does not exist; no moment was created` };
+        }
+        if (!stat.isFile()) {
+            return { ok: false, message: `${where}: ${value} is not a regular file; no moment was created` };
+        }
+        if (stat.size > MAX_UPLOAD_BYTES) {
+            return { ok: false, message: `${where}: ${value} is too large (${stat.size} bytes; max 20MB)` };
+        }
+        entries.push({ kind: "local", path: value });
+    }
+    return { ok: true, entries };
+}
 function validateMentionMessageParams(params) {
     if (!params || typeof params !== "object") {
         return { ok: false, message: "clawchat-plugin-openclaw: params are required" };
@@ -285,6 +335,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
             ok: true,
             client: createOpenclawClawlingApiClient({
                 baseUrl: acct.baseUrl,
+                mediaBaseUrl: acct.mediaBaseUrl,
                 token: acct.token,
                 userId: acct.userId,
             }),
@@ -329,8 +380,16 @@ export function registerOpenclawClawlingTools(api, options = {}) {
                             ? rawData
                             : {};
                         const outcome = mapGateOutcome(code, gateData);
-                        if (outcome !== null)
-                            return jsonResponse(outcome);
+                        if (outcome !== null) {
+                            // `next_step` is added here, not in mapGateOutcome: that mapping
+                            // is pinned byte-for-byte against the Hermes parity fixtures.
+                            return jsonResponse(outcome.status === "pending_owner_approval"
+                                ? {
+                                    ...outcome,
+                                    next_step: "Waiting for the owner's approval; do not call this tool again now. " + PERMISSION_RECEIPT_RULE,
+                                }
+                                : outcome);
+                        }
                     }
                     return apiError(err);
                 }
@@ -1100,7 +1159,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
             label: "Create ClawChat Moment",
             description: toolDescription("Create a new ClawChat moment/dynamic for the configured ClawChat account. " +
                 "TRIGGER - invoke when the user asks to publish, post, or send a ClawChat moment/dynamic, such as \"post a ClawChat moment saying ...\", \"publish a dynamic ...\", or \"send a friend moment ...\". " +
-                "At least one of text or images must be present. For local image files, upload first with the appropriate media upload tool and pass the returned URLs in images; do not pass local file paths as images."),
+                "At least one of text or images must be present. Each images entry is either an http(s) image URL (used as-is) or an absolute local image path (max 20MB) — for a local path this tool uploads it to ClawChat media itself and uses the hosted URL, so no separate upload step is needed. Any other value (relative path, file:// or data: URI, missing file) is rejected and no moment is created."),
             parameters: ClawchatCreateMomentSchema,
             async execute(_callId, params) {
                 return await recordClawchatToolCall(accountId, "clawchat_create_moment", params, async () => {
@@ -1110,10 +1169,33 @@ export function registerOpenclawClawlingTools(api, options = {}) {
                     if (!text && (!images || images.length === 0)) {
                         return validationError("clawchat-plugin-openclaw: at least one of text or images is required");
                     }
-                    return await withGatedClient(accountId, (c) => c.createMoment({
-                        ...(text !== undefined ? { text } : {}),
-                        ...(images !== undefined ? { images } : {}),
-                    }));
+                    // Validate every entry before touching the network, so a bad value
+                    // never leaves a half-uploaded batch or a moment with a broken image.
+                    const plan = images !== undefined ? planMomentImages(images) : { ok: true, entries: [] };
+                    if (!plan.ok)
+                        return validationError(plan.message);
+                    return await withGatedClient(accountId, async (c) => {
+                        const resolved = [];
+                        for (const entry of plan.entries) {
+                            if (entry.kind === "url") {
+                                resolved.push(entry.url);
+                                continue;
+                            }
+                            const uploaded = await c.uploadMedia({
+                                buffer: fs.readFileSync(entry.path),
+                                filename: path.basename(entry.path),
+                                mime: inferMimeFromPath(entry.path),
+                            });
+                            if (uploaded.kind !== "image") {
+                                throw new Error(`clawchat-plugin-openclaw: ${entry.path} is not an image (media service classified it as ${uploaded.kind}); no moment was created`);
+                            }
+                            resolved.push(uploaded.url);
+                        }
+                        return await c.createMoment({
+                            ...(text !== undefined ? { text } : {}),
+                            ...(images !== undefined ? { images: resolved } : {}),
+                        });
+                    });
                 });
             },
         };