jishushell 0.4.10 → 0.4.24

package/dist/services/runtime/adapters/openclaw.js

@@ -0,0 +1,2195 @@
+/**
+ * OpenClawAdapter — the framework face of OpenClaw business logic.
+ *
+ * Per §32.2 / §32.8 of docs/multi-agent-runtime-generalization-plan.md, the
+ * goal of this file is simple: **all OpenClaw-specific knowledge leaves the
+ * framework (instance-manager / nomad-manager / routes) and lives here**.
+ *
+ * Why not a huge rewrite in a single pass?
+ *   A full physical migration of ~6500 lines of OpenClaw code out of
+ *   `instance-manager.ts` / `nomad-manager.ts` / `setup-manager.ts` is a
+ *   multi-PR undertaking. This file lands the **structural** decoupling
+ *   (contract + dispatch) today, so:
+ *
+ *     1. Every framework call site now goes through `getAdapter(agentType).X()`
+ *        with zero string-literal branching on "openclaw" / "hermes".
+ *     2. OpenClaw-specific imperative logic that was already contained (Nomad
+ *        task build, on-disk patches, npm update seed, pairing CLI mapping)
+ *        is physically moved into this file.
+ *     3. Larger pieces that are still entangled inside instance-manager.ts
+ *        (`saveConfig` with channel-plugin auto-install, `createInstance`
+ *        with `openclaw.json` seeding) are exposed through adapter hooks
+ *        that framework code calls, and the physical code move from
+ *        instance-manager.ts into a sibling `openclaw-*.ts` file is a
+ *        straightforward follow-up PR — the `check-adapter-isolation.ts`
+ *        script (§32.2.1) will block any new code from sneaking back into
+ *        the framework layer.
+ *
+ * The user contract for adding a THIRD agent is therefore already satisfied
+ * even before the follow-up physical migration:
+ *
+ *     1. Create `src/services/runtime/adapters/foo.ts` mirroring this file.
+ *     2. Add `import "./adapters/foo.js"` to `src/services/runtime/index.ts`.
+ *     3. Add one line to `frontend/src/runtimes/registry.ts`.
+ *     4. Done. No `instance-manager.ts` / `nomad-manager.ts` / routes edits.
+ */
+import { execFile, execFileSync } from "child_process";
+import { chmodSync, chownSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, } from "fs";
+import { randomBytes } from "crypto";
+import { homedir, userInfo } from "os";
+import { dirname, join, resolve as pathResolve } from "path";
+import { getNomadDriver, getOpenclawDockerImage, JISHUSHELL_HOME, getPanelConfig, } from "../../../config.js";
+import { LEGACY_PROVIDER_API_ALIASES } from "../../../constants.js";
+import { ensureDirContainer, ensureDirHost, writeConfigFile } from "../../../utils/fs.js";
+import { safeWriteJson } from "../../../utils/safe-json.js";
+import { compileTaskRuntime } from "../../app/app-compiler.js";
+import { allocateGatewayPort, chownToServiceUser, extractGatewayPort, getInstance, getRuntimeEnv, getRuntimeEnvFiles, inferProviderApiKeyEnvName, listInstances, normalizePath, notifyConfigChange, releasePendingPort, resolveServiceUser, updateEnvFile, } from "../../instance-manager.js";
+import { getInstanceDir as framework_instanceDir, instanceMetaPath } from "../../../config.js";
+import { createTask, emitTask, spawnWithTask, getDirSizeMB, npmProgressParser, dockerBuildProgressParser, resolveDockerInvocation, } from "../../setup-manager.js";
+import { DEFAULT_OPENCLAW_DOCKER_IMAGE, setOpenclawDockerImage, OPENCLAW_MODULES, OPENCLAW_PKG_DIR, } from "../../../config.js";
+import { fileURLToPath } from "node:url";
+import { bootstrapInstanceProxy } from "../../llm-proxy/index.js";
+import { registerAdapter } from "../registry.js";
+import { registerOpenclawRoutes } from "./openclaw-routes.js";
+// ── Constants physically migrated from nomad-manager.ts ───────────────
+//
+// These used to live as module-scope constants in nomad-manager.ts and were
+// read by `buildTaskDocker` / `buildRuntime` helpers. They describe how
+// OpenClaw expects to be launched — container image paths, default command,
+// memory ceilings — and therefore belong to the OpenClaw adapter, not the
+// Nomad scheduler.
+const DEFAULT_COMMAND = "/usr/bin/openclaw";
+const DEFAULT_ARGS = ["gateway", "run", "--port", "18789", "--allow-unconfigured"];
+const DEFAULT_USER = userInfo().username;
+const DEFAULT_CWD = homedir();
+const DEFAULT_ENV = {
+    HOME: homedir(),
+    TMPDIR: "/tmp",
+    PATH: `${homedir()}/.local/bin:${homedir()}/.npm-global/bin:${homedir()}/bin:${homedir()}/.volta/bin:` +
+        `${homedir()}/.asdf/shims:${homedir()}/.bun/bin:${homedir()}/.nvm/current/bin:${homedir()}/.fnm/current/bin:` +
+        `${homedir()}/.local/share/pnpm:/usr/local/bin:/usr/bin:/bin`,
+};
+const DEFAULT_RESOURCES = { CPU: 500, MemoryMB: 512 };
+const DEFAULT_PIDS_LIMIT = 512;
+// Hard upper bounds applied before submitting any Nomad job. Prevents a
+// misconfigured or malicious instance config from exhausting scheduler
+// resources on the host (no Nomad Enterprise Resource Quotas in OSS).
+const MAX_CPU_MHZ = 4000;
+const MAX_MEMORY_MB = 4096;
+const MAX_MEMORY_MAX_MB = 4096;
+// Path inside the openclaw-runtime Docker image where the baked-in openclaw
+// npm package lives. Referenced by the entrypoint shim as the fallback and
+// used by the control-UI "Update now" path through a pre-seeded symlink in
+// $HOME/.npm-global (see ensureOpenclawUpdateSeed below).
+const CONTAINER_IMAGE_PKG_ROOT = "/app/node_modules/openclaw";
+const VALID_USER_RE = /^[a-z0-9._-]{1,32}$/;
+const DOCKER_IMAGE_RE = /^[a-zA-Z0-9][a-zA-Z0-9\-_.:/@]*$/;
+const MAX_DOCKER_IMAGE_NAME_LEN = 256;
+export const OPENCLAW_DEFAULT_GATEWAY_PORT = 18789;
+// ── Capability profile (moved from runtime/instance.ts) ──────────────
+//
+// Describes what the framework should expose for OpenClaw instances. The
+// frontend uses this to decide which tabs render and how the Chat tab looks.
+const DEFAULT_CAPABILITIES = {
+    gateway: {
+        http: true,
+        websocket: true,
+        chatPanel: "iframe",
+    },
+    pairing: {
+        list: true,
+        approve: true,
+        revoke: false,
+        clearPending: false,
+    },
+    configEditor: "json",
+    configSchema: false,
+    customProvider: true,
+    pluginInstall: true,
+    skills: true,
+    mcp: true,
+    memory: true,
+    backupRestore: true,
+    usageStats: true,
+    restartlessReload: false,
+    messagingPlatforms: ["feishu", "openclaw-weixin"],
+};
+// ── Path helpers (physically migrated from instance-manager.ts) ───────
+const INSTANCE_OPENCLAW_HOME_DIRNAME = "openclaw-home";
+const INSTANCE_MODEL_ENV_FILENAME = "model.env";
+const OPENCLAW_STATE_DIRNAME = ".openclaw";
+const OPENCLAW_CONFIG_FILENAME = "openclaw.json";
+function defaultOpenclawHome(instanceId) {
+    return join(framework_instanceDir(instanceId), INSTANCE_OPENCLAW_HOME_DIRNAME);
+}
+function defaultOpenclawModelEnvFile(instanceId) {
+    return join(framework_instanceDir(instanceId), INSTANCE_MODEL_ENV_FILENAME);
+}
+function isPrecreatedManagedAppDir(dir) {
+    return existsSync(join(dir, "app-spec.yaml")) && existsSync(join(dir, "manifest.json"));
+}
+function openclawConfigPath(instanceId, home) {
+    const h = home ?? defaultOpenclawHome(instanceId);
+    return join(h, OPENCLAW_STATE_DIRNAME, OPENCLAW_CONFIG_FILENAME);
+}
+function legacyOpenclawConfigPath(instanceId, home) {
+    const h = home ?? defaultOpenclawHome(instanceId);
+    return join(h, OPENCLAW_CONFIG_FILENAME);
+}
+/**
+ * Resolve the most relevant openclaw.json path for a SOURCE instance used
+ * by the clone_from branch. Prefers the .openclaw/ state dir, falls back
+ * to the legacy flat path so clones of old instances still work.
+ */
+function resolveExistingConfigPath(instanceId) {
+    const runtimePath = openclawConfigPath(instanceId);
+    if (existsSync(runtimePath))
+        return runtimePath;
+    const legacy = legacyOpenclawConfigPath(instanceId);
+    if (existsSync(legacy))
+        return legacy;
+    return runtimePath;
+}
+// ── Runtime + config defaults (physically migrated) ───────────────────
+function resolveOpenclawBin() {
+    const candidates = [
+        join(JISHUSHELL_HOME, "packages", "openclaw", "bin", "openclaw"),
+        "/usr/local/bin/openclaw",
+        "/usr/bin/openclaw",
+    ];
+    for (const p of candidates) {
+        if (existsSync(p)) {
+            try {
+                chmodSync(p, 0o755);
+            }
+            catch {
+                /* best effort — may be a symlink */
+            }
+            try {
+                const real = realpathSync(p);
+                if (real !== p)
+                    chmodSync(real, 0o755);
+            }
+            catch {
+                /* best effort */
+            }
+            return p;
+        }
+    }
+    return candidates[0]; // fallback, will fail with clear error at spawn
+}
+function buildDefaultRuntime(instanceId, port, openclawHome) {
+    const home = openclawHome || defaultOpenclawHome(instanceId);
+    return {
+        command: resolveOpenclawBin(),
+        args: ["gateway", "run", "--port", String(port), "--allow-unconfigured"],
+        cwd: home,
+        user: resolveServiceUser()?.username ?? userInfo().username,
+        env_files: [defaultOpenclawModelEnvFile(instanceId)],
+        env: {
+            OPENCLAW_GATEWAY_PORT: String(port),
+            NODE_OPTIONS: "--max-old-space-size=2048",
+        },
+        resources: { CPU: 1000, MemoryMB: 2048 },
+    };
+}
+function starterConfig() {
+    const dp = getPanelConfig().default_provider;
+    let providerName = "minimax";
+    let providerConfig = {
+        baseUrl: "https://api.minimaxi.com/v1",
+        api: "openai-completions",
+        models: [{ id: "MiniMax-M2.7", name: "MiniMax M2.7", contextWindow: 204800 }],
+    };
+    let defaultModel = "minimax/MiniMax-M2.7";
+    if (dp?.providerId) {
+        providerName = dp.providerId;
+        providerConfig = {
+            baseUrl: dp.baseUrl,
+            api: dp.api,
+            ...(dp.authHeader ? { authHeader: true } : {}),
+            models: dp.models || [],
+        };
+        const modelId = dp.selectedModelId || dp.models?.[0]?.id || "";
+        defaultModel = `${providerName}/${modelId}`;
+    }
+    const config = {
+        models: { providers: { [providerName]: providerConfig } },
+        agents: { defaults: { model: defaultModel, models: { [defaultModel]: {} } } },
+        channels: {},
+        gateway: {
+            mode: "local",
+            auth: { mode: "token", token: randomBytes(24).toString("hex") },
+            controlUi: { dangerouslyDisableDeviceAuth: true },
+        },
+        plugins: { entries: { feishu: { enabled: false } } },
+    };
+    if (dp?.providerId) {
+        config["x-jishushell"] = {
+            proxy: {
+                upstream: {
+                    providerId: dp.providerId,
+                    baseUrl: dp.baseUrl,
+                    api: dp.api,
+                    authHeader: dp.authHeader || false,
+                    models: dp.models || [],
+                    selectedModelId: dp.selectedModelId || dp.models?.[0]?.id || "",
+                    hasApiKey: !!dp.apiKey,
+                },
+            },
+        };
+    }
+    return config;
+}
+// ── Nomad-patching helpers (migrated from nomad-manager.ts) ───────────
+/**
+ * In docker bridge mode, 127.0.0.1 inside the container resolves to the
+ * container's own loopback, not the host. Rewrite the jsproxy provider
+ * baseUrl in openclaw.json to use host.docker.internal instead.
+ */
+function patchJsproxyBaseUrl(configPath) {
+    try {
+        const raw = readFileSync(configPath, "utf-8");
+        const patched = raw.replace(/http:\/\/127\.0\.0\.1:(\d+)\/proxy/g, `http://host.docker.internal:$1/proxy`);
+        if (patched !== raw) {
+            writeConfigFile(configPath, patched);
+            console.log(`[openclaw] Patched jsproxy baseUrl in ${configPath} (127.0.0.1 → host.docker.internal)`);
+        }
+    }
+    catch (e) {
+        console.warn(`[openclaw] Failed to patch jsproxy baseUrl in ${configPath}: ${e.message}`);
+    }
+}
+/**
+ * Docker bridge port publishing cannot reach a process that only binds the
+ * container loopback. Normalize default/loopback gateway binds to `lan` so
+ * Nomad's published host port can reach the gateway.
+ */
+function patchDockerBridgeGatewayBind(configPath) {
+    try {
+        const raw = readFileSync(configPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return;
+        const gatewayRaw = parsed.gateway;
+        const gateway = gatewayRaw && typeof gatewayRaw === "object" && !Array.isArray(gatewayRaw)
+            ? gatewayRaw
+            : (parsed.gateway = {});
+        const bind = typeof gateway.bind === "string" ? gateway.bind.trim() : "";
+        if (bind && bind !== "loopback")
+            return;
+        gateway.bind = "lan";
+        const next = JSON.stringify(parsed, null, 2);
+        const output = raw.endsWith("\n") ? `${next}\n` : next;
+        if (output === raw)
+            return;
+        writeConfigFile(configPath, output);
+        console.log(`[openclaw] Normalized gateway.bind to "lan" in ${configPath} for Docker bridge networking`);
+    }
+    catch (e) {
+        console.warn(`[openclaw] Failed to patch gateway.bind in ${configPath}: ${e.message}`);
+    }
+}
+/**
+ * Pre-seed the per-instance npm global prefix with a symlink to the image's
+ * baked openclaw package so OpenClaw's in-gateway "Update now" handler can
+ * detect the install as an npm global install. Idempotent; docker driver only.
+ */
+function ensureOpenclawUpdateSeed(openclawHome, instanceId) {
+    if (getNomadDriver() !== "docker")
+        return;
+    if (!openclawHome)
+        return;
+    const linkDir = join(openclawHome, ".npm-global", "lib", "node_modules");
+    const linkPath = join(linkDir, "openclaw");
+    try {
+        lstatSync(linkPath);
+        return;
+    }
+    catch (err) {
+        if (err?.code !== "ENOENT") {
+            console.warn(`[openclaw] update-seed: lstat failed for ${linkPath}: ${err?.message ?? err}`);
+            return;
+        }
+    }
+    try {
+        mkdirSync(linkDir, { recursive: true });
+        symlinkSync(CONTAINER_IMAGE_PKG_ROOT, linkPath);
+        console.log(`[openclaw] update-seed ${instanceId}: seeded ${linkPath} -> ${CONTAINER_IMAGE_PKG_ROOT}`);
+    }
+    catch (err) {
+        console.warn(`[openclaw] update-seed ${instanceId}: failed to create seed: ${err?.message ?? err}`);
+    }
+}
+// ── Resource helpers (migrated from nomad-manager.ts) ─────────────────
+function resolveUidGid(username) {
+    try {
+        if (!VALID_USER_RE.test(username)) {
+            console.warn(`[openclaw] Invalid username for UID lookup: ${username}`);
+            return `${process.getuid()}:${process.getgid()}`;
+        }
+        const passwd = readFileSync("/etc/passwd", "utf-8");
+        const line = passwd.split("\n").find((l) => l.startsWith(username + ":"));
+        if (line) {
+            const parts = line.split(":");
+            const uid = parseInt(parts[2], 10);
+            const gid = parseInt(parts[3], 10);
+            if (!isNaN(uid) && !isNaN(gid))
+                return `${uid}:${gid}`;
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return `${process.getuid()}:${process.getgid()}`;
+}
+function normalizeDockerResources(instanceId, resources) {
+    const requestedMemoryMB = Number(resources.MemoryMB ?? DEFAULT_RESOURCES.MemoryMB);
+    let effectiveMemoryMB = requestedMemoryMB;
+    let effectiveMemoryMaxMB = Math.min(Number(resources.MemoryMaxMB ?? requestedMemoryMB), MAX_MEMORY_MAX_MB);
+    if (effectiveMemoryMaxMB < effectiveMemoryMB) {
+        console.warn(`[openclaw] ${instanceId}: MemoryMaxMB (${effectiveMemoryMaxMB}) is below MemoryMB (${effectiveMemoryMB}); clamping.`);
+        effectiveMemoryMaxMB = effectiveMemoryMB;
+    }
+    return {
+        ...resources,
+        MemoryMB: effectiveMemoryMB,
+        MemoryMaxMB: effectiveMemoryMaxMB,
+    };
+}
+// ── Nomad template safety (migrated from nomad-manager.ts) ────────────
+const NOMAD_TEMPLATE_UNSAFE_RE = /[{}"\\]/;
+function assertSafeTemplateId(id) {
+    if (NOMAD_TEMPLATE_UNSAFE_RE.test(id)) {
+        throw new Error(`Job ID "${id}" contains characters unsafe for Nomad Template interpolation`);
+    }
+}
+// ── Lazy-imported framework helpers (avoid circular deps) ─────────────
+//
+// The adapter reaches back into instance-manager.ts for helpers that still
+// live there. Using lazy `await import()` keeps the static import graph
+// acyclic, so runtime/index.ts → adapters/openclaw.ts loads cleanly before
+// instance-manager.ts needs it.
+async function lazyIm() {
+    return await import("../../instance-manager.js");
+}
+// ── Docker image build helpers (physically migrated from setup-manager) ─
+//
+// All OpenClaw-specific docker image build knowledge lives here. setup-manager
+// only retains a thin dispatch wrapper so the public
+// `buildSlimOpenclawImage()` / `startBuildSlimOpenclawImage()` API remains
+// back-compatible for routes/setup.ts and the CLI installer.
+/** Base image used for the slim OpenClaw runtime image. */
+const DOCKER_BASE_IMAGE = "node:22-slim";
+/** Mirror list tried in order when docker.io is unreachable. */
+const DOCKER_BASE_MIRRORS = [
+    "node:22-slim",
+    "hub-mirror.c.163.com/library/node:22-slim",
+    "mirrors.tencent.com/library/node:22-slim",
+    "registry.cn-hangzhou.aliyuncs.com/library/node:22-slim",
+];
+/** 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.-]+)?$/;
+/**
+ * Pull DOCKER_BASE_IMAGE from mirrors if not already cached locally.
+ */
+async function ensureDockerBaseImage(invocation, task) {
+    try {
+        execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "inspect", DOCKER_BASE_IMAGE], {
+            timeout: 5000,
+            stdio: "ignore",
+        });
+        emitTask(task, { type: "log", message: `基础镜像已缓存: ${DOCKER_BASE_IMAGE}` });
+        return DOCKER_BASE_IMAGE;
+    }
+    catch {
+        /* not cached, fall through */
+    }
+    for (const mirror of DOCKER_BASE_MIRRORS) {
+        emitTask(task, { type: "log", message: `拉取基础镜像: ${mirror} ...` });
+        const result = await spawnWithTask(task, invocation.cmd, [...invocation.argsPrefix, "pull", mirror], { timeout: 300000 });
+        if (result.ok) {
+            if (mirror !== DOCKER_BASE_IMAGE) {
+                try {
+                    execFileSync(invocation.cmd, [...invocation.argsPrefix, "tag", mirror, DOCKER_BASE_IMAGE], { timeout: 10000 });
+                }
+                catch {
+                    /* tag failure is non-fatal */
+                }
+            }
+            emitTask(task, { type: "log", message: `基础镜像就绪: ${DOCKER_BASE_IMAGE}` });
+            return DOCKER_BASE_IMAGE;
+        }
+        emitTask(task, { type: "log", message: `  → ${mirror} 不可达，尝试下一个镜像源...` });
+    }
+    throw new Error(`无法获取基础镜像 ${DOCKER_BASE_IMAGE}。请检查网络或手动执行: docker pull ${DOCKER_BASE_MIRRORS[1]}`);
+}
+/**
+ * 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.
+ */
+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";
+}
+/**
+ * Read the OpenClaw version bundled at /app/ inside a Docker 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 "";
+}
+/**
+ * Add a pinned version alias for an image, then drop the mutable :latest /
+ * :slim tag. See original setup-manager commentary for details.
+ */
+function capturePinnedImageTag(invocation, targetTag, explicitVersion) {
+    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;
+    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 {
+        return targetTag;
+    }
+    if (/:(latest|slim)$/.test(targetTag)) {
+        try {
+            execFileSync(invocation.cmd, [...invocation.argsPrefix, "rmi", targetTag], { timeout: 10000, stdio: "ignore" });
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+    }
+    return pinnedTag;
+}
+/**
+ * Try docker pull, fall back to local `Dockerfile.openclaw-slim` build. This
+ * is the primary image-prep path used by every setup flow. Called from the
+ * adapter's `buildRuntimeImage()` method.
+ */
+async function pullOrBuildOpenclawImageWithTask(task, tag) {
+    const targetTag = tag || DEFAULT_OPENCLAW_DOCKER_IMAGE;
+    try {
+        const invocation = resolveDockerInvocation();
+        // Always attempt pull — when the image is already local and in sync
+        // with upstream, docker returns within seconds after a digest check.
+        // The "skip if image present" early exit was making "重新安装" feel
+        // like a no-op; explicit re-pull matches user intent better. On pull
+        // failure we still fall back to local build below.
+        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 };
+        }
+        console.log(`[openclaw] 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,
+            };
+        }
+        const openclawVersion = resolveOpenclawNpmVersion();
+        console.log(`[openclaw] building 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 {
+                /* best-effort */
+            }
+            emitTask(task, { type: "error", message: "Docker 镜像构建失败" });
+            task.status = "error";
+            return {
+                ok: false,
+                message: "Docker image build failed",
+                error: buildResult.output,
+                taskId: task.id,
+            };
+        }
+        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,
+        };
+    }
+}
+// ── OpenClawAdapter class ─────────────────────────────────────────────
+class OpenClawAdapter {
+    agentType = "openclaw";
+    displayName = "OpenClaw";
+    defaultCapabilities = DEFAULT_CAPABILITIES;
+    defaultGatewayPort = OPENCLAW_DEFAULT_GATEWAY_PORT;
+    manifest = {
+        agentType: "openclaw",
+        displayName: "OpenClaw",
+        description: "默认 runtime,支持克隆、飞书 / 企业微信插件",
+        defaultCapabilities: DEFAULT_CAPABILITIES,
+        requiresNomadDocker: false,
+        diskSpaceMB: 2048,
+    };
+    hooks = {
+        /**
+         * Full OpenClaw pre-start prelude — used to live inline in
+         * `nomad-manager.startInstance()` as an `if (!hermes) { ... }` branch
+         * (~80 lines). Framework code now calls this hook uniformly for every
+         * kind; Hermes provides a no-op and OpenClaw owns the full sequence:
+         *
+         *   1. Stop any legacy process-manager subprocess
+         *   2. Ensure `openclaw.json` exists + fix state-dir permissions
+         *   3. Docker-bridge: patch gateway.bind + jsproxy baseUrl
+         *   4. Seed `$HOME/.npm-global` for in-gateway "Update now"
+         *   5. Validate + image-inspect the Docker image; background-pull on miss
+         *   6. Write JSPROXY_API_KEY into Nomad Variables
+         *
+         * Throws on fatal errors. Framework catches and returns the structured
+         * result; a `taskId` property on the thrown error signals an async
+         * image pull in progress.
+         */
+        onBeforeStart: async ({ instanceId }) => {
+            // 1. Stop any legacy subprocess
+            try {
+                const { getLegacyStatus, stopInstance: stopLegacyInstance } = await import("../../process-manager.js");
+                const legacyStatus = await getLegacyStatus(instanceId);
+                if (legacyStatus.status === "running") {
+                    console.log(`[openclaw] Stopping legacy process for ${instanceId} (pid=${legacyStatus.pid}) before Nomad start`);
+                    await stopLegacyInstance(instanceId);
+                    await new Promise((r) => setTimeout(r, 2000));
+                }
+            }
+            catch {
+                /* process-manager may be absent; harmless */
+            }
+            // 2. Config path existence check + permissions — use local resolvers
+            //    instead of lazy importing back into instance-manager.
+            let configPath;
+            try {
+                configPath = openclawAdapter.resolveConfigPath(instanceId);
+            }
+            catch {
+                return; // bail gracefully for non-OpenClaw instances
+            }
+            if (!existsSync(configPath)) {
+                throw new Error("Config file not found");
+            }
+            if (getNomadDriver() === "docker") {
+                const stateDir = dirname(configPath);
+                ensureDirContainer(stateDir);
+                try {
+                    for (const entry of readdirSync(stateDir, { withFileTypes: true })) {
+                        if (entry.isDirectory()) {
+                            const sub = join(stateDir, entry.name);
+                            ensureDirContainer(sub);
+                            try {
+                                for (const child of readdirSync(sub, { withFileTypes: true })) {
+                                    if (child.isDirectory())
+                                        ensureDirContainer(join(sub, child.name));
+                                }
+                            }
+                            catch {
+                                /* ignore */
+                            }
+                        }
+                    }
+                }
+                catch {
+                    /* ignore */
+                }
+                if (existsSync(configPath))
+                    chmodSync(configPath, 0o644);
+                // 3. Docker bridge patches
+                patchDockerBridgeGatewayBind(configPath);
+                patchJsproxyBaseUrl(configPath);
+            }
+            // 4. npm update-seed — use local resolver
+            try {
+                const home = openclawAdapter.resolveAgentHome(instanceId);
+                if (home)
+                    ensureOpenclawUpdateSeed(home, instanceId);
+            }
+            catch {
+                /* best effort */
+            }
+            // 5. Docker image validation + background pull fallback
+            if (getNomadDriver() === "docker") {
+                const image = getOpenclawDockerImage();
+                if (!DOCKER_IMAGE_RE.test(image) || image.length > MAX_DOCKER_IMAGE_NAME_LEN) {
+                    throw new Error(`Invalid Docker image name: "${image}"`);
+                }
+                try {
+                    execFileSync("docker", ["image", "inspect", image], {
+                        timeout: 10000,
+                        stdio: "ignore",
+                    });
+                }
+                catch {
+                    console.log(`[openclaw] Docker image ${image} not found, starting background pull`);
+                    try {
+                        const result = openclawAdapter.startBuildRuntimeImage({ tag: image });
+                        const err = new Error(`Docker image ${image} not found. Pull started in background.`);
+                        err.building = true;
+                        err.taskId = result.taskId;
+                        throw err;
+                    }
+                    catch (e) {
+                        if (e?.building)
+                            throw e;
+                        throw new Error(`Docker image ${image} not available: ${e?.message ?? e}`);
+                    }
+                }
+            }
+            // 6. Write instance secrets to Nomad Variables
+            try {
+                const nomad = await import("../../nomad-manager.js");
+                if (typeof nomad.writeInstanceVariables === "function") {
+                    await nomad.writeInstanceVariables(instanceId);
+                }
+            }
+            catch (e) {
+                throw new Error(`Failed to store instance secrets in Nomad Variables: ${e?.message ?? e}`);
+            }
+        },
+        /**
+         * OpenClaw auto-installs IM channel plugins (feishu, weixin, etc.) when
+         * they're enabled in `openclaw.json`. That logic currently lives in
+         * `instance-manager.saveConfig()`; wiring it through this hook is a
+         * no-op during MVP because saveConfig still runs inline. The hook
+         * exists so the physical-migration follow-up PR can move the code into
+         * this file without touching framework code.
+         */
+        onConfigSaved: async (_args) => {
+            /* reserved — channel plugin install hook, filled by follow-up PR */
+        },
+        /**
+         * Surface an orphan-directory warning when the legacy `openclaw_home`
+         * field points outside the instance dir. The framework's deleteInstance
+         * only rm's the instance dir itself, so custom-home layouts leave a
+         * tree that the operator must clean up manually.
+         */
+        onDelete: async ({ instanceId, meta }) => {
+            const home = typeof meta?.openclaw_home === "string" ? meta.openclaw_home : null;
+            if (!home)
+                return;
+            const instDir = framework_instanceDir(instanceId);
+            if (home.startsWith(instDir))
+                return; // inside the instance dir — rm already caught it
+            if (!existsSync(home))
+                return;
+            return {
+                warnings: [
+                    `Custom openclaw_home '${home}' was preserved. Delete manually if no longer needed.`,
+                ],
+            };
+        },
+        /**
+         * Rewrite `openclaw.json` x-jishushell.proxy.upstream when the panel
+         * default provider changes. Delegates to instance-manager's existing
+         * helper so the transition stays stepwise.
+         */
+        onUpstreamProviderChange: async ({ instanceId, upstream }) => {
+            try {
+                const im = await lazyIm();
+                if (typeof im.pushUpstreamToInstance === "function") {
+                    await im.pushUpstreamToInstance(instanceId, upstream);
+                }
+            }
+            catch (e) {
+                console.warn(`[openclaw] onUpstreamProviderChange failed for ${instanceId}: ${e.message}`);
+            }
+        },
+    };
+    /**
+     * Full OpenClaw instance bootstrap, physically migrated from the legacy
+     * `instance-manager.createInstance()` (~270 lines). Framework code now
+     * calls this uniformly via `getAdapter(agentType).createInstance(args)` —
+     * instance-manager no longer owns any OpenClaw business logic.
+     *
+     * Responsibilities:
+     *   1. openclaw_home path validation (traversal + symlink safety)
+     *   2. Gateway port allocation + runtime spec generation
+     *   3. clone_from handling (extensions/workspace/memory/sessions copy)
+     *   4. starter config seeding + default-provider API key injection
+     *   5. AppSpec overlays (config_defaults / skills)
+     *   6. Proxy bootstrap token generation via LLM proxy
+     *   7. chown to service user when running as root
+     */
+    async createInstance(args) {
+        const { instanceId, name, description = "", cloneFrom, agentHome: openclawHomeArg, appSpec, cloneOptions, } = args;
+        // Guard: prevent creating an OpenClaw instance when the runtime isn't
+        // installed. Without this, the instance.json gets written but the first
+        // `service/start` fails with an opaque `npm package not found` or
+        // `docker image missing` error. The Setup wizard treats "any runtime
+        // ready" as overall ready, so the Hermes-only case reaches here.
+        // getInstallStatus() is best-effort: if config exports are unavailable
+        // (e.g. partially mocked in test environments) the check is skipped so
+        // tests that do not mock the install state continue to work unchanged.
+        // The e2e-real suite spawns a real CLI on hosts that intentionally do
+        // not have OpenClaw installed; NODE_ENV=test (set by the e2e helper)
+        // is the explicit opt-out so the gate doesn't break instance-lifecycle
+        // tests.
+        try {
+            const hasAppManagedRuntime = Boolean(appSpec?.tasks?.some((task) => (task.role ?? "service") === "service" && (task.command || task.image)));
+            if (!hasAppManagedRuntime && process.env.NODE_ENV !== "test") {
+                const installStatus = this.getInstallStatus();
+                if (!installStatus.installed) {
+                    throw new Error("OpenClaw runtime is not installed. Install it from the Apps page " +
+                        "or run `jishushell install openclaw`, then retry.");
+                }
+            }
+        }
+        catch (err) {
+            // Re-throw only our own install-gate error; absorb config-unavailable
+            // errors that arise in partially mocked test environments.
+            if (err?.message?.startsWith("OpenClaw runtime is not installed"))
+                throw err;
+        }
+        const d = framework_instanceDir(instanceId);
+        const metaPath = instanceMetaPath(instanceId);
+        if (existsSync(metaPath))
+            throw new Error(`Instance '${instanceId}' already exists`);
+        if (existsSync(d) && !isPrecreatedManagedAppDir(d)) {
+            throw new Error(`Instance '${instanceId}' already exists`);
+        }
+        const home = openclawHomeArg
+            ? normalizePath(openclawHomeArg)
+            : defaultOpenclawHome(instanceId);
+        // Restrict openclaw_home to be under JISHUSHELL_HOME or /home to prevent
+        // path traversal. Use realpathSync after mkdir to resolve symlinks.
+        if (openclawHomeArg) {
+            const resolved = pathResolve(home);
+            if (!resolved.startsWith(JISHUSHELL_HOME) && !resolved.startsWith("/home/")) {
+                throw new Error(`openclaw_home must be under ${JISHUSHELL_HOME} or /home/`);
+            }
+            const parentDir = dirname(resolved);
+            if (existsSync(parentDir)) {
+                const realParent = realpathSync(parentDir);
+                if (!realParent.startsWith(JISHUSHELL_HOME) && !realParent.startsWith("/home/")) {
+                    throw new Error(`openclaw_home parent resolves outside allowed paths (symlink detected)`);
+                }
+            }
+            const shared = listInstances().filter((inst) => normalizePath(inst.openclaw_home || defaultOpenclawHome(inst.id)) ===
+                normalizePath(home));
+            if (shared.length) {
+                throw new Error(`OpenClaw home '${home}' is already used by instance(s): ${shared
+                    .map((i) => i.id)
+                    .join(", ")}`);
+            }
+        }
+        // Orphaned openclaw_home (e.g. instance.json deleted but data remains).
+        if (existsSync(home)) {
+            try {
+                const entries = readdirSync(home);
+                if (entries.length > 0) {
+                    throw new Error(`OpenClaw home directory '${home}' already exists and is not empty. ` +
+                        `Remove it manually or choose a different path.`);
+                }
+            }
+            catch (e) {
+                if (e.message.includes("not empty"))
+                    throw e;
+            }
+        }
+        ensureDirContainer(d);
+        try {
+            const parentGid = statSync(dirname(d)).gid;
+            chownSync(d, -1, parentGid);
+        }
+        catch {
+            /* non-root without CAP_CHOWN */
+        }
+        ensureDirContainer(home);
+        ensureDirContainer(join(home, OPENCLAW_STATE_DIRNAME));
+        const portAlloc = await allocateGatewayPort(instanceId, OPENCLAW_DEFAULT_GATEWAY_PORT);
+        const baseRuntime = buildDefaultRuntime(instanceId, portAlloc.port, home);
+        let runtime = baseRuntime;
+        if (appSpec) {
+            const serviceTask = appSpec.tasks.find((t) => t.role === "service");
+            if (serviceTask) {
+                const compiled = compileTaskRuntime(serviceTask, instanceId);
+                runtime = { ...baseRuntime, ...compiled };
+            }
+        }
+        const allocatedPort = extractGatewayPort(runtime);
+        try {
+            const meta = {
+                id: instanceId,
+                name,
+                description,
+                agentType: "openclaw",
+                openclaw_home: home,
+                runtime,
+                created_at: new Date().toISOString(),
+                // Prefer appSpec.app_id (installed unique id set by routes/apps.ts:88-96)
+                // over appSpec.id (which materializeInstalledSpec preserves as the base id).
+                // Multi-instance / copied apps need the installed id so uninstall /
+                // capability rebuild / skills metadata find the right installed entry.
+                ...(appSpec ? { app_id: appSpec.app_id ?? appSpec.id } : {}),
+            };
+            safeWriteJson(instanceMetaPath(instanceId), meta);
+            const envFiles = (runtime.env_files || []).map((p) => normalizePath(p));
+            for (const ef of envFiles) {
+                if (!existsSync(ef))
+                    writeConfigFile(ef, "");
+            }
+            // After writing env files, ensure the runtime user can read them
+            try {
+                const runtimeUser = runtime.user;
+                if (runtimeUser && runtimeUser !== userInfo().username) {
+                    for (const ef of envFiles) {
+                        execFileSync("chown", [runtimeUser, ef], { timeout: 5000 });
+                    }
+                }
+            }
+            catch {
+                /* ignore - same user or no permission to chown */
+            }
+            const configPath = openclawConfigPath(instanceId, home);
+            ensureDirContainer(dirname(configPath));
+            if (cloneFrom && !existsSync(configPath)) {
+                const srcConfig = resolveExistingConfigPath(cloneFrom);
+                if (existsSync(srcConfig)) {
+                    try {
+                        const cloned = JSON.parse(readFileSync(srcConfig, "utf-8"));
+                        // Remove proxy provider (will be regenerated with new token)
+                        const providers = cloned?.models?.providers;
+                        if (providers) {
+                            for (const [pid, prov] of Object.entries(providers)) {
+                                if (typeof prov?.baseUrl === "string" &&
+                                    prov.baseUrl.includes("/proxy/")) {
+                                    delete providers[pid];
+                                }
+                            }
+                        }
+                        // Remove proxy model reference from agent defaults
+                        const defaultModel = cloned?.agents?.defaults?.model;
+                        if (typeof defaultModel === "string" &&
+                            (defaultModel.startsWith("jsproxy/") || defaultModel.startsWith("js-"))) {
+                            delete cloned.agents.defaults.model;
+                        }
+                        // Strip IM channel configs + matching plugin entries
+                        stripImBindings(cloned);
+                        // Copy extensions, workspace, (optionally) memory + sessions
+                        const subdirs = ["extensions", "workspace"];
+                        if (cloneOptions?.include_memory !== false) {
+                            const memDir = join(dirname(srcConfig), "memory");
+                            if (existsSync(memDir))
+                                subdirs.push("memory");
+                        }
+                        if (cloneOptions?.include_sessions) {
+                            const sessDir = join(dirname(srcConfig), "agents");
+                            if (existsSync(sessDir))
+                                subdirs.push("agents");
+                        }
+                        for (const subdir of subdirs) {
+                            const srcDir = join(dirname(srcConfig), subdir);
+                            const dstDir = join(dirname(configPath), subdir);
+                            if (existsSync(srcDir) && !existsSync(dstDir)) {
+                                try {
+                                    cpSync(srcDir, dstDir, { recursive: true });
+                                }
+                                catch {
+                                    /* best effort */
+                                }
+                            }
+                        }
+                        writeConfigFile(configPath, JSON.stringify(cloned, null, 2));
+                        // Copy x-jishushell upstream metadata from source instance.json
+                        const srcMetaPath = join(framework_instanceDir(cloneFrom), "instance.json");
+                        if (existsSync(srcMetaPath)) {
+                            try {
+                                const srcMeta = JSON.parse(readFileSync(srcMetaPath, "utf-8"));
+                                const srcXj = srcMeta?.["x-jishushell"];
+                                if (srcXj?.proxy?.upstream) {
+                                    const dstXj = { proxy: { upstream: srcXj.proxy.upstream } };
+                                    delete dstXj.proxy.upstream.apiKey;
+                                    const metaPath = instanceMetaPath(instanceId);
+                                    if (existsSync(metaPath)) {
+                                        const dstMeta = JSON.parse(readFileSync(metaPath, "utf-8"));
+                                        dstMeta["x-jishushell"] = dstXj;
+                                        writeConfigFile(metaPath, JSON.stringify(dstMeta, null, 2));
+                                    }
+                                }
+                            }
+                            catch {
+                                /* ignore metadata copy errors */
+                            }
+                        }
+                    }
+                    catch {
+                        copyFileSync(srcConfig, configPath);
+                    }
+                }
+            }
+            if (!existsSync(configPath)) {
+                writeConfigFile(configPath, JSON.stringify(starterConfig(), null, 2));
+                // Inject default provider API key from setup into both env files
+                const dp = getPanelConfig().default_provider;
+                if (dp?.apiKey && dp?.providerId && envFiles.length) {
+                    const envKey = inferProviderApiKeyEnvName(dp.providerId);
+                    updateEnvFile(envFiles[0], { [envKey]: dp.apiKey });
+                    const providerEnv = join(dirname(envFiles[0]), "provider.env");
+                    updateEnvFile(providerEnv, { UPSTREAM_API_KEY: dp.apiKey });
+                }
+            }
+            // Merge AppSpec runtime overlays into openclaw.json (shallow, app wins).
+            // Prefers the plan §17 shape `runtime.defaults`; falls back to the
+            // legacy `openclaw.config_defaults` namespace for pre-§17 specs.
+            const runtimeOverlay = appSpec?.runtime ??
+                appSpec?.openclaw;
+            const overlayDefaults = runtimeOverlay?.defaults
+                ?? runtimeOverlay?.config_defaults;
+            if (overlayDefaults && existsSync(configPath)) {
+                try {
+                    const existing = JSON.parse(readFileSync(configPath, "utf-8"));
+                    const defaults = overlayDefaults;
+                    for (const [key, value] of Object.entries(defaults)) {
+                        if (typeof value === "object" &&
+                            value !== null &&
+                            !Array.isArray(value) &&
+                            typeof existing[key] === "object" &&
+                            existing[key] !== null) {
+                            existing[key] = { ...existing[key], ...value };
+                        }
+                        else {
+                            existing[key] = value;
+                        }
+                    }
+                    writeConfigFile(configPath, JSON.stringify(existing, null, 2));
+                }
+                catch {
+                    /* ignore merge errors */
+                }
+            }
+            // Record App-level skills for later installation. Prefers the new
+            // `runtime.skills` namespace; falls back to `openclaw.skills` for
+            // pre-§17 specs.
+            const overlaySkills = Array.isArray(runtimeOverlay?.skills)
+                ? runtimeOverlay.skills
+                : null;
+            if (overlaySkills) {
+                try {
+                    const skillsDir = join(dirname(configPath), "skills");
+                    ensureDirContainer(skillsDir);
+                    const skillMeta = join(skillsDir, ".app-skills.json");
+                    safeWriteJson(skillMeta, {
+                        app_id: appSpec.app_id ?? appSpec.id,
+                        skills: overlaySkills,
+                    });
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            // Copy cloned provider.env BEFORE proxy bootstrap
+            if (cloneFrom && envFiles.length) {
+                const srcEnvFiles = getRuntimeEnvFiles(cloneFrom);
+                const srcEnvFile = srcEnvFiles[0];
+                const dstEnvFile = envFiles[0];
+                if (srcEnvFile) {
+                    const srcProvider = join(dirname(srcEnvFile), "provider.env");
+                    const dstProvider = join(dirname(dstEnvFile), "provider.env");
+                    if (existsSync(srcProvider) && !existsSync(dstProvider)) {
+                        copyFileSync(srcProvider, dstProvider);
+                    }
+                }
+            }
+            // Bootstrap proxy: generate proxy token and write model.env
+            try {
+                await bootstrapInstanceProxy(instanceId);
+            }
+            catch (e) {
+                console.warn(`[openclaw] Proxy bootstrap for ${instanceId} deferred: ${e.message}`);
+            }
+            // If running as root, hand ownership of all created files to service user
+            const svcUser = resolveServiceUser();
+            if (svcUser) {
+                try {
+                    execFileSync("chown", ["-R", `${svcUser.uid}:${svcUser.gid}`, d], {
+                        timeout: 10_000,
+                    });
+                    if (!home.startsWith(d + "/") && existsSync(home)) {
+                        execFileSync("chown", ["-R", `${svcUser.uid}:${svcUser.gid}`, home], {
+                            timeout: 10_000,
+                        });
+                    }
+                }
+                catch (e) {
+                    console.warn(`[openclaw] chown for ${instanceId} failed:`, e.message);
+                }
+            }
+            if (portAlloc.skipped.length > 0) {
+                meta.port_allocation = {
+                    assigned: portAlloc.port,
+                    requested: OPENCLAW_DEFAULT_GATEWAY_PORT,
+                    reason: "default_busy",
+                    skipped: portAlloc.skipped,
+                };
+            }
+            return meta;
+        }
+        finally {
+            if (allocatedPort)
+                releasePendingPort(allocatedPort);
+        }
+    }
+    async createInitialLayout(ctx) {
+        // Framework never calls this on OpenClaw directly — `createInstance()`
+        // above does the full layout. Kept to satisfy the interface for path
+        // preview / UI callers.
+        const instDir = framework_instanceDir(ctx.instanceId);
+        const agentHome = defaultOpenclawHome(ctx.instanceId);
+        return {
+            instanceDir: instDir,
+            agentHome,
+            primaryConfig: join(agentHome, OPENCLAW_STATE_DIRNAME, OPENCLAW_CONFIG_FILENAME),
+        };
+    }
+    async buildRuntime(instanceId) {
+        // OpenClaw persists its runtime in legacy snake_case shape
+        // ({env_files, resources, ...}). Translate at read time into the
+        // engine-neutral RuntimeSpec contract.
+        const im = await lazyIm();
+        const raw = im.getInstanceRuntime(instanceId);
+        const home = im.getOpenclawHome(instanceId);
+        return {
+            image: raw?.image ?? getOpenclawDockerImage(),
+            command: String(raw?.command || DEFAULT_COMMAND),
+            args: Array.isArray(raw?.args) ? raw.args.map(String) : [...DEFAULT_ARGS],
+            cwd: String(raw?.cwd || home || DEFAULT_CWD),
+            user: String(raw?.user || DEFAULT_USER),
+            env: { ...DEFAULT_ENV, ...(raw?.env || {}) },
+            envFiles: Array.isArray(raw?.env_files)
+                ? raw.env_files
+                : Array.isArray(raw?.envFiles)
+                    ? raw.envFiles
+                    : [],
+            resources: {
+                CPU: Number(raw?.resources?.CPU ?? DEFAULT_RESOURCES.CPU),
+                MemoryMB: Number(raw?.resources?.MemoryMB ?? DEFAULT_RESOURCES.MemoryMB),
+                MemoryMaxMB: raw?.resources?.MemoryMaxMB != null ? Number(raw.resources.MemoryMaxMB) : undefined,
+            },
+            ports: [
+                {
+                    name: "gateway",
+                    containerPort: im.getGatewayPort(instanceId),
+                    hostPort: im.getGatewayPort(instanceId),
+                    visibility: "external",
+                },
+            ],
+            volumes: [{ hostPath: home, containerPath: home, mode: "rw" }],
+            health: null,
+        };
+    }
+    async buildNomadTask(instanceId) {
+        // Physically moved from nomad-manager.buildTaskDocker. The adapter owns
+        // OpenClaw's Nomad task layout end-to-end so `nomad-manager.buildJob()`
+        // becomes a pure dispatcher.
+        const im = await lazyIm();
+        const rawRuntime = im.getInstanceRuntime(instanceId);
+        const openclawHome = im.getOpenclawHome(instanceId);
+        if (rawRuntime.user && !VALID_USER_RE.test(rawRuntime.user)) {
+            throw new Error(`Invalid runtime user: ${rawRuntime.user}`);
+        }
+        const image = rawRuntime.image || getOpenclawDockerImage();
+        const command = String(rawRuntime.command || DEFAULT_COMMAND);
+        const args = Array.isArray(rawRuntime.args)
+            ? rawRuntime.args.map(String)
+            : [...DEFAULT_ARGS];
+        const env = { ...DEFAULT_ENV };
+        Object.assign(env, im.getRuntimeEnv(instanceId));
+        delete env.JSPROXY_API_KEY; // supplied via Nomad Template from Variables
+        env.OPENCLAW_HOME = openclawHome;
+        env.OPENCLAW_INSTANCE_ID = instanceId;
+        // Resource clamping
+        const rawResources = { ...DEFAULT_RESOURCES };
+        for (const [k, v] of Object.entries(rawRuntime.resources || {})) {
+            if (v != null)
+                rawResources[k] = Number(v);
+        }
+        rawResources.CPU = Math.max(1, Math.min(rawResources.CPU, MAX_CPU_MHZ));
+        rawResources.MemoryMB = Math.max(1, Math.min(rawResources.MemoryMB, MAX_MEMORY_MB));
+        // Container env — OpenClaw-specific HOME / NODE_PATH / PATH / npm cfg
+        const containerEnv = { ...env };
+        containerEnv.HOME = openclawHome;
+        if (!containerEnv.OPENCLAW_STATE_DIR) {
+            containerEnv.OPENCLAW_STATE_DIR = `${openclawHome}/.openclaw`;
+        }
+        containerEnv.npm_config_prefix = `${openclawHome}/.npm-global`;
+        containerEnv.PIP_USER = "1";
+        containerEnv.PYTHONUSERBASE = `${openclawHome}/.local`;
+        containerEnv.NODE_ENV = "production";
+        containerEnv.NODE_PATH = [
+            `${openclawHome}/.npm-global/lib/node_modules`,
+            "/app/node_modules",
+        ].join(":");
+        containerEnv.PATH = [
+            `${openclawHome}/.npm-global/bin`,
+            `${openclawHome}/.local/bin`,
+            `${openclawHome}/go/bin`,
+            `${openclawHome}/.cargo/bin`,
+            "/usr/local/sbin",
+            "/usr/local/bin",
+            "/usr/sbin",
+            "/usr/bin",
+            "/sbin",
+            "/bin",
+        ].join(":");
+        const gatewayPort = im.getGatewayPort(instanceId);
+        const safeJobId = `${this.nomadJobPrefix}${instanceId}`;
+        assertSafeTemplateId(safeJobId);
+        const normalizedResources = normalizeDockerResources(instanceId, rawResources);
+        return {
+            Name: "gateway",
+            Driver: "docker",
+            User: resolveUidGid(String(rawRuntime.user || DEFAULT_USER)),
+            Config: {
+                image,
+                force_pull: false,
+                args,
+                work_dir: openclawHome,
+                volumes: [`${openclawHome}:${openclawHome}:rw`],
+                extra_hosts: ["host.docker.internal:host-gateway"],
+                cap_drop: ["ALL"],
+                security_opt: ["no-new-privileges"],
+                pids_limit: DEFAULT_PIDS_LIMIT,
+                readonly_rootfs: true,
+                mounts: [
+                    { type: "tmpfs", target: "/tmp", tmpfs_options: { size: 536870912 } },
+                    { type: "tmpfs", target: "/var/tmp", tmpfs_options: { size: 67108864 } },
+                    { type: "tmpfs", target: "/run", tmpfs_options: { size: 52428800 } },
+                ],
+            },
+            Env: containerEnv,
+            Resources: {
+                ...normalizedResources,
+                Networks: [{ ReservedPorts: [{ Label: "gateway", Value: gatewayPort }] }],
+            },
+            LogConfig: { MaxFiles: 3, MaxFileSizeMB: 10 },
+            Templates: [
+                {
+                    DestPath: "secrets/instance.env",
+                    Envvars: true,
+                    EmbeddedTmpl: [
+                        `{{ if nomadVarExists "nomad/jobs/${safeJobId}/openclaw/gateway" }}`,
+                        `JSPROXY_API_KEY={{ with nomadVar "nomad/jobs/${safeJobId}/openclaw/gateway" }}{{ .JSPROXY_API_KEY }}{{ end }}`,
+                        `{{ end }}`,
+                    ].join("\n"),
+                    ChangeMode: "restart",
+                },
+            ],
+        };
+    }
+    async getRuntimeVersion(_instanceId) {
+        // Parse the image reference (digest > tag) for the baseline image.
+        const image = getOpenclawDockerImage() || "";
+        let ref;
+        let digest;
+        if (image) {
+            if (image.includes("@")) {
+                digest = image.split("@", 2)[1];
+            }
+            else {
+                const lastColon = image.lastIndexOf(":");
+                const lastSlash = image.lastIndexOf("/");
+                if (lastColon > lastSlash)
+                    ref = image.slice(lastColon + 1);
+            }
+        }
+        return { agentType: "openclaw", ref, digest, mode: "baseline" };
+    }
+    async getConfigMeta(instanceId) {
+        return {
+            agentType: "openclaw",
+            format: "json",
+            schemaId: "openclaw/v1",
+            capabilities: DEFAULT_CAPABILITIES,
+            secretFields: ["content.x-jishushell.proxy.upstream.apiKey"],
+            runtimeVersion: await this.getRuntimeVersion(instanceId),
+        };
+    }
+    async readConfig(instanceId) {
+        const im = await lazyIm();
+        const content = im.getStoredConfig
+            ? im.getStoredConfig(instanceId)
+            : null;
+        return {
+            format: "json",
+            content: (content && typeof content === "object") ? content : {},
+        };
+    }
+    async writeConfig(instanceId, doc) {
+        if (doc.format !== "json") {
+            throw new Error(`OpenClaw config requires format="json", got "${doc.format}"`);
+        }
+        // Route through llmProxy.saveInstanceConfig so x-jishushell.proxy
+        // metadata is stripped, the upstream apiKey is AES-encrypted to
+        // provider.env, and models.providers is rewritten to the local
+        // proxy — same contract HermesAdapter.writeConfig uses. That
+        // function internally calls instanceManager.saveConfig, which
+        // dispatches back to this adapter's saveNativeConfig() for the
+        // raw disk write (distinct method, no recursion).
+        const { saveInstanceConfig } = await import("../../llm-proxy/index.js");
+        await saveInstanceConfig(instanceId, doc.content);
+        return this.readConfig(instanceId);
+    }
+    async buildPairingListCommand(_instanceId) {
+        return ["openclaw", "pairing", "list"];
+    }
+    async buildPairingApproveCommand(_instanceId, input) {
+        return ["openclaw", "pairing", "approve", input.channel, input.code];
+    }
+    /**
+     * Framework delete hook — returns warnings for the caller to surface to
+     * the user. OpenClaw supports a custom `openclaw_home` pointing outside
+     * the instance directory; those directories are preserved on delete.
+     */
+    async onDelete(args) {
+        const warnings = [];
+        const home = args.meta?.openclaw_home;
+        if (home) {
+            warnings.push(`Custom openclaw_home "${home}" was NOT removed; delete it manually if unused.`);
+        }
+        return warnings;
+    }
+    // ── Native config I/O (physically migrated from instance-manager) ───
+    channelPluginMap = CHANNEL_PLUGIN_MAP;
+    /**
+     * Get the stored raw OpenClaw config (from `.openclaw/openclaw.json`
+     * or the legacy `openclaw.json`), merged with the x-jishushell
+     * metadata pulled from `instance.json`. Returns null when the instance
+     * has no persisted config yet.
+     */
+    getNativeConfig(instanceId) {
+        const config = loadEffectiveConfig(instanceId);
+        if (!config)
+            return null;
+        // Always merge the latest upstream proxy config from instance.json
+        const meta = getInstance(instanceId);
+        if (meta?.["x-jishushell"]) {
+            config["x-jishushell"] = meta["x-jishushell"];
+        }
+        // Inject upstream provider apiKey from env file so callers see it
+        return injectProviderApiKeys(instanceId, config);
+    }
+    /**
+     * Get the stored raw config WITHOUT provider key injection. Used by
+     * callers that round-trip the config back to disk (e.g. credential
+     * writers) — injecting the provider key would re-persist it to the
+     * config file, which is exactly what `saveConfig` takes pains to avoid.
+     */
+    getStoredNativeConfig(instanceId) {
+        const config = loadEffectiveConfig(instanceId);
+        if (!config)
+            return null;
+        const meta = getInstance(instanceId);
+        if (meta?.["x-jishushell"]) {
+            config["x-jishushell"] = meta["x-jishushell"];
+        }
+        return config;
+    }
+    isChannelPluginInstalled(instanceId, channelId) {
+        return isChannelPluginInstalled(instanceId, channelId);
+    }
+    async installChannelPlugin(instanceId, channelId) {
+        return installChannelPlugin(instanceId, channelId);
+    }
+    saveNativeConfig(instanceId, config) {
+        return saveNativeConfigImpl(instanceId, config);
+    }
+    // ── Path resolvers (physically migrated) ───────────────────────────
+    resolveBin() {
+        return resolveOpenclawBin();
+    }
+    resolveAgentHome(instanceId) {
+        const meta = getInstance(instanceId);
+        return meta?.openclaw_home || defaultOpenclawHome(instanceId);
+    }
+    /** Env vars OpenClaw's CLI needs when backup-manager runs it as a subprocess. */
+    buildCliEnv(instanceId) {
+        return { OPENCLAW_HOME: this.resolveAgentHome(instanceId) };
+    }
+    /**
+     * Legacy gateway-port fallback for instances created before the
+     * RuntimeSpec.ports[] migration. OpenClaw persists its port in both
+     * `runtime.env.OPENCLAW_GATEWAY_PORT` and `runtime.args ["--port", N]`.
+     */
+    readLegacyGatewayPort(runtime) {
+        if (!runtime)
+            return null;
+        const envPort = runtime.env?.OPENCLAW_GATEWAY_PORT;
+        if (envPort) {
+            const p = parseInt(envPort, 10);
+            if (!isNaN(p))
+                return p;
+        }
+        const args = runtime.args || [];
+        for (let i = 0; i < args.length; i++) {
+            const arg = String(args[i]);
+            if (arg === "--port" && i + 1 < args.length) {
+                const p = parseInt(args[i + 1], 10);
+                return isNaN(p) ? null : p;
+            }
+            if (arg.startsWith("--port=")) {
+                const p = parseInt(arg.split("=")[1], 10);
+                return isNaN(p) ? null : p;
+            }
+        }
+        return null;
+    }
+    /**
+     * Rewrite a persisted OpenClaw runtime spec to use a new host port.
+     * Updates `args[--port]` + `env.OPENCLAW_GATEWAY_PORT` atomically so
+     * both places stay in sync.
+     */
+    reallocateRuntimePort(runtime, newPort) {
+        const args = Array.isArray(runtime.args) ? [...runtime.args] : [];
+        for (let i = 0; i < args.length; i++) {
+            if (args[i] === "--port" && i + 1 < args.length) {
+                args[i + 1] = String(newPort);
+            }
+            else if (typeof args[i] === "string" && args[i].startsWith("--port=")) {
+                args[i] = `--port=${newPort}`;
+            }
+        }
+        runtime.args = args;
+        const env = (runtime.env ?? {});
+        env.OPENCLAW_GATEWAY_PORT = String(newPort);
+        runtime.env = env;
+    }
+    nomadJobPrefix = "openclaw-";
+    // OpenClaw is the default/core runtime — runFullSetup must fail hard if
+    // its image install fails, because the panel is unusable without it.
+    // Third-party adapters should leave `required` unset (= optional).
+    required = true;
+    // Must match the path referenced by this adapter's buildNomadTask Templates
+    // (see `nomadVar "nomad/jobs/<jid>/openclaw/gateway"` in the template body).
+    nomadVariablePath = "openclaw/gateway";
+    resolveConfigPath(instanceId) {
+        return openclawConfigPath(instanceId, this.resolveAgentHome(instanceId));
+    }
+    resolveLegacyConfigPath(instanceId) {
+        return legacyOpenclawConfigPath(instanceId, this.resolveAgentHome(instanceId));
+    }
+    /**
+     * Return other OpenClaw instance IDs that share this one's
+     * `openclaw_home` path. Used by the start-time conflict check.
+     */
+    findInstancesSharingHome(instanceId) {
+        const target = normalizePath(this.resolveAgentHome(instanceId));
+        return listInstances()
+            .filter((inst) => inst.id !== instanceId)
+            .filter((inst) => {
+            const meta = inst;
+            const otherHome = meta.openclaw_home || defaultOpenclawHome(inst.id);
+            return normalizePath(otherHome) === target;
+        })
+            .map((inst) => inst.id);
+    }
+    // ── Feishu / WeChat credential writers (physically migrated) ───────
+    saveFeishuCredentials(instanceId, creds) {
+        if (!FEISHU_APP_ID_RE.test(creds.appId)) {
+            throw new Error(`Invalid Feishu appId format: expected cli_<alnum> (got "${creds.appId}")`);
+        }
+        if (!creds.appSecret || typeof creds.appSecret !== "string" || creds.appSecret.length < 4) {
+            throw new Error("Invalid Feishu appSecret: must be a non-empty string");
+        }
+        const configPath = this.resolveConfigPath(instanceId);
+        let config = {};
+        try {
+            if (existsSync(configPath)) {
+                config = JSON.parse(readFileSync(configPath, "utf-8"));
+            }
+        }
+        catch {
+            /* best effort */
+        }
+        config.plugins ??= {};
+        config.plugins.entries ??= {};
+        config.plugins.entries.feishu = { enabled: false };
+        config.plugins.entries["openclaw-lark"] = { enabled: true };
+        config.channels ??= {};
+        config.channels.feishu = {
+            ...config.channels.feishu,
+            enabled: true,
+            appId: creds.appId,
+            appSecret: creds.appSecret,
+            domain: creds.domain,
+            dmPolicy: "open",
+            allowFrom: ["*"],
+        };
+        safeWriteJson(configPath, config);
+        chownToServiceUser(configPath);
+        console.log(`[openclaw] Feishu credentials saved for ${instanceId}, domain=${creds.domain}`);
+    }
+    saveWeixinCredentials(instanceId, creds) {
+        if (!creds.accountId || !SAFE_ACCOUNT_ID_RE.test(creds.accountId) || creds.accountId.includes("..")) {
+            throw new Error(`Invalid accountId: must be 1-128 chars of [a-zA-Z0-9@._-] without '..'`);
+        }
+        const home = this.resolveAgentHome(instanceId);
+        const stateDir = join(home, OPENCLAW_STATE_DIRNAME, "openclaw-weixin");
+        const accountsDir = join(stateDir, "accounts");
+        ensureDirContainer(accountsDir);
+        const credObj = {
+            token: creds.token,
+            baseUrl: creds.baseUrl,
+            userId: creds.userId,
+            savedAt: new Date().toISOString(),
+        };
+        safeWriteJson(join(accountsDir, `${creds.accountId}.json`), credObj);
+        safeWriteJson(join(accountsDir, "default.json"), credObj);
+        chownToServiceUser(join(accountsDir, `${creds.accountId}.json`), join(accountsDir, "default.json"));
+        // Update accounts.json index
+        const indexPath = join(stateDir, "accounts.json");
+        let index = [];
+        try {
+            const raw = readFileSync(indexPath, "utf-8");
+            index = JSON.parse(raw);
+        }
+        catch {
+            /* start fresh */
+        }
+        if (!Array.isArray(index))
+            index = [];
+        if (!index.includes(creds.accountId))
+            index.push(creds.accountId);
+        safeWriteJson(indexPath, index);
+        const configPath = this.resolveConfigPath(instanceId);
+        let config = {};
+        try {
+            if (existsSync(configPath))
+                config = JSON.parse(readFileSync(configPath, "utf-8"));
+        }
+        catch {
+            /* best effort */
+        }
+        config.plugins ??= {};
+        config.plugins.entries ??= {};
+        config.plugins.entries["openclaw-weixin"] ??= {};
+        config.plugins.entries["openclaw-weixin"].enabled = true;
+        config.channels ??= {};
+        config.channels["openclaw-weixin"] ??= {};
+        config.channels["openclaw-weixin"].enabled = true;
+        const normalizedId = creds.accountId.replace(/[@.]/g, "-");
+        const accounts = config.channels["openclaw-weixin"].accounts ??= {};
+        accounts[creds.accountId] = { enabled: true };
+        if (normalizedId !== creds.accountId)
+            accounts[normalizedId] = { enabled: true };
+        accounts["default"] = { enabled: true };
+        if (!config.channels["openclaw-weixin"].defaultAccount) {
+            config.channels["openclaw-weixin"].defaultAccount = "default";
+        }
+        safeWriteJson(configPath, config);
+        chownToServiceUser(configPath);
+        console.log(`[openclaw] WeChat credentials saved for ${instanceId}, account=${creds.accountId}`);
+    }
+    getWeixinAccounts(instanceId) {
+        const home = this.resolveAgentHome(instanceId);
+        const stateDir = join(home, OPENCLAW_STATE_DIRNAME, "openclaw-weixin");
+        const accountsDir = join(stateDir, "accounts");
+        if (!existsSync(accountsDir))
+            return [];
+        let indexedIds = [];
+        try {
+            indexedIds = JSON.parse(readFileSync(join(stateDir, "accounts.json"), "utf-8"));
+        }
+        catch {
+            /* fallback to scanning */
+        }
+        const results = [];
+        for (const f of readdirSync(accountsDir)) {
+            if (!f.endsWith(".json"))
+                continue;
+            const id = f.replace(/\.json$/, "");
+            if (indexedIds.length > 0 && !indexedIds.includes(id))
+                continue;
+            if (id === "default")
+                continue;
+            try {
+                const data = JSON.parse(readFileSync(join(accountsDir, f), "utf-8"));
+                results.push({
+                    accountId: id,
+                    userId: data.userId,
+                    savedAt: data.savedAt,
+                });
+            }
+            catch {
+                /* skip */
+            }
+        }
+        return results;
+    }
+    // ── §32.2.4 runtime install (physically migrated from setup-manager) ──
+    //
+    // Installs the OpenClaw npm package via `npm install -g --prefix` so that
+    // postinstall scripts run naturally. Emits SSE progress through the task
+    // machinery exported by setup-manager.
+    async installRuntime(opts) {
+        const version = opts?.version ?? "latest";
+        try {
+            const openclawPkgDir = join(OPENCLAW_MODULES, "openclaw");
+            if (existsSync(openclawPkgDir)) {
+                const ver = readInstalledOpenclawVersion() || "unknown";
+                return { ok: true, message: `OpenClaw already installed: ${ver}` };
+            }
+            const task = createTask("openclaw");
+            ensureDirHost(OPENCLAW_PKG_DIR);
+            emitTask(task, { type: "progress", message: "开始安装 OpenClaw...", progress: 0 });
+            const sizeTracker = setInterval(() => {
+                const sizeMB = getDirSizeMB(OPENCLAW_PKG_DIR);
+                const pct = Math.min(95, Math.round((sizeMB / OPENCLAW_EXPECTED_SIZE_MB) * 95));
+                if (pct > 0) {
+                    emitTask(task, {
+                        type: "progress",
+                        message: `下载安装中... ${sizeMB}MB / ~${OPENCLAW_EXPECTED_SIZE_MB}MB`,
+                        progress: pct,
+                    });
+                }
+            }, 3000);
+            const result = await spawnWithTask(task, "npm", ["install", "-g", "--prefix", OPENCLAW_PKG_DIR, `openclaw@${version}`], { timeout: 600000, progressParser: npmProgressParser });
+            clearInterval(sizeTracker);
+            if (!result.ok) {
+                emitTask(task, { type: "error", message: "OpenClaw 安装失败" });
+                task.status = "error";
+                return {
+                    ok: false,
+                    message: "OpenClaw installation failed",
+                    error: result.output,
+                    taskId: task.id,
+                };
+            }
+            const ver = readInstalledOpenclawVersion() || "installed";
+            emitTask(task, { type: "done", message: `OpenClaw 安装完成: ${ver}`, progress: 100 });
+            task.status = "done";
+            return { ok: true, message: `OpenClaw installed: ${ver}`, taskId: task.id };
+        }
+        catch (e) {
+            return { ok: false, message: "OpenClaw installation failed", error: e.message };
+        }
+    }
+    /**
+     * Build / pull the OpenClaw Docker image. Blocking — useful for CLI
+     * installer and `runFullSetup()`. Non-blocking variant below is used by
+     * the REST API and the adapter's own `onBeforeStart` self-heal path.
+     */
+    async buildRuntimeImage(opts) {
+        const task = createTask("openclaw-docker-pull");
+        return pullOrBuildOpenclawImageWithTask(task, opts?.tag);
+    }
+    /**
+     * Non-blocking variant of `buildRuntimeImage` — returns a task id
+     * immediately so the caller can poll SSE progress.
+     */
+    startBuildRuntimeImage(opts) {
+        const task = createTask("openclaw-docker-pull");
+        void pullOrBuildOpenclawImageWithTask(task, opts?.tag).catch((err) => {
+            emitTask(task, {
+                type: "error",
+                message: `镜像获取失败: ${err?.message || err}`,
+            });
+            task.status = "error";
+        });
+        return { ok: true, message: "Docker image pull started", taskId: task.id };
+    }
+    /**
+     * §32.2.5 — register OpenClaw-specific HTTP endpoints. Called from
+     * `routes/instances.ts` at server startup via the generic adapter
+     * dispatch loop.
+     */
+    registerRoutes(app) {
+        registerOpenclawRoutes(app);
+    }
+    /**
+     * Return OpenClaw's readiness for spawning instances. Docker image
+     * presence is the gating factor in the default docker-mode deployment;
+     * the legacy `npm install` path is still reported as `installed` but is
+     * not required for the docker-driver stack.
+     */
+    getInstallStatus() {
+        // OPENCLAW_MODULES may be undefined when config is partially mocked in tests.
+        const pkgInstalled = OPENCLAW_MODULES ? existsSync(join(OPENCLAW_MODULES, "openclaw")) : false;
+        const version = pkgInstalled ? readInstalledOpenclawVersion() : undefined;
+        const imageTag = getOpenclawDockerImage?.() ?? "";
+        let imageReady = false;
+        try {
+            const invocation = resolveDockerInvocation();
+            if (invocation?.cmd) {
+                execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "inspect", imageTag], {
+                    timeout: 5000,
+                    stdio: "ignore",
+                });
+                imageReady = true;
+            }
+        }
+        catch { /* image absent */ }
+        return {
+            installed: imageReady || pkgInstalled,
+            imageReady,
+            version: version || undefined,
+        };
+    }
+}
+// ── Install-time helpers (used by installRuntime) ─────────────────────
+const OPENCLAW_EXPECTED_SIZE_MB = 700;
+function readInstalledOpenclawVersion() {
+    try {
+        const pkg = join(OPENCLAW_MODULES, "openclaw", "package.json");
+        if (existsSync(pkg))
+            return JSON.parse(readFileSync(pkg, "utf-8")).version || "";
+    }
+    catch {
+        /* best effort */
+    }
+    return "";
+}
+// Feishu app IDs issued by the open platform follow `cli_<hex/alnum>`.
+const FEISHU_APP_ID_RE = /^cli_[a-zA-Z0-9]{8,64}$/;
+const SAFE_ACCOUNT_ID_RE = /^[a-zA-Z0-9@._-]{1,128}$/;
+// ── Channel plugin constants (physically migrated) ───────────────────
+const CHANNEL_EXT_DIR_ALIAS = {
+    feishu: "openclaw-lark",
+    lark: "openclaw-lark",
+};
+const CHANNEL_PLUGIN_MAP = {
+    feishu: "@larksuite/openclaw-lark",
+    lark: "@larksuite/openclaw-lark",
+    telegram: "@openclaw/telegram",
+    discord: "@openclaw/discord",
+    slack: "@openclaw/slack",
+    whatsapp: "@openclaw/whatsapp",
+    signal: "@openclaw/signal",
+    line: "@openclaw/line",
+    msteams: "@openclaw/msteams",
+    "openclaw-weixin": "@tencent-weixin/openclaw-weixin",
+};
+const IM_PLUGIN_ENTRY_IDS = new Set([
+    ...Object.keys(CHANNEL_PLUGIN_MAP),
+    ...Object.values(CHANNEL_EXT_DIR_ALIAS),
+]);
+// ── Config I/O helpers (physically migrated) ─────────────────────────
+function hasConfiguredValue(value) {
+    if (typeof value !== "string")
+        return !!value;
+    return value.trim().length > 0;
+}
+function loadJsonSafe(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (e) {
+        console.warn(`[openclaw] Failed to parse ${path}: ${e.message}`);
+        return null;
+    }
+}
+function deepMergeConfig(base, overlay) {
+    if (typeof base !== "object" || base === null ||
+        typeof overlay !== "object" || overlay === null ||
+        Array.isArray(base) || Array.isArray(overlay)) {
+        return structuredClone(overlay);
+    }
+    const merged = structuredClone(base);
+    for (const key of Object.keys(overlay)) {
+        merged[key] = key in merged ? deepMergeConfig(merged[key], overlay[key]) : structuredClone(overlay[key]);
+    }
+    return merged;
+}
+function loadEffectiveConfig(instanceId) {
+    const runtimePath = openclawConfigPath(instanceId);
+    const legacyPath = legacyOpenclawConfigPath(instanceId);
+    const rExists = existsSync(runtimePath);
+    const lExists = existsSync(legacyPath);
+    if (rExists && lExists) {
+        const legacy = loadJsonSafe(legacyPath);
+        const runtime = loadJsonSafe(runtimePath);
+        if (legacy && runtime)
+            return deepMergeConfig(legacy, runtime);
+        return runtime || legacy || null;
+    }
+    if (rExists)
+        return loadJsonSafe(runtimePath);
+    if (lExists)
+        return loadJsonSafe(legacyPath);
+    return null;
+}
+function injectProviderApiKeys(instanceId, config) {
+    const merged = structuredClone(config);
+    const runtimeEnv = getRuntimeEnv(instanceId);
+    const providers = merged.models?.providers || {};
+    for (const [providerId, provider] of Object.entries(providers)) {
+        if (typeof provider !== "object" || provider === null)
+            continue;
+        const p = provider;
+        const api = p.api;
+        if (typeof api === "string" && api in LEGACY_PROVIDER_API_ALIASES) {
+            p.api = LEGACY_PROVIDER_API_ALIASES[api];
+        }
+        const apiKey = runtimeEnv[inferProviderApiKeyEnvName(providerId)];
+        if (apiKey)
+            p.apiKey = apiKey;
+    }
+    return merged;
+}
+function applyFeishuDebugAccessDefaults(channel) {
+    if (channel.enabled === false)
+        return;
+    if (!hasConfiguredValue(channel.appId))
+        return;
+    if (!hasConfiguredValue(channel.appSecret))
+        return;
+    let dmPolicy = channel.dmPolicy;
+    if (typeof dmPolicy !== "string" || !dmPolicy.trim()) {
+        channel.dmPolicy = "open";
+        dmPolicy = "open";
+    }
+    if (dmPolicy !== "open")
+        return;
+    if (!("resolveSenderNames" in channel))
+        channel.resolveSenderNames = false;
+    let accounts = channel.accounts;
+    if (typeof accounts !== "object" || accounts === null) {
+        accounts = {};
+        channel.accounts = accounts;
+    }
+    let defaultAccount = accounts.default;
+    if (typeof defaultAccount !== "object" || defaultAccount === null) {
+        defaultAccount = {};
+        accounts.default = defaultAccount;
+    }
+    if (!("resolveSenderNames" in defaultAccount))
+        defaultAccount.resolveSenderNames = false;
+    const allowFrom = channel.allowFrom;
+    if (Array.isArray(allowFrom)) {
+        const normalized = allowFrom.map((e) => String(e).trim()).filter(Boolean);
+        if (!normalized.includes("*"))
+            normalized.push("*");
+        channel.allowFrom = normalized;
+        return;
+    }
+    channel.allowFrom = ["*"];
+}
+function prepareConfigForSave(instanceId, config) {
+    const configToWrite = structuredClone(config);
+    delete configToWrite["x-jishushell"];
+    const envUpdates = {};
+    const providers = configToWrite.models?.providers || {};
+    const envFiles = getRuntimeEnvFiles(instanceId);
+    const channels = configToWrite.channels || {};
+    const plugins = configToWrite.plugins ??= {};
+    const pluginEntries = plugins.entries ??= {};
+    for (const [providerId, provider] of Object.entries(providers)) {
+        if (typeof provider !== "object" || provider === null)
+            continue;
+        const p = provider;
+        if (typeof p.api === "string" && p.api in LEGACY_PROVIDER_API_ALIASES) {
+            p.api = LEGACY_PROVIDER_API_ALIASES[p.api];
+        }
+        if (!("apiKey" in p))
+            continue;
+        if (typeof p.baseUrl === "string" && p.baseUrl.includes("/proxy/"))
+            continue;
+        const apiKey = p.apiKey;
+        delete p.apiKey;
+        if (envFiles.length) {
+            envUpdates[inferProviderApiKeyEnvName(providerId)] = String(apiKey || "");
+        }
+        else {
+            p.apiKey = apiKey;
+        }
+    }
+    for (const [channelId, channel] of Object.entries(channels)) {
+        if (typeof channel !== "object" || channel === null)
+            continue;
+        const ch = channel;
+        if (channelId === "feishu" || channelId === "lark")
+            applyFeishuDebugAccessDefaults(ch);
+        let pluginEntry = pluginEntries[channelId];
+        if (pluginEntry == null) {
+            pluginEntry = {};
+            pluginEntries[channelId] = pluginEntry;
+        }
+        if (typeof pluginEntry === "object") {
+            pluginEntry.enabled = ch.enabled !== false;
+        }
+    }
+    return [configToWrite, envUpdates];
+}
+/**
+ * Dissociate a cloned/imported config from its source instance's IM bindings.
+ * Physically migrated from `instance-manager.stripImBindings` so framework
+ * code no longer references OpenClaw channel concepts.
+ *
+ * Exported so `OpenClawAdapter.createInstance`'s clone path + `backup-manager`
+ * import paths can use it without depending on instance-manager.
+ */
+export function stripImBindings(config) {
+    if (config?.channels)
+        delete config.channels;
+    const entries = config?.plugins?.entries;
+    if (entries && typeof entries === "object") {
+        for (const key of Object.keys(entries)) {
+            if (IM_PLUGIN_ENTRY_IDS.has(key))
+                delete entries[key];
+        }
+    }
+}
+function getChannelExtensionsDir(instanceId) {
+    const home = getInstance(instanceId)?.openclaw_home ||
+        defaultOpenclawHome(instanceId);
+    return join(home, OPENCLAW_STATE_DIRNAME, "extensions");
+}
+function getStockExtensionsDir() {
+    return join(JISHUSHELL_HOME, "packages", "openclaw", "lib", "node_modules", "openclaw", "extensions");
+}
+function isChannelPluginInstalled(instanceId, channelId) {
+    const extDirName = CHANNEL_EXT_DIR_ALIAS[channelId] || channelId;
+    const stockExtDir = getStockExtensionsDir();
+    return (existsSync(join(getChannelExtensionsDir(instanceId), extDirName)) ||
+        existsSync(join(stockExtDir, extDirName)) ||
+        (extDirName !== channelId && existsSync(join(stockExtDir, channelId))));
+}
+/**
+ * Install a single channel plugin. Docker mode → `docker exec` inside the
+ * running container. Host mode → spawn the host openclaw binary directly.
+ * Physically migrated from `instance-manager.installChannelPlugin`.
+ */
+async function installChannelPlugin(instanceId, channelId) {
+    const pkg = CHANNEL_PLUGIN_MAP[channelId];
+    if (!pkg)
+        throw new Error(`Unknown channel: ${channelId}`);
+    if (isChannelPluginInstalled(instanceId, channelId))
+        return;
+    const home = getInstance(instanceId)?.openclaw_home ||
+        defaultOpenclawHome(instanceId);
+    const extensionsDir = getChannelExtensionsDir(instanceId);
+    if (getNomadDriver() === "docker") {
+        await installChannelPluginViaDocker(instanceId, channelId, pkg, extensionsDir);
+        return;
+    }
+    const openclawBin = resolveOpenclawBin();
+    const nodeBinDir = dirname(process.execPath);
+    const childPath = [nodeBinDir, process.env.PATH].filter(Boolean).join(":");
+    const proxyEnvKeys = [
+        "http_proxy", "HTTP_PROXY", "https_proxy", "HTTPS_PROXY",
+        "no_proxy", "NO_PROXY", "NODE_EXTRA_CA_CERTS", "NODE_TLS_REJECT_UNAUTHORIZED",
+    ];
+    const proxyEnv = {};
+    for (const key of proxyEnvKeys) {
+        if (process.env[key])
+            proxyEnv[key] = process.env[key];
+    }
+    const childEnv = {
+        PATH: childPath,
+        HOME: process.env.HOME,
+        LANG: process.env.LANG,
+        OPENCLAW_HOME: home,
+        ...proxyEnv,
+    };
+    const MAX_ATTEMPTS = 3;
+    const RETRY_DELAY_MS = 5_000;
+    const attemptInstall = () => new Promise((resolve, reject) => {
+        execFile(openclawBin, ["plugins", "install", pkg], { cwd: home, env: childEnv, timeout: 300_000 }, (err, stdout, stderr) => {
+            if (err && !isChannelPluginInstalled(instanceId, channelId)) {
+                const msg = [stderr?.trim(), stdout?.trim(), err.message].filter(Boolean).join(" | ");
+                console.error(`[plugins] ${pkg} exit code ${err.code ?? "?"}, stderr: ${stderr?.trim() || "(empty)"}, stdout: ${stdout?.trim() || "(empty)"}`);
+                try {
+                    if (existsSync(extensionsDir)) {
+                        for (const entry of readdirSync(extensionsDir)) {
+                            if (entry.startsWith(".openclaw-install-stage-")) {
+                                rmSync(join(extensionsDir, entry), { recursive: true, force: true });
+                                console.log(`[plugins] Cleaned up stage dir: ${entry}`);
+                            }
+                        }
+                    }
+                }
+                catch {
+                    /* ignore */
+                }
+                reject(new Error(msg));
+            }
+            else {
+                if (err)
+                    console.log(`[plugins] ${pkg} installed (ignored non-zero exit)`);
+                else
+                    console.log(`[plugins] ${pkg} installed`);
+                resolve();
+            }
+        });
+    });
+    console.log(`[plugins] Installing ${pkg} for ${channelId} (host)...`);
+    let lastErr;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        try {
+            await attemptInstall();
+            const extDirName = CHANNEL_EXT_DIR_ALIAS[channelId] || channelId;
+            const installedExtDir = join(extensionsDir, extDirName);
+            if (existsSync(installedExtDir)) {
+                ensureDirContainer(installedExtDir);
+                try {
+                    for (const entry of readdirSync(installedExtDir, { withFileTypes: true })) {
+                        if (entry.isDirectory()) {
+                            ensureDirContainer(join(installedExtDir, entry.name));
+                        }
+                    }
+                }
+                catch {
+                    /* best effort */
+                }
+            }
+            ensureDirContainer(extensionsDir);
+            return;
+        }
+        catch (err) {
+            lastErr = err;
+            const isFetchError = /fetch failed/i.test(err.message ?? "");
+            if (isFetchError && attempt < MAX_ATTEMPTS) {
+                console.warn(`[plugins] ${pkg} install attempt ${attempt}/${MAX_ATTEMPTS} failed, retrying in ${RETRY_DELAY_MS / 1000}s...`);
+                await new Promise((r) => setTimeout(r, RETRY_DELAY_MS));
+                continue;
+            }
+            console.error(`[plugins] Failed to install ${pkg}:`, err.message);
+            break;
+        }
+    }
+    throw lastErr;
+}
+async function installChannelPluginViaDocker(instanceId, channelId, pkg, extensionsDir) {
+    const { exec } = await import("../../nomad-manager.js");
+    const MAX_ATTEMPTS = 3;
+    const RETRY_DELAY_MS = 5_000;
+    console.log(`[plugins] Installing ${pkg} for ${channelId} via docker exec (instance: ${instanceId})...`);
+    let lastErr;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        try {
+            const result = await exec(instanceId, ["openclaw", "plugins", "install", pkg], 300_000);
+            if (result.exitCode !== 0 && !isChannelPluginInstalled(instanceId, channelId)) {
+                const msg = [result.stderr?.trim(), result.stdout?.trim()].filter(Boolean).join(" | ");
+                console.error(`[plugins] ${pkg} docker exec exit code ${result.exitCode}, output: ${msg}`);
+                throw new Error(msg || `openclaw plugins install exited with code ${result.exitCode}`);
+            }
+            if (result.exitCode !== 0) {
+                console.log(`[plugins] ${pkg} installed via docker (ignored non-zero exit)`);
+            }
+            else {
+                console.log(`[plugins] ${pkg} installed via docker`);
+            }
+            const extDirName = CHANNEL_EXT_DIR_ALIAS[channelId] || channelId;
+            const installedExtDir = join(extensionsDir, extDirName);
+            if (existsSync(installedExtDir)) {
+                ensureDirContainer(installedExtDir);
+                try {
+                    for (const entry of readdirSync(installedExtDir, { withFileTypes: true })) {
+                        if (entry.isDirectory()) {
+                            ensureDirContainer(join(installedExtDir, entry.name));
+                        }
+                    }
+                }
+                catch {
+                    /* best effort */
+                }
+            }
+            ensureDirContainer(extensionsDir);
+            return;
+        }
+        catch (err) {
+            lastErr = err;
+            if (/not running/i.test(err.message ?? "")) {
+                throw new Error("请先启动实例后再安装插件（Docker 模式下插件需在容器内安装）");
+            }
+            const isTransient = /fetch failed|ECONNREFUSED/i.test(err.message ?? "");
+            if (isTransient && attempt < MAX_ATTEMPTS) {
+                console.warn(`[plugins] ${pkg} docker install attempt ${attempt}/${MAX_ATTEMPTS} failed, retrying...`);
+                await new Promise((r) => setTimeout(r, RETRY_DELAY_MS));
+                continue;
+            }
+            console.error(`[plugins] Failed to install ${pkg} via docker:`, err.message);
+            break;
+        }
+    }
+    throw lastErr;
+}
+/**
+ * Full saveConfig implementation. Writes `.openclaw/openclaw.json`,
+ * mirrors into legacy `openclaw.json` path, updates env files with
+ * provider API keys, preserves backend-managed fields, and fires
+ * config-change listeners.
+ *
+ * Physically migrated from `instance-manager.saveConfig`.
+ */
+function saveNativeConfigImpl(instanceId, config) {
+    const configPath = openclawConfigPath(instanceId);
+    if (!existsSync(framework_instanceDir(instanceId)))
+        return false;
+    if (!existsSync(configPath)) {
+        const legacyPath = legacyOpenclawConfigPath(instanceId);
+        ensureDirContainer(dirname(configPath));
+        if (existsSync(legacyPath))
+            copyFileSync(legacyPath, configPath);
+    }
+    // Save x-jishushell metadata to instance.json (not openclaw.json)
+    if (config["x-jishushell"]) {
+        const metaPath = instanceMetaPath(instanceId);
+        if (existsSync(metaPath)) {
+            const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+            meta["x-jishushell"] = config["x-jishushell"];
+            safeWriteJson(metaPath, meta);
+            chownToServiceUser(metaPath);
+        }
+    }
+    const [configToWrite, envUpdates] = prepareConfigForSave(instanceId, config);
+    // If openclaw-lark is enabled, resolve which feishu plugin to use
+    if (configToWrite.plugins?.entries?.["openclaw-lark"]?.enabled) {
+        const stockExtDir = getStockExtensionsDir();
+        const stockFeishu = join(stockExtDir, "feishu");
+        const stockOcl = join(stockExtDir, "openclaw-lark");
+        const instanceOcl = join(getChannelExtensionsDir(instanceId), "openclaw-lark");
+        if (existsSync(stockFeishu) && !existsSync(stockOcl) && !existsSync(instanceOcl)) {
+            configToWrite.plugins.entries.feishu = { enabled: true };
+            delete configToWrite.plugins.entries["openclaw-lark"];
+        }
+        else if (existsSync(stockFeishu)) {
+            configToWrite.plugins ??= {};
+            configToWrite.plugins.entries ??= {};
+            configToWrite.plugins.entries.feishu = { enabled: false };
+        }
+    }
+    // Preserve backend-managed fields
+    if (existsSync(configPath)) {
+        try {
+            const existing = JSON.parse(readFileSync(configPath, "utf-8"));
+            if (existing.plugins?.installs) {
+                configToWrite.plugins ??= {};
+                configToWrite.plugins.installs = { ...existing.plugins.installs, ...configToWrite.plugins?.installs };
+            }
+            if (existing.plugins?.entries && configToWrite.plugins?.entries) {
+                for (const [key, val] of Object.entries(configToWrite.plugins.entries)) {
+                    const old = existing.plugins.entries[key];
+                    if (val && typeof val === "object" && !Array.isArray(val) && old && typeof old === "object") {
+                        configToWrite.plugins.entries[key] = { ...old, ...val };
+                    }
+                }
+            }
+            if (existing.channels && configToWrite.channels) {
+                for (const [key, val] of Object.entries(configToWrite.channels)) {
+                    const old = existing.channels[key];
+                    if (val && typeof val === "object" && !Array.isArray(val) && old && typeof old === "object") {
+                        configToWrite.channels[key] = { ...old, ...val };
+                    }
+                }
+            }
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    // Backup + atomic write
+    if (existsSync(configPath)) {
+        copyFileSync(configPath, configPath + ".bak");
+    }
+    const configJson = JSON.stringify(configToWrite, null, 2);
+    ensureDirContainer(dirname(configPath));
+    writeConfigFile(configPath + ".tmp", configJson);
+    JSON.parse(readFileSync(configPath + ".tmp", "utf-8"));
+    renameSync(configPath + ".tmp", configPath);
+    chownToServiceUser(configPath);
+    // Mirror into legacy path
+    const legacyPath = legacyOpenclawConfigPath(instanceId);
+    if (existsSync(legacyPath)) {
+        copyFileSync(legacyPath, legacyPath + ".bak");
+    }
+    writeConfigFile(legacyPath + ".tmp", configJson);
+    JSON.parse(readFileSync(legacyPath + ".tmp", "utf-8"));
+    renameSync(legacyPath + ".tmp", legacyPath);
+    chownToServiceUser(legacyPath);
+    if (Object.keys(envUpdates).length) {
+        const envFiles = getRuntimeEnvFiles(instanceId);
+        if (envFiles.length)
+            updateEnvFile(envFiles[0], envUpdates);
+    }
+    // Notify listeners (LLM proxy cache invalidation etc.)
+    notifyConfigChange(instanceId);
+    return true;
+}
+export const openclawAdapter = new OpenClawAdapter();
+registerAdapter(openclawAdapter);
+//# sourceMappingURL=openclaw.js.map