jishushell 0.0.1 → 0.4.2

package/dist/services/instance-manager.js

@@ -0,0 +1,1319 @@
+import { execFile, execFileSync } from "child_process";
+import { randomBytes } from "crypto";
+import { chmodSync, chownSync, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "fs";
+import { createServer as netCreateServer } from "net";
+import { userInfo } from "os";
+import { dirname, join, resolve } from "path";
+import { INSTANCES_DIR, JISHUSHELL_HOME, getPanelConfig } from "../config.js";
+import { LEGACY_PROVIDER_API_ALIASES } from "../constants.js";
+import { safeReadJson, safeWriteJson } from "../utils/safe-json.js";
+const _configChangeListeners = [];
+export function onConfigChange(listener) {
+    _configChangeListeners.push(listener);
+    return () => {
+        const idx = _configChangeListeners.indexOf(listener);
+        if (idx >= 0)
+            _configChangeListeners.splice(idx, 1);
+    };
+}
+const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const DEFAULT_GATEWAY_PORT = 18789;
+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";
+// ── Path helpers ──
+function instanceDir(instanceId) {
+    return join(INSTANCES_DIR, instanceId);
+}
+function instanceMetaPath(instanceId) {
+    return join(instanceDir(instanceId), "instance.json");
+}
+function defaultOpenclawHome(instanceId) {
+    return join(instanceDir(instanceId), INSTANCE_OPENCLAW_HOME_DIRNAME);
+}
+function defaultModelEnvFile(instanceId) {
+    return join(instanceDir(instanceId), INSTANCE_MODEL_ENV_FILENAME);
+}
+function getOpenclawHomeInternal(instanceId) {
+    const meta = getInstance(instanceId);
+    if (meta?.openclaw_home)
+        return meta.openclaw_home;
+    return defaultOpenclawHome(instanceId);
+}
+function openclawStateDir(instanceId) {
+    return join(getOpenclawHomeInternal(instanceId), OPENCLAW_STATE_DIRNAME);
+}
+function legacyOpenclawConfigPath(instanceId) {
+    return join(getOpenclawHomeInternal(instanceId), OPENCLAW_CONFIG_FILENAME);
+}
+function openclawConfigPathInternal(instanceId) {
+    return join(openclawStateDir(instanceId), OPENCLAW_CONFIG_FILENAME);
+}
+function normalizePath(p) {
+    return resolve(p.replace(/^~/, userInfo().homedir));
+}
+// ── JSON / deep merge ──
+function loadJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (e) {
+        console.warn(`[instance] Failed to parse ${path}: ${e.message}`);
+        return null;
+    }
+}
+function deepMerge(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 ? deepMerge(merged[key], overlay[key]) : structuredClone(overlay[key]);
+    }
+    return merged;
+}
+// ── Gateway port helpers ──
+// Track in-flight port allocations to prevent race conditions
+// between concurrent createInstance() calls.
+const _pendingPorts = new Set();
+function extractGatewayPort(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;
+}
+function usedGatewayPorts(excludeId) {
+    const ports = new Set();
+    for (const inst of listInstances()) {
+        if (inst.id === excludeId)
+            continue;
+        const port = extractGatewayPort(inst.runtime);
+        if (port)
+            ports.add(port);
+    }
+    return ports;
+}
+function safePort(port) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error(`Invalid port: ${port}`);
+    return String(port);
+}
+function isPortInUse(port) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        const server = netCreateServer();
+        server.once("error", () => resolve(true));
+        server.once("listening", () => {
+            server.close(() => resolve(false));
+        });
+        server.listen(port, "0.0.0.0");
+    });
+}
+async function defaultGatewayPort(instanceId) {
+    const used = usedGatewayPorts(instanceId);
+    let port = DEFAULT_GATEWAY_PORT;
+    while (true) {
+        if (port > 65535)
+            throw new Error("No available gateway port found (all ports 18789-65535 in use)");
+        if (used.has(port) || _pendingPorts.has(port)) {
+            port++;
+            continue;
+        }
+        // Reserve BEFORE the async isPortInUse check to prevent concurrent callers
+        // from selecting the same port during the await gap.
+        _pendingPorts.add(port);
+        try {
+            if (await isPortInUse(port)) {
+                _pendingPorts.delete(port);
+                port++;
+                continue;
+            }
+            return port;
+        }
+        catch {
+            _pendingPorts.delete(port);
+            // Skip this port on a transient OS error rather than failing the entire
+            // allocation — a single bad port check should not prevent instance creation.
+            console.warn(`[instance] Port ${port} availability check failed, trying next port`);
+            port++;
+            continue;
+        }
+    }
+}
+// ── Runtime / config builders ──
+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)) {
+            // Ensure executable permission (npm install may strip +x on some platforms)
+            try {
+                chmodSync(p, 0o755);
+            }
+            catch { /* best effort — may be a symlink */ }
+            // If symlink, also chmod the target
+            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
+}
+export function getResolvedOpenclawBin() {
+    return resolveOpenclawBin();
+}
+/**
+ * When jishushell runs as root (e.g. systemd service), returns the actual
+ * non-root user that should own instance files and run openclaw processes.
+ * Returns null when not running as root or when no suitable non-root user is found.
+ */
+export function resolveServiceUser() {
+    if (typeof process.getuid !== "function" || process.getuid() !== 0)
+        return null;
+    // SUDO_USER is set when launched via `sudo`
+    const sudoUser = process.env.SUDO_USER;
+    if (sudoUser && sudoUser !== "root") {
+        try {
+            const uid = parseInt(execFileSync("id", ["-u", sudoUser], { encoding: "utf-8" }).trim(), 10);
+            const gid = parseInt(execFileSync("id", ["-g", sudoUser], { encoding: "utf-8" }).trim(), 10);
+            if (!isNaN(uid) && !isNaN(gid))
+                return { username: sudoUser, uid, gid };
+        }
+        catch { /* fall through */ }
+    }
+    // Fall back to owner of INSTANCES_DIR or JISHUSHELL_HOME
+    try {
+        const target = existsSync(INSTANCES_DIR) ? INSTANCES_DIR : JISHUSHELL_HOME;
+        const uid = statSync(target).uid;
+        if (uid !== 0) {
+            const username = execFileSync("id", ["-un", String(uid)], { encoding: "utf-8" }).trim();
+            const gid = parseInt(execFileSync("id", ["-g", username], { encoding: "utf-8" }).trim(), 10);
+            if (!isNaN(gid))
+                return { username, uid, gid };
+        }
+    }
+    catch { /* fall through */ }
+    return null;
+}
+/**
+ * When running as root, chown a file (and its .bak) to the service user so the
+ * openclaw process (running as that user) can read/write its own data files.
+ * No-op when not running as root.
+ */
+function chownToServiceUser(...paths) {
+    const svc = resolveServiceUser();
+    if (!svc)
+        return;
+    for (const p of paths) {
+        for (const f of [p, p + ".bak"]) {
+            try {
+                if (existsSync(f))
+                    chownSync(f, svc.uid, svc.gid);
+            }
+            catch { /* best effort */ }
+        }
+    }
+}
+async function defaultRuntime(instanceId, openclawHome) {
+    const port = await defaultGatewayPort(instanceId);
+    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: [defaultModelEnvFile(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 } } },
+    };
+    // Store upstream proxy config so LLM proxy knows where to forward
+    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;
+}
+// ── Config loading ──
+function loadEffectiveConfig(instanceId) {
+    const runtimePath = openclawConfigPathInternal(instanceId);
+    const legacyPath = legacyOpenclawConfigPath(instanceId);
+    const rExists = existsSync(runtimePath);
+    const lExists = existsSync(legacyPath);
+    if (rExists && lExists) {
+        const legacy = loadJson(legacyPath);
+        const runtime = loadJson(runtimePath);
+        if (legacy && runtime)
+            return deepMerge(legacy, runtime);
+        return runtime || legacy || null;
+    }
+    if (rExists)
+        return loadJson(runtimePath);
+    if (lExists)
+        return loadJson(legacyPath);
+    return null;
+}
+// ── Env file helpers ──
+export function parseEnvFile(path) {
+    const env = {};
+    if (!existsSync(path))
+        return env;
+    for (let line of readFileSync(path, "utf-8").split("\n")) {
+        line = line.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        if (line.startsWith("export "))
+            line = line.slice(7).trimStart();
+        if (!line.includes("="))
+            continue;
+        const eqIdx = line.indexOf("=");
+        const key = line.slice(0, eqIdx).trim();
+        let value = line.slice(eqIdx + 1).trim();
+        if (!ENV_KEY_RE.test(key))
+            continue;
+        if (value.length >= 2 && value[0] === value[value.length - 1] && (value[0] === "'" || value[0] === '"')) {
+            value = value.slice(1, -1);
+        }
+        env[key] = value;
+    }
+    return env;
+}
+function quoteEnvValue(value) {
+    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value))
+        return value;
+    return JSON.stringify(value);
+}
+export function updateEnvFile(path, updates) {
+    mkdirSync(dirname(path), { recursive: true });
+    const existing = existsSync(path) ? readFileSync(path, "utf-8").split("\n") : [];
+    const remaining = { ...updates };
+    const newLines = [];
+    for (const rawLine of existing) {
+        const stripped = rawLine.trim();
+        const candidate = stripped.startsWith("export ") ? stripped.slice(7).trimStart() : stripped;
+        if (!candidate || candidate.startsWith("#") || !candidate.includes("=")) {
+            newLines.push(rawLine);
+            continue;
+        }
+        const key = candidate.slice(0, candidate.indexOf("=")).trim();
+        if (!ENV_KEY_RE.test(key) || !(key in remaining)) {
+            newLines.push(rawLine);
+            continue;
+        }
+        const value = remaining[key];
+        delete remaining[key];
+        if (value === "")
+            continue;
+        const prefix = stripped.startsWith("export ") ? "export " : "";
+        newLines.push(`${prefix}${key}=${quoteEnvValue(value)}`);
+    }
+    for (const [key, value] of Object.entries(remaining)) {
+        if (!ENV_KEY_RE.test(key) || value === "")
+            continue;
+        newLines.push(`${key}=${quoteEnvValue(value)}`);
+    }
+    const output = newLines.join("\n").trimEnd();
+    const content = output ? output + "\n" : "";
+    // Atomic write: tmp then rename to protect against RPi power loss
+    const tmp = path + ".tmp";
+    writeFileSync(tmp, content, { mode: 0o600 });
+    renameSync(tmp, path);
+}
+// ── Provider key helpers ──
+export function inferProviderApiKeyEnvName(providerId) {
+    let normalized = providerId.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_|_$/g, "").toUpperCase();
+    if (!normalized)
+        normalized = "OPENCLAW_PROVIDER";
+    return `${normalized}_API_KEY`;
+}
+function hasConfiguredValue(value) {
+    if (typeof value === "string")
+        return value.trim().length > 0;
+    if (typeof value === "object" && value !== null)
+        return Object.keys(value).length > 0;
+    return value != 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);
+    // Remove JishuShell metadata — OpenClaw rejects unrecognized keys
+    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;
+        // Keep proxy provider apiKey in config — OpenClaw reads it from config directly.
+        // Only real upstream provider keys get moved to env files for security.
+        // Detect proxy by baseUrl (provider ID now uses upstream name for display).
+        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];
+}
+// ── Channel plugin helpers ──
+// Channel → plugin package mapping for auto-install.
+// Stock plugins (bundled with newer OpenClaw) are detected via extensions/{id} dir;
+// if missing (older OpenClaw), they get installed as fallback.
+// @larksuite/openclaw-lark installs as "openclaw-lark" dir but registers channel "feishu"
+const CHANNEL_EXT_DIR_ALIAS = {
+    feishu: "openclaw-lark",
+    lark: "openclaw-lark",
+};
+export const CHANNEL_PLUGIN_MAP = {
+    // Official vendor plugins (ByteDance Feishu/Lark)
+    feishu: "@larksuite/openclaw-lark",
+    lark: "@larksuite/openclaw-lark",
+    // Built-in (stock) — fallback install for older OpenClaw versions
+    telegram: "@openclaw/telegram",
+    discord: "@openclaw/discord",
+    slack: "@openclaw/slack",
+    whatsapp: "@openclaw/whatsapp",
+    signal: "@openclaw/signal",
+    line: "@openclaw/line",
+    msteams: "@openclaw/msteams",
+    // Official vendor plugins — need install (not bundled)
+    "openclaw-weixin": "@tencent-weixin/openclaw-weixin",
+};
+/** Check if a channel plugin is installed for an instance. */
+export 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))
+        // Also accept the built-in directory named after the raw channelId (e.g. "feishu/" in stock)
+        || (extDirName !== channelId && existsSync(join(stockExtDir, channelId)));
+}
+/**
+ * Install a single channel plugin on the host.
+ * This is the unified entry point for all plugin installation — never use docker exec.
+ */
+export 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 openclawHome = getOpenclawHomeInternal(instanceId);
+    const openclawBin = resolveOpenclawBin();
+    const extensionsDir = getChannelExtensionsDir(instanceId);
+    // Ensure the node binary that runs jishushell is on PATH for the child process.
+    // When running under systemd, PATH may not include the nvm node directory, which
+    // causes the `#!/usr/bin/env node` shebang in the openclaw CLI to fail.
+    const nodeBinDir = dirname(process.execPath);
+    const childPath = [nodeBinDir, process.env.PATH].filter(Boolean).join(":");
+    // Pass through proxy and TLS env vars so fetch works under systemd / restricted environments.
+    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: openclawHome,
+        ...proxyEnv,
+    };
+    const MAX_ATTEMPTS = 3;
+    const RETRY_DELAY_MS = 5_000;
+    const attemptInstall = () => new Promise((resolve, reject) => {
+        execFile(openclawBin, ["plugins", "install", pkg], {
+            cwd: openclawHome,
+            env: childEnv,
+            timeout: 300_000,
+        }, (err, stdout, stderr) => {
+            // openclaw plugins install may exit non-zero due to "plugins.allow is empty" warning
+            // even though the plugin was installed successfully. Check actual directory.
+            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)'}`);
+                // Clean up leftover stage directories
+                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 { /* best effort */ }
+                reject(new Error(msg));
+            }
+            else {
+                if (err)
+                    console.log(`[plugins] ${pkg} installed (ignored non-zero exit: warning only)`);
+                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();
+            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 with fetch error, 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;
+}
+function getChannelExtensionsDir(instanceId) {
+    return join(getOpenclawHomeInternal(instanceId), OPENCLAW_STATE_DIRNAME, "extensions");
+}
+function getStockExtensionsDir() {
+    return join(JISHUSHELL_HOME, "packages", "openclaw", "lib", "node_modules", "openclaw", "extensions");
+}
+// ── Public API ──
+export function listInstances() {
+    if (!existsSync(INSTANCES_DIR))
+        return [];
+    const entries = readdirSync(INSTANCES_DIR).sort();
+    const instances = [];
+    for (const name of entries) {
+        const metaPath = join(INSTANCES_DIR, name, "instance.json");
+        const dirPath = join(INSTANCES_DIR, name);
+        try {
+            if (statSync(dirPath).isDirectory() && existsSync(metaPath)) {
+                instances.push(JSON.parse(readFileSync(metaPath, "utf-8")));
+            }
+        }
+        catch (e) {
+            // Permission errors (EACCES) caused by root-owned files are a common deployment
+            // mistake (e.g. running a maintenance script as sudo). Log clearly instead of
+            // silently dropping the instance from the list.
+            console.error(`[instance-manager] cannot read instance '${name}': ${e.message}`);
+        }
+    }
+    return instances;
+}
+export function getInstance(instanceId) {
+    const metaPath = instanceMetaPath(instanceId);
+    if (!existsSync(metaPath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(metaPath, "utf-8"));
+    }
+    catch (e) {
+        // Surface permission errors clearly (EACCES: instance.json owned by root after a sudo script)
+        throw new Error(`Cannot read instance '${instanceId}' metadata: ${e.message}. Check file ownership with: ls -la ${metaPath}`);
+    }
+}
+export async function createInstance(instanceId, name, description = "", cloneFrom, openclawHome) {
+    const d = instanceDir(instanceId);
+    if (existsSync(d))
+        throw new Error(`Instance '${instanceId}' already exists`);
+    const home = openclawHome ? normalizePath(openclawHome) : defaultOpenclawHome(instanceId);
+    // Restrict openclaw_home to be under JISHUSHELL_HOME or /home to prevent path traversal.
+    // Use realpathSync after mkdir to resolve symlinks, preventing symlink-based bypasses.
+    if (openclawHome) {
+        const resolved = resolve(home);
+        if (!resolved.startsWith(JISHUSHELL_HOME) && !resolved.startsWith("/home/")) {
+            throw new Error(`openclaw_home must be under ${JISHUSHELL_HOME} or /home/`);
+        }
+        // Resolve symlinks for the parent dir to catch symlink attacks
+        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(", ")}`);
+        }
+    }
+    // Check for orphaned openclaw_home directory (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;
+            // readdirSync failed — directory might not be readable, proceed cautiously
+        }
+    }
+    mkdirSync(d, { recursive: true, mode: 0o750 });
+    chmodSync(d, 0o750);
+    // Inherit group from INSTANCES_DIR so both root and the real user can access
+    try {
+        const parentGid = statSync(INSTANCES_DIR).gid;
+        chownSync(d, -1, parentGid);
+    }
+    catch { /* non-root without CAP_CHOWN — already correct owner */ }
+    mkdirSync(home, { recursive: true, mode: 0o750 });
+    chmodSync(home, 0o750);
+    mkdirSync(join(home, OPENCLAW_STATE_DIRNAME), { recursive: true, mode: 0o750 });
+    chmodSync(join(home, OPENCLAW_STATE_DIRNAME), 0o750);
+    const runtime = await defaultRuntime(instanceId, home);
+    const allocatedPort = extractGatewayPort(runtime);
+    // Port already reserved inside defaultGatewayPort; just track for cleanup
+    try {
+        const meta = {
+            id: instanceId,
+            name,
+            description,
+            openclaw_home: home,
+            runtime,
+            created_at: new Date().toISOString(),
+        };
+        safeWriteJson(instanceMetaPath(instanceId), meta);
+        const envFiles = (runtime.env_files || []).map((p) => normalizePath(p));
+        for (const ef of envFiles) {
+            mkdirSync(dirname(ef), { recursive: true });
+            if (!existsSync(ef))
+                writeFileSync(ef, "", { mode: 0o600 });
+        }
+        // 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 = openclawConfigPathInternal(instanceId);
+        mkdirSync(dirname(configPath), { recursive: true });
+        if (cloneFrom && !existsSync(configPath)) {
+            const srcConfig = resolveExistingConfigPath(cloneFrom);
+            if (existsSync(srcConfig)) {
+                // Domain-level clone: copy config but strip proxy identity (token, jsproxy provider)
+                // so the new instance gets its own proxy token via saveInstanceConfig later
+                try {
+                    const cloned = JSON.parse(readFileSync(srcConfig, "utf-8"));
+                    // Remove proxy provider (will be regenerated with new proxy token)
+                    // Detect by baseUrl since provider ID now uses upstream name (e.g. "js-minimax")
+                    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 (regenerated by bootstrap)
+                    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 — same channel cannot serve multiple instances
+                    if (cloned?.channels)
+                        delete cloned.channels;
+                    // Copy extensions directory so plugin references in config remain valid
+                    // Copy workspace directory to preserve agent personality (.md files)
+                    for (const subdir of ["extensions", "workspace", "skills"]) {
+                        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 */ }
+                        }
+                    }
+                    writeFileSync(configPath, JSON.stringify(cloned, null, 2), { mode: 0o600 });
+                    // Copy x-jishushell upstream metadata from source instance.json
+                    // (saveConfig stores x-jishushell in instance.json, not openclaw.json)
+                    const srcMetaPath = join(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 } };
+                                // Clear instance-specific fields
+                                delete dstXj.proxy.upstream.apiKey;
+                                const metaPath = instanceMetaPath(instanceId);
+                                if (existsSync(metaPath)) {
+                                    const dstMeta = JSON.parse(readFileSync(metaPath, "utf-8"));
+                                    dstMeta["x-jishushell"] = dstXj;
+                                    writeFileSync(metaPath, JSON.stringify(dstMeta, null, 2));
+                                }
+                            }
+                        }
+                        catch { /* ignore metadata copy errors */ }
+                    }
+                }
+                catch {
+                    // Fallback: raw copy if parse fails
+                    copyFileSync(srcConfig, configPath);
+                }
+            }
+        }
+        if (!existsSync(configPath)) {
+            writeFileSync(configPath, JSON.stringify(starterConfig(), null, 2), { mode: 0o600 });
+            // 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 });
+                // Also write to provider.env as UPSTREAM_API_KEY (LLM proxy reads this first)
+                const providerEnv = join(dirname(envFiles[0]), "provider.env");
+                updateEnvFile(providerEnv, { UPSTREAM_API_KEY: dp.apiKey });
+            }
+        }
+        // Copy cloned provider.env BEFORE proxy bootstrap so bootstrap can find the API key
+        if (cloneFrom && envFiles.length) {
+            const srcEnvFiles = getRuntimeEnvFiles(cloneFrom);
+            const srcEnvFile = srcEnvFiles[0];
+            const dstEnvFile = envFiles[0];
+            // Copy provider.env (upstream API key)
+            if (srcEnvFile) {
+                const srcProvider = join(dirname(srcEnvFile), "provider.env");
+                const dstProvider = join(dirname(dstEnvFile), "provider.env");
+                if (existsSync(srcProvider) && !existsSync(dstProvider)) {
+                    copyFileSync(srcProvider, dstProvider);
+                }
+            }
+            // Note: model.env is NOT copied (new instance needs its own proxy token)
+        }
+        // Bootstrap proxy: generate proxy token and write model.env so instance
+        // is ready to run immediately without requiring a manual "save config" first
+        try {
+            const { bootstrapInstanceProxy } = await import("../services/llm-proxy/index.js");
+            await bootstrapInstanceProxy(instanceId);
+        }
+        catch (e) {
+            console.warn(`[instance] Proxy bootstrap for ${instanceId} deferred: ${e.message}`);
+        }
+        // If running as root, hand ownership of all created files to the service user
+        // so the openclaw process (running as that user) can read/write its own files.
+        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(`[instance] chown for ${instanceId} failed:`, e.message);
+            }
+        }
+        return meta;
+    }
+    finally {
+        if (allocatedPort)
+            _pendingPorts.delete(allocatedPort);
+    }
+}
+export function updateInstance(instanceId, name, description) {
+    const meta = getInstance(instanceId);
+    if (!meta)
+        return null;
+    if (name != null)
+        meta.name = name;
+    if (description != null)
+        meta.description = description;
+    safeWriteJson(instanceMetaPath(instanceId), meta);
+    chownToServiceUser(instanceMetaPath(instanceId));
+    return meta;
+}
+export function deleteInstance(instanceId) {
+    const d = instanceDir(instanceId);
+    if (!existsSync(d))
+        return { ok: false, warnings: ["Instance directory not found"] };
+    const warnings = [];
+    // Cache metadata BEFORE deletion so we can check custom openclaw_home after rm
+    const meta = getInstance(instanceId);
+    const home = meta?.openclaw_home;
+    // Clean up Nomad Variables (async, best-effort)
+    import("./nomad-manager.js").then((nm) => {
+        nm.purgeInstanceVariables(instanceId).catch((e) => {
+            console.warn(`[instance] Failed to purge Nomad variables for ${instanceId}:`, e.message);
+        });
+    }).catch((e) => {
+        console.warn(`[instance] Could not load nomad-manager for cleanup:`, e.message);
+    });
+    let dirDeleted = false;
+    try {
+        rmSync(d, { recursive: true, force: true });
+        dirDeleted = true;
+    }
+    catch {
+        try {
+            execFileSync("sudo", ["rm", "-rf", d], { timeout: 10000 });
+            dirDeleted = true;
+        }
+        catch (e) {
+            warnings.push(`Failed to delete instance directory: ${e.message}`);
+        }
+    }
+    // Warn if custom openclaw_home exists outside the instance dir
+    if (home && !home.startsWith(d) && existsSync(home)) {
+        warnings.push(`Custom openclaw_home '${home}' was preserved. Delete manually if no longer needed.`);
+    }
+    return { ok: dirDeleted, warnings: warnings.length ? warnings : undefined };
+}
+export function getConfig(instanceId) {
+    const config = loadEffectiveConfig(instanceId);
+    if (!config)
+        return null;
+    // Merge x-jishushell metadata from instance.json
+    const meta = getInstance(instanceId);
+    if (meta?.["x-jishushell"]) {
+        config["x-jishushell"] = meta["x-jishushell"];
+    }
+    return injectProviderApiKeys(instanceId, config);
+}
+export function getStoredConfig(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;
+}
+export function saveConfig(instanceId, config) {
+    const configPath = openclawConfigPathInternal(instanceId);
+    if (!existsSync(instanceDir(instanceId)))
+        return false;
+    if (!existsSync(configPath)) {
+        const legacyPath = legacyOpenclawConfigPath(instanceId);
+        mkdirSync(dirname(configPath), { recursive: true });
+        // Ensure the state dir is group-writable so the Docker container (which may
+        // run as a different UID) can create sub-directories via shared group.
+        try {
+            chmodSync(dirname(configPath), 0o770);
+        }
+        catch { /* best effort */ }
+        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 configured as enabled, resolve which feishu plugin should actually be used:
+    // - If built-in feishu/ exists in stock AND openclaw-lark/ is not installed anywhere → switch to
+    //   built-in feishu (removes the stale openclaw-lark reference that breaks container startup).
+    // - If both exist → keep openclaw-lark but disable built-in feishu to avoid conflict.
+    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)) {
+            // Built-in available, community package absent → switch to built-in
+            configToWrite.plugins.entries.feishu = { enabled: true };
+            delete configToWrite.plugins.entries["openclaw-lark"];
+        }
+        else if (existsSync(stockFeishu)) {
+            // Both present → disable built-in to avoid conflict with community package
+            configToWrite.plugins ??= {};
+            configToWrite.plugins.entries ??= {};
+            configToWrite.plugins.entries.feishu = { enabled: false };
+        }
+    }
+    // Preserve plugins.installs from existing config on disk —
+    // these are managed by `openclaw plugins install` and must not be overwritten
+    // by the frontend config which doesn't track them.
+    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 };
+            }
+        }
+        catch { /* best effort */ }
+    }
+    // backup
+    if (existsSync(configPath)) {
+        copyFileSync(configPath, configPath + ".bak");
+    }
+    const configJson = JSON.stringify(configToWrite, null, 2);
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath + ".tmp", configJson, { mode: 0o600 });
+    // Verify tmp file is valid JSON before replacing (guards against disk-full partial writes)
+    JSON.parse(readFileSync(configPath + ".tmp", "utf-8"));
+    renameSync(configPath + ".tmp", configPath);
+    chownToServiceUser(configPath);
+    // also write to legacy path (with restricted permissions)
+    const legacyPath = legacyOpenclawConfigPath(instanceId);
+    if (existsSync(legacyPath)) {
+        copyFileSync(legacyPath, legacyPath + ".bak");
+    }
+    writeFileSync(legacyPath + ".tmp", configJson, { mode: 0o600 });
+    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);
+    }
+    // Plugins are installed inside the container — no host-side auto-install on config save.
+    // Notify listeners (e.g. llm-proxy cache invalidation)
+    for (const listener of _configChangeListeners) {
+        try {
+            listener(instanceId);
+        }
+        catch { /* ignore listener errors */ }
+    }
+    return true;
+}
+export function getOpenclawHome(instanceId) {
+    return getOpenclawHomeInternal(instanceId);
+}
+/**
+ * Save WeChat login credentials for an instance.
+ * Save Feishu/Lark credentials from OAuth Device Code flow.
+ */
+// Feishu app IDs issued by the open platform follow the pattern cli_<hex/alnum>.
+// Validate appId to reject malformed values sourced from OAuth API responses.
+const FEISHU_APP_ID_RE = /^cli_[a-zA-Z0-9]{8,64}$/;
+export function 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 = openclawConfigPathInternal(instanceId);
+    let config = safeReadJson(configPath, "feishu-creds") || {};
+    // Enable @larksuite/openclaw-lark plugin (installed inside Docker container),
+    // disable built-in @openclaw/feishu to avoid conflict.
+    config.plugins ??= {};
+    config.plugins.entries ??= {};
+    config.plugins.entries.feishu = { enabled: false };
+    config.plugins.entries["openclaw-lark"] = { enabled: true };
+    // Set channel config — official plugin reads from channels.feishu
+    config.channels ??= {};
+    config.channels.feishu = {
+        ...config.channels.feishu,
+        enabled: true,
+        appId: creds.appId,
+        appSecret: creds.appSecret,
+        domain: creds.domain,
+        dmPolicy: "pairing",
+    };
+    safeWriteJson(configPath, config);
+    chownToServiceUser(configPath);
+    console.log(`[instance-manager] Feishu credentials saved for ${instanceId}, domain=${creds.domain}`);
+}
+/**
+ * Writes account data + updates openclaw.json to enable the plugin and register the account.
+ */
+const SAFE_ACCOUNT_ID_RE = /^[a-zA-Z0-9@._-]{1,128}$/;
+export function saveWeixinCredentials(instanceId, creds) {
+    // Prevent path traversal via accountId (used as filename)
+    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 = getOpenclawHomeInternal(instanceId);
+    const stateDir = join(home, OPENCLAW_STATE_DIRNAME, "openclaw-weixin");
+    const accountsDir = join(stateDir, "accounts");
+    mkdirSync(accountsDir, { recursive: true });
+    // Save account credentials file (via safeWriteJson for atomic + .bak protection)
+    const credObj = {
+        token: creds.token,
+        baseUrl: creds.baseUrl,
+        userId: creds.userId,
+        savedAt: new Date().toISOString(),
+    };
+    safeWriteJson(join(accountsDir, `${creds.accountId}.json`), credObj);
+    // OpenClaw also needs a "default" account file with the same credentials
+    safeWriteJson(join(accountsDir, "default.json"), credObj);
+    chownToServiceUser(join(accountsDir, `${creds.accountId}.json`), join(accountsDir, "default.json"));
+    // Update accounts.json index (required by the plugin to discover accounts)
+    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);
+    // Update openclaw.json: enable plugin + register account
+    const configPath = openclawConfigPathInternal(instanceId);
+    let config = safeReadJson(configPath, "weixin-creds") || {};
+    // Enable plugin
+    config.plugins ??= {};
+    config.plugins.entries ??= {};
+    config.plugins.entries["openclaw-weixin"] ??= {};
+    config.plugins.entries["openclaw-weixin"].enabled = true;
+    // Enable channel with account
+    config.channels ??= {};
+    config.channels["openclaw-weixin"] ??= {};
+    config.channels["openclaw-weixin"].enabled = true;
+    // Register account with both original and normalized IDs (OpenClaw normalizes @ and . to -)
+    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 };
+    // Set defaultAccount (required by OpenClaw)
+    if (!config.channels["openclaw-weixin"].defaultAccount) {
+        config.channels["openclaw-weixin"].defaultAccount = "default";
+    }
+    safeWriteJson(configPath, config);
+    chownToServiceUser(configPath);
+    console.log(`[instance-manager] WeChat credentials saved for ${instanceId}, account=${creds.accountId}`);
+}
+/**
+ * Get connected WeChat accounts for an instance.
+ */
+export function getWeixinAccounts(instanceId) {
+    const home = getOpenclawHomeInternal(instanceId);
+    const stateDir = join(home, OPENCLAW_STATE_DIRNAME, "openclaw-weixin");
+    const accountsDir = join(stateDir, "accounts");
+    if (!existsSync(accountsDir))
+        return [];
+    // Only return accounts listed in the index (skip default.json and other auxiliary files)
+    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; // skip auxiliary files
+        if (id === "default")
+            continue; // always skip default alias
+        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;
+}
+export function getOpenclawConfigPath(instanceId) {
+    return openclawConfigPathInternal(instanceId);
+}
+export function getLegacyOpenclawConfigPath(instanceId) {
+    return legacyOpenclawConfigPath(instanceId);
+}
+export function getInstanceRuntime(instanceId) {
+    const meta = getInstance(instanceId);
+    if (!meta)
+        return {};
+    return structuredClone(meta.runtime || {});
+}
+export function getRuntimeEnvFiles(instanceId) {
+    const runtime = getInstanceRuntime(instanceId);
+    const envFiles = (runtime.env_files || []).map((p) => normalizePath(p)).filter(Boolean);
+    return envFiles.length ? envFiles : [defaultModelEnvFile(instanceId)];
+}
+export function getGatewayPort(instanceId) {
+    return extractGatewayPort(getInstanceRuntime(instanceId)) || DEFAULT_GATEWAY_PORT;
+}
+/**
+ * Detect the host address where the gateway port is actually listening.
+ *
+ * Strategy by driver:
+ *  - raw_exec (Linux/Pi): use `ss` to read the listening address directly.
+ *  - docker (macOS/bridge): Nomad publishes the port on the Nomad client's
+ *    interface IP (e.g. 10.x.x.x), NOT 127.0.0.1. Query the Nomad allocation
+ *    for `AllocatedResources.Shared.Ports[label=gateway].HostIP`.
+ *
+ * Result is cached for 30 s to avoid an API call on every proxy request.
+ */
+const _gwHostCache = new Map();
+const GW_HOST_CACHE_TTL = 30000;
+export async function getGatewayHost(instanceId) {
+    const cached = _gwHostCache.get(instanceId);
+    if (cached && Date.now() - cached.ts < GW_HOST_CACHE_TTL)
+        return cached.host;
+    const port = getGatewayPort(instanceId);
+    let result = "127.0.0.1";
+    try {
+        const { getNomadDriver } = await import("../config.js");
+        if (getNomadDriver() === "docker") {
+            const { getNomadAddr, getNomadToken } = await import("../config.js");
+            const jid = `openclaw-${instanceId}`;
+            const headers = { "Content-Type": "application/json" };
+            const token = getNomadToken();
+            if (token)
+                headers["X-Nomad-Token"] = token;
+            const resp = await fetch(`${getNomadAddr()}/v1/job/${encodeURIComponent(jid)}/allocations`, {
+                headers,
+                signal: AbortSignal.timeout(5000),
+            });
+            if (resp.ok) {
+                const allocs = await resp.json();
+                const alloc = allocs.find((a) => a.ClientStatus === "running")
+                    ?? allocs.find((a) => a.ClientStatus === "pending");
+                if (alloc) {
+                    const detail = await fetch(`${getNomadAddr()}/v1/allocation/${encodeURIComponent(alloc.ID)}`, { headers, signal: AbortSignal.timeout(5000) });
+                    if (detail.ok) {
+                        const d = await detail.json();
+                        const ports = d?.AllocatedResources?.Shared?.Ports ?? [];
+                        const gwPort = ports.find((p) => p.Label === "gateway");
+                        if (gwPort?.HostIP && gwPort.HostIP !== "0.0.0.0") {
+                            result = gwPort.HostIP;
+                        }
+                    }
+                }
+            }
+            // If Nomad API resolved a non-default host, cache and return it
+            if (result !== "127.0.0.1") {
+                _gwHostCache.set(instanceId, { host: result, ts: Date.now() });
+                return result;
+            }
+            // Otherwise fall through to ss-based detection
+        }
+    }
+    catch { /* fall through */ }
+    try {
+        const out = execFileSync("ss", ["-tlnH", "sport", "=", ":" + safePort(port)], { encoding: "utf-8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"] });
+        for (const line of out.split("\n")) {
+            const match = line.match(/\s([\d.]+):(\d+)\s/);
+            if (match && match[2] === String(port)) {
+                const addr = match[1];
+                result = addr === "0.0.0.0" ? "127.0.0.1" : addr;
+                break;
+            }
+        }
+    }
+    catch { /* fall through */ }
+    _gwHostCache.set(instanceId, { host: result, ts: Date.now() });
+    return result;
+}
+export function findInstancesSharingOpenclawHome(instanceId) {
+    const targetHome = normalizePath(getOpenclawHome(instanceId));
+    return listInstances()
+        .filter((inst) => inst.id !== instanceId)
+        .filter((inst) => normalizePath(inst.openclaw_home || defaultOpenclawHome(inst.id)) === targetHome)
+        .map((inst) => inst.id);
+}
+export function findInstancesSharingGatewayPort(instanceId) {
+    const targetPort = getGatewayPort(instanceId);
+    return listInstances()
+        .filter((inst) => inst.id !== instanceId)
+        .filter((inst) => extractGatewayPort(inst.runtime) === targetPort)
+        .map((inst) => inst.id);
+}
+export function getRuntimeEnv(instanceId) {
+    const runtime = getInstanceRuntime(instanceId);
+    const env = {};
+    for (const envFile of getRuntimeEnvFiles(instanceId)) {
+        Object.assign(env, parseEnvFile(envFile));
+    }
+    for (const [key, value] of Object.entries(runtime.env || {})) {
+        if (value != null)
+            env[key] = String(value);
+    }
+    return env;
+}
+// Re-export instanceDir for nomad-manager
+export { instanceDir as getInstanceDir };
+function resolveExistingConfigPath(instanceId) {
+    const runtimePath = openclawConfigPathInternal(instanceId);
+    if (existsSync(runtimePath))
+        return runtimePath;
+    const legacyPath = legacyOpenclawConfigPath(instanceId);
+    if (existsSync(legacyPath))
+        return legacyPath;
+    return runtimePath;
+}
+//# sourceMappingURL=instance-manager.js.map