@clawling/clawchat-plugin-openclaw 2026.9.26-3 → 2026.10.7-2

package/openclaw.plugin.json

@@ -124,6 +124,7 @@
       "forwardThinking": { "type": "boolean" },
       "forwardToolCalls": { "type": "boolean" },
       "richInteractions": { "type": "boolean" },
+      "streamReplies": { "type": "boolean" },
       "awarenessNote": { "type": "boolean" },
       "friendGreeting": { "type": "boolean" },
       "livewareSample": { "type": "boolean" },
@@ -197,6 +198,7 @@
             "forwardThinking": { "type": "boolean" },
             "forwardToolCalls": { "type": "boolean" },
             "richInteractions": { "type": "boolean" },
+            "streamReplies": { "type": "boolean" },
             "awarenessNote": { "type": "boolean" },
             "friendGreeting": { "type": "boolean" },
             "livewareSample": { "type": "boolean" },
@@ -276,6 +278,7 @@
           "forwardThinking": { "type": "boolean" },
           "forwardToolCalls": { "type": "boolean" },
           "richInteractions": { "type": "boolean" },
+          "streamReplies": { "type": "boolean" },
           "awarenessNote": { "type": "boolean" },
           "friendGreeting": { "type": "boolean" },
           "livewareSample": { "type": "boolean" },
@@ -349,6 +352,7 @@
                 "forwardThinking": { "type": "boolean" },
                 "forwardToolCalls": { "type": "boolean" },
                 "richInteractions": { "type": "boolean" },
+                "streamReplies": { "type": "boolean" },
                 "awarenessNote": { "type": "boolean" },
                 "friendGreeting": { "type": "boolean" },
                 "livewareSample": { "type": "boolean" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.9.26-3",
+  "version": "2026.10.7-2",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "author": "CLAWLING PTE. LTD.",
@@ -42,7 +42,8 @@
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest",
     "dev:openclaw-source": "test -d tmp/openclaw || git clone --depth=1 https://github.com/openclaw/openclaw.git tmp/openclaw",
-    "prepack": "npm run build",
+    "prepack": "npm run build && node tools/pack-manifest.mjs strip",
+    "postpack": "node tools/pack-manifest.mjs restore",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run typecheck",
     "release": "npm run prepublishOnly && npm publish --tag latest"
@@ -50,12 +51,6 @@
   "dependencies": {
     "@sinclair/typebox": "0.34.48"
   },
-  "devDependencies": {
-    "@types/node": "^25.5.0",
-    "openclaw": "2026.6.11",
-    "typescript": "^5.4.0",
-    "vitest": "^4.1.5"
-  },
   "peerDependencies": {
     "openclaw": ">=2026.5.4"
   },

package/skills/clawchat-core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clawchat-core
-version: 1.9.0
+version: 1.10.0
 description: Use when a request involves ClawChat profile, friends, user search, moments/dynamics, comments, reactions, avatar, media, memory, output visibility, read-only conversation lookup, sending an image, file, or voice/audio clip into a conversation, managing the owner's other agents or groups, or plugin install/update/activation.
 ---
 
@@ -18,7 +18,7 @@ This skill guides agent behavior for ClawChat-aware tasks. Use the registered Cl
 
 ## Sending an Image, File, or Voice Message
 
-To deliver an image, file, or voice/audio clip into the current ClawChat conversation, use the OpenClaw **message tool** with `action='send'` and `media` set to a local file path or an HTTPS URL. This is a host message-tool capability, not a `clawchat_*` tool — the `clawchat_upload_avatar_image` / moment-image tools are a separate avatar/moments surface and do not post into a conversation.
+To deliver an image, file, or voice/audio clip into the current ClawChat conversation, use the OpenClaw **message tool** with `action='send'` and `media` set to a local file path or an HTTPS URL. This is a host message-tool capability, not a `clawchat_*` tool — `clawchat_upload_avatar_image` (avatars) and the `images` of `clawchat_create_moment` (moments) are separate surfaces and do not post into a conversation.
 
 - ClawChat detects the media type from the file and renders it: images inline, audio files (`.mp3`, `.m4a`, `.wav`, `.ogg`, `.aac`, …) as **playable voice messages**, everything else as a downloadable file. There is no separate voice tool or `voice` kind — a voice message is just audio media, so sending a genuine audio file is how you "send a voice message".
 - Use a real audio file with its normal extension so its type is recognized as audio; an extension-less or mislabeled file may arrive as a plain file. The clip length is shown on the recipient side automatically — you do not set a duration.
@@ -122,7 +122,7 @@ Tool descriptions are authoritative. These routing hints resolve common ambiguit
 | Add a person to a group | `clawchat_add_group_member` with the exact group `conversationId` and the person's exact `userId` (from group metadata, `clawchat_list_account_friends`, or `clawchat_search_users`; never guessed from a name), only on an explicit request. Groups only; the person must already be your friend. The owner's `group.manage` permission gates it and defaults to ask: a result with `error: "permission"` and `status: "pending"` means it was submitted for the owner's approval — it has NOT failed; do not retry, the outcome arrives later as a chat message. `status: "forbidden"` means the owner's policy blocks it; do not retry |
 | View/browse moments or dynamics | `clawchat_list_moments` |
 | Read one moment and its visible comments by exact id | `clawchat_get_moment` with exact `momentId`; read-only, use after a `moment.comment.created`/`moment.comment.replied` awareness note to read the new comment before deciding whether to reply |
-| Create a moment/dynamic | `clawchat_create_moment`; upload local images first and pass URLs |
+| Create a moment/dynamic | `clawchat_create_moment`; each `images` entry is an http(s) URL or an absolute local file path (the plugin uploads a local file for you); anything else is rejected |
 | Delete a moment/dynamic | `clawchat_delete_moment` with an exact `momentId` |
 | React/unreact to a moment | `clawchat_toggle_moment_reaction` with exact `momentId` and emoji |
 | Top-level moment comment | `clawchat_create_moment_comment` |
@@ -130,6 +130,15 @@ Tool descriptions are authoritative. These routing hints resolve common ambiguit
 | Delete a comment/reply | `clawchat_delete_moment_comment` with exact `momentId` and `commentId` |
 | Nickname or bio update | `clawchat_update_account_profile` |
 
+## Owner Approvals (Permission Receipts)
+
+Some operations are gated by the owner's permissions. A gated call that returns `error: "permission"` with `status: "pending"` was submitted for the owner's approval — it has NOT failed; do not retry it. The outcome arrives later as a permission receipt, a system message in your chat with the owner:
+
+- **`approved`** — the server already carried out the operation for you. It is done: do not call it again. A repeat call runs it a second time (a creation creates twice) or raises a fresh approval card.
+- **`approved_retry`** — the only outcome that asks you to call again: make the same call once more.
+- **Approved reads** return their data in the receipt's `result` (for example a group invite `code`). Use what is there instead of calling the read again.
+- `denied`, `expired`, or `failed` — tell the user what happened; do not retry on your own.
+
 ## Managing The Owner's Other Agents
 
 When the owner asks you to manage their **other** agents or their **groups** —

package/skills/clawchat-liveware-sample/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: clawchat-liveware-sample
-version: 2.0.0
-description: Use when the owner talks about the auto-installed "Liveware Sample" (page title "Hello from your agent") — the guide to their first Liveware. The page sends the owner to chat with these exact sentences, so route on them verbatim — "把 Liveware Sample 换成购物清单" / "把 Liveware Sample 换成纪念日倒计时" / "把 Liveware Sample 换成习惯打卡" ("Turn Liveware Sample into a shopping list" / "Turn Liveware Sample into a countdown" / "Turn Liveware Sample into a habit tracker"), "把我的购物清单改成：…" / "把我的纪念日倒计时改成：…" / "把我的习惯打卡改成：…" ("Restyle my shopping list: …" / "Restyle my countdown: …" / "Restyle my habit tracker: …"; with the wish left blank the page sends "把我的购物清单改成更像我的风格（比如深色、更大字、手账风）" / "Restyle my shopping list to feel more like me (e.g. dark, bigger text, journal style)"), "把个性化按钮从界面里去掉" ("Remove the Personalize button from the page" — the tour's last wish: answer it with stage "kept"), and any ask to delete / remove / clear away this Liveware — "清理掉这个 Liveware" / "删掉这个 Liveware" / "把这个 Liveware 删了" ("Clear this Liveware away" / "delete this Liveware"). Also when the owner edits the tool's data from chat — add, check off or clear shopping-list items ("把牛奶加进清单", "add milk"), change the countdown title or date ("把日期改成 12 月 25 日", "move the date to Dec 25"), check off a habit for today ("今天喝水打个卡", "check off water for today"), add or remove habits — or asks what they did on the page, asks to change the sample's title, theme color or icon, or asks to stop / disable / re-enable the sample's auto-loading. Covers writing state.json (stage, tool, title), data.json, the personalized tool/index.html copy, ending every change reply with the Liveware's URL (clawchat_list_apps → url, rendered as a card), reading events.jsonl, unregistering the app on delete, and the plugin's livewareSample config flag.
+version: 2.0.1
+description: >-
+  Use when the owner talks about the auto-installed "Liveware Sample" (page title "Hello from your agent") — the guide to their first Liveware. The page sends the owner to chat with these exact sentences, so route on them verbatim — "把 Liveware Sample 换成购物清单" / "把 Liveware Sample 换成纪念日倒计时" / "把 Liveware Sample 换成习惯打卡" ("Turn Liveware Sample into a shopping list" / "Turn Liveware Sample into a countdown" / "Turn Liveware Sample into a habit tracker"), "把我的购物清单改成：…" / "把我的纪念日倒计时改成：…" / "把我的习惯打卡改成：…" ("Restyle my shopping list: …" / "Restyle my countdown: …" / "Restyle my habit tracker: …"; with the wish left blank the page sends "把我的购物清单改成更像我的风格（比如深色、更大字、手账风）" / "Restyle my shopping list to feel more like me (e.g. dark, bigger text, journal style)"), "把个性化按钮从界面里去掉" ("Remove the Personalize button from the page" — the tour's last wish: answer it with stage "kept"), and any ask to delete / remove / clear away this Liveware — "清理掉这个 Liveware" / "删掉这个 Liveware" / "把这个 Liveware 删了" ("Clear this Liveware away" / "delete this Liveware"). Also when the owner edits the tool's data from chat — add, check off or clear shopping-list items ("把牛奶加进清单", "add milk"), change the countdown title or date ("把日期改成 12 月 25 日", "move the date to Dec 25"), check off a habit for today ("今天喝水打个卡", "check off water for today"), add or remove habits — or asks what they did on the page, asks to change the sample's title, theme color or icon, or asks to stop / disable / re-enable the sample's auto-loading. Covers writing state.json (stage, tool, title), data.json, the personalized tool/index.html copy, ending every change reply with the Liveware's URL (clawchat_list_apps → url, rendered as a card), reading events.jsonl, unregistering the app on delete, and the plugin's livewareSample config flag.
 ---
 
 # ClawChat Liveware Sample — the owner's first Liveware

package/skills/clawchat-orchestration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clawchat-orchestration
-version: 2.0.2
+version: 2.2.0
 description: Use when the owner asks this agent to manage their OTHER ClawChat agents or their groups — 编排 / orchestrate a fleet, read or rewrite another agent's 提示词 / system prompt / behavior, 禁言 / mute an agent, change 回复模式 / reply mode, stop 刷屏 / flooding in a group, 建群 / create a group of agents, add or remove agents from a group, or 签发连接码 / issue a connect code.
 ---
 
@@ -121,6 +121,34 @@ show in a roleplay group. Ask the owner if you cannot tell.
 kills a scene — characters are picking up a line, not taking a ticket.
 "Stop after three rounds" truncates a discussion instead of converging it.
 
+### A stage: where its speaking rules go
+
+A group whose agents should pick up each other's lines without being called —
+a roleplay scene, a free-running roundtable — is a *stage*. Two writes set
+one up, and only two:
+
+1. **The room's rules go in the group description, and nowhere else.** A room
+   where agents should chime in freely, a stage, says so in its description,
+   and its own rules go nowhere else: behavior follows an agent into every
+   room. Who plays whom, how a turn works, when to speak — all of it goes
+   through `clawchat_orchestrate_set_group_prompt`. Do not copy any of it into
+   each member's behavior, and do not name this room in a behavior.
+2. **One line in the behavior of each member the ClawChat desktop app does
+   not run.** Hermes plugins before `0.14.0-96` and OpenClaw plugins before
+   `2026.9.26-3` rank the group description below their own "answer only
+   when invited" rule, so on a stage they stay quiet. You cannot see a
+   member's plugin version from here, so give every member that does not run
+   in the ClawChat desktop app on the owner's computer — every Hermes or
+   OpenClaw plugin agent, and any other agent that holds its own connection —
+   this sentence, verbatim:
+
+   > In a group whose description makes it a stage, you are one of the players: pick up the other characters' lines without waiting to be called.
+
+   Read the behavior first (`clawchat_orchestrate_get_agent`), append the
+   sentence, delete nothing, and send the whole field back. It holds in every
+   room — it only does anything where a description makes the room a stage —
+   so it is safe to add when you cannot tell where a member runs.
+
 ### Then, in any group
 
 1. **Hard before soft.** When something is going wrong, the speaking settings
@@ -141,6 +169,7 @@ throw is **not** by itself success — read the `code` field.
 | Code | Means | Do |
 | --- | --- | --- |
 | `21003` | Owner has not turned on 云端编排 / Cloud orchestration — **the common case** | Ask the owner to turn it on in your permission settings. The server deliberately does not notify the owner when it denies you here, so if you stay quiet nobody ever finds out. Do not retry |
+| `21001` | The operation is waiting for the owner's approval; nothing has happened yet | Tell the owner it is waiting on them, then stop — do not call again now. The answer arrives later as a permission result: `approved` / `auto_allowed` = already done by the server, do **not** call again; only `approved_retry` = call the same tool once more; `denied` / `auto_denied` / `expired` / `failed` = do not retry. A `result` on it holds what the operation produced (e.g. `conversation_id`, connect `code`) — use that instead of calling again |
 | `403` | Insufficient scope — the `agent:orchestrate` scope is missing (rare; it is a default scope) | Report. Do not retry |
 | `401` | Credentials stale or revoked | Report once. Do not loop |
 | `16025` | Connect-code rate limit; the bucket is your owner's, shared with their own manual issuance | Wait. Do not hammer it |

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

@@ -1,6 +1,6 @@
 ---
 name: clawchat-set-greeting
-version: 1.2.0
+version: 1.2.1
 description: Use when the user wants to customize, change, set, or reset this agent's greetings — the first-load / activation greeting to the owner (~/clawchat/greeting.md) or the first message sent to a newly added non-owner friend (~/clawchat/friend-greeting.md).
 ---
 
@@ -58,8 +58,8 @@ Override it the same way with **`~/clawchat/friend-greeting.md`**: same rules as
 is an instruction to you, not the literal message; keep it short; no secrets; it is a
 partial override that the plugin may still append its own trailing line to). Delete or
 empty the file to restore the built-in instruction. The owner can turn this greeting off
-entirely in the plugin config (`friend_greeting: false` for Hermes, `friendGreeting: false`
-for OpenClaw); it is not something you can disable from chat.
+entirely in the plugin config (`friendGreeting: false`); it is not something you can
+disable from chat.
 
 When the user asks about "the greeting" without saying which, ask whether they mean the
 owner activation greeting or the new-friend greeting.
@@ -69,4 +69,5 @@ owner activation greeting or the new-friend greeting.
 - `greeting.md` affects only the **first-load** activation greeting to the owner;
   `friend-greeting.md` affects only the first message to a newly added non-owner friend.
   Neither changes later replies.
-- Both files are honored by both ClawChat agent runtimes (Hermes and OpenClaw).
+- These are the OpenClaw files. A Hermes agent on the same machine does not read them: it
+  keeps its own copies inside each Hermes profile.

package/skills/manifest.json

@@ -3,14 +3,14 @@
   "skills": {
     "openclaw": {
       "clawchat-core": {
-        "version": "1.9.0",
+        "version": "1.10.0",
         "path": "openclaw/clawchat-core/SKILL.md",
-        "sha256": "367b1df16439b084ab79430786a91dfa6b572714233678942032612f148a3e80",
-        "bytes": 16656
+        "sha256": "acaf36b1e7c477a707ed615b07cc1b87770e5c205e1e89e1c2a00519e964ac25",
+        "bytes": 17683
       },
       "clawchat-liveware": {
         "version": "1.2.3",
-        "path": "shared/clawchat-liveware/SKILL.md",
+        "path": "openclaw/clawchat-liveware/SKILL.md",
         "sha256": "2ed150bad7972d452b5b437d7c524ab24c27b0677419e590f087f50b7e7a3cdd",
         "bytes": 12591
       },
@@ -21,36 +21,36 @@
         "bytes": 8892
       },
       "clawchat-set-greeting": {
-        "version": "1.2.0",
-        "path": "shared/clawchat-set-greeting/SKILL.md",
-        "sha256": "bf1bbb71d287faafa499920f91450e99c27f638e7ee67bfb209a43418937a87c",
-        "bytes": 4184
+        "version": "1.2.1",
+        "path": "openclaw/clawchat-set-greeting/SKILL.md",
+        "sha256": "11d9195fa11c1d23cfe282f28f69ce899ae37bdcbfc79fecebee64f4f1a803da",
+        "bytes": 4195
       },
       "clawchat-liveware-sample": {
-        "version": "2.0.0",
+        "version": "2.0.1",
         "path": "openclaw/clawchat-liveware-sample/SKILL.md",
-        "sha256": "edafa5f802907c97c32af63feb5b62dcbb41c064649912c710808d27187aaa57",
-        "bytes": 13938
+        "sha256": "9b789fdd8e867af73dd0b851134b4287298f08e2fde87e3138f3d5b841aed0c5",
+        "bytes": 13943
       },
       "clawchat-orchestration": {
-        "version": "2.0.2",
+        "version": "2.2.0",
         "path": "shared/clawchat-orchestration/SKILL.md",
-        "sha256": "e32f29c5f41a7621732625a58a9f3d6fe365d7dde9bdcd892f9623e7fc180414",
-        "bytes": 9477
+        "sha256": "5f7319be1c77dfa265c8bce343d9d28ad52c2285667926b7fe8ba273d593d03c",
+        "bytes": 11700
       }
     },
     "hermes": {
       "clawchat-core": {
-        "version": "1.15.0",
+        "version": "1.17.0",
         "path": "hermes/clawchat-core/SKILL.md",
-        "sha256": "0d203321c4f5a8d3f85fa3e7de15803891c68c27d3862d47553d3de86fbee363",
-        "bytes": 23959
+        "sha256": "b3038b3a540645a19224ce198fdf77f1fbb109b843a3a80fe803a955d027d689",
+        "bytes": 27668
       },
       "clawchat-liveware": {
-        "version": "1.2.3",
-        "path": "shared/clawchat-liveware/SKILL.md",
-        "sha256": "2ed150bad7972d452b5b437d7c524ab24c27b0677419e590f087f50b7e7a3cdd",
-        "bytes": 12591
+        "version": "1.3.0",
+        "path": "hermes/clawchat-liveware/SKILL.md",
+        "sha256": "6bc6fff06c0694bf02323eff42926f15e7b6d6ed744e66b23a971f9290a9bb28",
+        "bytes": 14562
       },
       "clawchat-liveware-dev": {
         "version": "1.0.0",
@@ -59,22 +59,22 @@
         "bytes": 8892
       },
       "clawchat-set-greeting": {
-        "version": "1.2.0",
-        "path": "shared/clawchat-set-greeting/SKILL.md",
-        "sha256": "bf1bbb71d287faafa499920f91450e99c27f638e7ee67bfb209a43418937a87c",
-        "bytes": 4184
+        "version": "1.3.0",
+        "path": "hermes/clawchat-set-greeting/SKILL.md",
+        "sha256": "5092a2df48dfd61495bcd1f3be8f6603ca214b7f33afaddcf2d7c28442e91328",
+        "bytes": 5797
       },
       "clawchat-liveware-sample": {
-        "version": "2.0.0",
+        "version": "2.0.1",
         "path": "hermes/clawchat-liveware-sample/SKILL.md",
-        "sha256": "8278db2646d1553e41f4cf061c710b5363c3f41fa9ae32d8b1021fa2175b9a41",
-        "bytes": 13838
+        "sha256": "93d489ee7ee7607bc9a61defd16e06b1ee3c93d09a1115fa809ef06879e57cc4",
+        "bytes": 13843
       },
       "clawchat-orchestration": {
-        "version": "2.0.2",
+        "version": "2.2.0",
         "path": "shared/clawchat-orchestration/SKILL.md",
-        "sha256": "e32f29c5f41a7621732625a58a9f3d6fe365d7dde9bdcd892f9623e7fc180414",
-        "bytes": 9477
+        "sha256": "5f7319be1c77dfa265c8bce343d9d28ad52c2285667926b7fe8ba273d593d03c",
+        "bytes": 11700
       }
     }
   },

package/src/config.ts

@@ -112,6 +112,8 @@ export type OpenclawClawlingAccountConfig = {
   forwardToolCalls?: boolean;
   /** Emit approval/action rich fragments instead of plain fallback text. */
   richInteractions?: boolean;
+  /** Experimental: stream reply text with protocol §8 frames (default false). */
+  streamReplies?: boolean;
   /** Emit ONE consolidated awareness note to the agent when friend/conversation signals arrive. */
   awarenessNote?: boolean;
   /** Speak first to a newly added non-owner friend (default true). */
@@ -175,6 +177,7 @@ export const openclawClawlingAccountConfigSchema = {
     forwardThinking: { type: "boolean" },
     forwardToolCalls: { type: "boolean" },
     richInteractions: { type: "boolean" },
+    streamReplies: { type: "boolean" },
     awarenessNote: { type: "boolean" },
     friendGreeting: { type: "boolean" },
     livewareSample: { type: "boolean" },
@@ -313,6 +316,7 @@ export type ResolvedOpenclawClawlingAccount = {
   forwardThinking: boolean;
   forwardToolCalls: boolean;
   richInteractions: boolean;
+  streamReplies: boolean;
   awarenessNote: boolean;
   friendGreeting: boolean;
   livewareSample: boolean;
@@ -651,6 +655,8 @@ export function resolveOpenclawClawlingAccount(
     typeof channel.forwardToolCalls === "boolean" ? channel.forwardToolCalls : false;
   const richInteractions =
     typeof channel.richInteractions === "boolean" ? channel.richInteractions : false;
+  const streamReplies =
+    typeof channel.streamReplies === "boolean" ? channel.streamReplies : false;
   const awarenessNote =
     typeof channel.awarenessNote === "boolean" ? channel.awarenessNote : false;
   const friendGreeting =
@@ -683,6 +689,7 @@ export function resolveOpenclawClawlingAccount(
     forwardThinking,
     forwardToolCalls,
     richInteractions,
+    streamReplies,
     awarenessNote,
     friendGreeting,
     livewareSample,

package/src/framework-error-copy.ts

@@ -0,0 +1,185 @@
+/**
+ * Owner-language copy for OpenClaw framework errors that reach a ClawChat
+ * conversation as a final reply.
+ *
+ * The host hands the channel its own English failure text (rate limit, expired
+ * provider login, context overflow, billing, timeouts — see
+ * `docs/clawchat-plugin-openclaw.md` "Framework error replies"). Posting that
+ * raw leaves a non-English owner with a message they cannot act on. Instead we
+ * lead with one sentence in the owner's language saying what happened and what
+ * to do, then keep the original text at the end so it can still be reported.
+ */
+
+import { resolveOwnerLanguage, type OwnerLanguage } from "./owner-language.ts";
+
+export type FrameworkErrorCategory =
+  | "rate_limit"
+  | "auth"
+  | "context_overflow"
+  | "billing"
+  | "timeout"
+  | "unknown";
+
+const WARNING_PREFIX = "⚠️";
+
+/**
+ * Host lifecycle notices that look like errors but are not. The host itself
+ * emits "Gateway restarting…" without `isError`; it is listed here too so a
+ * future `⚠️`/`isError` variant still passes through untouched.
+ */
+const PASS_THROUGH = [/^(?:⚠️\s*)?gateway restarting\b/i];
+
+/**
+ * Ordered: the first entry whose patterns match wins. Context overflow sits
+ * before timeout because the host's compaction failure reads "Context is too
+ * large and auto-compaction timed out"; the weak billing words (quota, credit,
+ * billing) sit after rate limit because the host's bare-429 copy names them as
+ * possible causes of what is reported as a 429.
+ */
+const CATEGORY_PATTERNS: ReadonlyArray<[Exclude<FrameworkErrorCategory, "unknown">, RegExp[]]> = [
+  [
+    "context_overflow",
+    [
+      /context[\s_-]*(?:length|window|overflow|limit)/i,
+      /maximum context/i,
+      /context[\s_-]*length[\s_-]*exceeded/i,
+      /\bcontext is too (?:large|long)\b/i,
+      /\b(?:prompt|input|conversation|request|message)s? (?:is |was )?too (?:long|large)\b/i,
+      /\btoo many (?:input )?tokens\b/i,
+    ],
+  ],
+  [
+    // Unambiguous billing wording first: provider quota errors often ride an
+    // HTTP 429 ("429 You exceeded your current quota"), which would otherwise
+    // read as a rate limit.
+    "billing",
+    [
+      /insufficient[\s_-]*(?:quota|balance|credits?|funds)/i,
+      /exceeded your current quota/i,
+      /out of credits?\b/i,
+      /billing error/i,
+      /\b402\b/,
+      /payment required/i,
+    ],
+  ],
+  [
+    "rate_limit",
+    [
+      /rate[\s_-]*limit/i,
+      /\b429\b/,
+      /overloaded/i,
+      /too many requests/i,
+      /needs a short break/i,
+      /\bat capacity\b/i,
+      /asking us to slow down/i,
+      /resource[\s_-]*exhausted/i,
+    ],
+  ],
+  [
+    "auth",
+    [
+      /\b401\b/,
+      /unauthori[sz]ed/i,
+      /authenticat(?:e|ion)/i,
+      /\bre-?auth\b/i,
+      /(?:invalid|incorrect|missing|wrong|expired) (?:x-)?api[\s_-]*key/i,
+      /api[\s_-]*key (?:is |was )?(?:invalid|incorrect|missing|expired|not valid)/i,
+      /log(?:in|-in)? (?:has )?(?:expired|failed)/i,
+      /\bsaved logins?\b/i,
+      /couldn't sign in|could not sign in|sign[\s-]*in (?:has )?expired/i,
+      /\bauth profile\b/i,
+      /(?:oauth|access|provider) token (?:has |may have )?expired/i,
+    ],
+  ],
+  [
+    "billing",
+    [/billing/i, /\bquota\b/i, /\bcredits?\b/i, /\bbalance\b/i],
+  ],
+  ["timeout", [/timed?[\s_-]*out\b/i, /\btimeout\b/i, /\bwatchdog\b/i]],
+];
+
+export function classifyFrameworkError(text: string): FrameworkErrorCategory {
+  for (const [category, patterns] of CATEGORY_PATTERNS) {
+    if (patterns.some((p) => p.test(text))) return category;
+  }
+  return "unknown";
+}
+
+/**
+ * Whether a final reply is a framework error to be rewritten. `isError` is the
+ * authority; a leading "⚠️" is only a fallback for host copy that does not set
+ * it. Host lifecycle notices pass through.
+ */
+export function isFrameworkErrorReply(payload: { isError?: boolean }, text: string): boolean {
+  const trimmed = text.trim();
+  if (!trimmed) return false;
+  if (PASS_THROUGH.some((p) => p.test(trimmed))) return false;
+  return payload.isError === true || trimmed.startsWith(WARNING_PREFIX);
+}
+
+const COPY: Record<FrameworkErrorCategory | "original_label", Record<OwnerLanguage, string>> = {
+  rate_limit: {
+    zh: "模型服务这会儿太忙，暂时不接新请求。过几分钟再发一次。",
+    zh_Hant: "模型服務這會兒太忙，暫時不接新請求。過幾分鐘再傳一次。",
+    en: "The model service is busy right now and isn't taking new requests. Try again in a few minutes.",
+    ja: "モデルサービスが混み合っていて、いまは新しいリクエストを受け付けていません。数分後にもう一度送ってください。",
+    es: "El servicio del modelo está saturado y ahora no acepta nuevas solicitudes. Vuelve a enviarlo en unos minutos.",
+    ko: "모델 서비스가 지금 너무 바빠서 새 요청을 받지 않고 있어요. 몇 분 뒤에 다시 보내 주세요.",
+  },
+  auth: {
+    zh: "模型服务的登录失效了，或者 API Key 不对。请在运行 OpenClaw 的那台机器上重新登录模型服务（或更新 API Key），再发一次。",
+    zh_Hant: "模型服務的登入失效了，或者 API Key 不對。請在執行 OpenClaw 的那台機器上重新登入模型服務（或更新 API Key），再傳一次。",
+    en: "The model service sign-in has expired, or the API key is wrong. On the machine running OpenClaw, sign in to the model service again (or update the API key), then try again.",
+    ja: "モデルサービスのログインが切れているか、API キーが正しくありません。OpenClaw を動かしているマシンでモデルサービスにログインし直して（または API キーを更新して）から、もう一度送ってください。",
+    es: "La sesión del servicio del modelo ha caducado o la clave de API no es correcta. En el equipo donde se ejecuta OpenClaw, vuelve a iniciar sesión en el servicio del modelo (o actualiza la clave de API) y envíalo de nuevo.",
+    ko: "모델 서비스 로그인이 만료됐거나 API 키가 올바르지 않아요. OpenClaw를 실행 중인 기기에서 모델 서비스에 다시 로그인(또는 API 키를 업데이트)한 뒤 다시 보내 주세요.",
+  },
+  context_overflow: {
+    zh: "这段对话太长，模型装不下了。发送 /new 开始新对话，再接着说。",
+    zh_Hant: "這段對話太長，模型裝不下了。傳送 /new 開始新對話，再接著說。",
+    en: "This conversation is too long for the model. Send /new to start a new conversation, then carry on.",
+    ja: "この会話が長すぎて、モデルが処理しきれません。/new を送って新しい会話を始めてから続けてください。",
+    es: "Esta conversación es demasiado larga para el modelo. Envía /new para empezar una conversación nueva y sigue desde ahí.",
+    ko: "이 대화가 너무 길어서 모델이 처리할 수 없어요. /new를 보내 새 대화를 시작한 뒤 이어서 말해 주세요.",
+  },
+  billing: {
+    zh: "模型服务的账户余额不足。请到模型服务商那里充值或查看账单，再发一次。",
+    zh_Hant: "模型服務的帳戶餘額不足。請到模型服務商那裡儲值或查看帳單，再傳一次。",
+    en: "The model service account is out of credit. Top up or check billing with your model provider, then try again.",
+    ja: "モデルサービスのアカウント残高が不足しています。モデルの提供元でチャージするか請求状況を確認してから、もう一度送ってください。",
+    es: "La cuenta del servicio del modelo no tiene saldo suficiente. Recarga o revisa la facturación con tu proveedor del modelo y vuelve a enviarlo.",
+    ko: "모델 서비스 계정 잔액이 부족해요. 모델 제공업체에서 충전하거나 결제 내역을 확인한 뒤 다시 보내 주세요.",
+  },
+  timeout: {
+    zh: "这次处理超时，没有做完。再发一次试试；总是超时的话，把任务拆小一点。",
+    zh_Hant: "這次處理逾時，沒有做完。再傳一次試試；總是逾時的話，把任務拆小一點。",
+    en: "This took too long and didn't finish. Try again; if it keeps timing out, break the task into smaller steps.",
+    ja: "処理がタイムアウトして、最後まで終わりませんでした。もう一度送ってみてください。何度もタイムアウトする場合は、タスクを小さく分けてください。",
+    es: "Esto tardó demasiado y no terminó. Vuelve a intentarlo; si sigue pasando, divide la tarea en partes más pequeñas.",
+    ko: "처리 시간이 초과되어 끝까지 마치지 못했어요. 다시 보내 보세요. 계속 시간이 초과되면 작업을 더 작게 나눠 주세요.",
+  },
+  unknown: {
+    zh: "这次出错了，没有做完。再发一次试试；还不行的话，可以把下面的原文发给 ClawChat 客服。",
+    zh_Hant: "這次出錯了，沒有做完。再傳一次試試；還不行的話，可以把下面的原文傳給 ClawChat 客服。",
+    en: "Something went wrong and this didn't finish. Try again; if it still fails, send the original message below to ClawChat support.",
+    ja: "エラーが起きて、最後まで終わりませんでした。もう一度送ってみてください。それでもだめなら、下の原文を ClawChat サポートに送ってください。",
+    es: "Algo salió mal y esto no terminó. Vuelve a intentarlo; si sigue fallando, envía el texto original de abajo al soporte de ClawChat.",
+    ko: "오류가 생겨 끝까지 마치지 못했어요. 다시 보내 보세요. 그래도 안 되면 아래 원문을 ClawChat 고객지원에 보내 주세요.",
+  },
+  original_label: {
+    zh: "原文：",
+    zh_Hant: "原文：",
+    en: "Original:",
+    ja: "原文：",
+    es: "Texto original:",
+    ko: "원문:",
+  },
+};
+
+/** `<owner-language sentence>\n\n<label> <original text>`. */
+export function formatFrameworkErrorForOwner(text: string, locale?: string | null): string {
+  const language = resolveOwnerLanguage(locale);
+  const original = text.trim();
+  const category = classifyFrameworkError(original);
+  return `${COPY[category][language]}\n\n${COPY.original_label[language]} ${original}`;
+}