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

package/src/profile-prompt.ts

@@ -331,10 +331,24 @@ function renderGroupMessageMetadata(turn: ClawChatTurnPrompt, groupMetadata?: Cl
   return lines.join("\n");
 }
 
-function renderGroupParticipants(participants: ClawChatGroupParticipantPrompt[]): string | null {
+function renderCurrentAgent(agentId: string, nickname: string | null | undefined): string {
+  const self = nickname ? `${formatValue(agentId)} (${formatValue(nickname)})` : formatValue(agentId);
+  return [
+    "## ClawChat Current Agent",
+    `current_agent_id: ${formatValue(agentId)}`,
+    `current_agent_nickname: ${formatValue(nickname)}`,
+    `You are ${self}. A sender_id of ${formatValue(agentId)} is you. In a group, mentions_current_agent=true (mention_routing addressed_to_current_agent) means the message is addressed to you, whatever name the text shows.`,
+  ].join("\n");
+}
+
+function renderGroupParticipants(
+  participants: ClawChatGroupParticipantPrompt[],
+  currentAgentId: string | null,
+): string | null {
   if (participants.length === 0) return null;
   const lines = participants.map((participant) => {
     const labels = [participant.profileType || "user"];
+    if (currentAgentId && participant.id === currentAgentId) labels.push("current_agent");
     if (participant.isAgentOwner) labels.push("agent_owner");
     if (participant.isGroupOwner) labels.push("group_owner");
     const type = labels.join(", ");
@@ -347,6 +361,7 @@ export function renderClawChatProfilePrompt(params: {
   basePrompt: string;
   ownerMetadata?: ClawChatPromptMetadata | null;
   ownerIdFallback?: string | null;
+  currentAgentIdFallback?: string | null;
   userMetadata?: ClawChatPromptMetadata | null;
   groupMetadata?: ClawChatPromptMetadata | null;
   groupParticipants?: ClawChatGroupParticipantPrompt[];
@@ -365,6 +380,10 @@ export function renderClawChatProfilePrompt(params: {
   if (Object.keys(ownerMetadata).length > 0) {
     sections.push(renderMetadataSection("ClawChat Agent Owner Metadata", ownerMetadata));
   }
+  const currentAgentId = ownerMetadataSource.agent_id || params.currentAgentIdFallback || null;
+  if (currentAgentId) {
+    sections.push(renderCurrentAgent(currentAgentId, ownerMetadataSource.agent_nickname));
+  }
   if (
     params.turn.chatType === "dm" &&
     !params.turn.senderIsOwner &&
@@ -387,7 +406,7 @@ export function renderClawChatProfilePrompt(params: {
     }
   }
   if (params.turn.chatType === "group") {
-    const participantSection = renderGroupParticipants(params.groupParticipants ?? []);
+    const participantSection = renderGroupParticipants(params.groupParticipants ?? [], currentAgentId);
     if (participantSection) sections.push(participantSection);
   }
   sections.push(

package/src/reply-dispatcher.ts

@@ -11,6 +11,11 @@ import type { PluginRuntime } from "openclaw/plugin-sdk/core";
 import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
 import { resolveOutboundMediaUrls } from "openclaw/plugin-sdk/reply-payload";
 import type { ReplyPayload } from "openclaw/plugin-sdk/reply-runtime";
+import {
+  classifyFrameworkError,
+  formatFrameworkErrorForOwner,
+  isFrameworkErrorReply,
+} from "./framework-error-copy.ts";
 import { createOpenclawClawlingApiClient } from "./api-client.ts";
 import type { ChatType } from "./client.ts";
 import {
@@ -77,6 +82,12 @@ export interface ReplyDispatcherOptions {
    * dispatcher was constructed is still picked up.
    */
   resolveOwnerConversationId?: () => string | null;
+  /**
+   * The owner's reported app locale (`agent_owner_locale`), read lazily at
+   * send time. Picks the language of the sentence that leads a rewritten
+   * framework error final; null/absent means English.
+   */
+  resolveOwnerLocale?: () => string | null;
   log?: { info?: (m: string) => void; error?: (m: string) => void };
 }
 
@@ -418,6 +429,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
     inboundMessageId,
     store,
     resolveOwnerConversationId,
+    resolveOwnerLocale,
     log,
   } = options;
   const isGroupTarget = target.chatType === "group";
@@ -933,7 +945,18 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
           });
           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) &&

package/src/runtime.ts

@@ -1210,6 +1210,10 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   // `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: (text: string) => Promise<boolean> = 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: LivewareSampleSupervisor | null = null;
   if (store) {
     const stateDirForSample = runtime.state?.resolveStateDir?.();
     const livewareSampleDeps: LivewareSampleSupervisorDeps = {
@@ -1253,6 +1257,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     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
@@ -1263,9 +1268,12 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       runningSupervisor.adoptDeps(livewareSampleDeps);
     } 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);
         }
@@ -1576,6 +1584,25 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   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: unknown): void => {
+    const subject = typeof entityId === "string" ? entityId.trim() : "";
+    if (!persistOwnerProfile || !subject || subject !== account.ownerUserId) return;
+    void (async () => {
+      try {
+        const owner = await getConversationApiClient().getAgentOwner();
+        persistOwnerProfile(owner as unknown as Record<string, unknown>);
+      } 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: {
     metadataVersion?: number;
     source: string;
@@ -2791,6 +2818,9 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         if (type === "friend.added") {
           scheduleFriendGreeting(payload as Record<string, unknown> | undefined);
         }
+        if (type === "friend.profile_updated") {
+          refreshOwnerProfileOnUpdate(payload?.entity_id);
+        }
       }
     }
   });
@@ -2903,6 +2933,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
             ? 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;
@@ -2941,6 +2972,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       basePrompt: turn.peer.kind === "group" ? getClawChatGroupPrompt() : getClawChatUserPrompt(),
       ...promptMetadata,
       ownerIdFallback: account.ownerUserId,
+      currentAgentIdFallback: account.userId,
       groupParticipants,
       turn: {
         chatType: promptChatType,
@@ -2961,8 +2993,76 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     });
   };
 
+  // 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: string, userId: string): Promise<string | null> => {
+    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<string, string>();
+
+  const withCachedGroupSenderNames = async <T extends IngestTurnParams>(
+    turn: T,
+    memoryRoot: string | null,
+  ): Promise<T> => {
+    if (turn.peer.kind !== "group" || !memoryRoot) return turn;
+    const isBareId = (name: string | null | undefined, id: string): boolean => !name || name === id;
+    const cache = new Map<string, string | null>();
+    let groupOwner: { id?: string; nickname?: string } | null = null;
+    const lookup = async (userId: string): Promise<string | null> => {
+      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;
+    const groupMessages = turn.groupMessages
+      ? await Promise.all(turn.groupMessages.map(async (message) =>
+          isBareId(message.senderName, message.senderId)
+            ? { ...message, senderName: (await lookup(message.senderId)) ?? message.senderName }
+            : message
+        ))
+      : turn.groupMessages;
+    return { ...turn, senderNickName, ...(groupMessages ? { groupMessages } : {}) };
+  };
+
   const resolveSenderNickNameForTurn = (turn: IngestTurnParams): string => {
     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;
   };
 
@@ -2970,7 +3070,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     senderRelation: NonNullable<IngestTurnParams["senderRelation"]>;
     senderProfileType: string;
     senderIsOwner: boolean;
-    senderIsGroupOwner: boolean;
+    senderIsGroupOwner?: boolean;
   } => {
     const senderRelation = resolveSenderRelation({
       senderId: turn.senderId,
@@ -2983,7 +3083,9 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       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 } : {}),
     };
   };
 
@@ -3062,6 +3164,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         `[${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;
@@ -3202,6 +3305,8 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
           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,
@@ -3871,6 +3976,17 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       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/src/skill-update.ts

@@ -71,7 +71,7 @@ export const OFFICIAL_SKILLS_BASE =
  * 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;

package/src/tools-schema.ts

@@ -328,7 +328,7 @@ export const ClawchatCreateMomentSchema = Type.Object({
   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).",
       }),
     ),
   ),

package/src/tools.ts

@@ -148,6 +148,17 @@ function extractRequestId(err: ClawlingApiError): string | undefined {
   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: ClawlingApiError) {
   const code = (err.meta as Record<string, unknown> | undefined)?.code;
   const requestId = extractRequestId(err);
@@ -158,7 +169,8 @@ function permissionGateResult(err: ClawlingApiError) {
       "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 {
     message =
@@ -257,6 +269,50 @@ function inferMimeFromPath(filePath: string): string {
   return MIME_BY_EXT[ext] ?? "application/octet-stream";
 }
 
+type MomentImageEntry = { kind: "url"; url: string } | { kind: "local"; path: string };
+
+/**
+ * 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: unknown[],
+): { ok: true; entries: MomentImageEntry[] } | { ok: false; message: string } {
+  const entries: MomentImageEntry[] = [];
+  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: fs.Stats;
+    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: unknown):
   | { ok: true; params: ClawchatMentionMessageParams }
   | { ok: false; message: string } {
@@ -442,6 +498,7 @@ export function registerOpenclawClawlingTools(
       ok: true,
       client: createOpenclawClawlingApiClient({
         baseUrl: acct.baseUrl,
+        mediaBaseUrl: acct.mediaBaseUrl,
         token: acct.token,
         userId: acct.userId,
       }),
@@ -490,7 +547,19 @@ export function registerOpenclawClawlingTools(
                 ? (rawData as Record<string, unknown>)
                 : {};
             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);
         }
@@ -1413,7 +1482,7 @@ export function registerOpenclawClawlingTools(
         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) {
@@ -1424,12 +1493,34 @@ export function registerOpenclawClawlingTools(
             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({
+            // 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 as const, entries: [] };
+            if (!plan.ok) return validationError(plan.message);
+            return await withGatedClient(accountId, async (c) => {
+              const resolved: string[] = [];
+              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 } : {}),
-              }),
-            );
+                ...(images !== undefined ? { images: resolved } : {}),
+              });
+            });
           });
         },
       };