@clawling/clawchat-plugin-openclaw 2026.6.22-1 → 2026.6.24-1

package/dist/src/api-client.js

@@ -318,6 +318,20 @@ export function createOpenclawClawlingApiClient(opts) {
             assertNonBlankId(friendUserId, "removeFriend: friendUserId");
             return await call("DELETE", `/v1/friendships/${encodeURIComponent(friendUserId)}`);
         },
+        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" },
+            });
+        },
+        async listApps() {
+            return await call("GET", "/v1/agents/me/apps");
+        },
+        async unregisterApp(appId) {
+            assertNonBlankId(appId, "unregisterApp: appId");
+            return await call("DELETE", `/v1/agents/me/apps/${encodeURIComponent(appId)}`);
+        },
         async searchUsers(params) {
             const sp = new URLSearchParams();
             if (typeof params.q === "string")

package/dist/src/liveware-cli.js

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
+export const LIVEWARE_BASE_URL = "https://media.clawling.chat/liveware/";
+// A non-default User-Agent is required: the CDN (Cloudflare) returns 403 for
+// known scripting/default UAs, so download requests must identify themselves.
+const LIVEWARE_USER_AGENT = "clawchat-liveware-installer";
+/** Directory where the downloaded binaries live: <stateDir>/clawchat/liveware. */
+export function livewareDir(stateDir) {
+    const root = stateDir ?? resolveStateDir();
+    return path.join(root, "clawchat", "liveware");
+}
+/** Map host platform/arch to the two asset filenames, or null if unsupported. */
+export function platformAssets(plat = process.platform, arch = process.arch) {
+    const os = plat === "darwin" ? "darwin" : plat === "linux" ? "linux" : null;
+    const cpu = arch === "x64" ? "amd64" : arch === "arm64" ? "arm64" : null;
+    if (!os || !cpu)
+        return null;
+    return { liveware: `liveware-${os}-${cpu}`, tunneAgent: `tunnel-agent-${os}-${cpu}` };
+}
+function findOnPath(name) {
+    const raw = process.env.PATH ?? "";
+    for (const dir of raw.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = path.join(dir, name);
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // not here; keep scanning
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the liveware executable to invoke:
+ *  1. on PATH        → "liveware" (let the OS resolve it)
+ *  2. downloaded dir → absolute path
+ *  3. otherwise      → null
+ */
+export function resolveLivewarePath(stateDir) {
+    if (findOnPath("liveware"))
+        return "liveware";
+    const local = path.join(livewareDir(stateDir), "liveware");
+    try {
+        fs.accessSync(local, fs.constants.X_OK);
+        return local;
+    }
+    catch {
+        return null;
+    }
+}
+async function downloadTo(url, dest) {
+    const res = await fetch(url, { headers: { "user-agent": LIVEWARE_USER_AGENT } });
+    if (!res.ok)
+        throw new Error(`download ${url} failed: HTTP ${res.status}`);
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (buf.length === 0)
+        throw new Error(`download ${url} returned empty body`);
+    const tmp = `${dest}.tmp`;
+    await fs.promises.writeFile(tmp, buf);
+    await fs.promises.chmod(tmp, 0o755);
+    await fs.promises.rename(tmp, dest);
+}
+/**
+ * Startup hook: ensure the liveware CLI is available, downloading it when not.
+ * Fire-and-forget — never throws; logs and returns on any failure.
+ */
+export async function ensureLivewareCli(opts = {}) {
+    const { stateDir, log } = opts;
+    try {
+        if (findOnPath("liveware"))
+            return; // PATH wins
+        const dir = livewareDir(stateDir);
+        const target = path.join(dir, "liveware");
+        if (fs.existsSync(target))
+            return;
+        const assets = platformAssets();
+        if (!assets) {
+            log?.warn?.(`clawchat-plugin-openclaw: unsupported platform ${process.platform}/${process.arch}; skipping liveware download`);
+            return;
+        }
+        await fs.promises.mkdir(dir, { recursive: true });
+        await downloadTo(LIVEWARE_BASE_URL + assets.liveware, path.join(dir, "liveware"));
+        await downloadTo(LIVEWARE_BASE_URL + assets.tunneAgent, path.join(dir, "tunnel-agent"));
+        log?.debug?.(`clawchat-plugin-openclaw: liveware CLI downloaded to ${dir}`);
+    }
+    catch (err) {
+        log?.warn?.(`clawchat-plugin-openclaw: liveware CLI download skipped: ${String(err)}`);
+    }
+}

package/dist/src/runtime.js

@@ -5,6 +5,7 @@ import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
 import { createOpenclawClawlingClient, resolveOpenclawClawlingDeviceId } from "./client.js";
 import { createOpenclawClawlingApiClient } from "./api-client.js";
 import { reportPluginVersionSafe, resolvePluginVersion } from "./plugin-report.js";
+import { ensureLivewareCli } from "./liveware-cli.js";
 import { ClawlingApiError } from "./api-types.js";
 import { RefreshManager } from "./refresh-manager.js";
 import { runOpenclawClawlingLogin, } from "./login.runtime.js";
@@ -618,6 +619,15 @@ export async function startOpenclawClawlingGateway(params) {
         authenticated: false,
         log,
     });
+    // Ensure the liveware CLI is installed (async, never blocks startup).
+    void ensureLivewareCli({
+        stateDir: runtime.state?.resolveStateDir?.(),
+        log: {
+            warn: (m) => log?.info?.(m),
+            debug: (m) => log?.debug?.(m),
+            error: (m) => log?.error?.(m),
+        },
+    });
     // §B self-heal — non-interactive env connect-code activation BEFORE blocking on
     // the wait-for-activation loop. Gated so the common path (no env code, or an
     // already-credentialed account) adds NO async work: on success it credentials

package/dist/src/tools-schema.js

@@ -233,3 +233,13 @@ export const ClawchatUploadAvatarImageSchema = Type.Object({
         description: "Absolute local path of the avatar image to upload for the agent's connected ClawChat account (max 20MB)",
     }),
 });
+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)." }),
+});
+export const ClawchatListAppsSchema = Type.Object({});
+export const ClawchatUnregisterAppSchema = Type.Object({
+    appId: Type.String({ minLength: 1, description: "The liveware app id to unregister." }),
+});
+export const ClawchatLivewareLoginSchema = Type.Object({});

package/dist/src/tools.js

@@ -1,6 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
+import { execFile } from "node:child_process";
 import { createOpenclawClawlingApiClient } from "./api-client.js";
+import { resolveLivewarePath } from "./liveware-cli.js";
 import { ClawlingApiError, } from "./api-types.js";
 import { resolveOpenclawClawlingAccount } from "./config.js";
 import { clawChatDbPathForStateDir, getClawChatStore, } from "./storage.js";
@@ -9,7 +11,7 @@ import { getOpenclawClawlingClient, } from "./runtime.js";
 import { markTerminalClawChatSend } from "./terminal-send.js";
 import { editClawChatMemoryBody, readClawChatMemoryFile, resolveClawChatMemoryPath, searchClawChatMemory, writeClawChatMemoryBody, } from "./clawchat-memory.js";
 import { pullGroupMetadata, pullOwnerMetadata, pullUserMetadata, pushMetadata, updateMetadata, } from "./clawchat-metadata.js";
-import { ClawchatGetAccountProfileSchema, ClawchatGetConversationSchema, ClawchatGetUserProfileSchema, ClawchatAcceptFriendRequestSchema, ClawchatMemoryEditSchema, ClawchatMemoryReadSchema, ClawchatMemorySearchSchema, ClawchatMemoryWriteSchema, ClawchatMetadataSyncSchema, ClawchatMetadataUpdateSchema, ClawchatCreateMomentCommentSchema, ClawchatCreateMomentSchema, ClawchatDeleteMomentCommentSchema, ClawchatDeleteMomentSchema, ClawchatListAccountFriendsSchema, ClawchatListFriendRequestsSchema, ClawchatListMomentsSchema, ClawchatMentionMessageSchema, ClawchatReplyMomentCommentSchema, ClawchatRejectFriendRequestSchema, ClawchatRemoveFriendSchema, ClawchatSearchUsersSchema, ClawchatSendFriendRequestSchema, ClawchatToggleMomentReactionSchema, ClawchatUpdateAccountProfileSchema, ClawchatUploadAvatarImageSchema, } from "./tools-schema.js";
+import { ClawchatGetAccountProfileSchema, ClawchatGetConversationSchema, ClawchatGetUserProfileSchema, ClawchatAcceptFriendRequestSchema, ClawchatMemoryEditSchema, ClawchatMemoryReadSchema, ClawchatMemorySearchSchema, ClawchatMemoryWriteSchema, ClawchatMetadataSyncSchema, ClawchatMetadataUpdateSchema, ClawchatCreateMomentCommentSchema, ClawchatCreateMomentSchema, ClawchatDeleteMomentCommentSchema, ClawchatDeleteMomentSchema, ClawchatListAccountFriendsSchema, ClawchatListFriendRequestsSchema, ClawchatListMomentsSchema, ClawchatMentionMessageSchema, ClawchatReplyMomentCommentSchema, ClawchatRejectFriendRequestSchema, ClawchatRemoveFriendSchema, ClawchatSearchUsersSchema, ClawchatSendFriendRequestSchema, ClawchatToggleMomentReactionSchema, ClawchatUpdateAccountProfileSchema, ClawchatUploadAvatarImageSchema, ClawchatRegisterAppSchema, ClawchatListAppsSchema, ClawchatUnregisterAppSchema, ClawchatLivewareLoginSchema, } from "./tools-schema.js";
 const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
 // Owner-approval gate business codes (must match member-backend codes.go).
 const CODE_PENDING_APPROVAL = 21001;
@@ -997,5 +999,93 @@ export function registerOpenclawClawlingTools(api, options = {}) {
             });
         },
     }, { name: "clawchat_upload_avatar_image" });
-    api.logger.debug?.("clawchat-plugin-openclaw: registered 26 clawchat_* tools (get_account_profile, get_user_profile, list_account_friends, send_friend_request, list_friend_requests, accept_friend_request, reject_friend_request, remove_friend, search_users, get_conversation, mention_message, list_moments, create_moment, delete_moment, toggle_moment_reaction, create_moment_comment, reply_moment_comment, delete_moment_comment, update_account_profile, upload_avatar_image, memory_search, memory_read, memory_write, memory_edit, metadata_sync, metadata_update)");
+    api.registerTool({
+        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)."),
+        parameters: ClawchatRegisterAppSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_register_app", params, async () => {
+                const p = params;
+                return await withClient((c) => c.registerApp({ name: p.name, appId: p.appId, url: p.url }));
+            });
+        },
+    }, { name: "clawchat_register_app" });
+    api.registerTool({
+        name: "clawchat_list_apps",
+        label: "List ClawChat Apps",
+        description: toolDescription("List the liveware web apps this agent has registered to ClawChat."),
+        parameters: ClawchatListAppsSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_list_apps", params, async () => withClient((c) => c.listApps()));
+        },
+    }, { name: "clawchat_list_apps" });
+    api.registerTool({
+        name: "clawchat_unregister_app",
+        label: "Unregister ClawChat App",
+        description: toolDescription("Unregister a previously registered liveware app from ClawChat. Param: appId (liveware app id)."),
+        parameters: ClawchatUnregisterAppSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_unregister_app", params, async () => {
+                const p = params;
+                return await withClient((c) => c.unregisterApp(p.appId));
+            });
+        },
+    }, { name: "clawchat_unregister_app" });
+    api.registerTool({
+        name: "clawchat_liveware_login",
+        label: "Login to Liveware",
+        description: toolDescription("Log in to liveware CLI using the plugin-held ClawChat access token. " +
+            "The token is resolved from the plugin's own credential store and is never passed through the LLM context. " +
+            "Call this BEFORE any liveware tunnel or app commands; it is idempotent. " +
+            "Returns { ok: true } on success. Returns an error if liveware is not installed, the ClawChat account is not activated, or login fails."),
+        parameters: ClawchatLivewareLoginSchema,
+        async execute(_callId, params) {
+            return await recordClawchatToolCall("clawchat_liveware_login", params, async () => {
+                const acct = resolveCurrent();
+                const token = acct.token;
+                if (!token) {
+                    return configError("clawchat-plugin-openclaw: token is required");
+                }
+                return await new Promise((resolve) => {
+                    const livewarePath = resolveLivewarePath(api.runtime.state?.resolveStateDir?.());
+                    if (!livewarePath) {
+                        resolve(jsonResponse({
+                            error: "config",
+                            message: "liveware CLI not found in PATH; install liveware before calling this tool",
+                        }));
+                        return;
+                    }
+                    // Security: the token is passed as a child process argv value using
+                    // liveware's documented --access-token interface. It is in the child
+                    // argv briefly during process creation; env-var or stdin delivery
+                    // would be preferred if liveware supported it.
+                    // NEVER log the argv array; scrub token from any captured output below.
+                    execFile(livewarePath, ["login", "--access-token", token], { timeout: 30000 }, (err, stdout, stderr) => {
+                        const scrub = (s) => (token ? s.split(token).join("***") : s);
+                        const safeStdout = scrub(stdout ?? "").trim();
+                        const safeStderr = scrub(stderr ?? "").trim();
+                        if (err) {
+                            if (err.code === "ENOENT") {
+                                resolve(jsonResponse({
+                                    error: "config",
+                                    message: "liveware CLI not found in PATH; install liveware before calling this tool",
+                                }));
+                                return;
+                            }
+                            const detail = [safeStderr, safeStdout].filter(Boolean).join("\n").trim();
+                            resolve(jsonResponse({
+                                error: "liveware_login_failed",
+                                message: "liveware login failed" + (detail ? `: ${detail}` : ""),
+                            }));
+                            return;
+                        }
+                        resolve(jsonResponse({ ok: true }));
+                    });
+                });
+            });
+        },
+    }, { name: "clawchat_liveware_login" });
+    api.logger.debug?.("clawchat-plugin-openclaw: registered 30 clawchat_* tools (get_account_profile, get_user_profile, list_account_friends, send_friend_request, list_friend_requests, accept_friend_request, reject_friend_request, remove_friend, search_users, get_conversation, mention_message, list_moments, create_moment, delete_moment, toggle_moment_reaction, create_moment_comment, reply_moment_comment, delete_moment_comment, update_account_profile, upload_avatar_image, memory_search, memory_read, memory_write, memory_edit, metadata_sync, metadata_update, register_app, list_apps, unregister_app, liveware_login)");
 }

package/openclaw.plugin.json

@@ -59,7 +59,11 @@
       "clawchat_memory_write",
       "clawchat_memory_edit",
       "clawchat_metadata_sync",
-      "clawchat_metadata_update"
+      "clawchat_metadata_update",
+      "clawchat_register_app",
+      "clawchat_list_apps",
+      "clawchat_unregister_app",
+      "clawchat_liveware_login"
     ]
   },
   "configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.6.22-1",
+  "version": "2026.6.24-1",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "files": [

package/skills/liveware-app/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: liveware-app
+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, and registering the public URL to ClawChat.
+---
+
+# liveware App Hosting
+
+Expose a local web service through a liveware tunnel and register the public URL to
+ClawChat so it shows as an app tile in the owner's chat with this agent.
+
+## Prerequisites — check first, stop if unmet
+
+1. Run `command -v liveware`. If it prints nothing (liveware is not installed), tell the
+   user this environment does not support liveware app hosting and STOP. Do not attempt
+   any further step or invent a URL.
+2. Authentication is handled by the ClawChat plugin, not by you. You log in by calling the
+   `clawchat_liveware_login` tool (step 1 below). Never read, print, or pass the ClawChat
+   access token yourself — the plugin holds it in its own credential store and never
+   exposes it to you or puts it in your context.
+
+## Procedure
+
+1. **Login** (idempotent) — call the tool; do NOT run `liveware login` yourself:
+   `clawchat_liveware_login()`
+   The plugin resolves the ClawChat access token from its own credential store and runs
+   the liveware login internally. If it returns an error (liveware missing, ClawChat not
+   activated, or login failed), relay that error to the user and STOP.
+2. **Decide the app name and local port.** Ask the user for the local web service port if
+   not already known (the port the agent's own web server listens on). Accept ONLY a plain
+   integer in the range 1–65535. Reject anything that is not purely numeric (e.g.
+   `3000; rm -rf /`) — never paste user-supplied text into a shell command. The bind target
+   is then exactly `http://127.0.0.1:<port>`.
+3. **List existing apps** to avoid duplicates and to recover ids:
+   `liveware app list`
+4. **Create the app** (skip if reusing an existing one):
+   `liveware app create "<app name>"`
+   - This prints/returns the new **app id**. Capture it.
+   - If liveware reports an app-limit / quota error, relay that error to the user verbatim
+     and STOP. Do not delete other apps to make room.
+5. **Bind the tunnel** to the local service. Use only the numeric `<port>` validated in
+   step 2, and pass the bind target as a single argument — do not wrap the command in extra
+   shell that interpolates unvalidated user input:
+   `liveware tunnel bind <app id> http://127.0.0.1:<port>`
+   - Capture the **public URL** liveware returns.
+6. **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>")`
+7. **Confirm** to the user: report the app name and public URL, and that it now appears in
+   their chat with this agent (open the「…」menu → the app tile).
+
+## Managing apps
+
+- To see what is registered to ClawChat: `clawchat_list_apps()`.
+- To remove one: `clawchat_unregister_app(appId="<app id>")` (this only removes it from
+  ClawChat; tear down the liveware tunnel/app with liveware's own commands separately).
+
+## Notes
+
+- Apps can be created up to liveware's account limit; surface its error rather than working
+  around it.
+- The registered web app opens in a sandboxed in-app browser on mobile with no ClawChat
+  login injected — do not assume the page can read the user's ClawChat identity.

package/src/api-client.ts

@@ -1,5 +1,6 @@
 import {
   ClawlingApiError,
+  type AgentAppView,
   type AgentMetadataPatch,
   type AgentProfile,
   type AgentConnectResult,
@@ -170,6 +171,9 @@ export interface OpenclawClawlingApiClient {
    * error still throws.
    */
   getMyGroupSettings(): Promise<GroupSettingsFetchResult>;
+  registerApp(params: { name: string; appId: string; url: string }): Promise<{ app: AgentAppView }>;
+  listApps(): Promise<{ apps: AgentAppView[] }>;
+  unregisterApp(appId: string): Promise<{ deleted: boolean }>;
 }
 
 /** Backend envelope codes for `POST /v1/auth/refresh` (§0). */
@@ -515,6 +519,20 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
         `/v1/friendships/${encodeURIComponent(friendUserId)}`,
       );
     },
+    async registerApp(params: { name: string; appId: string; url: string }): 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" },
+      });
+    },
+    async listApps(): Promise<{ apps: AgentAppView[] }> {
+      return await call<{ apps: AgentAppView[] }>("GET", "/v1/agents/me/apps");
+    },
+    async unregisterApp(appId: string): Promise<{ deleted: boolean }> {
+      assertNonBlankId(appId, "unregisterApp: appId");
+      return await call<{ deleted: boolean }>("DELETE", `/v1/agents/me/apps/${encodeURIComponent(appId)}`);
+    },
     async searchUsers(params): Promise<{ users: UserSearchHit[] }> {
       const sp = new URLSearchParams();
       if (typeof params.q === "string") sp.set("q", params.q);

package/src/api-types.ts

@@ -145,6 +145,8 @@ export interface AgentConnectResult {
   conversation?: AgentConnectConversation;
 }
 
+export type AgentAppView = { id: string; app_id?: string; name: string; url: string };
+
 export type ClawlingApiErrorKind =
   | "auth" // 401 / 403 — token bad or expired
   | "api" // server-returned non-zero `code`

package/src/liveware-cli.ts

@@ -0,0 +1,106 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
+
+export const LIVEWARE_BASE_URL = "https://media.clawling.chat/liveware/";
+
+// A non-default User-Agent is required: the CDN (Cloudflare) returns 403 for
+// known scripting/default UAs, so download requests must identify themselves.
+const LIVEWARE_USER_AGENT = "clawchat-liveware-installer";
+
+export type LivewareLogger = {
+  warn?: (m: string) => void;
+  debug?: (m: string) => void;
+  error?: (m: string) => void;
+};
+
+/** Directory where the downloaded binaries live: <stateDir>/clawchat/liveware. */
+export function livewareDir(stateDir?: string): string {
+  const root = stateDir ?? resolveStateDir();
+  return path.join(root, "clawchat", "liveware");
+}
+
+/** Map host platform/arch to the two asset filenames, or null if unsupported. */
+export function platformAssets(
+  plat: string = process.platform,
+  arch: string = process.arch,
+): { liveware: string; tunneAgent: string } | null {
+  const os = plat === "darwin" ? "darwin" : plat === "linux" ? "linux" : null;
+  const cpu = arch === "x64" ? "amd64" : arch === "arm64" ? "arm64" : null;
+  if (!os || !cpu) return null;
+  return { liveware: `liveware-${os}-${cpu}`, tunneAgent: `tunnel-agent-${os}-${cpu}` };
+}
+
+function findOnPath(name: string): string | null {
+  const raw = process.env.PATH ?? "";
+  for (const dir of raw.split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, name);
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return candidate;
+    } catch {
+      // not here; keep scanning
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the liveware executable to invoke:
+ *  1. on PATH        → "liveware" (let the OS resolve it)
+ *  2. downloaded dir → absolute path
+ *  3. otherwise      → null
+ */
+export function resolveLivewarePath(stateDir?: string): string | null {
+  if (findOnPath("liveware")) return "liveware";
+  const local = path.join(livewareDir(stateDir), "liveware");
+  try {
+    fs.accessSync(local, fs.constants.X_OK);
+    return local;
+  } catch {
+    return null;
+  }
+}
+
+async function downloadTo(url: string, dest: string): Promise<void> {
+  const res = await fetch(url, { headers: { "user-agent": LIVEWARE_USER_AGENT } });
+  if (!res.ok) throw new Error(`download ${url} failed: HTTP ${res.status}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  if (buf.length === 0) throw new Error(`download ${url} returned empty body`);
+  const tmp = `${dest}.tmp`;
+  await fs.promises.writeFile(tmp, buf);
+  await fs.promises.chmod(tmp, 0o755);
+  await fs.promises.rename(tmp, dest);
+}
+
+/**
+ * Startup hook: ensure the liveware CLI is available, downloading it when not.
+ * Fire-and-forget — never throws; logs and returns on any failure.
+ */
+export async function ensureLivewareCli(
+  opts: { stateDir?: string; log?: LivewareLogger } = {},
+): Promise<void> {
+  const { stateDir, log } = opts;
+  try {
+    if (findOnPath("liveware")) return; // PATH wins
+    const dir = livewareDir(stateDir);
+    const target = path.join(dir, "liveware");
+    if (fs.existsSync(target)) return;
+
+    const assets = platformAssets();
+    if (!assets) {
+      log?.warn?.(
+        `clawchat-plugin-openclaw: unsupported platform ${process.platform}/${process.arch}; skipping liveware download`,
+      );
+      return;
+    }
+
+    await fs.promises.mkdir(dir, { recursive: true });
+    await downloadTo(LIVEWARE_BASE_URL + assets.liveware, path.join(dir, "liveware"));
+    await downloadTo(LIVEWARE_BASE_URL + assets.tunneAgent, path.join(dir, "tunnel-agent"));
+    log?.debug?.(`clawchat-plugin-openclaw: liveware CLI downloaded to ${dir}`);
+  } catch (err) {
+    log?.warn?.(`clawchat-plugin-openclaw: liveware CLI download skipped: ${String(err)}`);
+  }
+}

package/src/runtime.ts

@@ -16,6 +16,7 @@ import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
 import { createOpenclawClawlingClient, resolveOpenclawClawlingDeviceId } from "./client.ts";
 import { createOpenclawClawlingApiClient } from "./api-client.ts";
 import { reportPluginVersionSafe, resolvePluginVersion } from "./plugin-report.ts";
+import { ensureLivewareCli } from "./liveware-cli.ts";
 import { ClawlingApiError } from "./api-types.ts";
 import { RefreshManager } from "./refresh-manager.ts";
 import {
@@ -920,6 +921,15 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     authenticated: false,
     log,
   });
+  // Ensure the liveware CLI is installed (async, never blocks startup).
+  void ensureLivewareCli({
+    stateDir: runtime.state?.resolveStateDir?.(),
+    log: {
+      warn: (m) => log?.info?.(m),
+      debug: (m) => log?.debug?.(m),
+      error: (m) => log?.error?.(m),
+    },
+  });
   // §B self-heal — non-interactive env connect-code activation BEFORE blocking on
   // the wait-for-activation loop. Gated so the common path (no env code, or an
   // already-credentialed account) adds NO async work: on success it credentials

package/src/tools-schema.ts

@@ -374,3 +374,21 @@ export const ClawchatUploadAvatarImageSchema = Type.Object({
   }),
 });
 export type ClawchatUploadAvatarImageParams = Static<typeof ClawchatUploadAvatarImageSchema>;
+
+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)." }),
+});
+export type ClawchatRegisterAppParams = Static<typeof ClawchatRegisterAppSchema>;
+
+export const ClawchatListAppsSchema = Type.Object({});
+export type ClawchatListAppsParams = Static<typeof ClawchatListAppsSchema>;
+
+export const ClawchatUnregisterAppSchema = Type.Object({
+  appId: Type.String({ minLength: 1, description: "The liveware app id to unregister." }),
+});
+export type ClawchatUnregisterAppParams = Static<typeof ClawchatUnregisterAppSchema>;
+
+export const ClawchatLivewareLoginSchema = Type.Object({});
+export type ClawchatLivewareLoginParams = Static<typeof ClawchatLivewareLoginSchema>;

package/src/tools.ts

@@ -1,8 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
+import { execFile } from "node:child_process";
 import type { OpenClawAgentToolResult } from "openclaw/plugin-sdk/agent-harness-runtime";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk/core";
 import { createOpenclawClawlingApiClient } from "./api-client.ts";
+import { resolveLivewarePath } from "./liveware-cli.ts";
 import {
   ClawlingApiError,
   type Profile,
@@ -60,6 +62,10 @@ import {
   ClawchatToggleMomentReactionSchema,
   ClawchatUpdateAccountProfileSchema,
   ClawchatUploadAvatarImageSchema,
+  ClawchatRegisterAppSchema,
+  ClawchatListAppsSchema,
+  ClawchatUnregisterAppSchema,
+  ClawchatLivewareLoginSchema,
   type ClawchatMemoryEditParams,
   type ClawchatMemoryReadParams,
   type ClawchatMemorySearchParams,
@@ -84,6 +90,9 @@ import {
   type ClawchatToggleMomentReactionParams,
   type ClawchatUpdateAccountProfileParams,
   type ClawchatUploadAvatarImageParams,
+  type ClawchatRegisterAppParams,
+  type ClawchatUnregisterAppParams,
+  type ClawchatLivewareLoginParams,
 } from "./tools-schema.ts";
 
 const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
@@ -1290,7 +1299,123 @@ export function registerOpenclawClawlingTools(
     { name: "clawchat_upload_avatar_image" },
   );
 
+  api.registerTool(
+    {
+      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).",
+      ),
+      parameters: ClawchatRegisterAppSchema,
+      async execute(_callId, params) {
+        return await recordClawchatToolCall("clawchat_register_app", params, async () => {
+          const p = params as ClawchatRegisterAppParams;
+          return await withClient((c) => c.registerApp({ name: p.name, appId: p.appId, url: p.url }));
+        });
+      },
+    },
+    { name: "clawchat_register_app" },
+  );
+
+  api.registerTool(
+    {
+      name: "clawchat_list_apps",
+      label: "List ClawChat Apps",
+      description: toolDescription("List the liveware web apps this agent has registered to ClawChat."),
+      parameters: ClawchatListAppsSchema,
+      async execute(_callId, params) {
+        return await recordClawchatToolCall("clawchat_list_apps", params, async () => withClient((c) => c.listApps()));
+      },
+    },
+    { name: "clawchat_list_apps" },
+  );
+
+  api.registerTool(
+    {
+      name: "clawchat_unregister_app",
+      label: "Unregister ClawChat App",
+      description: toolDescription("Unregister a previously registered liveware app from ClawChat. Param: appId (liveware app id)."),
+      parameters: ClawchatUnregisterAppSchema,
+      async execute(_callId, params) {
+        return await recordClawchatToolCall("clawchat_unregister_app", params, async () => {
+          const p = params as ClawchatUnregisterAppParams;
+          return await withClient((c) => c.unregisterApp(p.appId));
+        });
+      },
+    },
+    { name: "clawchat_unregister_app" },
+  );
+
+  api.registerTool(
+    {
+      name: "clawchat_liveware_login",
+      label: "Login to Liveware",
+      description: toolDescription(
+        "Log in to liveware CLI using the plugin-held ClawChat access token. " +
+        "The token is resolved from the plugin's own credential store and is never passed through the LLM context. " +
+        "Call this BEFORE any liveware tunnel or app commands; it is idempotent. " +
+        "Returns { ok: true } on success. Returns an error if liveware is not installed, the ClawChat account is not activated, or login fails.",
+      ),
+      parameters: ClawchatLivewareLoginSchema,
+      async execute(_callId, params) {
+        return await recordClawchatToolCall("clawchat_liveware_login", params as ClawchatLivewareLoginParams, async () => {
+          const acct = resolveCurrent();
+          const token = acct.token;
+          if (!token) {
+            return configError("clawchat-plugin-openclaw: token is required");
+          }
+
+          return await new Promise<ReturnType<typeof jsonResponse>>((resolve) => {
+            const livewarePath = resolveLivewarePath(api.runtime.state?.resolveStateDir?.());
+            if (!livewarePath) {
+              resolve(jsonResponse({
+                error: "config",
+                message: "liveware CLI not found in PATH; install liveware before calling this tool",
+              }));
+              return;
+            }
+            // Security: the token is passed as a child process argv value using
+            // liveware's documented --access-token interface. It is in the child
+            // argv briefly during process creation; env-var or stdin delivery
+            // would be preferred if liveware supported it.
+            // NEVER log the argv array; scrub token from any captured output below.
+            execFile(
+              livewarePath,
+              ["login", "--access-token", token],
+              { timeout: 30000 },
+              (err, stdout, stderr) => {
+                const scrub = (s: string) => (token ? s.split(token).join("***") : s);
+                const safeStdout = scrub(stdout ?? "").trim();
+                const safeStderr = scrub(stderr ?? "").trim();
+
+                if (err) {
+                  if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+                    resolve(jsonResponse({
+                      error: "config",
+                      message: "liveware CLI not found in PATH; install liveware before calling this tool",
+                    }));
+                    return;
+                  }
+                  const detail = [safeStderr, safeStdout].filter(Boolean).join("\n").trim();
+                  resolve(jsonResponse({
+                    error: "liveware_login_failed",
+                    message: "liveware login failed" + (detail ? `: ${detail}` : ""),
+                  }));
+                  return;
+                }
+
+                resolve(jsonResponse({ ok: true }));
+              },
+            );
+          });
+        });
+      },
+    },
+    { name: "clawchat_liveware_login" },
+  );
+
   api.logger.debug?.(
-    "clawchat-plugin-openclaw: registered 26 clawchat_* tools (get_account_profile, get_user_profile, list_account_friends, send_friend_request, list_friend_requests, accept_friend_request, reject_friend_request, remove_friend, search_users, get_conversation, mention_message, list_moments, create_moment, delete_moment, toggle_moment_reaction, create_moment_comment, reply_moment_comment, delete_moment_comment, update_account_profile, upload_avatar_image, memory_search, memory_read, memory_write, memory_edit, metadata_sync, metadata_update)",
+    "clawchat-plugin-openclaw: registered 30 clawchat_* tools (get_account_profile, get_user_profile, list_account_friends, send_friend_request, list_friend_requests, accept_friend_request, reject_friend_request, remove_friend, search_users, get_conversation, mention_message, list_moments, create_moment, delete_moment, toggle_moment_reaction, create_moment_comment, reply_moment_comment, delete_moment_comment, update_account_profile, upload_avatar_image, memory_search, memory_read, memory_write, memory_edit, metadata_sync, metadata_update, register_app, list_apps, unregister_app, liveware_login)",
   );
 }