@clawling/clawchat-plugin-openclaw 2026.9.23-2 → 2026.9.26-2

package/dist/src/api-client.js

@@ -346,6 +346,30 @@ export function createOpenclawClawlingApiClient(opts) {
         }
         return obj;
     }
+    function isLivewareView(v) {
+        if (!v || typeof v !== "object" || Array.isArray(v))
+            return false;
+        const o = v;
+        const optionalString = (x) => x === undefined || typeof x === "string";
+        return (typeof o.id === "string" &&
+            typeof o.liveware_id === "string" &&
+            o.liveware_id !== "" &&
+            typeof o.name === "string" &&
+            typeof o.url === "string" &&
+            optionalString(o.subtitle) &&
+            optionalString(o.icon_url));
+    }
+    function livewareToAppView(v) {
+        return {
+            id: v.id,
+            app_id: v.liveware_id,
+            liveware_id: v.liveware_id,
+            name: v.name,
+            subtitle: v.subtitle ?? "",
+            icon_url: v.icon_url ?? "",
+            url: v.url,
+        };
+    }
     function assertNonBlankId(value, label) {
         if (!value.trim()) {
             throw new ClawlingApiError("validation", `${label} is required`);
@@ -475,17 +499,45 @@ export function createOpenclawClawlingApiClient(opts) {
         },
         async registerApp(params) {
             assertNonBlankId(params.appId, "registerApp: appId");
-            return await call("POST", "/v1/agents/me/apps", {
-                body: JSON.stringify({ name: params.name, app_id: params.appId, url: params.url }),
-                headers: { "content-type": "application/json" },
-            });
+            // Multipart even without an icon: the liveware route reads form fields.
+            const fd = new FormData();
+            fd.set("name", params.name);
+            fd.set("liveware_id", params.appId);
+            fd.set("url", params.url);
+            // The server only replaces a subtitle when the new one is non-empty, so
+            // an empty value cannot clear it; do not send one.
+            const subtitle = params.subtitle?.trim();
+            if (subtitle)
+                fd.set("subtitle", subtitle);
+            if (params.icon) {
+                const file = new File([new Uint8Array(params.icon.buffer)], params.icon.filename, {
+                    type: params.icon.mime,
+                });
+                fd.set("icon", file);
+            }
+            const data = await call("POST", "/v1/agents/me/liveware", { body: fd });
+            if (!isLivewareView(data?.liveware)) {
+                throw new ClawlingApiError("transport", "invalid liveware response: missing liveware entry", {
+                    path: "/v1/agents/me/liveware",
+                });
+            }
+            return { app: livewareToAppView(data.liveware) };
         },
         async listApps() {
-            return await call("GET", "/v1/agents/me/apps");
+            const data = await call("GET", "/v1/agents/me/liveware");
+            // A malformed body must not read as "no apps": the liveware sample
+            // bootstrap would take that as a fresh account and register a duplicate.
+            const list = data?.liveware;
+            if (!Array.isArray(list) || !list.every(isLivewareView)) {
+                throw new ClawlingApiError("transport", "invalid liveware response: malformed liveware list", {
+                    path: "/v1/agents/me/liveware",
+                });
+            }
+            return { apps: list.map(livewareToAppView) };
         },
         async unregisterApp(appId) {
             assertNonBlankId(appId, "unregisterApp: appId");
-            return await call("DELETE", `/v1/agents/me/apps/${encodeURIComponent(appId)}`);
+            return await call("DELETE", `/v1/agents/me/liveware/${encodeURIComponent(appId)}`);
         },
         async searchUsers(params) {
             const sp = new URLSearchParams();

package/dist/src/liveware-icon.js

@@ -0,0 +1,113 @@
+import fs from "node:fs";
+import path from "node:path";
+/** Server-side cap on the WHOLE registration request (default configuration). */
+export const LIVEWARE_REQUEST_MAX_BYTES = 25 * 1024 * 1024;
+/**
+ * Fixed reserve for the multipart envelope (boundaries and part headers).
+ * The text fields' own UTF-8 bytes are subtracted on top of this, so an icon
+ * that passes local validation also fits the server's request cap. Keep in
+ * sync with the Hermes plugin.
+ */
+export const LIVEWARE_MULTIPART_OVERHEAD_BYTES = 64 * 1024;
+export const LIVEWARE_SUBTITLE_MAX_CHARS = 200;
+/** Largest icon that fits in one request next to text fields of `textFieldBytes`. */
+export function livewareIconMaxBytes(textFieldBytes) {
+    return LIVEWARE_REQUEST_MAX_BYTES - LIVEWARE_MULTIPART_OVERHEAD_BYTES - textFieldBytes;
+}
+/** UTF-8 byte length of the multipart text fields (and icon filename). */
+export function livewareTextFieldBytes(values) {
+    let n = 0;
+    for (const v of values)
+        if (v)
+            n += Buffer.byteLength(v, "utf8");
+    return n;
+}
+/**
+ * Normalise a subtitle the way it is sent: trimmed, one line, at most 200
+ * characters. An omitted, empty or blank subtitle becomes `undefined` and is
+ * not sent. The server then keeps the existing subtitle, because it only
+ * replaces a subtitle when the new one is non-empty.
+ */
+export function normalizeLivewareSubtitle(raw) {
+    if (raw === undefined || raw === null)
+        return { ok: true, value: undefined };
+    if (typeof raw !== "string")
+        return { ok: false, message: "subtitle must be a string" };
+    // Line breaks are checked on the raw value: trimming would hide a trailing
+    // "\n" and let a caller believe a multi-line value was accepted.
+    if (/[\r\n]/.test(raw))
+        return { ok: false, message: "subtitle must be one line (no line breaks)" };
+    const value = raw.trim();
+    if (!value)
+        return { ok: true, value: undefined };
+    if ([...value].length > LIVEWARE_SUBTITLE_MAX_CHARS) {
+        return { ok: false, message: "subtitle must be at most 200 characters" };
+    }
+    return { ok: true, value };
+}
+/**
+ * Detect the icon type from its leading bytes, mirroring the server, which
+ * sniffs the content and ignores the declared type and file extension.
+ */
+export function sniffLivewareIconMime(head) {
+    const b = head;
+    if (b.length >= 8 &&
+        b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47 &&
+        b[4] === 0x0d && b[5] === 0x0a && b[6] === 0x1a && b[7] === 0x0a) {
+        return "image/png";
+    }
+    if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) {
+        return "image/jpeg";
+    }
+    const ascii = (from, to) => String.fromCharCode(...b.subarray(from, to));
+    if (b.length >= 14 && ascii(0, 4) === "RIFF" && ascii(8, 14) === "WEBPVP") {
+        return "image/webp";
+    }
+    return undefined;
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Read and validate a local liveware icon file. Returns either the upload
+ * part or a human-readable validation message; filesystem errors never throw.
+ * `textFieldBytes` is the UTF-8 size of the other multipart fields, used to
+ * keep the whole request under the server cap.
+ */
+export function readLivewareIcon(iconPath, textFieldBytes = 0) {
+    if (!iconPath || !path.isAbsolute(iconPath)) {
+        return { ok: false, message: "iconPath must be an absolute local path" };
+    }
+    let stat;
+    try {
+        stat = fs.statSync(iconPath);
+    }
+    catch (err) {
+        return { ok: false, message: `cannot stat ${iconPath}: ${errMessage(err)}` };
+    }
+    if (!stat.isFile()) {
+        return { ok: false, message: `${iconPath} is not a regular file` };
+    }
+    const filename = path.basename(iconPath);
+    const max = livewareIconMaxBytes(textFieldBytes + Buffer.byteLength(filename, "utf8"));
+    const tooLarge = (size) => `icon too large (${size} bytes; max ${max} bytes for this request: the 25MB request limit minus multipart overhead)`;
+    if (stat.size > max) {
+        return { ok: false, message: tooLarge(stat.size) };
+    }
+    let buffer;
+    try {
+        buffer = fs.readFileSync(iconPath);
+    }
+    catch (err) {
+        return { ok: false, message: `cannot read ${iconPath}: ${errMessage(err)}` };
+    }
+    // The file may have grown between stat and read.
+    if (buffer.length > max) {
+        return { ok: false, message: tooLarge(buffer.length) };
+    }
+    const mime = sniffLivewareIconMime(buffer.subarray(0, 16));
+    if (!mime) {
+        return { ok: false, message: `icon must be a PNG, JPEG or WebP image (checked from the file's bytes): ${iconPath}` };
+    }
+    return { ok: true, icon: { buffer, filename, mime } };
+}

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.15.0";
+export const DEFAULT_SKILLS_REF = "skills-v1.15.2";
 /** 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

@@ -278,6 +278,12 @@ export const ClawchatRegisterAppSchema = Type.Object({
     name: Type.String({ minLength: 1, description: "Human-readable app name shown on the launcher tile." }),
     appId: Type.String({ minLength: 1, description: "The liveware app id from `liveware app create`/`liveware app list`." }),
     url: Type.String({ minLength: 1, description: "Public tunnel URL from `liveware tunnel bind` (http/https)." }),
+    subtitle: Type.Optional(Type.String({
+        description: "Optional one-line subtitle for the tile (one line, max 200 characters, surrounding spaces trimmed). An omitted or empty subtitle keeps the current one: re-registering cannot clear a subtitle.",
+    })),
+    iconPath: Type.Optional(Type.String({
+        description: "Optional absolute local path of the tile icon: a PNG, JPEG or WebP image, under 25MB (the whole request is capped at 25MB). Omit to keep the current icon on re-registration.",
+    })),
 });
 export const ClawchatListAppsSchema = Type.Object({});
 export const ClawchatUnregisterAppSchema = Type.Object({

package/dist/src/tools.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { execFile } from "node:child_process";
 import { createOpenclawClawlingApiClient } from "./api-client.js";
 import { resolveLivewarePath } from "./liveware-cli.js";
+import { livewareTextFieldBytes, normalizeLivewareSubtitle, readLivewareIcon } from "./liveware-icon.js";
 import { ClawlingApiError, } from "./api-types.js";
 import { mapGateOutcome } from "./gate-outcome.js";
 import { CHANNEL_ID, normalizeOpenclawClawlingAccountId, resolveOpenclawClawlingAccount, } from "./config.js";
@@ -1295,12 +1296,27 @@ export function registerOpenclawClawlingTools(api, options = {}) {
             name: "clawchat_register_app",
             label: "Register ClawChat App",
             description: toolDescription("Register a liveware-tunneled web app to ClawChat so it appears in the owner's chat with this agent. " +
-                "Call AFTER `liveware tunnel bind` returns a public URL. Params: name, appId (liveware app id), url (public URL)."),
+                "Call AFTER `liveware tunnel bind` returns a public URL. Params: name, appId (liveware app id), url (public URL), " +
+                "optional subtitle (one line, max 200 characters) and optional iconPath (absolute local PNG/JPEG/WebP file, under 25MB). " +
+                "Registering the same appId again updates that tile: name and url are replaced; subtitle and icon only when given " +
+                "(an empty subtitle keeps the current one, so re-registering cannot clear a subtitle)."),
             parameters: ClawchatRegisterAppSchema,
             async execute(_callId, params) {
                 return await recordClawchatToolCall(accountId, "clawchat_register_app", params, async () => {
                     const p = params;
-                    return await withClient(accountId, (c) => c.registerApp({ name: p.name, appId: p.appId, url: p.url }));
+                    const sub = normalizeLivewareSubtitle(p.subtitle);
+                    if (!sub.ok)
+                        return validationError(`clawchat-plugin-openclaw: ${sub.message}`);
+                    const subtitle = sub.value;
+                    let icon;
+                    if (p.iconPath !== undefined && p.iconPath !== "") {
+                        const textBytes = livewareTextFieldBytes([p.name, p.appId, p.url, subtitle]);
+                        const read = readLivewareIcon(String(p.iconPath), textBytes);
+                        if (!read.ok)
+                            return validationError(`clawchat-plugin-openclaw: ${read.message}`);
+                        icon = read.icon;
+                    }
+                    return await withClient(accountId, (c) => c.registerApp({ name: p.name, appId: p.appId, url: p.url, subtitle, icon }));
                 });
             },
         };
@@ -1571,7 +1587,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
         return {
             name: "clawchat_orchestrate_create_connect_code",
             label: "Issue A Connect Code",
-            description: toolDescription("Mint a connect code on the owner's behalf, valid 30 minutes. " +
+            description: toolDescription("Mint a connect code on the owner's behalf, valid 45 minutes. " +
                 "TRIGGER — invoke when the owner asks for a code to connect a new agent. " +
                 "The rate limit bucket belongs to the owner and is shared with their own manual issuance, so do not retry on a limit."),
             parameters: ClawchatOrchCreateConnectCodeSchema,

package/package.json

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

package/skills/clawchat-liveware/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clawchat-liveware
-version: 1.2.2
+version: 1.2.3
 description: Use when the user wants to expose this agent's local web service to the public internet via the liveware CLI and make it appear as an app in their ClawChat chat with this agent. Covers logging in to liveware with the ClawChat account, creating a liveware app, binding a tunnel to a local port, registering the public URL to ClawChat, restricting who may open each app, and fully unregistering and deleting an app.
 ---
 
@@ -78,6 +78,14 @@ ClawChat so it shows as an app tile in the owner's chat with this agent.
 7. **Register to ClawChat** so it appears in the owner's chat — call the tool, do NOT
    curl the API directly:
    `clawchat_register_app(name="<app name>", appId="<app id>", url="<public URL>")`
+   Two optional arguments decorate the tile:
+   - `subtitle="<text>"`: one line, no line breaks, at most 200 characters after
+     surrounding spaces are trimmed. An omitted or empty subtitle keeps the current one:
+     re-registering the same app id cannot clear a subtitle, so do not promise the user
+     that it can.
+   - `iconPath="<absolute local path>"`: a PNG, JPEG, or WebP image on this machine. The
+     whole registration request is capped at 25 MiB, so the icon must stay under that.
+     Omit it to keep the current icon when re-registering.
 8. **Confirm** to the user: report the app name, public URL, final `bound`,
    `relayConnected`, and `live` values, and that it now appears in their chat with this
    agent (open the「…」menu → the app tile).

package/skills/clawchat-orchestration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clawchat-orchestration
-version: 2.0.1
+version: 2.0.2
 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.
 ---
 
@@ -82,7 +82,7 @@ The backend enforces these. Violating one is a failed call, not a warning.
   `replyMode`, `batchDelaySeconds`. `replyMode` has exactly two values, `"all"`
   or `"mention"`. `batchDelaySeconds` is 1–3600 (default 10). Omitted
   parameters are left unchanged.
-- `clawchat_orchestrate_create_connect_code` — **no parameters**. The code is valid 30 minutes.
+- `clawchat_orchestrate_create_connect_code` — **no parameters**. The code is valid 45 minutes.
 
 ### What this surface deliberately cannot do
 

package/skills/manifest.json

@@ -9,10 +9,10 @@
         "bytes": 16656
       },
       "clawchat-liveware": {
-        "version": "1.2.2",
+        "version": "1.2.3",
         "path": "shared/clawchat-liveware/SKILL.md",
-        "sha256": "159546d6b9e106af3ae8f75cbe25e945f53d1421cace7700ce4c47f646ef2fec",
-        "bytes": 12035
+        "sha256": "2ed150bad7972d452b5b437d7c524ab24c27b0677419e590f087f50b7e7a3cdd",
+        "bytes": 12591
       },
       "clawchat-liveware-dev": {
         "version": "1.0.0",
@@ -33,9 +33,9 @@
         "bytes": 13938
       },
       "clawchat-orchestration": {
-        "version": "2.0.1",
+        "version": "2.0.2",
         "path": "shared/clawchat-orchestration/SKILL.md",
-        "sha256": "f477b627b73243c9b41ad871b074cba644a8074fc73ce30b719c59ab32434c9d",
+        "sha256": "e32f29c5f41a7621732625a58a9f3d6fe365d7dde9bdcd892f9623e7fc180414",
         "bytes": 9477
       }
     },
@@ -47,10 +47,10 @@
         "bytes": 23959
       },
       "clawchat-liveware": {
-        "version": "1.2.2",
+        "version": "1.2.3",
         "path": "shared/clawchat-liveware/SKILL.md",
-        "sha256": "159546d6b9e106af3ae8f75cbe25e945f53d1421cace7700ce4c47f646ef2fec",
-        "bytes": 12035
+        "sha256": "2ed150bad7972d452b5b437d7c524ab24c27b0677419e590f087f50b7e7a3cdd",
+        "bytes": 12591
       },
       "clawchat-liveware-dev": {
         "version": "1.0.0",
@@ -71,9 +71,9 @@
         "bytes": 13838
       },
       "clawchat-orchestration": {
-        "version": "2.0.1",
+        "version": "2.0.2",
         "path": "shared/clawchat-orchestration/SKILL.md",
-        "sha256": "f477b627b73243c9b41ad871b074cba644a8074fc73ce30b719c59ab32434c9d",
+        "sha256": "e32f29c5f41a7621732625a58a9f3d6fe365d7dde9bdcd892f9623e7fc180414",
         "bytes": 9477
       }
     }

package/src/api-client.ts

@@ -1,6 +1,8 @@
 import {
   ClawlingApiError,
   type AgentAppView,
+  type LivewareIconUpload,
+  type LivewareView,
   type AgentConnectCheckInput,
   type AgentConnectCheckResult,
   type AgentMetadataPatch,
@@ -252,7 +254,13 @@ export interface OpenclawClawlingApiClient {
    * cache (never throw / never block message handling).
    */
   getMyPermissions(): Promise<PermissionPolicy>;
-  registerApp(params: { name: string; appId: string; url: string }): Promise<{ app: AgentAppView }>;
+  registerApp(params: {
+    name: string;
+    appId: string;
+    url: string;
+    subtitle?: string;
+    icon?: LivewareIconUpload;
+  }): Promise<{ app: AgentAppView }>;
   listApps(): Promise<{ apps: AgentAppView[] }>;
   unregisterApp(appId: string): Promise<{ deleted: boolean }>;
 }
@@ -604,6 +612,33 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
     return obj as UploadResult;
   }
 
+  function isLivewareView(v: unknown): v is LivewareView {
+    if (!v || typeof v !== "object" || Array.isArray(v)) return false;
+    const o = v as Record<string, unknown>;
+    const optionalString = (x: unknown) => x === undefined || typeof x === "string";
+    return (
+      typeof o.id === "string" &&
+      typeof o.liveware_id === "string" &&
+      o.liveware_id !== "" &&
+      typeof o.name === "string" &&
+      typeof o.url === "string" &&
+      optionalString(o.subtitle) &&
+      optionalString(o.icon_url)
+    );
+  }
+
+  function livewareToAppView(v: LivewareView): AgentAppView {
+    return {
+      id: v.id,
+      app_id: v.liveware_id,
+      liveware_id: v.liveware_id,
+      name: v.name,
+      subtitle: v.subtitle ?? "",
+      icon_url: v.icon_url ?? "",
+      url: v.url,
+    };
+  }
+
   function assertNonBlankId(value: string, label: string): void {
     if (!value.trim()) {
       throw new ClawlingApiError("validation", `${label} is required`);
@@ -761,19 +796,46 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
     async orchGetConnectCode(code): Promise<unknown> {
       return await orchCall("GET", `${ORCH}/connect-codes/${encodeURIComponent(code)}`);
     },
-    async registerApp(params: { name: string; appId: string; url: string }): Promise<{ app: AgentAppView }> {
+    async registerApp(params): Promise<{ app: AgentAppView }> {
       assertNonBlankId(params.appId, "registerApp: appId");
-      return await call<{ app: AgentAppView }>("POST", "/v1/agents/me/apps", {
-        body: JSON.stringify({ name: params.name, app_id: params.appId, url: params.url }),
-        headers: { "content-type": "application/json" },
-      });
+      // Multipart even without an icon: the liveware route reads form fields.
+      const fd = new FormData();
+      fd.set("name", params.name);
+      fd.set("liveware_id", params.appId);
+      fd.set("url", params.url);
+      // The server only replaces a subtitle when the new one is non-empty, so
+      // an empty value cannot clear it; do not send one.
+      const subtitle = params.subtitle?.trim();
+      if (subtitle) fd.set("subtitle", subtitle);
+      if (params.icon) {
+        const file = new File([new Uint8Array(params.icon.buffer)], params.icon.filename, {
+          type: params.icon.mime,
+        });
+        fd.set("icon", file);
+      }
+      const data = await call<{ liveware?: LivewareView }>("POST", "/v1/agents/me/liveware", { body: fd });
+      if (!isLivewareView(data?.liveware)) {
+        throw new ClawlingApiError("transport", "invalid liveware response: missing liveware entry", {
+          path: "/v1/agents/me/liveware",
+        });
+      }
+      return { app: livewareToAppView(data.liveware) };
     },
     async listApps(): Promise<{ apps: AgentAppView[] }> {
-      return await call<{ apps: AgentAppView[] }>("GET", "/v1/agents/me/apps");
+      const data = await call<{ liveware?: unknown }>("GET", "/v1/agents/me/liveware");
+      // A malformed body must not read as "no apps": the liveware sample
+      // bootstrap would take that as a fresh account and register a duplicate.
+      const list = data?.liveware;
+      if (!Array.isArray(list) || !list.every(isLivewareView)) {
+        throw new ClawlingApiError("transport", "invalid liveware response: malformed liveware list", {
+          path: "/v1/agents/me/liveware",
+        });
+      }
+      return { apps: list.map(livewareToAppView) };
     },
     async unregisterApp(appId: string): Promise<{ deleted: boolean }> {
       assertNonBlankId(appId, "unregisterApp: appId");
-      return await call<{ deleted: boolean }>("DELETE", `/v1/agents/me/apps/${encodeURIComponent(appId)}`);
+      return await call<{ deleted: boolean }>("DELETE", `/v1/agents/me/liveware/${encodeURIComponent(appId)}`);
     },
     async searchUsers(params): Promise<{ users: UserSearchHit[] }> {
       const sp = new URLSearchParams();

package/src/api-types.ts

@@ -164,7 +164,32 @@ export interface AgentConnectCheckResult {
   bound_agent?: boolean;
 }
 
-export type AgentAppView = { id: string; app_id?: string; name: string; url: string };
+/** Wire shape of one entry on `/v1/agents/me/liveware`. */
+export type LivewareView = {
+  id: string;
+  liveware_id?: string;
+  name: string;
+  subtitle?: string;
+  icon_url?: string;
+  url: string;
+};
+
+/**
+ * Shape returned by the `clawchat_*_app` tools. `app_id` mirrors
+ * `liveware_id` so callers written against the older app routes keep working.
+ */
+export type AgentAppView = {
+  id: string;
+  app_id?: string;
+  liveware_id?: string;
+  name: string;
+  subtitle?: string;
+  icon_url?: string;
+  url: string;
+};
+
+/** An icon file part for `registerApp`. */
+export type LivewareIconUpload = { buffer: Buffer | Uint8Array; filename: string; mime: string };
 
 export type ClawlingApiErrorKind =
   | "auth" // 401 / 403 — token bad or expired

package/src/liveware-icon.ts

@@ -0,0 +1,122 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import type { LivewareIconUpload } from "./api-types.ts";
+
+/** Server-side cap on the WHOLE registration request (default configuration). */
+export const LIVEWARE_REQUEST_MAX_BYTES = 25 * 1024 * 1024;
+/**
+ * Fixed reserve for the multipart envelope (boundaries and part headers).
+ * The text fields' own UTF-8 bytes are subtracted on top of this, so an icon
+ * that passes local validation also fits the server's request cap. Keep in
+ * sync with the Hermes plugin.
+ */
+export const LIVEWARE_MULTIPART_OVERHEAD_BYTES = 64 * 1024;
+export const LIVEWARE_SUBTITLE_MAX_CHARS = 200;
+
+/** Largest icon that fits in one request next to text fields of `textFieldBytes`. */
+export function livewareIconMaxBytes(textFieldBytes: number): number {
+  return LIVEWARE_REQUEST_MAX_BYTES - LIVEWARE_MULTIPART_OVERHEAD_BYTES - textFieldBytes;
+}
+
+/** UTF-8 byte length of the multipart text fields (and icon filename). */
+export function livewareTextFieldBytes(values: readonly (string | undefined)[]): number {
+  let n = 0;
+  for (const v of values) if (v) n += Buffer.byteLength(v, "utf8");
+  return n;
+}
+
+/**
+ * Normalise a subtitle the way it is sent: trimmed, one line, at most 200
+ * characters. An omitted, empty or blank subtitle becomes `undefined` and is
+ * not sent. The server then keeps the existing subtitle, because it only
+ * replaces a subtitle when the new one is non-empty.
+ */
+export function normalizeLivewareSubtitle(
+  raw: unknown,
+): { ok: true; value: string | undefined } | { ok: false; message: string } {
+  if (raw === undefined || raw === null) return { ok: true, value: undefined };
+  if (typeof raw !== "string") return { ok: false, message: "subtitle must be a string" };
+  // Line breaks are checked on the raw value: trimming would hide a trailing
+  // "\n" and let a caller believe a multi-line value was accepted.
+  if (/[\r\n]/.test(raw)) return { ok: false, message: "subtitle must be one line (no line breaks)" };
+  const value = raw.trim();
+  if (!value) return { ok: true, value: undefined };
+  if ([...value].length > LIVEWARE_SUBTITLE_MAX_CHARS) {
+    return { ok: false, message: "subtitle must be at most 200 characters" };
+  }
+  return { ok: true, value };
+}
+
+/**
+ * Detect the icon type from its leading bytes, mirroring the server, which
+ * sniffs the content and ignores the declared type and file extension.
+ */
+export function sniffLivewareIconMime(head: Uint8Array): string | undefined {
+  const b = head;
+  if (
+    b.length >= 8 &&
+    b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47 &&
+    b[4] === 0x0d && b[5] === 0x0a && b[6] === 0x1a && b[7] === 0x0a
+  ) {
+    return "image/png";
+  }
+  if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) {
+    return "image/jpeg";
+  }
+  const ascii = (from: number, to: number) => String.fromCharCode(...b.subarray(from, to));
+  if (b.length >= 14 && ascii(0, 4) === "RIFF" && ascii(8, 14) === "WEBPVP") {
+    return "image/webp";
+  }
+  return undefined;
+}
+
+function errMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Read and validate a local liveware icon file. Returns either the upload
+ * part or a human-readable validation message; filesystem errors never throw.
+ * `textFieldBytes` is the UTF-8 size of the other multipart fields, used to
+ * keep the whole request under the server cap.
+ */
+export function readLivewareIcon(
+  iconPath: string,
+  textFieldBytes = 0,
+): { ok: true; icon: LivewareIconUpload } | { ok: false; message: string } {
+  if (!iconPath || !path.isAbsolute(iconPath)) {
+    return { ok: false, message: "iconPath must be an absolute local path" };
+  }
+  let stat: fs.Stats;
+  try {
+    stat = fs.statSync(iconPath);
+  } catch (err) {
+    return { ok: false, message: `cannot stat ${iconPath}: ${errMessage(err)}` };
+  }
+  if (!stat.isFile()) {
+    return { ok: false, message: `${iconPath} is not a regular file` };
+  }
+  const filename = path.basename(iconPath);
+  const max = livewareIconMaxBytes(textFieldBytes + Buffer.byteLength(filename, "utf8"));
+  const tooLarge = (size: number) =>
+    `icon too large (${size} bytes; max ${max} bytes for this request: the 25MB request limit minus multipart overhead)`;
+  if (stat.size > max) {
+    return { ok: false, message: tooLarge(stat.size) };
+  }
+  let buffer: Buffer;
+  try {
+    buffer = fs.readFileSync(iconPath);
+  } catch (err) {
+    return { ok: false, message: `cannot read ${iconPath}: ${errMessage(err)}` };
+  }
+  // The file may have grown between stat and read.
+  if (buffer.length > max) {
+    return { ok: false, message: tooLarge(buffer.length) };
+  }
+  const mime = sniffLivewareIconMime(buffer.subarray(0, 16));
+  if (!mime) {
+    return { ok: false, message: `icon must be a PNG, JPEG or WebP image (checked from the file's bytes): ${iconPath}` };
+  }
+  return { ok: true, icon: { buffer, filename, mime } };
+}

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.15.0";
+export const DEFAULT_SKILLS_REF = "skills-v1.15.2";
 
 /** 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

@@ -439,6 +439,18 @@ export const ClawchatRegisterAppSchema = Type.Object({
   name: Type.String({ minLength: 1, description: "Human-readable app name shown on the launcher tile." }),
   appId: Type.String({ minLength: 1, description: "The liveware app id from `liveware app create`/`liveware app list`." }),
   url: Type.String({ minLength: 1, description: "Public tunnel URL from `liveware tunnel bind` (http/https)." }),
+  subtitle: Type.Optional(
+    Type.String({
+      description:
+        "Optional one-line subtitle for the tile (one line, max 200 characters, surrounding spaces trimmed). An omitted or empty subtitle keeps the current one: re-registering cannot clear a subtitle.",
+    }),
+  ),
+  iconPath: Type.Optional(
+    Type.String({
+      description:
+        "Optional absolute local path of the tile icon: a PNG, JPEG or WebP image, under 25MB (the whole request is capped at 25MB). Omit to keep the current icon on re-registration.",
+    }),
+  ),
 });
 export type ClawchatRegisterAppParams = Static<typeof ClawchatRegisterAppSchema>;
 

package/src/tools.ts

@@ -5,6 +5,8 @@ import type { OpenClawAgentToolResult } from "openclaw/plugin-sdk/agent-harness-
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk/core";
 import { createOpenclawClawlingApiClient } from "./api-client.ts";
 import { resolveLivewarePath } from "./liveware-cli.ts";
+import { livewareTextFieldBytes, normalizeLivewareSubtitle, readLivewareIcon } from "./liveware-icon.ts";
+import type { LivewareIconUpload } from "./api-types.ts";
 import {
   ClawlingApiError,
   type Profile,
@@ -1667,13 +1669,28 @@ export function registerOpenclawClawlingTools(
         label: "Register ClawChat App",
         description: toolDescription(
           "Register a liveware-tunneled web app to ClawChat so it appears in the owner's chat with this agent. " +
-          "Call AFTER `liveware tunnel bind` returns a public URL. Params: name, appId (liveware app id), url (public URL).",
+          "Call AFTER `liveware tunnel bind` returns a public URL. Params: name, appId (liveware app id), url (public URL), " +
+          "optional subtitle (one line, max 200 characters) and optional iconPath (absolute local PNG/JPEG/WebP file, under 25MB). " +
+          "Registering the same appId again updates that tile: name and url are replaced; subtitle and icon only when given " +
+          "(an empty subtitle keeps the current one, so re-registering cannot clear a subtitle).",
         ),
         parameters: ClawchatRegisterAppSchema,
         async execute(_callId, params) {
           return await recordClawchatToolCall(accountId, "clawchat_register_app", params, async () => {
             const p = params as ClawchatRegisterAppParams;
-            return await withClient(accountId, (c) => c.registerApp({ name: p.name, appId: p.appId, url: p.url }));
+            const sub = normalizeLivewareSubtitle(p.subtitle);
+            if (!sub.ok) return validationError(`clawchat-plugin-openclaw: ${sub.message}`);
+            const subtitle = sub.value;
+            let icon: LivewareIconUpload | undefined;
+            if (p.iconPath !== undefined && p.iconPath !== "") {
+              const textBytes = livewareTextFieldBytes([p.name, p.appId, p.url, subtitle]);
+              const read = readLivewareIcon(String(p.iconPath), textBytes);
+              if (!read.ok) return validationError(`clawchat-plugin-openclaw: ${read.message}`);
+              icon = read.icon;
+            }
+            return await withClient(accountId, (c) =>
+              c.registerApp({ name: p.name, appId: p.appId, url: p.url, subtitle, icon }),
+            );
           });
         },
       };
@@ -2065,7 +2082,7 @@ export function registerOpenclawClawlingTools(
         name: "clawchat_orchestrate_create_connect_code",
         label: "Issue A Connect Code",
         description: toolDescription(
-          "Mint a connect code on the owner's behalf, valid 30 minutes. " +
+          "Mint a connect code on the owner's behalf, valid 45 minutes. " +
           "TRIGGER — invoke when the owner asks for a code to connect a new agent. " +
           "The rate limit bucket belongs to the owner and is shared with their own manual issuance, so do not retry on a limit.",
         ),