jishushell 0.4.2 → 0.4.17

package/dist/services/setup-manager.js

@@ -1,12 +1,13 @@
 import { execFileSync, execSync, spawn as nodeSpawn } from "child_process";
-import { chmodSync, existsSync, mkdirSync, readFileSync, symlinkSync, unlinkSync, writeFileSync } from "fs";
-import { userInfo, homedir } from "node:os";
+import { chmodSync, copyFileSync, existsSync, mkdtempSync, readFileSync, renameSync, rmSync, symlinkSync, unlinkSync } from "fs";
+import { userInfo } from "node:os";
 import { randomBytes } from "node:crypto";
 import { tmpdir } from "node:os";
 import { dirname, join } from "path";
 import { StringDecoder } from "string_decoder";
 import { fileURLToPath } from "url";
-import { JISHUSHELL_HOME, getPanelConfig, savePanelConfig, setOpenclawDockerImage, getOpenclawDockerImage, isOfficialImage, CUSTOM_IMAGE_PREFIX, DEFAULT_OPENCLAW_DOCKER_IMAGE } from "../config.js";
+import { JISHUSHELL_HOME, getPanelConfig, savePanelConfig, setOpenclawDockerImage, getOpenclawDockerImage, DEFAULT_OPENCLAW_DOCKER_IMAGE } from "../config.js";
+import { ensureDirContainer, ensureDirHost, writeConfigFile, writeSecretFile, writeExecutableFile, writeSystemTmpFile } from "../utils/fs.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // ── Paths ──────────────────────────────────────────────────────────
@@ -20,7 +21,10 @@ const NOMAD_BIN = join(BIN_DIR, "nomad");
 const NOMAD_CONFIG_DIR = join(JISHUSHELL_HOME, "nomad");
 const NOMAD_DATA_DIR = join(JISHUSHELL_HOME, "nomad", "data");
 const NOMAD_ALLOC_DIR = join(JISHUSHELL_HOME, "nomad", "data", "alloc");
-const NOMAD_VERSION = "1.11.3";
+const COLIMA_DIR = join(JISHUSHELL_HOME, "colima");
+const COLIMA_PROFILE = "jishushell";
+const COLIMA_SOCKET = join(COLIMA_DIR, COLIMA_PROFILE, "docker.sock");
+const NOMAD_VERSION = "1.6.5";
 let _serverPort = 8090;
 export function setServerPort(port) { _serverPort = port; }
 // ── Resolve non-root service user (board-agnostic) ─────────────────
@@ -340,7 +344,7 @@ export function ensureCgroupMemory() {
             execFileSync("sudo", ["cp", f, f + ".bak"], { timeout: 5000 });
             // Write to tmp file then sudo cp to avoid shell interpolation of file content
             const tmpPath = join(dirname(f), ".cmdline.tmp");
-            writeFileSync(tmpPath, patched + "\n");
+            writeSystemTmpFile(tmpPath, patched + "\n");
             execFileSync("sudo", ["cp", tmpPath, f], { timeout: 5000 });
             try {
                 unlinkSync(tmpPath);
@@ -356,13 +360,16 @@ export function ensureCgroupMemory() {
     return false;
 }
 function canAccessDockerDaemon(timeout = 10000) {
+    const env = process.platform === "darwin" && existsSync(COLIMA_SOCKET)
+        ? { ...process.env, DOCKER_HOST: `unix://${COLIMA_SOCKET}` }
+        : undefined;
     try {
-        execFileSync("docker", ["info"], { timeout, stdio: "ignore" });
+        execFileSync("docker", ["info"], { timeout, stdio: "ignore", env });
         return true;
     }
     catch { }
     try {
-        execFileSync("sudo", ["-n", "docker", "info"], { timeout, stdio: "ignore" });
+        execFileSync("sudo", ["-n", "docker", "info"], { timeout, stdio: "ignore", env });
         return true;
     }
     catch { }
@@ -386,10 +393,7 @@ export function getSetupStatus() {
         const localBin = join(OPENCLAW_BIN_DIR, "openclaw");
         const localBinOk = existsSync(localBin);
         const fastDockerImageReady = checkDockerImageExists();
-        const baseTag = resolveDockerImageTag();
-        const official = isOfficialImage(baseTag);
-        // Official image: Docker image alone is sufficient. Slim base: also needs npm package.
-        const openclawOk = official ? fastDockerImageReady : (localBinOk || fastDockerImageReady);
+        const openclawOk = localBinOk || fastDockerImageReady;
         // Lightweight validation: verify critical services are actually available
         const dockerOk = canAccessDockerDaemon(5000);
         const nomadOk = isPortListening(4646);
@@ -412,34 +416,14 @@ export function getSetupStatus() {
             catch { }
             let openclawVer = "installed";
             let openclawPath = localBin;
-            if (official && fastDockerImageReady) {
-                // Official image: extract version from Docker image tag
-                openclawVer = baseTag.split(":").pop() || "local";
-                openclawPath = baseTag;
-            }
-            else {
-                // Prefer npm package.json for accurate OpenClaw version.
-                try {
-                    const pkg = join(OPENCLAW_MODULES, "openclaw", "package.json");
-                    if (existsSync(pkg))
-                        openclawVer = JSON.parse(readFileSync(pkg, "utf-8")).version || openclawVer;
-                }
-                catch { }
-                // Fallback: extract version from old-style openclaw:* image tag (legacy migration path).
-                if (openclawVer === "installed" && fastDockerImageReady) {
-                    const imageTag = resolveDockerImageTag();
-                    if (/^openclaw:/i.test(imageTag)) {
-                        openclawVer = imageTag.replace(/^openclaw:/i, "");
-                        openclawPath = imageTag;
-                    }
-                }
+            // Prefer npm package.json for accurate OpenClaw version.
+            try {
+                const pkg = join(OPENCLAW_MODULES, "openclaw", "package.json");
+                if (existsSync(pkg))
+                    openclawVer = JSON.parse(readFileSync(pkg, "utf-8")).version || openclawVer;
             }
-            // Official image: only Docker image needed.
-            // Slim base (jishushell-base:*): both npm package and Docker image required.
-            const needsNpmForMount = /^jishushell-base:/i.test(baseTag);
-            const ready = official
-                ? fastDockerImageReady
-                : (openclawOk && fastDockerImageReady && (!needsNpmForMount || localBinOk));
+            catch { }
+            const ready = openclawOk && fastDockerImageReady;
             return {
                 node: { name: "Node.js", installed: true, running: true, version: process.version, path: process.execPath },
                 docker: { name: "Docker", installed: true, running: true, version: dockerVer, path: "" },
@@ -510,11 +494,7 @@ export function getSetupStatus() {
     // the local npm package is absent — the image is all that's needed to run instances.
     if (!openclaw.ok && dockerImageReady) {
         const imageTag = resolveDockerImageTag();
-        // Official image: extract version from tag (e.g. ghcr.io/openclaw/openclaw:2026.3.31 → 2026.3.31)
-        // Legacy image: strip openclaw: prefix
-        const tagVersion = isOfficialImage(imageTag)
-            ? (imageTag.split(":").pop() || "local")
-            : imageTag.replace(/^openclaw:/i, "");
+        const tagVersion = imageTag.split(":").pop() || "local";
         openclaw = { ok: true, version: tagVersion, path: imageTag };
     }
     const openclawStatus = {
@@ -789,6 +769,227 @@ function getNomadDownloadUrl() {
     const os = process.platform === "linux" ? "linux" : "darwin";
     return `https://releases.hashicorp.com/nomad/${NOMAD_VERSION}/nomad_${NOMAD_VERSION}_${os}_${arch}.zip`;
 }
+/**
+ * Signal nomad agents by exact process name (pgrep -x nomad) to avoid the
+ * classic pkill -f self-match bug: a command line like "pkill -f 'nomad agent'"
+ * literally contains the pattern and pkill kills itself before reaching the
+ * real nomad process. pgrep's own comm is "pgrep" (not "nomad") so -x nomad
+ * cannot self-match. Unprivileged kill is tried first; sudo -n as a fallback
+ * if the running nomad is owned by root (1.6.5 User=root unit).
+ */
+function killNomadByProcName() {
+    const collect = () => {
+        try {
+            const out = execSync("pgrep -x nomad 2>/dev/null || true", { encoding: "utf-8" }).trim();
+            return out.split("\n").filter(Boolean);
+        }
+        catch {
+            return [];
+        }
+    };
+    const sendSignal = (sig, pids) => {
+        if (pids.length === 0)
+            return;
+        try {
+            execFileSync("sudo", ["-n", "kill", `-${sig}`, ...pids], { timeout: 5000, stdio: "pipe" });
+            return;
+        }
+        catch { }
+        try {
+            execSync(`kill -${sig} ${pids.join(" ")} 2>/dev/null || true`, { timeout: 5000 });
+        }
+        catch { }
+    };
+    let pids = collect();
+    sendSignal("TERM", pids);
+    if (pids.length > 0) {
+        // Short grace period, then SIGKILL any survivors.
+        execSync("sleep 2");
+        pids = collect();
+        sendSignal("KILL", pids);
+    }
+}
+/** Compare two "a.b.c" semver strings; returns a > b. */
+function isNomadVersionGreater(a, b) {
+    const parse = (v) => v.replace(/^v/, "").split(".").map(n => parseInt(n, 10) || 0);
+    const [aMaj, aMin, aPat] = parse(a);
+    const [bMaj, bMin, bPat] = parse(b);
+    if (aMaj !== bMaj)
+        return aMaj > bMaj;
+    if (aMin !== bMin)
+        return aMin > bMin;
+    return aPat > bPat;
+}
+/**
+ * Auto-migrate from a higher Nomad version (e.g. 1.11.3 BSL) back to the
+ * jishushell target (1.6.5 MPL). Called when installNomad detects a local
+ * binary whose semver is > NOMAD_VERSION. Destructive to Nomad's raft state
+ * (schema is not backward compatible) but preserves instance configs under
+ * ~/.jishushell/instances/*. A single tar.gz snapshot of the old data_dir
+ * is kept under ~/.jishushell/nomad/backups/ for forensic inspection.
+ *
+ * Safe-first: the new binary is downloaded and verified BEFORE any existing
+ * state is touched. If any stage 1 step fails, state is untouched.
+ *
+ * Throws on failure so the caller's outer catch reports the error.
+ */
+async function migrateNomadToTarget(currentVersion) {
+    console.log(`[nomad] Auto-migrating v${currentVersion} → v${NOMAD_VERSION} (BSL → MPL)`);
+    console.log("[nomad]   Raft state is not backward-compatible; allocation history will be reset.");
+    console.log("[nomad]   Instance configs under ~/.jishushell/instances/ are preserved.");
+    // ── Stage 1: download + verify new binary into a staging dir ─────────
+    const stageDir = mkdtempSync(join(tmpdir(), "nomad-migrate-"));
+    let backupFile = "";
+    try {
+        const stagedBin = join(stageDir, "nomad");
+        const zipPath = join(stageDir, "nomad.zip");
+        const url = getNomadDownloadUrl();
+        const arch = process.arch === "arm64" ? "arm64" : "amd64";
+        const os = process.platform === "linux" ? "linux" : "darwin";
+        const sumsUrl = `https://releases.hashicorp.com/nomad/${NOMAD_VERSION}/nomad_${NOMAD_VERSION}_SHA256SUMS`;
+        const sumsPath = join(stageDir, "SHA256SUMS");
+        console.log(`[nomad] Staging v${NOMAD_VERSION} (${os}/${arch})...`);
+        execFileSync("curl", ["-fsSL", url, "-o", zipPath], { timeout: 300000, stdio: "pipe" });
+        execFileSync("curl", ["-fsSL", sumsUrl, "-o", sumsPath], { timeout: 30000, stdio: "pipe" });
+        const sums = readFileSync(sumsPath, "utf-8");
+        const sumLine = sums.split("\n").find(l => l.includes(`nomad_${NOMAD_VERSION}_${os}_${arch}.zip`));
+        if (!sumLine)
+            throw new Error(`No checksum entry for nomad_${NOMAD_VERSION}_${os}_${arch}.zip`);
+        const expected = sumLine.split(/\s+/)[0];
+        // Match the bash installer: prefer sha256sum (GNU coreutils, Linux),
+        // fall back to shasum -a 256 (BSD, macOS default — sha256sum is not
+        // preinstalled there). Without this, triggering auto-migration from
+        // the WebUI / Node path on macOS would fail even though the shell
+        // installer works fine.
+        let actual;
+        try {
+            actual = execSync(`sha256sum "${zipPath}" | awk '{print $1}'`, { encoding: "utf-8" }).trim();
+        }
+        catch {
+            actual = execSync(`shasum -a 256 "${zipPath}" | awk '{print $1}'`, { encoding: "utf-8" }).trim();
+        }
+        if (expected !== actual) {
+            throw new Error(`Nomad checksum mismatch: expected ${expected}, got ${actual}`);
+        }
+        console.log("[nomad] Checksum verified");
+        execFileSync("unzip", ["-o", zipPath, "-d", stageDir], { timeout: 30000 });
+        chmodSync(stagedBin, 0o755);
+        const stagedVersionLine = execFileSync(stagedBin, ["version"], { encoding: "utf-8", timeout: 5000 }).trim().split("\n")[0];
+        if (!stagedVersionLine.includes(`v${NOMAD_VERSION}`)) {
+            throw new Error(`Staged binary reports "${stagedVersionLine}", expected v${NOMAD_VERSION}`);
+        }
+        console.log(`[nomad] Staged ${stagedVersionLine}`);
+        // ── Stage 2: destructive state changes begin ───────────────────────
+        console.log("[nomad] Stopping services...");
+        try {
+            execFileSync("sudo", ["-n", "systemctl", "stop", "jishushell"], { timeout: 15000, stdio: "pipe" });
+        }
+        catch { }
+        try {
+            execFileSync("sudo", ["-n", "systemctl", "stop", "nomad"], { timeout: 15000, stdio: "pipe" });
+        }
+        catch { }
+        // pkill -f 'nomad agent' matches pkill's own cmdline and self-terminates
+        // before reaching the real nomad process. Use pgrep -x nomad (exact proc
+        // name match; pgrep's comm is "pgrep") to avoid the self-match bug.
+        killNomadByProcName();
+        await new Promise(r => setTimeout(r, 2000));
+        // ── Stage 3: tar backup (single snapshot, overwrite any previous) ──
+        const backupDir = join(NOMAD_CONFIG_DIR, "backups");
+        if (existsSync(NOMAD_DATA_DIR)) {
+            try {
+                ensureDirHost(backupDir);
+            }
+            catch { }
+            const ts = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "").replace("T", "-");
+            const candidate = join(backupDir, `data-${ts}.tar.gz`);
+            console.log(`[nomad] Backing up raft state → ${candidate}`);
+            try {
+                execSync(`tar czf "${candidate}" -C "${NOMAD_CONFIG_DIR}" data 2>/dev/null`, { timeout: 120000 });
+                backupFile = candidate;
+                // Keep only the most recent snapshot
+                try {
+                    const list = execSync(`ls -t "${backupDir}"/data-*.tar.gz 2>/dev/null | tail -n +2 || true`, { encoding: "utf-8" }).trim();
+                    for (const old of list.split("\n").filter(Boolean)) {
+                        try {
+                            unlinkSync(old);
+                        }
+                        catch { }
+                    }
+                }
+                catch { }
+            }
+            catch {
+                console.warn("[nomad] Backup tar failed — continuing (raft state will still be wiped)");
+            }
+        }
+        // ── Stage 4: wipe raft state + env files (schema incompatible) ─────
+        try {
+            execFileSync("sudo", ["-n", "rm", "-rf", NOMAD_DATA_DIR], { timeout: 15000, stdio: "pipe" });
+        }
+        catch {
+            try {
+                rmSync(NOMAD_DATA_DIR, { recursive: true, force: true });
+            }
+            catch { }
+        }
+        try {
+            unlinkSync(join(JISHUSHELL_HOME, "nomad.env"));
+        }
+        catch { }
+        try {
+            execFileSync("sudo", ["-n", "rm", "-f", "/etc/jishushell/nomad.env"], { timeout: 5000, stdio: "pipe" });
+        }
+        catch { }
+        // ── Stage 5: orphaned gateway containers ───────────────────────────
+        // Panel normally has docker group via jishushell.service SupplementaryGroups,
+        // but postinstall may run this helper from a shell where the invoking
+        // user is not in docker group. Probe first, fall back to sudo docker.
+        try {
+            let dockerCmd = "docker";
+            try {
+                execSync("docker ps >/dev/null 2>&1", { timeout: 5000 });
+            }
+            catch {
+                dockerCmd = "sudo -n docker";
+            }
+            const names = execSync(`${dockerCmd} ps -a --format '{{.Names}}' 2>/dev/null | grep '^gateway-' || true`, { encoding: "utf-8" }).trim();
+            if (names) {
+                const rows = names.split("\n").filter(Boolean);
+                for (const name of rows) {
+                    try {
+                        execSync(`${dockerCmd} rm -f "${name}" 2>/dev/null`, { timeout: 10000 });
+                    }
+                    catch { }
+                }
+                console.log(`[nomad] Removed ${rows.length} orphaned gateway container(s)`);
+            }
+        }
+        catch { }
+        // ── Stage 6: swap binary into place (atomic via temp name + rename)
+        ensureDirHost(BIN_DIR);
+        const destTmp = `${NOMAD_BIN}.tmp.${process.pid}`;
+        copyFileSync(stagedBin, destTmp);
+        chmodSync(destTmp, 0o755);
+        renameSync(destTmp, NOMAD_BIN);
+        console.log(`[nomad] Migrated to v${NOMAD_VERSION}`);
+        if (backupFile)
+            console.log(`[nomad]   Backup (forensic, not self-recovery): ${backupFile}`);
+        console.log("[nomad]   JishuShell will re-bootstrap ACL and resubmit jobs on next start.");
+    }
+    catch (err) {
+        if (backupFile) {
+            console.error(`[nomad] Migration failed — backup preserved at ${backupFile}`);
+        }
+        throw err;
+    }
+    finally {
+        try {
+            rmSync(stageDir, { recursive: true, force: true });
+        }
+        catch { }
+    }
+}
 export async function installNomad() {
     try {
         if (existsSync(NOMAD_BIN)) {
@@ -810,8 +1011,38 @@ export async function installNomad() {
                 }
                 catch { }
                 // Boundary check 3: does it actually run?
+                let versionLine = "";
                 try {
-                    const version = execSync(`"${NOMAD_BIN}" version`, { encoding: "utf-8", timeout: 5000 }).trim();
+                    versionLine = execSync(`"${NOMAD_BIN}" version`, { encoding: "utf-8", timeout: 5000 }).trim().split("\n")[0];
+                }
+                catch {
+                    // Binary is corrupt or wrong arch — remove and reinstall
+                    try {
+                        unlinkSync(NOMAD_BIN);
+                    }
+                    catch { }
+                }
+                if (versionLine) {
+                    const match = versionLine.match(/v(\d+\.\d+\.\d+)/);
+                    const currentVersion = match ? match[1] : "";
+                    if (currentVersion && isNomadVersionGreater(currentVersion, NOMAD_VERSION)) {
+                        // Current > target — auto-migrate (nomad 1.11.3 BSL → 1.6.5 MPL).
+                        // Migration failure is a hard stop: the old state has been
+                        // partially mutated (or about to be), returning falls through
+                        // to the reinstall path which would make a bad situation worse.
+                        try {
+                            await migrateNomadToTarget(currentVersion);
+                        }
+                        catch (migErr) {
+                            return {
+                                ok: false,
+                                message: "Nomad auto-migration failed",
+                                error: migErr?.message || String(migErr),
+                            };
+                        }
+                        const newLine = execSync(`"${NOMAD_BIN}" version`, { encoding: "utf-8", timeout: 5000 }).trim().split("\n")[0];
+                        return { ok: true, message: `Nomad migrated to ${newLine}` };
+                    }
                     // Ensure Nomad is started even if already installed
                     if (!isPortListening(4646)) {
                         try {
@@ -822,14 +1053,7 @@ export async function installNomad() {
                             await startNomad();
                         }
                     }
-                    return { ok: true, message: `Nomad already installed: ${version.split("\n")[0]}` };
-                }
-                catch {
-                    // Binary is corrupt or wrong arch — remove and reinstall
-                    try {
-                        unlinkSync(NOMAD_BIN);
-                    }
-                    catch { }
+                    return { ok: true, message: `Nomad already installed: ${versionLine}` };
                 }
             }
         }
@@ -839,7 +1063,7 @@ export async function installNomad() {
             try {
                 const systemNomad = execSync("which nomad 2>/dev/null", { encoding: "utf-8" }).trim();
                 if (systemNomad && existsSync(systemNomad)) {
-                    mkdirSync(BIN_DIR, { recursive: true });
+                    ensureDirHost(BIN_DIR);
                     symlinkSync(systemNomad, NOMAD_BIN);
                     const version = execSync(`${NOMAD_BIN} version`, { encoding: "utf-8", timeout: 5000 }).trim();
                     console.log(`[nomad] Linked system nomad ${systemNomad} → ${NOMAD_BIN}`);
@@ -849,7 +1073,7 @@ export async function installNomad() {
             catch { /* system nomad not found — proceed to download */ }
         }
         const task = createTask("nomad");
-        mkdirSync(BIN_DIR, { recursive: true });
+        ensureDirHost(BIN_DIR);
         const url = getNomadDownloadUrl();
         const zipPath = join(BIN_DIR, "nomad.zip");
         emitTask(task, { type: "progress", message: "下载 Nomad...", progress: 0 });
@@ -917,12 +1141,10 @@ function fixNomadDirOwnership() {
 }
 function writeNomadConfig() {
     fixNomadDirOwnership();
-    mkdirSync(NOMAD_CONFIG_DIR, { recursive: true, mode: 0o755 });
-    chmodSync(NOMAD_CONFIG_DIR, 0o755);
-    mkdirSync(NOMAD_DATA_DIR, { recursive: true, mode: 0o755 });
-    chmodSync(NOMAD_DATA_DIR, 0o755);
-    mkdirSync(NOMAD_ALLOC_DIR, { recursive: true, mode: 0o755 });
-    chmodSync(NOMAD_ALLOC_DIR, 0o755);
+    ensureDirHost(NOMAD_CONFIG_DIR);
+    ensureDirContainer(NOMAD_DATA_DIR);
+    ensureDirContainer(NOMAD_ALLOC_DIR);
+    const loopbackIface = process.platform === "darwin" ? "lo0" : "lo";
     const config = `
 data_dir = "${NOMAD_DATA_DIR}"
 
@@ -944,18 +1166,18 @@ server {
 client {
   enabled = true
   servers = ["127.0.0.1:4647"]
+  network_interface = "${loopbackIface}"
   alloc_dir = "${NOMAD_ALLOC_DIR}"
 
-  drain_on_shutdown {
-    deadline           = "30s"
-    force              = true
-    ignore_system_jobs = true
-  }
+  # drain_on_shutdown intentionally omitted: on single-node Pi there is
+  # nowhere to drain workloads to, and draining on every systemctl restart
+  # would kill every running OpenClaw instance. Without this block Nomad
+  # leaves allocations running across client restarts — the docker driver
+  # re-attaches to the existing containers on startup.
 }
 
 plugin "docker" {
   config {
-    disable_log_collection = true
     volumes {
       enabled = true
     }
@@ -966,7 +1188,7 @@ acl {
   enabled = true
 }
 `;
-    writeFileSync(join(NOMAD_CONFIG_DIR, "nomad.hcl"), config);
+    writeConfigFile(join(NOMAD_CONFIG_DIR, "nomad.hcl"), config);
 }
 export function loadNomadToken() {
     if (process.env.NOMAD_TOKEN)
@@ -1077,10 +1299,10 @@ async function bootstrapNomadACL() {
     const saveToken = (token) => {
         const envFile = join(JISHUSHELL_HOME, "nomad.env");
         const envContent = `NOMAD_TOKEN=${token}\n`;
-        writeFileSync(envFile, envContent, { mode: 0o600 });
+        writeSecretFile(envFile, envContent);
         try {
             execFileSync("sudo", ["-n", "mkdir", "-p", "/etc/jishushell"], { timeout: 5000, stdio: "pipe" });
-            writeFileSync("/tmp/.nomad-env-tmp", envContent, { mode: 0o600 });
+            writeSystemTmpFile("/tmp/.nomad-env-tmp", envContent);
             execFileSync("sudo", ["-n", "cp", "/tmp/.nomad-env-tmp", "/etc/jishushell/nomad.env"], { timeout: 5000, stdio: "pipe" });
             execFileSync("sudo", ["-n", "chmod", "600", "/etc/jishushell/nomad.env"], { timeout: 5000, stdio: "pipe" });
             try {
@@ -1111,14 +1333,27 @@ async function bootstrapNomadACL() {
         }
         const resetIndex = resetMatch[1];
         console.log(`[nomad] Bootstrap already done (reset index: ${resetIndex}). Performing ACL bootstrap reset...`);
-        // Write the reset trigger file (Nomad reads this on startup to allow re-bootstrap)
+        // Write the reset trigger file (Nomad reads this on startup to allow re-bootstrap).
+        // NOMAD_DATA_DIR/server is owned by root because nomad.service runs as User=root
+        // (docker driver on 1.6.5 requires euid==0). The panel runs as a non-root user, so
+        // plain writeConfigFile would fail with EACCES — route through `sudo tee` instead.
         const resetFile = join(NOMAD_DATA_DIR, "server", "acl-bootstrap-reset");
         try {
-            writeFileSync(resetFile, resetIndex, { encoding: "utf-8" });
+            writeConfigFile(resetFile, resetIndex);
         }
         catch (writeErr) {
-            console.warn("[nomad] Could not write acl-bootstrap-reset file:", writeErr.message);
-            return;
+            try {
+                execFileSync("sudo", ["-n", "mkdir", "-p", dirname(resetFile)], { timeout: 5000, stdio: "pipe" });
+                execFileSync("sudo", ["-n", "tee", resetFile], {
+                    timeout: 5000,
+                    input: resetIndex,
+                    stdio: ["pipe", "ignore", "pipe"],
+                });
+            }
+            catch (sudoErr) {
+                console.warn("[nomad] Could not write acl-bootstrap-reset file:", sudoErr.message || writeErr.message);
+                return;
+            }
         }
         // Restart Nomad so it picks up the reset file
         try {
@@ -1127,9 +1362,14 @@ async function bootstrapNomadACL() {
         catch {
             // No passwordless sudo — try pkill/re-spawn path (best effort)
             try {
-                execFileSync("pkill", ["-TERM", "-f", "nomad agent"], { stdio: "pipe" });
+                execFileSync("sudo", ["-n", "pkill", "-TERM", "-f", "nomad agent"], { stdio: "pipe" });
+            }
+            catch {
+                try {
+                    execFileSync("pkill", ["-TERM", "-f", "nomad agent"], { stdio: "pipe" });
+                }
+                catch { }
             }
-            catch { }
         }
         // Wait for Nomad to come back
         for (let i = 0; i < 20; i++) {
@@ -1257,14 +1497,15 @@ export async function stopNomad() {
     try {
         if (!isPortListening(4646))
             return { ok: true, message: "Nomad not running" };
-        // SIGTERM: graceful shutdown — Nomad flushes state, drains allocs (force=true in HCL)
-        // Nomad runs as the current user; no sudo needed to send SIGTERM
-        try {
-            execSync("pkill -TERM -f 'nomad agent'", { timeout: 5000 });
-        }
-        catch { }
-        // Wait up to 35s for process to exit (drain_on_shutdown deadline + grace)
-        for (let i = 0; i < 35; i++) {
+        // SIGTERM: graceful shutdown — Nomad flushes state and detaches from
+        // running allocs without killing them (drain_on_shutdown is deliberately
+        // not configured, so the docker containers keep running and will be
+        // re-attached when Nomad comes back).
+        // Use killNomadByProcName (pgrep -x) to avoid pkill -f self-matching.
+        killNomadByProcName();
+        // Wait up to 10s for the process to exit. No drain means shutdown is
+        // near-instant — most of this budget is slack for slow disks on Pi.
+        for (let i = 0; i < 10; i++) {
             await new Promise(r => setTimeout(r, 1000));
             if (!isPortListening(4646))
                 return { ok: true, message: "Nomad stopped" };
@@ -1292,8 +1533,7 @@ export function installNomadSystemd() {
         if (process.platform === "darwin") {
             const plistLabel = "com.jishushell.nomad";
             const logPath = join(NOMAD_CONFIG_DIR, "nomad.log");
-            const primarySocket = join(homedir(), ".docker", "run", "docker.sock");
-            const dockerSock = existsSync(primarySocket) ? primarySocket : "/var/run/docker.sock";
+            const dockerSock = COLIMA_SOCKET;
             const plistContent = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -1317,8 +1557,7 @@ export function installNomadSystemd() {
 </dict>
 </plist>`;
             const plistPath = join(process.env.HOME || dirname(JISHUSHELL_HOME), `Library/LaunchAgents/${plistLabel}.plist`);
-            mkdirSync(dirname(plistPath), { recursive: true });
-            writeFileSync(plistPath, plistContent);
+            writeConfigFile(plistPath, plistContent);
             try {
                 execSync(`launchctl unload "${plistPath}" 2>/dev/null`);
             }
@@ -1326,17 +1565,18 @@ export function installNomadSystemd() {
             execSync(`launchctl load -w "${plistPath}"`, { timeout: 15000 });
             return { ok: true, message: "Nomad launchd agent installed and started" };
         }
-        // Nomad runs as the current (non-root) user so all ~/.jishushell/ files remain accessible.
-        // Group=docker gives the process access to /var/run/docker.sock for the Docker driver.
-        const currentUser = process.env.USER || process.env.LOGNAME || process.env.SUDO_USER || "jishu";
+        // Nomad 1.6.5's docker driver fingerprint requires euid==0 — PR #18197 lifted
+        // that restriction only in 1.7+, and we intentionally stay on the 1.6 MPL line.
+        // The panel stays as the installing user via a separate jishushell.service unit;
+        // it talks to this agent over HTTP, so no files under ~/.jishushell/nomad/data/
+        // are read directly by the panel.
         const serviceContent = `[Unit]
 Description=Nomad Agent
 After=network-online.target docker.service
 Wants=network-online.target
 
 [Service]
-User=${currentUser}
-SupplementaryGroups=docker
+User=root
 Type=simple
 EnvironmentFile=-/etc/jishushell/nomad.env
 ExecStart=${nomadPath} agent -config=${configPath}
@@ -1348,7 +1588,7 @@ WantedBy=multi-user.target
 `;
         const servicePath = "/etc/systemd/system/nomad.service";
         execFileSync("sudo", ["mkdir", "-p", "/etc/jishushell"], { timeout: 5000 });
-        writeFileSync("/tmp/nomad.service", serviceContent);
+        writeSystemTmpFile("/tmp/nomad.service", serviceContent);
         execFileSync("sudo", ["cp", "/tmp/nomad.service", servicePath], { timeout: 5000 });
         execFileSync("sudo", ["systemctl", "daemon-reload"], { timeout: 5000 });
         execFileSync("sudo", ["systemctl", "enable", "--now", "nomad"], { timeout: 15000 });
@@ -1384,11 +1624,11 @@ export function installJishushellSystemd(port) {
 export JISHUSHELL_HOME="${JISHUSHELL_HOME}"
 export HOME="${realHome}"
 export NODE_ENV=production
-export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin:/Applications/Docker.app/Contents/Resources/bin:${dirname(nodeBin)}:\${PATH}"
+export DOCKER_HOST="unix://${COLIMA_SOCKET}"
+export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin:${dirname(nodeBin)}:\${PATH}"
 exec "${nodeBin}" "${cliBin}" serve --port ${resolvedPort}
 `;
-            mkdirSync(dirname(wrapperPath), { recursive: true });
-            writeFileSync(wrapperPath, wrapperContent, { mode: 0o755 });
+            writeExecutableFile(wrapperPath, wrapperContent);
             const plistContent = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -1406,8 +1646,7 @@ exec "${nodeBin}" "${cliBin}" serve --port ${resolvedPort}
 </dict>
 </plist>`;
             const plistPath = join(process.env.HOME || realHome, `Library/LaunchAgents/${plistLabel}.plist`);
-            mkdirSync(dirname(plistPath), { recursive: true });
-            writeFileSync(plistPath, plistContent);
+            writeConfigFile(plistPath, plistContent);
             const panelAlreadyRunning = isPortListening(resolvedPort);
             if (!panelAlreadyRunning) {
                 try {
@@ -1441,7 +1680,7 @@ Environment=NODE_ENV=production
 WantedBy=multi-user.target
 `;
         execFileSync("sudo", ["mkdir", "-p", "/etc/jishushell"], { timeout: 5000 });
-        writeFileSync("/tmp/jishushell.service", serviceContent);
+        writeSystemTmpFile("/tmp/jishushell.service", serviceContent);
         execFileSync("sudo", ["cp", "/tmp/jishushell.service", "/etc/systemd/system/jishushell.service"], { timeout: 5000 });
         execFileSync("sudo", ["systemctl", "daemon-reload"], { timeout: 5000 });
         execFileSync("sudo", ["systemctl", "enable", "jishushell"], { timeout: 15000 });
@@ -1463,7 +1702,7 @@ export async function installOpenclaw(version = "latest") {
             return { ok: true, message: `OpenClaw already installed: ${ver}` };
         }
         const task = createTask("openclaw");
-        mkdirSync(OPENCLAW_PKG_DIR, { recursive: true });
+        ensureDirHost(OPENCLAW_PKG_DIR);
         emitTask(task, { type: "progress", message: "开始安装 OpenClaw...", progress: 0 });
         // Monitor directory size for progress estimation
         const sizeTracker = setInterval(() => {
@@ -1532,40 +1771,47 @@ function checkDockerImageExists() {
         return true;
     }
     catch {
+        // Fallback scan: list all local images and try to find any known runtime image.
+        // This handles two scenarios:
+        //  1. panel.json was wiped (e.g. after `jishushell reset`) and the pinned version
+        //     tag is no longer stored, causing getOpenclawDockerImage() to return the default
+        //     `:latest` tag which may have been removed locally during the first-run migration.
+        //  2. The environment uses a locally built runtime image (e.g. jishushell-hermes:latest)
+        //     that differs from the registry default.
+        // When a candidate is found we restore panel.json (self-heal) so the fast path works next time.
+        try {
+            const invocation = resolveDockerInvocation();
+            const out = execFileSync(invocation.cmd, [...invocation.argsPrefix, "images", "--format", "{{.Repository}}:{{.Tag}}"], { encoding: "utf8", timeout: 5000 });
+            const lines = out.split("\n").map((l) => l.trim()).filter(Boolean);
+            // 1. Same repository as DEFAULT_OPENCLAW_DOCKER_IMAGE (e.g. after pinned-tag migration).
+            const defaultImage = DEFAULT_OPENCLAW_DOCKER_IMAGE;
+            const repoColonIdx = defaultImage.lastIndexOf(":");
+            const repoSlashIdx = defaultImage.lastIndexOf("/");
+            if (repoColonIdx > repoSlashIdx) {
+                const repo = defaultImage.slice(0, repoColonIdx);
+                const repoPrefix = repo + ":";
+                const found = lines.find((l) => l.startsWith(repoPrefix) && !l.endsWith(":<none>") && !l.endsWith(":none"));
+                if (found) {
+                    setOpenclawDockerImage(found);
+                    return true;
+                }
+            }
+            // 2. Backward compat: older locally-built jishushell-openclaw:* image names.
+            //    These use the same slim base architecture as ghcr.io/x-aijishu/openclaw-runtime:*
+            //    and are fully compatible. Self-heal panel.json so the tag stored there becomes
+            //    the concrete existing tag, preventing repeated DEFAULT-migration side effects.
+            const legacyFound = lines.find((l) => /^jishushell-openclaw:[^\s]+/.test(l) && !l.endsWith(":<none>") && !l.endsWith(":none"));
+            if (legacyFound) {
+                setOpenclawDockerImage(legacyFound);
+                return true;
+            }
+        }
+        catch { }
         return false;
     }
 }
 // The stable tag for the JishuShell base image (slim — no OpenClaw binary baked in).
-// This tag does NOT change when OpenClaw is upgraded; the binary is bind-mounted from
-// the host at runtime. Rebuild this image only when system packages (Node.js, python3…)
-// need to change.
-export const BASE_IMAGE_TAG = "jishushell-base:v1";
 function resolveDockerImageTag() {
-    // 1. Environment variable takes precedence (same as runtime getOpenclawDockerImage)
-    if (process.env.OPENCLAW_DOCKER_IMAGE)
-        return process.env.OPENCLAW_DOCKER_IMAGE;
-    // 2. Stored in panel.json — honours custom images and pre-existing openclaw:*
-    //    images that haven't been migrated yet (backward compatibility).
-    const stored = getPanelConfig().openclaw_image;
-    if (typeof stored === "string" && stored.trim())
-        return stored;
-    // 3. Scan local daemon — prefer official ghcr.io image, fall back to legacy jishushell-base.
-    try {
-        const invocation = resolveDockerInvocation();
-        const output = execFileSync(invocation.cmd, [...invocation.argsPrefix, "images", "--format", "{{.Repository}}:{{.Tag}}"], { encoding: "utf-8", timeout: 5000 });
-        const lines = output.split("\n").map(l => l.trim());
-        // Prefer custom image (built with Python), then official, then legacy
-        const custom = lines.find(l => l.startsWith(CUSTOM_IMAGE_PREFIX + ":"));
-        if (custom)
-            return custom;
-        const official = lines.find(l => l.startsWith("ghcr.io/openclaw/openclaw:"));
-        if (official)
-            return official;
-        const legacy = lines.find(l => /^jishushell-base:/i.test(l));
-        if (legacy)
-            return legacy;
-    }
-    catch { }
     return getOpenclawDockerImage();
 }
 // Base image and mirror list for the OpenClaw Docker build.
@@ -1615,7 +1861,7 @@ function resolveVersionedBuildTag() {
         if (existsSync(pkg)) {
             const ver = JSON.parse(readFileSync(pkg, "utf-8")).version;
             if (ver)
-                return `${CUSTOM_IMAGE_PREFIX}:${ver}`;
+                return `jishushell-openclaw:${ver}`;
         }
     }
     catch { }
@@ -1665,9 +1911,9 @@ CMD ["gateway", "run", "--port", "18789", "--allow-unconfigured"]
 `;
         // Use a temp dir as build context — no files to COPY means no large transfer.
         const buildDir = join(tmpdir(), `jishushell-base-build-${Date.now()}`);
-        mkdirSync(buildDir, { recursive: true });
+        ensureDirHost(buildDir);
         const dockerfilePath = join(buildDir, "Dockerfile");
-        writeFileSync(dockerfilePath, dockerfile);
+        writeConfigFile(dockerfilePath, dockerfile);
         emitTask(task, { type: "progress", message: `构建基础镜像 ${targetTag}（无需拷贝二进制，速度极快）...`, progress: 10 });
         let result;
         try {
@@ -1694,7 +1940,7 @@ CMD ["gateway", "run", "--port", "18789", "--allow-unconfigured"]
             task.status = "error";
             return { ok: false, message: "Docker image build failed", error: result.output, taskId: task.id };
         }
-        const localTag = `${CUSTOM_IMAGE_PREFIX}:local`;
+        const localTag = "jishushell-openclaw:local";
         if (targetTag !== localTag) {
             try {
                 execFileSync(invocation.cmd, [...invocation.argsPrefix, "tag", targetTag, localTag], { timeout: 10000, stdio: "ignore" });
@@ -1787,7 +2033,7 @@ CMD ["node", "openclaw.mjs", "gateway", "--allow-unconfigured"]
 `;
         // Write Dockerfile into the npm package directory (build context)
         const dockerfilePath = join(OPENCLAW_PKG_DIR, "Dockerfile");
-        writeFileSync(dockerfilePath, dockerfile);
+        writeConfigFile(dockerfilePath, dockerfile);
         let buildResult;
         try {
             buildResult = await spawnWithTask(task, invocation.cmd, [...invocation.argsPrefix, "build", "--network=host", "-t", targetTag, OPENCLAW_PKG_DIR], { timeout: 1800000, progressParser: dockerBuildProgressParser });
@@ -1818,24 +2064,212 @@ CMD ["node", "openclaw.mjs", "gateway", "--allow-unconfigured"]
         return { ok: false, message: "Docker image build failed", error: e.message, taskId: task.id };
     }
 }
-export async function buildCustomOpenclawImage(tag) {
-    const task = createTask("openclaw-docker-build");
-    return buildCustomOpenclawImageWithTask(task, tag);
+// ── Pull or build OpenClaw Docker image ───────────────────────────
+/** Matches a semver-ish tag suffix, e.g. "...:2026.4.9" or "...:v1.2.3-beta". */
+const PINNED_IMAGE_TAG_RE = /:[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9.-]+)?$/;
+/**
+ * Query the npm registry for the current OpenClaw version. Used to bust the
+ * Docker layer cache for `RUN npm install openclaw@${ver}` during local build.
+ * Returns "latest" when npm is unreachable so the build can still proceed.
+ */
+function resolveOpenclawNpmVersion() {
+    try {
+        const out = execFileSync("npm", ["view", "openclaw", "version"], {
+            timeout: 15000,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (/^\d+\.\d+\.\d+/.test(out))
+            return out;
+    }
+    catch { /* npm not reachable */ }
+    return "latest";
 }
-export function startBuildCustomOpenclawImage(tag) {
-    const task = createTask("openclaw-docker-build");
-    void buildCustomOpenclawImageWithTask(task, tag).catch((err) => {
-        emitTask(task, { type: "error", message: `镜像构建失败: ${err?.message || err}` });
+/**
+ * Read the OpenClaw version actually bundled at /app/ inside a Docker image,
+ * bypassing `openclaw-entry.sh`'s `.npm-global/` override. This is the
+ * authoritative source of truth — the image's OCI label can be wrong
+ * (CI bugs, layer cache reuse), but `/app/node_modules/openclaw/package.json`
+ * is the exact content that ran through `npm install`.
+ *
+ * Spawns a throw-away container with `--entrypoint node` so Node prints the
+ * version directly. Returns "" when docker is unavailable or the path is
+ * missing (e.g. a non-openclaw image).
+ */
+function readBundledOpenclawVersion(invocation, image) {
+    try {
+        const out = execFileSync(invocation.cmd, [
+            ...invocation.argsPrefix,
+            "run", "--rm",
+            "--entrypoint", "node",
+            image,
+            "-p",
+            "require('/app/node_modules/openclaw/package.json').version",
+        ], { timeout: 20000, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        if (/^\d+\.\d+\.\d+/.test(out))
+            return out;
+    }
+    catch { /* docker unavailable, image missing, or path not present */ }
+    return "";
+}
+/**
+ * After a successful pull or build, capture the image's real OpenClaw version
+ * and return a pinned tag of the form `ghcr.io/.../openclaw-runtime:<version>`.
+ * The pinned tag is added as a local alias via `docker tag` so subsequent
+ * Nomad allocations see an immutable reference and never re-pull on restart.
+ *
+ * Version discovery order:
+ *  1. `explicitVersion` when the caller already knows it (e.g. the local build
+ *     path, which queries npm for the version and passes it as `--build-arg`).
+ *  2. Bundled `/app/node_modules/openclaw/package.json` inside the image
+ *     (authoritative — bypasses both the `.npm-global/` override layer and a
+ *     potentially stale OCI label).
+ *
+ * Returns the original tag unchanged when:
+ *  - the target is already a pinned version tag
+ *  - no version can be discovered
+ *  - docker tag fails for any reason
+ */
+function capturePinnedImageTag(invocation, targetTag, explicitVersion) {
+    // Already pinned? Nothing to do.
+    if (PINNED_IMAGE_TAG_RE.test(targetTag))
+        return targetTag;
+    let version = explicitVersion && /^\d+\.\d+\.\d+/.test(explicitVersion) ? explicitVersion : "";
+    if (!version) {
+        version = readBundledOpenclawVersion(invocation, targetTag);
+    }
+    if (!version || !/^\d+\.\d+\.\d+/.test(version))
+        return targetTag;
+    // Build the pinned tag by replacing the mutable tag portion.
+    // "ghcr.io/foo/bar:latest"   → "ghcr.io/foo/bar:2026.4.9"
+    // "ghcr.io/foo/bar"          → "ghcr.io/foo/bar:2026.4.9"
+    const colonIdx = targetTag.lastIndexOf(":");
+    const slashIdx = targetTag.lastIndexOf("/");
+    const hasTag = colonIdx > slashIdx;
+    const repo = hasTag ? targetTag.slice(0, colonIdx) : targetTag;
+    const pinnedTag = `${repo}:${version}`;
+    if (pinnedTag === targetTag)
+        return targetTag;
+    try {
+        execFileSync(invocation.cmd, [...invocation.argsPrefix, "tag", targetTag, pinnedTag], { timeout: 10000, stdio: "ignore" });
+    }
+    catch {
+        // Could not create the local alias — fall back to original tag.
+        return targetTag;
+    }
+    // Drop the mutable original alias (`:latest` / `:slim`) now that the pinned
+    // tag is in place. Removing a tag is cheap and leaves the underlying image
+    // alive because the new pinned reference still points to it. Best-effort:
+    // silent when the tag is already gone or in use.
+    if (/:(latest|slim)$/.test(targetTag)) {
+        try {
+            execFileSync(invocation.cmd, [...invocation.argsPrefix, "rmi", targetTag], { timeout: 10000, stdio: "ignore" });
+        }
+        catch { /* best-effort cleanup */ }
+    }
+    return pinnedTag;
+}
+async function pullOrBuildOpenclawImageWithTask(task, tag) {
+    const targetTag = tag || DEFAULT_OPENCLAW_DOCKER_IMAGE;
+    try {
+        const invocation = resolveDockerInvocation();
+        // Fast check: if image already exists locally, skip
+        try {
+            execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "inspect", targetTag], {
+                timeout: 10000,
+                stdio: "ignore",
+            });
+            const pinned = capturePinnedImageTag(invocation, targetTag);
+            setOpenclawDockerImage(pinned);
+            emitTask(task, { type: "done", message: `Docker 镜像已存在: ${pinned}`, progress: 100 });
+            task.status = "done";
+            return { ok: true, message: `Docker image ${pinned} already exists`, taskId: task.id };
+        }
+        catch { /* image not found, proceed */ }
+        // ── Step 1: Try docker pull from registry ─────────────────────
+        emitTask(task, { type: "progress", message: `正在拉取镜像: ${targetTag} ...`, progress: 10 });
+        const pullResult = await spawnWithTask(task, invocation.cmd, [...invocation.argsPrefix, "pull", targetTag], { timeout: 600000 });
+        if (pullResult.ok) {
+            const pinned = capturePinnedImageTag(invocation, targetTag);
+            setOpenclawDockerImage(pinned);
+            emitTask(task, { type: "done", message: `镜像拉取成功: ${pinned}`, progress: 100 });
+            task.status = "done";
+            return { ok: true, message: `Docker image ${pinned} pulled`, taskId: task.id };
+        }
+        // ── Step 2: Fallback to local build ───────────────────────────
+        console.log(`[setup] docker pull failed for ${targetTag}, falling back to local build...`);
+        emitTask(task, { type: "progress", message: `拉取失败，正在本地构建镜像: ${targetTag} ...`, progress: 20 });
+        const projectRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
+        const dockerfilePath = join(projectRoot, "Dockerfile.openclaw-slim");
+        if (!existsSync(dockerfilePath)) {
+            emitTask(task, { type: "error", message: "Dockerfile.openclaw-slim not found, cannot fallback to local build" });
+            task.status = "error";
+            return { ok: false, message: "Docker pull failed and Dockerfile.openclaw-slim not found", taskId: task.id };
+        }
+        // Resolve the OpenClaw version from npm so the build-arg busts the Docker
+        // layer cache for `RUN npm install openclaw@${ver}`. The Dockerfile's
+        // ARG OPENCLAW_VERSION=latest default would otherwise cause the layer to
+        // be silently reused across releases.
+        const openclawVersion = resolveOpenclawNpmVersion();
+        console.log(`[setup] building openclaw image with OPENCLAW_VERSION=${openclawVersion}`);
+        const buildResult = await spawnWithTask(task, invocation.cmd, [
+            ...invocation.argsPrefix,
+            "build",
+            "--network=host",
+            "--build-arg", `OPENCLAW_VERSION=${openclawVersion}`,
+            "-f", dockerfilePath,
+            "-t", targetTag,
+            projectRoot,
+        ], { timeout: 1800000, progressParser: dockerBuildProgressParser });
+        if (!buildResult.ok) {
+            try {
+                execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "prune", "-f"], { timeout: 15000, stdio: "ignore" });
+            }
+            catch { }
+            emitTask(task, { type: "error", message: "Docker 镜像构建失败" });
+            task.status = "error";
+            return { ok: false, message: "Docker image build failed", error: buildResult.output, taskId: task.id };
+        }
+        // Local builds don't get labels from the GitHub Action's `labels:` field,
+        // so pass the npm version we already know to let capturePinnedImageTag
+        // mint the pinned tag without relying on docker inspect.
+        const pinned = capturePinnedImageTag(invocation, targetTag, openclawVersion);
+        setOpenclawDockerImage(pinned);
+        emitTask(task, { type: "done", message: `OpenClaw 镜像就绪 (本地构建): ${pinned}`, progress: 100 });
+        task.status = "done";
+        return { ok: true, message: `Docker image ${pinned} built locally`, taskId: task.id };
+    }
+    catch (e) {
+        emitTask(task, { type: "error", message: `镜像获取失败: ${e.message}` });
+        task.status = "error";
+        return { ok: false, message: "Docker image pull/build failed", error: e.message, taskId: task.id };
+    }
+}
+export async function buildSlimOpenclawImage(tag) {
+    const task = createTask("openclaw-docker-pull");
+    return pullOrBuildOpenclawImageWithTask(task, tag);
+}
+export function startBuildSlimOpenclawImage(tag) {
+    const task = createTask("openclaw-docker-pull");
+    void pullOrBuildOpenclawImageWithTask(task, tag).catch((err) => {
+        emitTask(task, { type: "error", message: `镜像获取失败: ${err?.message || err}` });
         task.status = "error";
     });
-    return { ok: true, message: "Docker image build started", taskId: task.id };
+    return { ok: true, message: "Docker image pull started", taskId: task.id };
+}
+/** @deprecated Use buildSlimOpenclawImage instead */
+export async function buildCustomOpenclawImage(tag) {
+    return buildSlimOpenclawImage(tag);
+}
+/** @deprecated Use startBuildSlimOpenclawImage instead */
+export function startBuildCustomOpenclawImage(tag) {
+    return startBuildSlimOpenclawImage(tag);
 }
 export async function runFullSetup(options = {}) {
     const steps = [];
     let allOk = true;
     const defaults = {
         installNomad: true,
-        installOpenclaw: true,
         buildDockerImage: true,
         ...options,
     };
@@ -1872,14 +2306,6 @@ export async function runFullSetup(options = {}) {
             }
         }
     }
-    if (defaults.installOpenclaw) {
-        steps.push({ step: "openclaw", status: "running", message: "Installing OpenClaw..." });
-        const result = await installOpenclaw();
-        steps[steps.length - 1].status = result.ok ? "done" : "error";
-        steps[steps.length - 1].message = result.message;
-        if (!result.ok)
-            allOk = false;
-    }
     // Prepare Docker image: pull official image or build slim base (legacy).
     if (defaults.buildDockerImage) {
         // Restart Nomad so it re-detects Docker driver after Docker was installed
@@ -1893,9 +2319,7 @@ export async function runFullSetup(options = {}) {
         }
         catch { }
         steps.push({ step: "docker-image", status: "running", message: "Building OpenClaw Docker image..." });
-        const imgResult = isOfficialImage()
-            ? await buildCustomOpenclawImage()
-            : await buildOpenclawDockerImage();
+        const imgResult = await buildSlimOpenclawImage();
         steps[steps.length - 1].status = imgResult.ok ? "done" : "error";
         steps[steps.length - 1].message = imgResult.message;
         if (!imgResult.ok)