create-openclaw-bot 5.15.2 → 5.16.0

package/dist/server/local-server.js

@@ -16,6 +16,7 @@ function loadSharedModule(modulePath, globalName) {
 const { buildWorkspaceFileMap, buildCronjobSkillMd, buildInfographicGeneratorSkillMd, buildInfographicGeneratorJs } = loadSharedModule('../setup/shared/workspace-gen.js', '__openclawWorkspace');
 const { buildOpenclawJson, buildEnvFileContent, buildExecApprovalsJson, buildZaloConnectChannelConfig } = loadSharedModule('../setup/shared/bot-config-gen.js', '__openclawBotConfig');
 const { buildDockerArtifacts } = loadSharedModule('../setup/shared/docker-gen.js', '__openclawDockerGen');
+const { HOST_UI_PS1, HOST_UI_PS1_VERSION } = loadSharedModule('../setup/shared/host-ui-ps1.js', '__openclawHostUiPs1');
 const { OPENCLAW_NPM_SPEC, NINE_ROUTER_NPM_SPEC, ZALO_CHANNEL_ID, ZALO_PLUGIN_ID, ZALO_CONNECT_VERSION, ZALO_CONNECT_PLUGIN_SPEC, build9RouterProviderConfig, get9RouterBaseUrl } = loadSharedModule('../setup/shared/common-gen.js', '__openclawCommon');
 const dataExport = loadSharedModule('../setup/data/index.js', '__openclawData');
 
@@ -591,7 +592,18 @@ function detectOs() {
   const platform = process.platform;
   if (platform === 'win32') return 'win';
   if (platform === 'darwin') return 'macos';
-  if (platform === 'linux') return os.release().toLowerCase().includes('microsoft') ? 'linux-desktop' : 'linux-desktop';
+  if (platform === 'linux') {
+    // WSL always has a Windows desktop behind it, so it counts as a desktop. Otherwise a session
+    // with no display server is a headless server, and the distinction is not cosmetic: 'vps' is
+    // what opens the gateway bind past loopback (bot-config-gen) — pick 'linux-desktop' on a VPS
+    // and the dashboard is only reachable through an SSH tunnel, while the browser tooling is set
+    // up as though a local Chrome existed.
+    if (os.release().toLowerCase().includes('microsoft')) return 'linux-desktop';
+    const sessionType = String(process.env.XDG_SESSION_TYPE || '').toLowerCase();
+    const hasDisplay = !!(process.env.DISPLAY || process.env.WAYLAND_DISPLAY || process.env.XDG_CURRENT_DESKTOP)
+      || sessionType === 'x11' || sessionType === 'wayland';
+    return hasDisplay ? 'linux-desktop' : 'vps';
+  }
   return 'linux-desktop';
 }
 
@@ -913,6 +925,11 @@ function runCapture(cmd, args, opts = {}) {
       windowsHide: opts.windowsHide ?? true,
       env: { ...process.env, ...(opts.env || {}) },
     });
+    // Some callers need to feed stdin (pbcopy/xclip take the clipboard text that way).
+    if (opts.input != null) {
+      try { child.stdin.write(String(opts.input)); } catch (_) {}
+      try { child.stdin.end(); } catch (_) {}
+    }
     let timedOut = false;
     const timer = Number.isFinite(opts.timeout) && opts.timeout > 0
       ? setTimeout(() => {
@@ -1755,6 +1772,25 @@ function portStatus(port) {
   });
 }
 
+/**
+ * First port at or after `start` that nothing on this host is listening on.
+ *
+ * The install-time allocator only knows about setup-managed projects, so it cannot see a docker
+ * project from another install, an SSH tunnel forwarding a remote bot's ports, or any other
+ * listener. Docker tolerates that (compose publishes into loopback and fails loudly on a clash);
+ * native binds the host directly, so it has to ask the host.
+ *
+ * `reserveNext` also requires port+1 to be free — that is where the zalo-mod dashboard lands.
+ */
+async function findFreeHostPort(start, { reserveNext = false, limit = 100 } = {}) {
+  for (let port = start; port < start + limit; port++) {
+    if ((await portStatus(port)) === 'online') continue;
+    if (reserveNext && (await portStatus(port + 1)) === 'online') continue;
+    return port;
+  }
+  return start;
+}
+
 async function buildBotStatus() {
   if (state.projectDir) await syncRuntimeState(state.projectDir).catch(() => {});
   const [gatewayStatus, routerStatus, bots, runtimeVersions] = await Promise.all([
@@ -2104,6 +2140,35 @@ async function waitForDockerContainer(name, timeoutMs = 30000) {
   return false;
 }
 
+/**
+ * Drop OpenClaw's boxed "Config warnings" banner (and any stray warning line) from CLI output.
+ *
+ * The banner prints on EVERY invocation and quotes the offending config keys verbatim, so a project
+ * whose zalo-connect plugin is missing has `channels.zalo-connect: unknown channel id: zalo-connect`
+ * in the output of *any* command. A readiness check that greps stdout for a channel id therefore
+ * reports "channel loaded" precisely when the plugin is absent — the check inverts itself. Strip the
+ * warnings before matching so only real command output counts.
+ */
+function stripCliWarnings(text = '') {
+  const kept = [];
+  let inBanner = false;
+  for (const line of String(text).split(/\r?\n/)) {
+    if (/◇\s*Config warnings/.test(line)) { inBanner = true; continue; }
+    // The banner is drawn as a box; its bottom edge is the only line starting with ├ or └.
+    if (inBanner) {
+      if (/^\s*[├└]/.test(line)) inBanner = false;
+      continue;
+    }
+    if (/unknown channel id|plugin not found|stale config|no channel plugin is installed/i.test(line)) continue;
+    kept.push(line);
+  }
+  return kept.join('\n');
+}
+
+// Both keywords are load-bearing, and callers must not narrow them to the id alone: `channels
+// status` lists a loaded channel by its DISPLAY NAME ("OpenClaw Zalo Connect default: enabled, …"),
+// so the hyphenated id shows up only in the stale-config warnings stripCliWarnings now removes.
+// Match on the id alone and the check can never pass once the plugin is actually installed.
 async function waitForGatewayZaloReady(botContainer, projectDir, timeoutMs = 90000, channelKeywords = ['zalo-connect', 'openclaw zalo connect']) {
   const started = Date.now();
   // Use dynamic port from env: OPENCLAW_GATEWAY_PORT → OPENCLAW_PORT → fallback 18789
@@ -2118,7 +2183,7 @@ async function waitForGatewayZaloReady(botContainer, projectDir, timeoutMs = 900
       const status = String(out.stdout || '').trim();
       if (status === 'READY') {
         const pluginCheck = await runCapture('docker', ['exec', botContainer, 'sh', '-c', 'openclaw channels status 2>&1 || true'], { cwd: projectDir, shell: false });
-        const output = ((pluginCheck.stdout || '') + ' ' + (pluginCheck.stderr || '')).toLowerCase();
+        const output = stripCliWarnings((pluginCheck.stdout || '') + '\n' + (pluginCheck.stderr || '')).toLowerCase();
         if (channelKeywords.some((kw) => output.includes(kw))) {
           ready = true;
           break;
@@ -2142,13 +2207,21 @@ async function waitForNativeGatewayZaloReady(projectDir, timeoutMs = 90000, chan
   const started = Date.now();
   const meta = readNativeMeta(projectDir) || {};
   const port = String(meta.gatewayPort || state.gatewayPort || NATIVE_DEFAULT_GATEWAY_PORT);
+  const extDir = join(projectDir, '.openclaw', 'extensions', 'zalo-connect');
   let ready = false;
   let attempts = 0;
   while (Date.now() - started < timeoutMs) {
     attempts++;
+    // Decisive, free, and immune to the warning-banner trap above: with no plugin folder the channel
+    // cannot possibly be loaded, so return right away and let the caller install it instead of
+    // burning the whole timeout waiting for something that will never appear.
+    if (!existsSync(extDir)) {
+      sendLog('[zalo-connect] Plugin folder .openclaw/extensions/zalo-connect is absent — not waiting.');
+      return false;
+    }
     if (await probeHttpOk(`http://127.0.0.1:${port}/health`, 2500)) {
       const st = await ocCapture(projectDir, ['channels', 'status']).catch(() => ({ stdout: '', stderr: '' }));
-      const output = ((st.stdout || '') + ' ' + (st.stderr || '')).toLowerCase();
+      const output = stripCliWarnings((st.stdout || '') + '\n' + (st.stderr || '')).toLowerCase();
       if (channelKeywords.some((kw) => output.includes(kw))) { ready = true; break; }
       if (attempts > 2) sendLog('[zalo-connect] Gateway healthy but Zalo Connect is not loaded yet (' + Math.round((Date.now() - started) / 1000) + 's)...');
     } else if (attempts > 2 && attempts % 3 === 0) {
@@ -2198,20 +2271,17 @@ async function startZaloConnectLogin(projectDir, accountId = 'default') {
       // No container: the gateway runs as a managed service on the host. Wait for it to
       // report the zalo-connect channel; if it never does and the plugin folder is absent,
       // install it on the host (into this project's .openclaw/extensions) and reload.
-      const gatewayReady = await waitForNativeGatewayZaloReady(projectDir, 180000, ['zalo-connect']);
+      const gatewayReady = await waitForNativeGatewayZaloReady(projectDir, 180000);
       if (!gatewayReady) {
-        const extDir = join(projectDir, '.openclaw', 'extensions', 'zalo-connect');
-        if (!existsSync(extDir)) {
-          sendLog(`[zalo-connect] Plugin missing — installing ${ZALO_CONNECT_PLUGIN_SPEC} natively...`);
-          const inst = await ocCapture(projectDir, ['plugins', 'install', ZALO_CONNECT_PLUGIN_SPEC, '--force', '--acknowledge-clawhub-risk']);
-          const instOut = `${inst.stdout}\n${inst.stderr}`;
-          for (const line of instOut.split(/\r?\n/).filter(Boolean)) sendLog(`[zalo-connect] ${line}`);
-          if (/installed plugin/i.test(instOut) || existsSync(extDir)) {
-            await restartNativeRuntime(projectDir).catch((err) => sendLog(`[native] restart skipped/failed: ${err.message}`));
-            await waitForNativeGatewayZaloReady(projectDir, 180000, ['zalo-connect']);
-          } else {
-            sendLog('[zalo-connect] Cài plugin không thành công — thử lại bằng nút "Đăng nhập Zalo".');
-          }
+        // ensureNativePlugins is the single place that knows what a native project owes itself, and
+        // it skips whatever is already on disk — so this covers learning-memory too, and reconnects
+        // on a healthy project cost nothing.
+        const installed = await ensureNativePlugins(projectDir);
+        if (installed.includes(ZALO_PLUGIN_ID)) {
+          await restartNativeRuntime(projectDir).catch((err) => sendLog(`[native] restart skipped/failed: ${err.message}`));
+          await waitForNativeGatewayZaloReady(projectDir, 180000);
+        } else if (!existsSync(join(projectDir, '.openclaw', 'extensions', 'zalo-connect'))) {
+          sendLog('[zalo-connect] Cài plugin không thành công — thử lại bằng nút "Đăng nhập Zalo".');
         }
       }
     } else {
@@ -2224,7 +2294,7 @@ async function startZaloConnectLogin(projectDir, accountId = 'default') {
       // backend-aware entrypoint existed).
       const containerUp = await waitForDockerContainer(botContainer, 90000);
       if (!containerUp) sendLog(`[zalo-connect] ${botContainer} chưa chạy sau 90s — vẫn thử tiếp...`);
-      const gatewayReady = await waitForGatewayZaloReady(botContainer, projectDir, 180000, ['zalo-connect']);
+      const gatewayReady = await waitForGatewayZaloReady(botContainer, projectDir, 180000);
       if (!gatewayReady) {
         const check = await runCapture('docker', ['exec', botContainer, 'sh', '-lc', '[ -d "${OPENCLAW_HOME:-/home/node/project/.openclaw}/extensions/zalo-connect" ] && echo OK || echo MISSING'], { cwd: projectDir, shell: false }).catch(() => ({ stdout: 'ERR' }));
         if (String(check.stdout || '').trim() === 'MISSING') {
@@ -2237,7 +2307,7 @@ async function startZaloConnectLogin(projectDir, accountId = 'default') {
             // Gateway must reload to pick the plugin up — safe here: the gateway is past
             // its boot (we only reach this branch when it answered the exec above).
             await restartDockerBotContainer(projectDir).catch((err) => sendLog(`[docker] restart skipped/failed: ${err.message}`));
-            await waitForGatewayZaloReady(botContainer, projectDir, 180000, ['zalo-connect']);
+            await waitForGatewayZaloReady(botContainer, projectDir, 180000);
           } else {
             sendLog('[zalo-connect] Cài plugin không thành công — thử lại bằng nút "Đăng nhập Zalo" sau khi container ổn định.');
           }
@@ -2563,10 +2633,13 @@ function getBotServiceName(projectDir) {
 // single fixed one, so without this a second native project would take over the first's service.
 
 const NATIVE_MARKER = 'native.json';
-// Native ports sit one hundred above the docker ones (18789/20128) so a native project can run
-// next to a docker project — or next to an SSH tunnel forwarding a remote bot's ports — untouched.
-const NATIVE_DEFAULT_GATEWAY_PORT = 18889;
-const NATIVE_DEFAULT_ROUTER_PORT = 20228;
+// Native uses the same ports as everything else: openclaw's 18789 and 9router's 20128. It used to
+// jump a hundred above them unconditionally so it could sit next to a docker project, but that fired
+// even on a machine with nothing running at all — a fresh VPS still landed on 18889/20228, so every
+// tunnel command, bookmark and doc pointed at a port the user never chose. findFreeHostPort() now
+// handles coexistence by asking the host what is actually taken, which the fixed offset never did.
+const NATIVE_DEFAULT_GATEWAY_PORT = 18789;
+const NATIVE_DEFAULT_ROUTER_PORT = 20128;
 
 function nativeMarkerPath(projectDir) {
   return join(projectDir || state.projectDir || '', '.openclaw', NATIVE_MARKER);
@@ -2638,6 +2711,47 @@ function ocCapture(projectDir, args, opts = {}) {
   return runCapture(a.cmd, a.args, { shell: false, ...a.opts, ...opts, env: { ...(a.opts.env || {}), ...(opts.env || {}) } });
 }
 
+/** Probe the managed gateway's own /health until it answers. */
+async function waitForNativeGatewayHealthy(projectDir, timeoutMs = 120000) {
+  const meta = readNativeMeta(projectDir) || {};
+  const port = String(meta.gatewayPort || state.gatewayPort || NATIVE_DEFAULT_GATEWAY_PORT);
+  const started = Date.now();
+  let attempts = 0;
+  while (Date.now() - started < timeoutMs) {
+    if (await probeHttpOk(`http://127.0.0.1:${port}/health`, 2500)) return true;
+    attempts++;
+    if (attempts % 5 === 0) sendLog(`[native] Waiting for gateway on ${port}... (${Math.round((Date.now() - started) / 1000)}s)`);
+    await new Promise((r) => setTimeout(r, 3000));
+  }
+  sendLog(`[native] Gateway did not answer /health on ${port} within ${Math.round(timeoutMs / 1000)}s.`);
+  return false;
+}
+
+/**
+ * The first gateway boot runs OpenClaw's startup migrations under a state-directory lease, and a
+ * second gateway that tries to start meanwhile exits 1 with this message rather than waiting. The
+ * docker path sidesteps it by never poking a booting container (see startZaloConnectLogin); when we
+ * do hit it natively, the message carries the exact instant the lease frees — so wait that out
+ * instead of retrying blind into systemd's StartLimitBurst (5 per 60s, after which the unit is
+ * abandoned for good).
+ */
+function migrationLeaseDeadline(text = '') {
+  const m = String(text).match(/migrations are already running[\s\S]*?after\s+(\d{4}-\d{2}-\d{2}T[\d:.]+Z)/i);
+  if (!m) return 0;
+  const t = Date.parse(m[1]);
+  return Number.isFinite(t) ? t : 0;
+}
+
+/** `openclaw daemon <verb>` for a native project: streams output to the UI log AND returns it. */
+async function ocDaemon(projectDir, verb, extraArgs = []) {
+  const args = ['daemon', verb, ...extraArgs];
+  sendLog(`$ openclaw ${args.join(' ')}`);
+  const out = await runCapture('openclaw', args, { cwd: projectDir, env: nativeEnv(projectDir), shell: false, timeout: 120000 });
+  const text = `${out.stdout || ''}\n${out.stderr || ''}`;
+  for (const line of text.split(/\r?\n/).map((l) => l.trimEnd()).filter(Boolean)) sendLog(line);
+  return { ...out, text };
+}
+
 /**
  * Restart the native gateway service.
  *
@@ -2646,20 +2760,215 @@ function ocCapture(projectDir, args, opts = {}) {
  * newly installed plugins never load, silently). stop+start is what actually works there, and it
  * works everywhere else too, so Windows takes that path and other systems keep `restart` with
  * stop+start as a fallback.
+ *
+ * Health is confirmed over /health at the end rather than trusted from the CLI's exit code: the
+ * CLI gives up verifying after ~13s while the generated unit allows 30s to start, so a slow but
+ * perfectly healthy gateway reports "restart failed" — which used to send callers down a pointless
+ * stop+start that raced the migration lease all over again.
  */
 async function restartNativeRuntime(projectDir) {
-  const env = nativeEnv(projectDir);
+  // Every restart is a chance to repair a project installed before these two fixes existed — both
+  // calls are no-ops once the service env is complete and the stray files have been adopted.
+  await adoptStrayNativeHome(projectDir).catch(() => {});
+  await syncNativeServiceEnv(projectDir).catch(() => {});
   const stopStart = async () => {
-    await run('openclaw', ['daemon', 'stop'], { cwd: projectDir, env }).catch(() => {});
-    await run('openclaw', ['daemon', 'start'], { cwd: projectDir, env });
+    await ocDaemon(projectDir, 'stop');
+    return ocDaemon(projectDir, 'start');
   };
-  if (process.platform === 'win32') return stopStart();
-  try {
-    await run('openclaw', ['daemon', 'restart'], { cwd: projectDir, env });
-  } catch (e) {
-    sendLog(`[native] daemon restart failed (${e.message}); falling back to stop+start`);
-    await stopStart();
+  let res;
+  if (process.platform === 'win32') {
+    res = await stopStart();
+  } else {
+    res = await ocDaemon(projectDir, 'restart');
+    // A lease collision is a "come back in a moment", not a broken service: stop+start would only
+    // collide again, so fall through to the wait below instead.
+    if (res.code !== 0 && !migrationLeaseDeadline(res.text)) {
+      sendLog(`[native] daemon restart exited ${res.code}; falling back to stop+start`);
+      res = await stopStart();
+    }
+  }
+  const deadline = migrationLeaseDeadline(res.text);
+  if (deadline) {
+    const waitMs = Math.max(0, Math.min(deadline - Date.now(), 300000)) + 3000;
+    sendLog(`[native] Startup migrations hold the state lease — waiting ${Math.ceil(waitMs / 1000)}s before retrying.`);
+    await new Promise((r) => setTimeout(r, waitMs));
+    res = await ocDaemon(projectDir, 'restart');
+    if (res.code !== 0) res = await stopStart();
+  }
+  // systemd keeps restarting a crash-looping unit every RestartSec, so a gateway blocked by a lease
+  // we never saw still comes up on its own — give it room before calling the restart a failure.
+  if (!(await waitForNativeGatewayHealthy(projectDir, 180000))) {
+    throw new Error('gateway did not answer /health after restart');
+  }
+  return true;
+}
+
+/**
+ * Make the generated service carry everything nativeEnv() promises.
+ *
+ * `openclaw daemon install` propagates only a fixed allow-list into the service it writes:
+ * OPENCLAW_STATE_DIR survives, but OPENCLAW_HOME does NOT — verified on both a systemd user unit and
+ * a launchd env-wrapper. Anything resolving paths from OPENCLAW_HOME then falls back to `~/.openclaw`
+ * and writes OUTSIDE the project. zalo-connect is the visible casualty: it stages inbound files and
+ * its Zalo session credentials under the wrong home, so a PDF sent to the bot lands somewhere the
+ * agent's workspace cannot reach ("em chưa trích xuất được nội dung từ PDF") and the session sits in
+ * a different home from the config that describes it.
+ *
+ * Idempotent: keys already present are left alone, so this is safe to run on every restart and it
+ * self-heals projects created before the fix.
+ */
+async function syncNativeServiceEnv(projectDir) {
+  if (!isNativeProject(projectDir)) return [];
+  const want = nativeEnv(projectDir);
+  const label = nativeServiceLabel(projectDir);
+
+  if (process.platform === 'linux') {
+    const unit = `${label}.service`;
+    const shown = await runCapture('systemctl', ['--user', 'show', '-p', 'FragmentPath', '--value', unit], { shell: false, timeout: 10000 });
+    const path = String(shown.stdout || '').trim() || join(os.homedir(), '.config', 'systemd', 'user', unit);
+    if (!existsSync(path)) return [];
+    const lines = (await fsp.readFile(path, 'utf8')).split('\n');
+    const have = new Set();
+    for (const line of lines) {
+      const m = line.trim().match(/^Environment="?([A-Z_0-9]+)=/);
+      if (m) have.add(m[1]);
+    }
+    const missing = Object.entries(want).filter(([k, v]) => !have.has(k) && v !== '');
+    if (!missing.length) return [];
+    // Insert after the last existing Environment= line so the additions stay inside [Service].
+    let at = -1;
+    lines.forEach((line, i) => { if (line.startsWith('Environment=')) at = i; });
+    if (at < 0) at = lines.findIndex((line) => line.trim() === '[Service]');
+    if (at < 0) return [];
+    lines.splice(at + 1, 0, ...missing.map(([k, v]) => `Environment=${k}=${v}`));
+    await fsp.copyFile(path, `${path}.bak`).catch(() => {});
+    await fsp.writeFile(path, lines.join('\n'), 'utf8');
+    await run('systemctl', ['--user', 'daemon-reload'], {}).catch(() => {});
+    sendLog(`[native] service env completed: ${missing.map(([k]) => k).join(', ')}`);
+    return missing.map(([k]) => k);
   }
+
+  if (process.platform === 'darwin') {
+    // launchd runs the gateway through an env-wrapper that sources this file, so patching it is the
+    // launchd equivalent of adding Environment= lines to a unit.
+    const envFile = join(projectDir, '.openclaw', 'service-env', `${label}.env`);
+    if (!existsSync(envFile)) return [];
+    const body = await fsp.readFile(envFile, 'utf8');
+    const have = new Set([...body.matchAll(/^\s*export\s+([A-Z_0-9]+)=/gm)].map((m) => m[1]));
+    const missing = Object.entries(want).filter(([k, v]) => !have.has(k) && v !== '');
+    if (!missing.length) return [];
+    const added = missing.map(([k, v]) => `export ${k}='${String(v).replace(/'/g, "'\\''")}'`).join('\n');
+    await fsp.copyFile(envFile, `${envFile}.bak`).catch(() => {});
+    await fsp.writeFile(envFile, `${body.replace(/\n*$/, '')}\n${added}\n`, 'utf8');
+    sendLog(`[native] service env completed: ${missing.map(([k]) => k).join(', ')}`);
+    return missing.map(([k]) => k);
+  }
+
+  return [];
+}
+
+/**
+ * Reunite a native project with the files an unset OPENCLAW_HOME scattered into `~/.openclaw`.
+ *
+ * This MUST run before syncNativeServiceEnv takes effect: once OPENCLAW_HOME is finally correct, the
+ * plugin looks for its Zalo session inside the project — and if the credentials are still sitting in
+ * the home directory it finds nothing and demands a fresh QR login. Copy (never move) so a failed
+ * run leaves the working original in place; skip anything the project already has.
+ */
+async function adoptStrayNativeHome(projectDir) {
+  if (!isNativeProject(projectDir)) return [];
+  const projectHome = join(projectDir, '.openclaw');
+  const strayHome = join(os.homedir(), '.openclaw');
+  if (resolve(strayHome) === resolve(projectHome) || !existsSync(strayHome)) return [];
+  const moved = [];
+  const entries = await fsp.readdir(strayHome, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    // `state` is deliberately excluded: the project has its own live database and merging two
+    // sqlite files is not something a copy can do correctly.
+    const isCreds = /^zalo-connect-credentials.*\.json$/.test(entry.name);
+    if (!isCreds && entry.name !== 'media') continue;
+    const from = join(strayHome, entry.name);
+    const to = join(projectHome, entry.name);
+    if (existsSync(to)) continue;
+    await fsp.cp(from, to, { recursive: true }).catch(() => {});
+    if (existsSync(to)) moved.push(entry.name);
+  }
+  if (moved.length) {
+    sendLog(`[migrate] Native: adopted ${moved.join(', ')} from ${strayHome} (written there while OPENCLAW_HOME was unset).`);
+  }
+  return moved;
+}
+
+/**
+ * `openclaw daemon install` has no `--system` flag, so on Linux the gateway becomes a systemd USER
+ * unit — and a user manager without linger is torn down when that user's last session exits. On a
+ * desktop the graphical session holds it open, which is why this never showed up on macOS or a
+ * Linux desktop; on a VPS the bot dies the moment the operator closes SSH and never comes back
+ * after a reboot. Linger is what makes a user unit behave like the `restart: always` container it
+ * replaces. Best-effort: a box without loginctl just keeps the old behaviour, loudly.
+ */
+async function ensureSystemdLinger() {
+  if (process.platform !== 'linux') return false;
+  let user = '';
+  try { user = process.env.SUDO_USER || os.userInfo().username; } catch { return false; }
+  if (!user) return false;
+  const cur = await runCapture('loginctl', ['show-user', user, '-p', 'Linger'], { shell: false, timeout: 10000 });
+  if (/Linger=yes/i.test(cur.stdout || '')) return true;
+  const out = await runCapture('loginctl', ['enable-linger', user], { shell: false, timeout: 20000 });
+  if (out.code === 0) {
+    sendLog(`[native] systemd linger enabled for "${user}" — the gateway now survives logout and reboot.`);
+    return true;
+  }
+  sendLog(`[native] WARNING: could not enable systemd linger for "${user}" (${(out.stderr || out.stdout || '').trim() || `exit ${out.code}`}).`);
+  sendLog(`[native] The gateway will stop when this user's last session ends. Fix it with: sudo loginctl enable-linger ${user}`);
+  return false;
+}
+
+/**
+ * Native counterpart of the docker entrypoint's `ensure_plugin` (docker-gen.js).
+ *
+ * A container reinstalls its missing plugins on every boot; a native project has no entrypoint, so
+ * nothing ever put zalo-connect or learning-memory on disk. The generated config declares both
+ * anyway (bot-config-gen writes plugins.entries + allow + slots.contextEngine), so without this the
+ * gateway boots with "plugin not found" warnings, `channels.zalo-connect` has no owner — Zalo login
+ * fails with `Unsupported channel "zalo-connect"` — and the bot silently runs with no context
+ * engine at all. Same set and same skip-if-present cheapness as ensure_plugin.
+ */
+async function ensureNativePlugins(projectDir, { restart = false } = {}) {
+  if (!isNativeProject(projectDir)) return [];
+  // Same cleanup the container entrypoint does (docker-gen.js): an interrupted `plugins install`
+  // leaves extensions/.openclaw-install-stage-XXXXXX behind, and it still carries a plugin manifest —
+  // so the gateway logs "duplicate plugin id detected" every boot and a stale build competes with the
+  // real one for the same id. Native has no entrypoint, so it has to happen here.
+  const extRoot = join(projectDir, '.openclaw', 'extensions');
+  for (const entry of await fsp.readdir(extRoot, { withFileTypes: true }).catch(() => [])) {
+    if (!entry.isDirectory() || !entry.name.startsWith('.openclaw-install-stage-')) continue;
+    await fsp.rm(join(extRoot, entry.name), { recursive: true, force: true }).catch(() => {});
+    sendLog(`[native] removed abandoned plugin staging dir ${entry.name}`);
+  }
+  let cfg = {};
+  try { cfg = JSON.parse(await fsp.readFile(join(projectDir, '.openclaw', 'openclaw.json'), 'utf8')); } catch {}
+  // learning-memory backs plugins.slots.contextEngine for every bot; zalo-connect only when a bot
+  // actually declares the channel (mirrors docker-gen's `if (zaloBackend === 'zalo-connect')`).
+  const wanted = new Set(['learning-memory']);
+  if (cfg?.channels?.[ZALO_CHANNEL_ID] || cfg?.plugins?.entries?.[ZALO_PLUGIN_ID]) wanted.add(ZALO_PLUGIN_ID);
+  const installed = [];
+  for (const id of wanted) {
+    const dir = join(projectDir, '.openclaw', 'extensions', id);
+    if (existsSync(dir)) continue;
+    const spec = id === ZALO_PLUGIN_ID ? ZALO_CONNECT_PLUGIN_SPEC : pluginInstallSpec(id);
+    sendLog(`[native] plugin ${id} missing; installing ${spec}`);
+    const out = await ocCapture(projectDir, ['plugins', 'install', spec, '--force', '--acknowledge-clawhub-risk'], { timeout: 300000 });
+    const text = `${out.stdout || ''}\n${out.stderr || ''}`;
+    for (const line of text.split(/\r?\n/).map((l) => l.trimEnd()).filter(Boolean)) sendLog(`[native] ${line}`);
+    if (existsSync(dir) || /installed plugin/i.test(text)) installed.push(id);
+    else sendLog(`[native] WARNING: could not install plugin ${id} — the bot will run without it.`);
+  }
+  if (installed.length && restart) {
+    sendLog(`[native] Restarting gateway to load: ${installed.join(', ')}`);
+    await restartNativeRuntime(projectDir).catch((e) => sendLog(`[native] restart after plugin install: ${e.message}`));
+  }
+  return installed;
 }
 
 /** Fire-and-forget background process (9router has no service wrapper of its own). */
@@ -2763,11 +3072,25 @@ async function startNativeRuntime({ projectDir, osChoice = '', gatewayPort, rout
   await new Promise((r) => setTimeout(r, 8000));
   await applyResolved9RouterApiKey(projectDir).catch(() => {});
 
+  // Plugins BEFORE the gateway's first boot — the container entrypoint installs them ahead of the
+  // gateway for the same reason: a gateway that boots with its plugins already on disk loads them
+  // straight away, needs no follow-up restart, and prints no "plugin not found" warnings.
+  await ensureNativePlugins(projectDir).catch((e) => sendLog(`[native] plugin bootstrap skipped: ${e.message}`));
+
   // Managed service = auto-restart (KeepAlive/Restart=always) and start-at-login, the native
   // equivalent of docker's `restart: always`. --force so re-running install updates the port.
   const env = nativeEnv(projectDir);
+  await ensureSystemdLinger();
   await run('openclaw', ['daemon', 'install', '--force', '--port', String(gwPort)], { cwd: projectDir, env });
+  // Order is load-bearing: adopt the stray files FIRST, then complete the service env. The other way
+  // round, the gateway boots with a corrected OPENCLAW_HOME, finds no Zalo session there, and asks
+  // for a new QR scan even though a perfectly good session exists in the home directory.
+  await adoptStrayNativeHome(projectDir).catch((e) => sendLog(`[migrate] stray home skipped: ${e.message}`));
+  await syncNativeServiceEnv(projectDir).catch((e) => sendLog(`[native] service env sync skipped: ${e.message}`));
   await run('openclaw', ['daemon', 'start'], { cwd: projectDir, env });
+  // Let the first boot finish its state migrations here, while nothing else is competing for the
+  // lease. Every later action (create bot, install plugin) then restarts a settled gateway.
+  await waitForNativeGatewayHealthy(projectDir, 180000);
   sendLog(`[native] gateway service "${label}" running on 127.0.0.1:${gwPort}, 9router on 127.0.0.1:${rtPort}`);
   return { gatewayPort: gwPort, routerPort: rtPort, label };
 }
@@ -2916,6 +3239,14 @@ async function recreateDockerBot(projectDir) {
   // Native: there is no image to rebuild — the gateway reads openclaw.json from disk on boot, so
   // reloading config after a bot/plugin change is just a service restart. Callers stay unchanged.
   if (isNativeProject(projectDir)) {
+    // Never restart a gateway that is still on its first boot: OpenClaw runs startup migrations
+    // under a state lease, a restart mid-migration exits 1, and systemd's start limit can then
+    // abandon the unit. This is the same trap the docker path avoids by waiting for the container
+    // before touching it (see startZaloConnectLogin) — wait for /health first.
+    await waitForNativeGatewayHealthy(projectDir, 180000);
+    // The bot that was just created/edited may have added the Zalo channel or the context engine to
+    // openclaw.json; put those plugins on disk now so this one reload loads them too.
+    await ensureNativePlugins(projectDir).catch((e) => sendLog(`[native] plugin ensure skipped: ${e.message}`));
     sendLog('[native] Reloading gateway to pick up openclaw.json changes...');
     await restartNativeRuntime(projectDir).catch((e) => sendLog(`[native] restart failed: ${e.message}`));
     probeCacheClear();
@@ -3277,13 +3608,58 @@ function whichSync(name) {
   try {
     const finder = process.platform === 'win32' ? 'where' : 'which';
     const out = execFileSync(finder, [name], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
-    const first = String(out).split(/\r?\n/).map((s) => s.trim()).find(Boolean);
-    return first || '';
+    const hits = String(out).split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+    if (process.platform !== 'win32') return hits[0] || '';
+    // `where claude` lists the extensionless npm shim FIRST — a shell script Windows cannot spawn
+    // ("spawn ...\\npm\\claude ENOENT"), which is how an allow-listed CLI ended up unusable for the
+    // bot. Prefer something Windows can actually execute.
+    const rank = (f) => {
+      const ext = extname(f).toLowerCase();
+      const order = ['.exe', '.cmd', '.bat', '.com', '.ps1'];
+      const idx = order.indexOf(ext);
+      return idx === -1 ? order.length : idx;
+    };
+    return [...hits].sort((a, b) => rank(a) - rank(b))[0] || '';
   } catch (_) {
     return '';
   }
 }
 
+/**
+ * What to actually spawn for an allow-listed command. Windows needs the indirection:
+ *  - the path may be the extensionless npm shim (a shell script) — try the real siblings;
+ *  - a `.cmd`/`.bat` shim cannot be spawned without a shell on current Node, so read it and run
+ *    what it points at (`…\pkg\bin\x.exe`, or node + a cli.js) directly.
+ * Keeping shell:false matters: the bot supplies the arguments, and a shell would let one of them
+ * become a second command.
+ */
+function resolveHostExecutable(bin) {
+  if (process.platform !== 'win32') return { file: bin, prefixArgs: [] };
+  let target = bin;
+  if (!extname(target)) {
+    const candidate = ['.exe', '.cmd', '.bat'].map((ext) => target + ext).find((f) => existsSync(f));
+    if (candidate) target = candidate;
+  }
+  const ext = extname(target).toLowerCase();
+  if (ext !== '.cmd' && ext !== '.bat') return { file: target, prefixArgs: [] };
+  try {
+    const shim = readFileSync(target, 'utf8');
+    const dir = dirname(target);
+    const expand = (p) => resolve(dir, p.replace(/%~?dp0%\\?/gi, '').replace(/^\\+/, ''));
+    const exeRef = shim.match(/"([^"\n]*?\.exe)"/i);
+    if (exeRef) {
+      const exe = expand(exeRef[1]);
+      if (existsSync(exe)) return { file: exe, prefixArgs: [] };
+    }
+    const jsRef = shim.match(/"([^"\n]*?\.js)"/i);
+    if (jsRef) {
+      const js = expand(jsRef[1]);
+      if (existsSync(js)) return { file: process.execPath, prefixArgs: [js] };
+    }
+  } catch (_) {}
+  return { file: target, prefixArgs: [] };
+}
+
 /**
  * CLI tools the bot may RUN (not just open) via /api/host/exec — output is captured and
  * returned. Kept as a name→path allow-list, mirroring detectHostApps: the executable is fixed,
@@ -3348,6 +3724,13 @@ function grantHostCapabilities(cfg) {
       added.push(name);
     }
   }
+  // Desktop actions (/api/host/ui) come with the same grant: screenshot, pointer, keyboard,
+  // clipboard, windows. Built in, so they work on a machine with no Codex and no extra tools —
+  // on Linux they lean on xdotool/scrot, which the endpoint reports if missing.
+  if (cfg.ui !== true) {
+    cfg.ui = true;
+    added.push('desktop actions (screenshot/click/type)');
+  }
   return added;
 }
 
@@ -3619,7 +4002,8 @@ function runHostCommand(res, name, bin, args, input, timeoutMs) {
     };
     let child;
     try {
-      child = spawn(bin, args, { shell: false, windowsHide: true });
+      const target = resolveHostExecutable(bin);
+      child = spawn(target.file, [...target.prefixArgs, ...args], { shell: false, windowsHide: true });
     } catch (e) {
       return finish({ ok: false, error: e.message }, 500);
     }
@@ -3639,6 +4023,262 @@ function runHostCommand(res, name, bin, args, input, timeoutMs) {
   });
 }
 
+/**
+ * Desktop actions for the bot: see the screen, move and click, type, read the clipboard, list and
+ * focus windows. The bot runs in a container with no desktop of its own, so the installer — which
+ * already runs on the operator's machine and already opens apps for it — performs them.
+ *
+ * No native modules: the approach follows the dependency-free tools (and Anthropic's own
+ * computer-use reference, which drives xdotool + a screenshot binary):
+ *   Windows  a version-stamped PowerShell helper (user32 P/Invoke, SendKeys, System.Drawing)
+ *   macOS    screencapture + osascript/System Events + pbcopy/pbpaste
+ *   Linux    xdotool + scrot|import|gnome-screenshot|spectacle + xclip|wl-copy
+ * Whatever the OS, the bot sends the same JSON and gets the same shape back, so its instructions
+ * do not fork per platform.
+ *
+ * Windows note: input injection and screen capture need a real desktop session. When the installer
+ * itself was started over SSH there is none, and the capture fails — the error says so instead of
+ * leaking a raw Win32Exception.
+ */
+const HOST_UI_ACTIONS = new Set([
+  'screenshot', 'screen_size', 'mouse_move', 'click', 'drag', 'scroll',
+  'type', 'key', 'clipboard_get', 'clipboard_set', 'windows', 'focus',
+]);
+
+function hostUiScriptPath(projectDir) {
+  return join(projectDir, '.openclaw', 'host-ui.ps1');
+}
+
+async function ensureHostUiScript(projectDir) {
+  const path = hostUiScriptPath(projectDir);
+  const stamp = `# OpenClaw host UI helper — version ${HOST_UI_PS1_VERSION}`;
+  try {
+    if (existsSync(path) && (await fsp.readFile(path, 'utf8')).startsWith(stamp)) return path;
+  } catch (_) {}
+  await fsp.mkdir(dirname(path), { recursive: true }).catch(() => {});
+  await fsp.writeFile(path, HOST_UI_PS1, 'utf8');
+  return path;
+}
+
+function firstExistingCommand(names) {
+  for (const name of names) {
+    const bin = whichSync(name);
+    if (bin) return { name, bin };
+  }
+  return null;
+}
+
+async function hostUiScreenshotTarget(projectDir) {
+  const dir = join(projectDir, '.openclaw', 'media', 'host-ui');
+  await fsp.mkdir(dir, { recursive: true }).catch(() => {});
+  // Keep the folder from growing forever: the bot takes a lot of these.
+  try {
+    const files = (await fsp.readdir(dir)).filter((f) => f.endsWith('.png')).sort();
+    for (const stale of files.slice(0, Math.max(0, files.length - 20))) {
+      await fsp.rm(join(dir, stale), { force: true }).catch(() => {});
+    }
+  } catch (_) {}
+  const name = `shot-${new Date().toISOString().replace(/[:.]/g, '-')}.png`;
+  return { hostPath: join(dir, name), containerPath: `/home/node/project/.openclaw/media/host-ui/${name}` };
+}
+
+async function runHostUiWindows(projectDir, action, body, shot) {
+  const script = await ensureHostUiScript(projectDir);
+  const args = ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', script, '-Action', action];
+  const push = (flag, value) => { if (value !== undefined && value !== null && value !== '') args.push(flag, String(value)); };
+  push('-X', body.x);
+  push('-Y', body.y);
+  push('-ToX', body.toX);
+  push('-ToY', body.toY);
+  push('-Amount', body.amount);
+  push('-Text', body.text);
+  push('-Button', body.button);
+  push('-Clicks', body.clicks);
+  push('-Title', body.title);
+  if (shot) push('-Path', shot.hostPath);
+  const r = await runCapture('powershell', args, { shell: false, timeout: 30000 });
+  const parsed = parseJsonText(String(r.stdout || '').trim(), null);
+  if (parsed) return parsed;
+  const err = String(r.stderr || r.stdout || '').trim();
+  if (/Win32Exception|CopyFromScreen|handle is invalid/i.test(err)) {
+    return { ok: false, error: 'no desktop session available. The installer must run in the logged-in desktop session (not over SSH) for screen capture and input to work.' };
+  }
+  return { ok: false, error: err.split('\n')[0] || `powershell exited ${r.code}` };
+}
+
+async function runHostUiMac(action, body, shot) {
+  const osa = (script) => runCapture('osascript', ['-e', script], { shell: false, timeout: 20000 });
+  const point = () => `{${Number(body.x) || 0}, ${Number(body.y) || 0}}`;
+  switch (action) {
+    case 'screenshot': {
+      const r = await runCapture('screencapture', ['-x', shot.hostPath], { shell: false, timeout: 20000 });
+      return r.code === 0 ? { ok: true, path: shot.hostPath } : { ok: false, error: String(r.stderr || 'screencapture failed').trim() };
+    }
+    case 'screen_size': {
+      const r = await osa('tell application "Finder" to get bounds of window of desktop');
+      const nums = String(r.stdout || '').trim().split(/\s*,\s*/).map(Number);
+      return nums.length === 4 ? { ok: true, width: nums[2], height: nums[3] } : { ok: false, error: 'could not read screen bounds' };
+    }
+    case 'mouse_move':
+    case 'click': {
+      // System Events can click at a point; a plain move has no equivalent, so a move is a click
+      // target set-up only. Accessibility permission is required (System Settings → Privacy).
+      const clicks = Math.max(1, Number(body.clicks) || 1);
+      if (action === 'mouse_move') return { ok: true, note: 'macOS has no pointer-move without a click; pass x/y to click instead', x: body.x, y: body.y };
+      for (let i = 0; i < clicks; i++) {
+        const r = await osa(`tell application "System Events" to click at ${point()}`);
+        if (r.code !== 0) return { ok: false, error: String(r.stderr || '').trim() || 'click failed (grant Accessibility permission)' };
+      }
+      return { ok: true, button: 'left', clicks };
+    }
+    case 'type': {
+      const text = String(body.text || '').replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+      const r = await osa(`tell application "System Events" to keystroke "${text}"`);
+      return r.code === 0 ? { ok: true, typed: String(body.text || '').length } : { ok: false, error: String(r.stderr || '').trim() };
+    }
+    case 'key': {
+      const map = { enter: 'return', esc: 'escape', pageup: 'page up', pagedown: 'page down' };
+      for (const combo of String(body.text || '').split(/\s+/).filter(Boolean)) {
+        const parts = combo.toLowerCase().split('+').map((p) => p.trim()).filter(Boolean);
+        const key = map[parts[parts.length - 1]] || parts[parts.length - 1];
+        const mods = parts.slice(0, -1).map((m) => ({ ctrl: 'control down', control: 'control down', cmd: 'command down', meta: 'command down', alt: 'option down', option: 'option down', shift: 'shift down' })[m]).filter(Boolean);
+        const using = mods.length ? ` using {${mods.join(', ')}}` : '';
+        const named = ['return', 'escape', 'tab', 'space', 'delete', 'up', 'down', 'left', 'right', 'home', 'end', 'page up', 'page down'];
+        const script = named.includes(key)
+          ? `tell application "System Events" to key code ${{ return: 36, escape: 53, tab: 48, space: 49, delete: 51, up: 126, down: 125, left: 123, right: 124, home: 115, end: 119, 'page up': 116, 'page down': 121 }[key]}${using}`
+          : `tell application "System Events" to keystroke "${key}"${using}`;
+        const r = await osa(script);
+        if (r.code !== 0) return { ok: false, error: String(r.stderr || '').trim() };
+      }
+      return { ok: true, keys: body.text };
+    }
+    case 'scroll': {
+      const amount = Number(body.amount) || 3;
+      const dir = amount < 0 ? 121 : 116; // page down / page up
+      for (let i = 0; i < Math.abs(amount); i++) await osa(`tell application "System Events" to key code ${dir}`);
+      return { ok: true, amount };
+    }
+    case 'clipboard_get': {
+      const r = await runCapture('pbpaste', [], { shell: false, timeout: 10000 });
+      return { ok: true, text: String(r.stdout || '') };
+    }
+    case 'clipboard_set': {
+      const r = await runCapture('sh', ['-c', 'pbcopy'], { shell: false, timeout: 10000, input: String(body.text || '') });
+      return r.code === 0 ? { ok: true, length: String(body.text || '').length } : { ok: false, error: 'pbcopy failed' };
+    }
+    case 'windows': {
+      const r = await osa('tell application "System Events" to get name of every process whose background only is false');
+      const list = String(r.stdout || '').trim().split(/\s*,\s*/).filter(Boolean).map((title) => ({ title, process: title }));
+      return { ok: true, windows: list };
+    }
+    case 'focus': {
+      const title = String(body.title || '').replace(/"/g, '');
+      if (!title) return { ok: false, error: 'focus needs a title' };
+      const r = await osa(`tell application "${title}" to activate`);
+      return r.code === 0 ? { ok: true, focused: title } : { ok: false, error: String(r.stderr || '').trim() || `no app named ${title}` };
+    }
+    default:
+      return { ok: false, error: `unsupported on macOS: ${action}` };
+  }
+}
+
+async function runHostUiLinux(action, body, shot) {
+  const xdo = whichSync('xdotool');
+  const need = (bin, hint) => ({ ok: false, error: `${hint} needs ${bin}; install it (e.g. apt install ${bin})` });
+  switch (action) {
+    case 'screenshot': {
+      const tool = firstExistingCommand(['gnome-screenshot', 'scrot', 'spectacle', 'import']);
+      if (!tool) return need('scrot', 'screenshot');
+      const argv = tool.name === 'gnome-screenshot' ? ['-f', shot.hostPath]
+        : tool.name === 'spectacle' ? ['-b', '-n', '-o', shot.hostPath]
+          : tool.name === 'import' ? ['-window', 'root', shot.hostPath]
+            : [shot.hostPath];
+      const r = await runCapture(tool.bin, argv, { shell: false, timeout: 20000 });
+      return r.code === 0 ? { ok: true, path: shot.hostPath, tool: tool.name } : { ok: false, error: String(r.stderr || 'capture failed').trim() };
+    }
+    case 'screen_size': {
+      if (!xdo) return need('xdotool', 'screen_size');
+      const r = await runCapture(xdo, ['getdisplaygeometry'], { shell: false, timeout: 10000 });
+      const [w, h] = String(r.stdout || '').trim().split(/\s+/).map(Number);
+      return w && h ? { ok: true, width: w, height: h } : { ok: false, error: 'could not read display geometry' };
+    }
+    case 'mouse_move':
+    case 'click':
+    case 'drag':
+    case 'scroll':
+    case 'type':
+    case 'key':
+    case 'windows':
+    case 'focus': {
+      if (!xdo) return need('xdotool', action);
+      const button = { left: 1, middle: 2, right: 3 }[String(body.button || 'left')] || 1;
+      const argvFor = {
+        mouse_move: ['mousemove', String(body.x ?? 0), String(body.y ?? 0)],
+        click: ['mousemove', String(body.x ?? 0), String(body.y ?? 0), 'click', '--repeat', String(Math.max(1, Number(body.clicks) || 1)), String(button)],
+        drag: ['mousemove', String(body.x ?? 0), String(body.y ?? 0), 'mousedown', '1', 'mousemove', String(body.toX ?? 0), String(body.toY ?? 0), 'mouseup', '1'],
+        scroll: ['click', '--repeat', String(Math.max(1, Math.abs(Number(body.amount) || 3))), (Number(body.amount) || 3) < 0 ? '5' : '4'],
+        type: ['type', '--delay', '12', '--', String(body.text || '')],
+        key: ['key', ...String(body.text || '').split(/\s+/).filter(Boolean)],
+        windows: ['search', '--onlyvisible', '--name', '.'],
+        focus: ['search', '--onlyvisible', '--name', String(body.title || ''), 'windowactivate'],
+      }[action];
+      const r = await runCapture(xdo, argvFor, { shell: false, timeout: 20000 });
+      if (action === 'windows') {
+        const ids = String(r.stdout || '').trim().split(/\s+/).filter(Boolean).slice(0, 40);
+        const titles = [];
+        for (const id of ids) {
+          const t = await runCapture(xdo, ['getwindowname', id], { shell: false, timeout: 5000 });
+          const title = String(t.stdout || '').trim();
+          if (title) titles.push({ title, id });
+        }
+        return { ok: true, windows: titles };
+      }
+      return r.code === 0 ? { ok: true, action } : { ok: false, error: String(r.stderr || '').trim() || `xdotool exited ${r.code}` };
+    }
+    case 'clipboard_get': {
+      const tool = firstExistingCommand(['wl-paste', 'xclip', 'xsel']);
+      if (!tool) return need('xclip', 'clipboard_get');
+      const argv = tool.name === 'xclip' ? ['-o', '-selection', 'clipboard'] : tool.name === 'xsel' ? ['-b', '-o'] : [];
+      const r = await runCapture(tool.bin, argv, { shell: false, timeout: 10000 });
+      return { ok: true, text: String(r.stdout || '') };
+    }
+    case 'clipboard_set': {
+      const tool = firstExistingCommand(['wl-copy', 'xclip', 'xsel']);
+      if (!tool) return need('xclip', 'clipboard_set');
+      const argv = tool.name === 'xclip' ? ['-selection', 'clipboard'] : tool.name === 'xsel' ? ['-b', '-i'] : [];
+      const r = await runCapture(tool.bin, argv, { shell: false, timeout: 10000, input: String(body.text || '') });
+      return r.code === 0 ? { ok: true, length: String(body.text || '').length } : { ok: false, error: `${tool.name} failed` };
+    }
+    default:
+      return { ok: false, error: `unsupported on Linux: ${action}` };
+  }
+}
+
+async function runHostUi(projectDir, body = {}) {
+  const action = String(body.action || '').trim();
+  if (!HOST_UI_ACTIONS.has(action)) {
+    return { status: 400, payload: { ok: false, error: `unknown action: ${action || '(none)'}`, actions: [...HOST_UI_ACTIONS] } };
+  }
+  const shot = action === 'screenshot' ? await hostUiScreenshotTarget(projectDir) : null;
+  let result;
+  try {
+    if (process.platform === 'win32') result = await runHostUiWindows(projectDir, action, body, shot);
+    else if (process.platform === 'darwin') result = await runHostUiMac(action, body, shot);
+    else result = await runHostUiLinux(action, body, shot);
+  } catch (err) {
+    result = { ok: false, error: err.message };
+  }
+  if (shot && result?.ok) {
+    // The project folder is bind-mounted into the container, so hand back the path the bot can
+    // actually open — otherwise it gets a Windows path it cannot read and reports failure.
+    result.path = shot.hostPath;
+    result.containerPath = shot.containerPath;
+    result.bytes = existsSync(shot.hostPath) ? (await fsp.stat(shot.hostPath)).size : 0;
+  }
+  sendLog(`[host-control] UI "${action}" → ${result?.ok ? 'ok' : `lỗi: ${result?.error || 'unknown'}`}`);
+  return { status: result?.ok ? 200 : 500, payload: result };
+}
+
 async function handleHostControl(req, res, projectDir) {
   const cfg = await readHostControlConfig(projectDir);
   const url = new URL(req.url, 'http://localhost');
@@ -3656,6 +4296,16 @@ async function handleHostControl(req, res, projectDir) {
   if (url.pathname === '/api/host/apps' && req.method === 'GET') {
     return json(res, { ok: true, apps: Object.keys(cfg.apps || {}), commands: Object.keys(cfg.commands || {}), platform: process.platform });
   }
+  if (url.pathname === '/api/host/ui' && req.method === 'POST') {
+    // Part of PC control, but its own switch: seeing the screen and moving the pointer is a bigger
+    // step than opening an app, so it only answers once the operator has granted capabilities.
+    if (cfg.ui !== true) {
+      return json(res, { ok: false, error: 'desktop actions are not granted. Ask the operator to press "Điều khiển máy" again in the dashboard (that writes ui:true).' }, 403);
+    }
+    const body = await readJson(req).catch(() => ({}));
+    const { status, payload } = await runHostUi(projectDir, body || {});
+    return json(res, payload, status);
+  }
   if (url.pathname === '/api/host/exec' && req.method === 'POST') {
     const body = await readJson(req).catch(() => ({}));
     const name = String(body.command || '').trim().toLowerCase();
@@ -3723,6 +4373,39 @@ async function writeHostControlAccess(projectDir, cfg) {
     '',
     `Lệnh khả dụng: ${commands.map((c) => `\`${c}\``).join(', ')}. Lệnh mặc định timeout 180s, output tối đa ~200KB/luồng.`,
   ] : [];
+  // Desktop actions: one endpoint, same JSON on every OS, so the bot does not need per-platform
+  // instructions. Screenshots land in the project folder, which the container already sees.
+  const uiBlock = cfg.ui === true ? [
+    '',
+    '### Thao tác trên màn hình chủ',
+    '',
+    'Một endpoint duy nhất cho mọi hệ điều hành. Cách làm đúng: **chụp màn hình trước, xem toạ độ, rồi mới click** —',
+    'đừng đoán vị trí. Toạ độ tính bằng pixel màn hình, gốc ở góc trên-trái.',
+    '',
+    '```sh',
+    `curl -s -X POST ${base}/api/host/ui -H "x-openclaw-token: ${cfg.token}" \\`,
+    '  -H "content-type: application/json" -d \'{"action":"screenshot"}\'',
+    '```',
+    '',
+    'Trả về `containerPath` — **đọc/gửi ảnh bằng đường dẫn đó** (nằm trong project nên bạn thấy được),',
+    'kèm `width`/`height` để biết màn hình bao lớn.',
+    '',
+    'Các action khác (cùng dạng `{"action":...}`):',
+    '',
+    '- `screen_size` — kích thước màn hình',
+    '- `mouse_move` + `x`,`y` — di chuột',
+    '- `click` + `x`,`y`, tuỳ chọn `button` (`left`/`right`/`middle`) và `clicks` (2 = double-click)',
+    '- `drag` + `x`,`y`,`toX`,`toY` — kéo thả',
+    '- `scroll` + `amount` (âm = xuống), tuỳ chọn `x`,`y`',
+    '- `type` + `text` — gõ chữ vào cửa sổ đang focus',
+    '- `key` + `text` — nhấn tổ hợp, ví dụ `"ctrl+c"`, `"enter"`, `"alt+tab"`; nhiều tổ hợp thì cách nhau bằng space',
+    '- `clipboard_get` / `clipboard_set` + `text` — đọc/ghi clipboard',
+    '- `windows` — liệt kê cửa sổ đang mở; `focus` + `title` — đưa cửa sổ lên trước',
+    '',
+    'Nếu trả về lỗi "no desktop session available" thì installer đang chạy ngoài phiên desktop —',
+    'nói chủ mở lại installer trong máy, đừng thử cách khác.',
+    'Trên Linux, thiếu `xdotool`/`scrot` thì endpoint nói rõ cần cài gì — báo lại cho chủ.',
+  ] : [];
   // Screen capture / recording — only advertised when the operator granted the matching tool, so
   // the bot never tries a binary that is not on this machine's allow-list.
   // Windows has no capture binary to allow-list (PowerShell does it inline), so the section shows
@@ -3829,6 +4512,7 @@ async function writeHostControlAccess(projectDir, cfg) {
     '',
     apps.length ? `App khả dụng trên máy này: ${apps.map((a) => `\`${a}\``).join(', ')}.` : 'Máy này chưa khai báo app nào — nhờ chủ thêm vào `.openclaw/host-control.json`.',
     ...execBlock,
+    ...uiBlock,
     // Docker only: a screenshot taken on the host lands on the HOST filesystem, which this
     // container cannot read — say so instead of letting the bot hunt for a missing file.
     ...(hasCapture ? [
@@ -4156,13 +4840,18 @@ async function installCore({ osChoice, mode, projectDir, gatewayPort = 18789, ro
   state.os = osChoice;
   state.startedAt = new Date().toISOString();
   try {
-    // Native runs on the host's own ports, so it must not land on the docker defaults: a machine
-    // often has a docker project (or an SSH tunnel to a remote bot) already holding 18789/20128.
+    // Native binds the host directly, so it needs ports nothing else holds — but only when something
+    // actually holds them. Ask the host rather than assuming: a fresh machine keeps openclaw's and
+    // 9router's real defaults, and a machine that already runs a docker project (or an SSH tunnel to
+    // a remote bot) steps to the next free pair instead.
     if (mode === 'native') {
-      if (gatewayPort === 18789) gatewayPort = NATIVE_DEFAULT_GATEWAY_PORT;
-      if (routerPort === 20128) routerPort = NATIVE_DEFAULT_ROUTER_PORT;
+      gatewayPort = await findFreeHostPort(gatewayPort, { reserveNext: true });
+      routerPort = await findFreeHostPort(routerPort);
       state.gatewayPort = gatewayPort;
       state.routerPort = routerPort;
+      state.gatewayUrl = `http://127.0.0.1:${gatewayPort}`;
+      state.routerUrl = `http://127.0.0.1:${routerPort}`;
+      sendLog(`[native] ports: gateway ${gatewayPort}, 9router ${routerPort}`);
     }
     sendLog('OpenClaw local installer started');
     sendLog(`Target: OS=${osChoice}, mode=${mode}, project=${projectDir}, gatewayPort=${gatewayPort}, routerPort=${routerPort}`);
@@ -6084,4 +6773,4 @@ export async function startLocalInstaller({ host = '127.0.0.1', preferredPort =
   ]).catch(() => {});
 }
 
-export { patchBrowserAutomationHostPreference, debugChromeProfileDir, defaultChromeProfileDir, createBotInProject, updateBotInProject, deleteBotInProject, validateOpenclawConfig, startZaloLogin, readBotCredentials, resolveProject9RouterApiKey, installCore, deleteProjectFolder, buildZaloHealthSnapshot, removeEmptyWorkspaceAttestations, runHostCommand, detectHostCommands, detectHostCapabilityCommands, grantHostCapabilities, detectCodexApp, detectCodexMarketplace, resolveCodexCli, openPrivacyPane, projectDeployMode, isNativeProject, nativeServiceLabel, nativeEnv, ocArgv, migrateNativePaths, discoverNativeProjectRoots };
+export { patchBrowserAutomationHostPreference, debugChromeProfileDir, defaultChromeProfileDir, createBotInProject, updateBotInProject, deleteBotInProject, validateOpenclawConfig, startZaloLogin, readBotCredentials, resolveProject9RouterApiKey, installCore, deleteProjectFolder, buildZaloHealthSnapshot, removeEmptyWorkspaceAttestations, runHostCommand, detectHostCommands, detectHostCapabilityCommands, grantHostCapabilities, detectCodexApp, detectCodexMarketplace, resolveCodexCli, openPrivacyPane, projectDeployMode, isNativeProject, nativeServiceLabel, nativeEnv, ocArgv, migrateNativePaths, discoverNativeProjectRoots, detectOs, stripCliWarnings, migrationLeaseDeadline, ensureNativePlugins, findFreeHostPort, syncNativeServiceEnv, adoptStrayNativeHome };