jishushell 0.4.2-beta2 → 0.4.10

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, existsSync, readFileSync, 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,6 +21,9 @@ 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 COLIMA_DIR = join(JISHUSHELL_HOME, "colima");
+const COLIMA_PROFILE = "jishushell";
+const COLIMA_SOCKET = join(COLIMA_DIR, COLIMA_PROFILE, "docker.sock");
 const NOMAD_VERSION = "1.11.3";
 let _serverPort = 8090;
 export function setServerPort(port) { _serverPort = port; }
@@ -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 = {
@@ -839,7 +819,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 +829,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 +897,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,13 +922,14 @@ 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" {
@@ -966,7 +945,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 +1056,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 {
@@ -1114,7 +1093,7 @@ async function bootstrapNomadACL() {
         // Write the reset trigger file (Nomad reads this on startup to allow re-bootstrap)
         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);
@@ -1257,14 +1236,18 @@ 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
+        // 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).
+        // 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++) {
+        // 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 +1275,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 +1299,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`);
             }
@@ -1348,7 +1329,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 +1365,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 +1387,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 +1421,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 +1443,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 +1512,21 @@ function checkDockerImageExists() {
         return true;
     }
     catch {
+        // Backward compat: after upgrading from old image names (jishushell-openclaw:*)
+        // to the new slim tag, the new image may not exist yet. Check if any old image
+        // is still available so we don't kick the user back to the Setup wizard.
+        try {
+            const invocation = resolveDockerInvocation();
+            const out = execFileSync(invocation.cmd, [...invocation.argsPrefix, "images", "--format", "{{.Repository}}:{{.Tag}}"], { encoding: "utf8", timeout: 5000 });
+            if (out.split("\n").some((l) => /^jishushell-openclaw:/.test(l)))
+                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 +1576,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 +1626,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 +1655,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 +1748,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 +1779,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 +2021,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 +2034,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)