@clawling/clawchat-plugin-openclaw 2026.9.18-1 → 2026.9.19-1

package/dist/src/activation-greeting.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { languageDisplayName } from "./owner-language.js";
 // Worded to make the greeting the single required action. Earlier wording
 // ("ClawChat activation bootstrap: ... do both ...") led some agents to treat
 // it as a setup task and write a `BOOTSTRAP.md` file instead of replying, so
@@ -15,13 +16,27 @@ const ACTIVATION_BOOTSTRAP_FALLBACK = [
 ].join("\n");
 // Cross-plugin, user-editable override read lazily so edits apply on the next
 // first-load without a restart. Any read failure falls back to the built-in text.
-export function buildActivationBootstrapText(homeDir = os.homedir()) {
+// The override does NOT fully replace the built-in text: when the owner's
+// language is known a trailing instruction is appended (see below), because the
+// override says what to say, not which language to say it in — that's a
+// cross-cutting concern the user did not opt out of by supplying their own
+// greeting.
+//
+// `language` is nullable and defaults to null on purpose. The owner-profile
+// cache is cold on a fresh install, and this prompt is dispatched immediately
+// on connect without awaiting it, so the caller often has NO locale. Asserting
+// "Reply in English." to an owner who never said they speak English is worse
+// than asserting nothing — with no line the model infers the language from
+// context, which is what it did before this feature existed. So: unknown
+// language ⇒ no line at all.
+export function buildActivationBootstrapText(homeDir = os.homedir(), language = null) {
     const greetingPath = path.join(homeDir, "clawchat", "greeting.md");
+    let base = ACTIVATION_BOOTSTRAP_FALLBACK;
     try {
         const raw = fs.readFileSync(greetingPath);
         const override = new TextDecoder("utf-8", { fatal: true }).decode(raw).trim();
         if (override.length > 0) {
-            return override;
+            base = override;
         }
     }
     catch (error) {
@@ -30,5 +45,7 @@ export function buildActivationBootstrapText(homeDir = os.homedir()) {
             console.warn(`clawchat.greeting failed to read override ${greetingPath}:`, error);
         }
     }
-    return ACTIVATION_BOOTSTRAP_FALLBACK;
+    if (language === null)
+        return base;
+    return `${base}\n\nReply in ${languageDisplayName(language)}.`;
 }

package/dist/src/friend-greeting.js

@@ -16,6 +16,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { EVENT } from "./protocol-types.js";
+import { languageDisplayName } from "./owner-language.js";
 export const FRIEND_GREETING_FALLBACK = [
     "A ClawChat user has just become your friend. You are now in a direct conversation with them; they are not your owner.",
     "Reply now with one short, friendly greeting message in this conversation: introduce yourself by name, say you are an AI agent acting on behalf of your owner, and invite them to tell you what they need.",
@@ -24,14 +25,20 @@ export const FRIEND_GREETING_FALLBACK = [
 ].join("\n");
 // Cross-plugin, user-editable override read lazily so edits apply on the next
 // friend without a restart. Any read failure falls back to the built-in text.
-// Mirrors `buildActivationBootstrapText` (`~/clawchat/greeting.md`).
-export function buildFriendGreetingText(homeDir = os.homedir()) {
+// Mirrors `buildActivationBootstrapText` (`~/clawchat/greeting.md`), including
+// its nullable `language`: the override does NOT fully replace the built-in
+// text — when the owner's language is known a trailing instruction is appended
+// (see below), because the override says what to say, not which language to say
+// it in. When it is NOT known the line is omitted entirely rather than guessed;
+// see `buildActivationBootstrapText` for why "en" is the wrong guess here.
+export function buildFriendGreetingText(homeDir = os.homedir(), language = null) {
     const greetingPath = path.join(homeDir, "clawchat", "friend-greeting.md");
+    let base = FRIEND_GREETING_FALLBACK;
     try {
         const raw = fs.readFileSync(greetingPath);
         const override = new TextDecoder("utf-8", { fatal: true }).decode(raw).trim();
         if (override.length > 0) {
-            return override;
+            base = override;
         }
     }
     catch (error) {
@@ -40,7 +47,9 @@ export function buildFriendGreetingText(homeDir = os.homedir()) {
             console.warn(`clawchat.friend-greeting failed to read override ${greetingPath}:`, error);
         }
     }
-    return FRIEND_GREETING_FALLBACK;
+    if (language === null)
+        return base;
+    return `${base}\n\nReply in ${languageDisplayName(language)}.`;
 }
 /**
  * Synthetic inbound envelope for the friend greeting turn. Same invariant as
@@ -49,8 +58,8 @@ export function buildFriendGreetingText(homeDir = os.homedir()) {
  * refused at the outbound boundary after a full LLM turn has been spent.
  */
 export function buildFriendGreetingEnvelope(params) {
-    const { account, conversationId, friendUserId } = params;
-    const text = buildFriendGreetingText();
+    const { account, conversationId, friendUserId, language } = params;
+    const text = buildFriendGreetingText(undefined, language);
     const now = Date.now();
     return {
         version: "2",

package/dist/src/liveware-sample.js

@@ -13,6 +13,7 @@ import { DEFAULT_SKILLS_REF, OFFICIAL_SKILLS_BASE } from "./skill-update.js";
 import { livewareCliEnv } from "./liveware-cli.js";
 import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
 import { normalizeOpenclawClawlingAccountId } from "./config.js";
+import { resolveOwnerLanguage } from "./owner-language.js";
 export const LIVEWARES_TARGET = "openclaw";
 export const LIVEWARE_SAMPLE_ID = "liveware-sample";
 export const LIVEWARE_SAMPLE_APP_NAME = "Liveware Sample";
@@ -568,10 +569,51 @@ export async function livewareAppCreate(opts) {
         throw new Error(`liveware app create: cannot parse app id from output: ${stdout.slice(0, 500)}`);
     return appId;
 }
-export const LIVEWARE_SAMPLE_INTRO_TEXT = "我给你安装了一个 liveware 演示应用「Liveware Sample」。" +
-    "入口：在我们的对话页面，点右上角的「应用」按钮（✦），在打开的面板里选名为「Liveware Sample」的应用。" +
-    "页面上有完整的使用引导，试试对我说：把标题改成 Hello Liveware。" +
-    "你在页面上点的按钮、提交的留言我也能看到，随时问我。";
+/** Last-resort copy when the content tree's table cannot be read. English only:
+ *  a second full translation set in-process would be a competing source of truth. */
+export const LIVEWARE_SAMPLE_INTRO_FALLBACK_EN = "I've installed a liveware demo app for you — \"Liveware Sample\". " +
+    "To open it: in our chat, tap the Apps button (✦) in the top-right corner, " +
+    "then pick \"Liveware Sample\" in the panel. " +
+    "The page has a full walkthrough — try saying to me: Change the title to Hello Liveware. " +
+    "I can also see the buttons you tap and the notes you submit there, so just ask me anytime.";
+/** Read the localized intro from the installed sample's `intro.i18n.json`.
+ *  Any failure returns the English fallback — delivery must never be blocked
+ *  by a content-tree problem.
+ *
+ *  Every one of the four degradation modes (missing file / corrupt JSON /
+ *  missing key / empty value) warns first. Falling back silently means a
+ *  mistake in the content tree ships English to every non-English owner with
+ *  zero signal anywhere; the fallback is the safety net, not the plan. Kept
+ *  symmetric with `load_intro_text` in the hermes plugin. */
+export function loadIntroText(appDir, language) {
+    const tablePath = path.join(appDir, "intro.i18n.json");
+    let raw;
+    try {
+        raw = fs.readFileSync(tablePath, "utf8");
+    }
+    catch (error) {
+        console.warn(`clawchat.liveware-sample intro table unreadable at ${tablePath}; using the English fallback:`, error);
+        return LIVEWARE_SAMPLE_INTRO_FALLBACK_EN;
+    }
+    let value;
+    try {
+        const table = JSON.parse(raw);
+        value = table?.intro?.[language];
+    }
+    catch (error) {
+        console.warn(`clawchat.liveware-sample intro table at ${tablePath} is not valid JSON; using the English fallback:`, error);
+        return LIVEWARE_SAMPLE_INTRO_FALLBACK_EN;
+    }
+    if (typeof value !== "string") {
+        console.warn(`clawchat.liveware-sample intro table at ${tablePath} has no "${language}" entry; using the English fallback`);
+        return LIVEWARE_SAMPLE_INTRO_FALLBACK_EN;
+    }
+    if (value.trim().length === 0) {
+        console.warn(`clawchat.liveware-sample intro table at ${tablePath} has an empty "${language}" entry; using the English fallback`);
+        return LIVEWARE_SAMPLE_INTRO_FALLBACK_EN;
+    }
+    return value;
+}
 const DEFAULT_SAMPLE_PORT = 43110;
 const RESTART_WINDOW_MS = 30 * 60 * 1000;
 const MAX_RESTARTS_PER_WINDOW = 5;
@@ -1007,7 +1049,8 @@ export class LivewareSampleSupervisor {
         const { deps } = this;
         let delivered = false;
         try {
-            delivered = await deps.notifyOwner(LIVEWARE_SAMPLE_INTRO_TEXT);
+            const language = resolveOwnerLanguage(deps.resolveOwnerLocale?.() ?? null);
+            delivered = await deps.notifyOwner(loadIntroText(path.join(deps.sampleRoot, "app"), language));
         }
         catch (err) {
             deps.log?.debug?.(`liveware-sample: intro send error: ${String(err)}`);

package/dist/src/owner-language.js

@@ -0,0 +1,54 @@
+/**
+ * Resolve the owner's reported app language into one of the six languages the
+ * ClawChat content tree carries. `agent_owner_locale` comes from the owner's
+ * ClawChat app setting and is omitted entirely when they never reported one —
+ * every unresolvable case lands on English rather than guessing.
+ */
+export const OWNER_LANGUAGES = [
+    "en", "es", "ja", "ko", "zh", "zh_Hant",
+];
+const DISPLAY_NAMES = {
+    en: "English",
+    es: "Spanish",
+    ja: "Japanese",
+    ko: "Korean",
+    zh: "Simplified Chinese",
+    zh_Hant: "Traditional Chinese",
+};
+// Traditional-Chinese regions must be tested before the bare `zh` prefix,
+// because they also start with "zh".
+const TRADITIONAL_PREFIXES = ["zh-hant", "zh-tw", "zh-hk", "zh-mo"];
+export function resolveOwnerLanguage(locale) {
+    const tag = String(locale ?? "").trim().toLowerCase().replace(/_/g, "-");
+    if (!tag)
+        return "en";
+    if (TRADITIONAL_PREFIXES.some((p) => tag.startsWith(p)))
+        return "zh_Hant";
+    if (tag.startsWith("zh"))
+        return "zh";
+    if (tag.startsWith("ja"))
+        return "ja";
+    if (tag.startsWith("ko"))
+        return "ko";
+    if (tag.startsWith("es"))
+        return "es";
+    return "en";
+}
+export function languageDisplayName(lang) {
+    return DISPLAY_NAMES[lang];
+}
+/**
+ * Resolve a locale ONLY when one was actually reported; `null` otherwise.
+ *
+ * `resolveOwnerLanguage` must answer with a language because the intro lookup
+ * has to pick one copy and `en` is the documented default. The greeting path
+ * is the opposite case: the language line is an explicit assertion to the
+ * model, and the owner-profile cache is COLD on a fresh install (the
+ * activation row is written without a locale and the bootstrap fires
+ * immediately on connect). Collapsing "unknown" into "en" there tells a
+ * Chinese owner's agent to reply in English. Callers on the greeting path use
+ * this and omit the line entirely when it returns null.
+ */
+export function resolveOwnerLanguageIfKnown(locale) {
+    return String(locale ?? "").trim() ? resolveOwnerLanguage(locale) : null;
+}

package/dist/src/runtime.js

@@ -6,6 +6,7 @@ import { createOpenclawClawlingClient, resolveOpenclawClawlingDeviceId } from ".
 import { createOpenclawClawlingApiClient } from "./api-client.js";
 import { buildActivationBootstrapText } from "./activation-greeting.js";
 import { buildFriendGreetingEnvelope } from "./friend-greeting.js";
+import { resolveOwnerLanguageIfKnown } from "./owner-language.js";
 import { reportPluginVersionSafe, resolvePluginVersion } from "./plugin-report.js";
 import { readOnboardingReport } from "./onboarding-report.js";
 import { ensureLivewareCli, livewareCliHomeDir, livewareSampleRootDir, resolveLivewarePath, } from "./liveware-cli.js";
@@ -367,7 +368,7 @@ function withClawChatSessionScope(cfg) {
  * the source and skip rather than hand an unroutable id down here.
  */
 function buildActivationBootstrapEnvelope(params) {
-    const text = buildActivationBootstrapText();
+    const text = buildActivationBootstrapText(undefined, params.language);
     const now = Date.now();
     return {
         version: "2",
@@ -887,6 +888,7 @@ export async function startOpenclawClawlingGateway(params) {
                 return await client.registerApp(p);
             },
             notifyOwner: (text) => livewareSampleNotify(text),
+            resolveOwnerLocale: () => store.getOwnerProfile?.({ platform: "openclaw", accountId })?.locale ?? null,
             fetchFn: globalThis.fetch,
             log: {
                 warn: (m) => log?.info?.(m),
@@ -2195,7 +2197,17 @@ export async function startOpenclawClawlingGateway(params) {
                 return;
             }
             log?.info?.(`[${accountId}] clawchat-plugin-openclaw friend greeting dispatch friend=${friendUserId} chat_id=${conversationId}`);
-            await handleInboundEnvelope(buildFriendGreetingEnvelope({ account, conversationId, friendUserId }));
+            // The recipient here is the new friend, NOT the owner — but we
+            // deliberately use the OWNER's language anyway: friends are usually in
+            // the same language circle, and the backend only exposes `locale` on
+            // the owner profile endpoint, so no third-party locale is obtainable.
+            //
+            // `…IfKnown`, not `resolveOwnerLanguage`: this is a synchronous read of a
+            // cache that may never have been filled, and it must NOT be awaited here.
+            // A cold cache yields null and the greeting simply carries no language
+            // line — see `buildActivationBootstrapText`.
+            const language = resolveOwnerLanguageIfKnown(store?.getOwnerProfile?.({ platform: "openclaw", accountId })?.locale ?? null);
+            await handleInboundEnvelope(buildFriendGreetingEnvelope({ account, conversationId, friendUserId, language }));
         })().catch((err) => {
             log?.error?.(`[${accountId}] clawchat-plugin-openclaw friend greeting failed friend=${friendUserId}: ${err instanceof Error ? err.message : String(err)}`);
         });
@@ -3047,7 +3059,18 @@ export async function startOpenclawClawlingGateway(params) {
             claimedInFlight = true;
             incrementActivationBootstrapInFlight(accountId);
             bootstrapGreetingDelivered = false;
-            const result = await handleInboundEnvelope(buildActivationBootstrapEnvelope({ account, conversationId: claimedBootstrap.conversationId }));
+            // Synchronous, un-awaited read: the bootstrap is dispatched the moment
+            // the connection comes up (`void dispatchActivationBootstrap()`), so on a
+            // fresh install `owner_profile` has not been pulled yet and there is no
+            // locale to be had. `…IfKnown` returns null there and the prompt ships
+            // with no language line, instead of hard-asserting English at an owner
+            // who may not speak it. Do NOT add an await here to reach the locale.
+            const language = resolveOwnerLanguageIfKnown(store?.getOwnerProfile?.({ platform: "openclaw", accountId })?.locale ?? null);
+            const result = await handleInboundEnvelope(buildActivationBootstrapEnvelope({
+                account,
+                conversationId: claimedBootstrap.conversationId,
+                language,
+            }));
             if (result !== "submitted") {
                 settleBootstrap("turn was not submitted");
                 return;

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.11.0";
+export const DEFAULT_SKILLS_REF = "skills-v1.12.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/package.json

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

package/src/activation-greeting.ts

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { languageDisplayName, type OwnerLanguage } from "./owner-language.ts";
 
 // Worded to make the greeting the single required action. Earlier wording
 // ("ClawChat activation bootstrap: ... do both ...") led some agents to treat
@@ -17,13 +18,30 @@ const ACTIVATION_BOOTSTRAP_FALLBACK = [
 
 // Cross-plugin, user-editable override read lazily so edits apply on the next
 // first-load without a restart. Any read failure falls back to the built-in text.
-export function buildActivationBootstrapText(homeDir: string = os.homedir()): string {
+// The override does NOT fully replace the built-in text: when the owner's
+// language is known a trailing instruction is appended (see below), because the
+// override says what to say, not which language to say it in — that's a
+// cross-cutting concern the user did not opt out of by supplying their own
+// greeting.
+//
+// `language` is nullable and defaults to null on purpose. The owner-profile
+// cache is cold on a fresh install, and this prompt is dispatched immediately
+// on connect without awaiting it, so the caller often has NO locale. Asserting
+// "Reply in English." to an owner who never said they speak English is worse
+// than asserting nothing — with no line the model infers the language from
+// context, which is what it did before this feature existed. So: unknown
+// language ⇒ no line at all.
+export function buildActivationBootstrapText(
+  homeDir: string = os.homedir(),
+  language: OwnerLanguage | null = null,
+): string {
   const greetingPath = path.join(homeDir, "clawchat", "greeting.md");
+  let base = ACTIVATION_BOOTSTRAP_FALLBACK;
   try {
     const raw = fs.readFileSync(greetingPath);
     const override = new TextDecoder("utf-8", { fatal: true }).decode(raw).trim();
     if (override.length > 0) {
-      return override;
+      base = override;
     }
   } catch (error) {
     const code = (error as NodeJS.ErrnoException).code;
@@ -31,5 +49,6 @@ export function buildActivationBootstrapText(homeDir: string = os.homedir()): st
       console.warn(`clawchat.greeting failed to read override ${greetingPath}:`, error);
     }
   }
-  return ACTIVATION_BOOTSTRAP_FALLBACK;
+  if (language === null) return base;
+  return `${base}\n\nReply in ${languageDisplayName(language)}.`;
 }

package/src/friend-greeting.ts

@@ -17,6 +17,7 @@ import os from "node:os";
 import path from "node:path";
 import { EVENT, type Envelope } from "./protocol-types.ts";
 import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+import { languageDisplayName, type OwnerLanguage } from "./owner-language.ts";
 
 export const FRIEND_GREETING_FALLBACK = [
   "A ClawChat user has just become your friend. You are now in a direct conversation with them; they are not your owner.",
@@ -27,14 +28,23 @@ export const FRIEND_GREETING_FALLBACK = [
 
 // Cross-plugin, user-editable override read lazily so edits apply on the next
 // friend without a restart. Any read failure falls back to the built-in text.
-// Mirrors `buildActivationBootstrapText` (`~/clawchat/greeting.md`).
-export function buildFriendGreetingText(homeDir: string = os.homedir()): string {
+// Mirrors `buildActivationBootstrapText` (`~/clawchat/greeting.md`), including
+// its nullable `language`: the override does NOT fully replace the built-in
+// text — when the owner's language is known a trailing instruction is appended
+// (see below), because the override says what to say, not which language to say
+// it in. When it is NOT known the line is omitted entirely rather than guessed;
+// see `buildActivationBootstrapText` for why "en" is the wrong guess here.
+export function buildFriendGreetingText(
+  homeDir: string = os.homedir(),
+  language: OwnerLanguage | null = null,
+): string {
   const greetingPath = path.join(homeDir, "clawchat", "friend-greeting.md");
+  let base = FRIEND_GREETING_FALLBACK;
   try {
     const raw = fs.readFileSync(greetingPath);
     const override = new TextDecoder("utf-8", { fatal: true }).decode(raw).trim();
     if (override.length > 0) {
-      return override;
+      base = override;
     }
   } catch (error) {
     const code = (error as NodeJS.ErrnoException).code;
@@ -42,7 +52,8 @@ export function buildFriendGreetingText(homeDir: string = os.homedir()): string
       console.warn(`clawchat.friend-greeting failed to read override ${greetingPath}:`, error);
     }
   }
-  return FRIEND_GREETING_FALLBACK;
+  if (language === null) return base;
+  return `${base}\n\nReply in ${languageDisplayName(language)}.`;
 }
 
 export interface BuildFriendGreetingEnvelopeParams {
@@ -51,6 +62,22 @@ export interface BuildFriendGreetingEnvelopeParams {
   conversationId: string;
   /** The new friend's `usr_…` id — becomes the sender so the turn's session and sender metadata resolve to them. */
   friendUserId: string;
+  /**
+   * Language the greeting should reply in, or `null` when the owner's locale
+   * is not known yet — in which case no language line is emitted at all.
+   *
+   * Required, not optional: the activation-greeting equivalent is required,
+   * and an optional one here would let a future call site silently omit it and
+   * re-acquire the default that item 1 of the cross-repo review removed. Pass
+   * an explicit `null` to mean "unknown".
+   *
+   * The recipient here is the new friend, NOT the owner — but we deliberately
+   * use the OWNER's language anyway: friends are usually in the same language
+   * circle, and the backend only exposes `locale` on the owner profile
+   * endpoint, so no third-party locale is obtainable. Do not "fix" this into a
+   * friend-specific lookup.
+   */
+  language: OwnerLanguage | null;
 }
 
 /**
@@ -60,8 +87,8 @@ export interface BuildFriendGreetingEnvelopeParams {
  * refused at the outbound boundary after a full LLM turn has been spent.
  */
 export function buildFriendGreetingEnvelope(params: BuildFriendGreetingEnvelopeParams): Envelope {
-  const { account, conversationId, friendUserId } = params;
-  const text = buildFriendGreetingText();
+  const { account, conversationId, friendUserId, language } = params;
+  const text = buildFriendGreetingText(undefined, language);
   const now = Date.now();
   return {
     version: "2",

package/src/liveware-sample.ts

@@ -14,6 +14,7 @@ import type { LivewareSampleRow, LivewareSampleUpsert } from "./storage.ts";
 import { livewareCliEnv, type LivewareLogger } from "./liveware-cli.ts";
 import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
 import { normalizeOpenclawClawlingAccountId } from "./config.ts";
+import { resolveOwnerLanguage, type OwnerLanguage } from "./owner-language.ts";
 
 export const LIVEWARES_TARGET = "openclaw";
 export const LIVEWARE_SAMPLE_ID = "liveware-sample";
@@ -712,6 +713,10 @@ export type LivewareSampleSupervisorDeps = {
   listApps: () => Promise<{ apps: { app_id?: string }[] }>;
   registerApp: (p: { name: string; appId: string; url: string }) => Promise<unknown>;
   notifyOwner: (text: string) => Promise<boolean>;
+  /** The owner's reported app locale (`agent_owner_locale`), read lazily:
+   *  the intro can be retried for ~10 minutes, by which time a locale that
+   *  was absent at construction may have landed. */
+  resolveOwnerLocale?: () => string | null;
   fetchFn: FetchLike;
   ref?: string;
   spawnFn?: SpawnLike;
@@ -726,11 +731,61 @@ export type LivewareSampleSupervisorDeps = {
   setTimeoutFn?: typeof setTimeout;
 };
 
-export const LIVEWARE_SAMPLE_INTRO_TEXT =
-  "我给你安装了一个 liveware 演示应用「Liveware Sample」。" +
-  "入口：在我们的对话页面，点右上角的「应用」按钮（✦），在打开的面板里选名为「Liveware Sample」的应用。" +
-  "页面上有完整的使用引导，试试对我说：把标题改成 Hello Liveware。" +
-  "你在页面上点的按钮、提交的留言我也能看到，随时问我。";
+/** Last-resort copy when the content tree's table cannot be read. English only:
+ *  a second full translation set in-process would be a competing source of truth. */
+export const LIVEWARE_SAMPLE_INTRO_FALLBACK_EN =
+  "I've installed a liveware demo app for you — \"Liveware Sample\". " +
+  "To open it: in our chat, tap the Apps button (✦) in the top-right corner, " +
+  "then pick \"Liveware Sample\" in the panel. " +
+  "The page has a full walkthrough — try saying to me: Change the title to Hello Liveware. " +
+  "I can also see the buttons you tap and the notes you submit there, so just ask me anytime.";
+
+/** Read the localized intro from the installed sample's `intro.i18n.json`.
+ *  Any failure returns the English fallback — delivery must never be blocked
+ *  by a content-tree problem.
+ *
+ *  Every one of the four degradation modes (missing file / corrupt JSON /
+ *  missing key / empty value) warns first. Falling back silently means a
+ *  mistake in the content tree ships English to every non-English owner with
+ *  zero signal anywhere; the fallback is the safety net, not the plan. Kept
+ *  symmetric with `load_intro_text` in the hermes plugin. */
+export function loadIntroText(appDir: string, language: OwnerLanguage): string {
+  const tablePath = path.join(appDir, "intro.i18n.json");
+  let raw: string;
+  try {
+    raw = fs.readFileSync(tablePath, "utf8");
+  } catch (error) {
+    console.warn(
+      `clawchat.liveware-sample intro table unreadable at ${tablePath}; using the English fallback:`,
+      error,
+    );
+    return LIVEWARE_SAMPLE_INTRO_FALLBACK_EN;
+  }
+  let value: unknown;
+  try {
+    const table = JSON.parse(raw) as { intro?: Record<string, unknown> } | null;
+    value = table?.intro?.[language];
+  } catch (error) {
+    console.warn(
+      `clawchat.liveware-sample intro table at ${tablePath} is not valid JSON; using the English fallback:`,
+      error,
+    );
+    return LIVEWARE_SAMPLE_INTRO_FALLBACK_EN;
+  }
+  if (typeof value !== "string") {
+    console.warn(
+      `clawchat.liveware-sample intro table at ${tablePath} has no "${language}" entry; using the English fallback`,
+    );
+    return LIVEWARE_SAMPLE_INTRO_FALLBACK_EN;
+  }
+  if (value.trim().length === 0) {
+    console.warn(
+      `clawchat.liveware-sample intro table at ${tablePath} has an empty "${language}" entry; using the English fallback`,
+    );
+    return LIVEWARE_SAMPLE_INTRO_FALLBACK_EN;
+  }
+  return value;
+}
 
 const DEFAULT_SAMPLE_PORT = 43110;
 const RESTART_WINDOW_MS = 30 * 60 * 1000;
@@ -1153,7 +1208,8 @@ export class LivewareSampleSupervisor {
     const { deps } = this;
     let delivered = false;
     try {
-      delivered = await deps.notifyOwner(LIVEWARE_SAMPLE_INTRO_TEXT);
+      const language = resolveOwnerLanguage(deps.resolveOwnerLocale?.() ?? null);
+      delivered = await deps.notifyOwner(loadIntroText(path.join(deps.sampleRoot, "app"), language));
     } catch (err) {
       deps.log?.debug?.(`liveware-sample: intro send error: ${String(err)}`);
     }

package/src/owner-language.ts

@@ -0,0 +1,56 @@
+/**
+ * Resolve the owner's reported app language into one of the six languages the
+ * ClawChat content tree carries. `agent_owner_locale` comes from the owner's
+ * ClawChat app setting and is omitted entirely when they never reported one —
+ * every unresolvable case lands on English rather than guessing.
+ */
+
+export type OwnerLanguage = "en" | "es" | "ja" | "ko" | "zh" | "zh_Hant";
+
+export const OWNER_LANGUAGES: readonly OwnerLanguage[] = [
+  "en", "es", "ja", "ko", "zh", "zh_Hant",
+];
+
+const DISPLAY_NAMES: Record<OwnerLanguage, string> = {
+  en: "English",
+  es: "Spanish",
+  ja: "Japanese",
+  ko: "Korean",
+  zh: "Simplified Chinese",
+  zh_Hant: "Traditional Chinese",
+};
+
+// Traditional-Chinese regions must be tested before the bare `zh` prefix,
+// because they also start with "zh".
+const TRADITIONAL_PREFIXES = ["zh-hant", "zh-tw", "zh-hk", "zh-mo"];
+
+export function resolveOwnerLanguage(locale?: string | null): OwnerLanguage {
+  const tag = String(locale ?? "").trim().toLowerCase().replace(/_/g, "-");
+  if (!tag) return "en";
+  if (TRADITIONAL_PREFIXES.some((p) => tag.startsWith(p))) return "zh_Hant";
+  if (tag.startsWith("zh")) return "zh";
+  if (tag.startsWith("ja")) return "ja";
+  if (tag.startsWith("ko")) return "ko";
+  if (tag.startsWith("es")) return "es";
+  return "en";
+}
+
+export function languageDisplayName(lang: OwnerLanguage): string {
+  return DISPLAY_NAMES[lang];
+}
+
+/**
+ * Resolve a locale ONLY when one was actually reported; `null` otherwise.
+ *
+ * `resolveOwnerLanguage` must answer with a language because the intro lookup
+ * has to pick one copy and `en` is the documented default. The greeting path
+ * is the opposite case: the language line is an explicit assertion to the
+ * model, and the owner-profile cache is COLD on a fresh install (the
+ * activation row is written without a locale and the bootstrap fires
+ * immediately on connect). Collapsing "unknown" into "en" there tells a
+ * Chinese owner's agent to reply in English. Callers on the greeting path use
+ * this and omit the line entirely when it returns null.
+ */
+export function resolveOwnerLanguageIfKnown(locale?: string | null): OwnerLanguage | null {
+  return String(locale ?? "").trim() ? resolveOwnerLanguage(locale) : null;
+}

package/src/runtime.ts

@@ -18,6 +18,7 @@ import { createOpenclawClawlingClient, resolveOpenclawClawlingDeviceId } from ".
 import { createOpenclawClawlingApiClient } from "./api-client.ts";
 import { buildActivationBootstrapText } from "./activation-greeting.ts";
 import { buildFriendGreetingEnvelope } from "./friend-greeting.ts";
+import { resolveOwnerLanguageIfKnown, type OwnerLanguage } from "./owner-language.ts";
 import { reportPluginVersionSafe, resolvePluginVersion } from "./plugin-report.ts";
 import { readOnboardingReport } from "./onboarding-report.ts";
 import path from "node:path";
@@ -139,6 +140,7 @@ type RuntimeConnectionStore = Pick<
       | "listRecentGroupMessages"
       | "recallMessage"
       | "upsertOwnerProfile"
+      | "getOwnerProfile"
     >
   >;
 
@@ -537,8 +539,10 @@ function withClawChatSessionScope(cfg: OpenClawConfig): OpenClawConfig {
 function buildActivationBootstrapEnvelope(params: {
   account: ResolvedOpenclawClawlingAccount;
   conversationId: string;
+  /** `null` when the owner's locale is not known — then no language line is emitted. */
+  language: OwnerLanguage | null;
 }): Envelope {
-  const text = buildActivationBootstrapText();
+  const text = buildActivationBootstrapText(undefined, params.language);
   const now = Date.now();
   return {
     version: "2",
@@ -1235,6 +1239,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         return await client.registerApp(p);
       },
       notifyOwner: (text) => livewareSampleNotify(text),
+      resolveOwnerLocale: () => store.getOwnerProfile?.({ platform: "openclaw", accountId })?.locale ?? null,
       fetchFn: globalThis.fetch,
       log: {
         warn: (m) => log?.info?.(m),
@@ -2645,8 +2650,20 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       log?.info?.(
         `[${accountId}] clawchat-plugin-openclaw friend greeting dispatch friend=${friendUserId} chat_id=${conversationId}`,
       );
+      // The recipient here is the new friend, NOT the owner — but we
+      // deliberately use the OWNER's language anyway: friends are usually in
+      // the same language circle, and the backend only exposes `locale` on
+      // the owner profile endpoint, so no third-party locale is obtainable.
+      //
+      // `…IfKnown`, not `resolveOwnerLanguage`: this is a synchronous read of a
+      // cache that may never have been filled, and it must NOT be awaited here.
+      // A cold cache yields null and the greeting simply carries no language
+      // line — see `buildActivationBootstrapText`.
+      const language = resolveOwnerLanguageIfKnown(
+        store?.getOwnerProfile?.({ platform: "openclaw", accountId })?.locale ?? null,
+      );
       await handleInboundEnvelope(
-        buildFriendGreetingEnvelope({ account, conversationId, friendUserId }),
+        buildFriendGreetingEnvelope({ account, conversationId, friendUserId, language }),
       );
     })().catch((err) => {
       log?.error?.(
@@ -3623,8 +3640,21 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       claimedInFlight = true;
       incrementActivationBootstrapInFlight(accountId);
       bootstrapGreetingDelivered = false;
+      // Synchronous, un-awaited read: the bootstrap is dispatched the moment
+      // the connection comes up (`void dispatchActivationBootstrap()`), so on a
+      // fresh install `owner_profile` has not been pulled yet and there is no
+      // locale to be had. `…IfKnown` returns null there and the prompt ships
+      // with no language line, instead of hard-asserting English at an owner
+      // who may not speak it. Do NOT add an await here to reach the locale.
+      const language = resolveOwnerLanguageIfKnown(
+        store?.getOwnerProfile?.({ platform: "openclaw", accountId })?.locale ?? null,
+      );
       const result = await handleInboundEnvelope(
-        buildActivationBootstrapEnvelope({ account, conversationId: claimedBootstrap.conversationId }),
+        buildActivationBootstrapEnvelope({
+          account,
+          conversationId: claimedBootstrap.conversationId,
+          language,
+        }),
       );
       if (result !== "submitted") {
         settleBootstrap("turn was not submitted");

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.11.0";
+export const DEFAULT_SKILLS_REF = "skills-v1.12.0";
 
 /** Refuse to treat an absurdly large response as a skill file (defence in depth). */
 export const MAX_SKILL_BYTES = 256 * 1024;