jishushell 0.4.30 → 0.5.22

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

@@ -34,10 +34,10 @@
  *     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 { accessSync, chmodSync, chownSync, copyFileSync, cpSync, constants, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync, } from "fs";
+import { createHash, randomBytes } from "crypto";
 import { homedir, userInfo } from "os";
-import { dirname, join, resolve as pathResolve } from "path";
+import { delimiter, 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";
@@ -48,7 +48,7 @@ import { getInstanceDir as framework_instanceDir, instanceMetaPath } from "../..
 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 { bootstrapInstanceProxy, decryptApiKey, getInstanceConfig as getProxyInstanceConfig } from "../../llm-proxy/index.js";
 import { registerAdapter } from "../registry.js";
 import { registerOpenclawRoutes } from "./openclaw-routes.js";
 // ── Constants physically migrated from nomad-manager.ts ───────────────
@@ -114,6 +114,55 @@ const DEFAULT_CAPABILITIES = {
     restartlessReload: false,
     messagingPlatforms: ["feishu", "openclaw-weixin"],
 };
+import { FILES_ROOT } from "../../../config.js";
+import { defaultMountsForNewInstance, ensureMountTargets, } from "../../files-mounts.js";
+/**
+ * Tolerate both `fileMounts` and `file_mounts` in instance.json — some
+ * earlier migrations may have written snake_case.
+ */
+function readFileMounts(runtime) {
+    const raw = runtime.fileMounts ?? runtime.file_mounts;
+    return Array.isArray(raw) ? raw : [];
+}
+/**
+ * Build the volume list for the docker driver:
+ *   1. The existing openclaw-home self-mount (HOME == container HOME)
+ *   2. The root FILES_ROOT bind when any mount has empty path
+ *      ({"path":"","alias":"","mode":"rw"} — the default for new
+ *      instances). Without this, in-container plugins (Feishu / WeChat
+ *      send_file) try `fs.open("/home/.../files/...")` and hit ENOENT
+ *      because the host path isn't bind-mounted. Verified on pi2
+ *      2026-05-11: claw1's drive_resolve_local_path returned a valid
+ *      abs_path; feishu_im_user_message then ENOENT'd on it.
+ *   3. One additional bind per non-root FileMount, host==container so
+ *      the workspace/{alias} symlink (placed by rebuildWorkspace)
+ *      resolves identically inside the container.
+ *
+ * Mode "ro" is enforced by the docker bind option; raw_exec / process
+ * modes don't go through this path (the agent runs natively on the host
+ * and reads files directly).
+ */
+function buildVolumes(openclawHome, runtime) {
+    const list = [`${openclawHome}:${openclawHome}:rw`];
+    let rootBound = false;
+    for (const m of readFileMounts(runtime)) {
+        if (!m)
+            continue;
+        const mode = m.mode === "ro" ? "ro" : "rw";
+        if (!m.path) {
+            if (rootBound)
+                continue;
+            list.push(`${FILES_ROOT}:${FILES_ROOT}:${mode}`);
+            rootBound = true;
+            continue;
+        }
+        if (rootBound)
+            continue; // root already covers every subtree
+        const abs = join(FILES_ROOT, m.path);
+        list.push(`${abs}:${abs}:${mode}`);
+    }
+    return list;
+}
 // ── Path helpers (physically migrated from instance-manager.ts) ───────
 const INSTANCE_OPENCLAW_HOME_DIRNAME = "openclaw-home";
 const INSTANCE_MODEL_ENV_FILENAME = "model.env";
@@ -176,7 +225,32 @@ function resolveOpenclawBin() {
             return p;
         }
     }
-    return candidates[0]; // fallback, will fail with clear error at spawn
+    // Fallback: scan $PATH for user-installed openclaw (nvm, homebrew, etc.)
+    // Uses in-process lookup instead of spawning `which` for security and performance.
+    const fromPath = findExecutableOnPath("openclaw");
+    if (fromPath)
+        return fromPath;
+    return candidates[0]; // will fail with clear error at spawn
+}
+/**
+ * Search $PATH for an executable by name. Returns the first match or null.
+ * Does not chmod the result — PATH-discovered binaries are not managed by JishuShell.
+ */
+function findExecutableOnPath(name) {
+    const pathEnv = process.env.PATH || "";
+    for (const dir of pathEnv.split(delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = join(dir, name);
+        try {
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch {
+            /* not found or not executable in this dir */
+        }
+    }
+    return null;
 }
 function buildDefaultRuntime(instanceId, port, openclawHome) {
     const home = openclawHome || defaultOpenclawHome(instanceId);
@@ -189,6 +263,12 @@ function buildDefaultRuntime(instanceId, port, openclawHome) {
         env: {
             OPENCLAW_GATEWAY_PORT: String(port),
             NODE_OPTIONS: "--max-old-space-size=2048",
+            // Let mcporter find its config regardless of the agent's CWD. The
+            // gateway's CWD is openclaw-home (no config/), and `cd workspace`
+            // means the user-files symlink (also no config/). Without this env,
+            // every `mcporter call drive.*` fails with "Unknown MCP server 'drive'"
+            // and the agent reports a generic "network error" to the user.
+            MCPORTER_CONFIG: `${home}/.openclaw/workspace/config/mcporter.json`,
         },
         resources: { CPU: 1000, MemoryMB: 2048 },
     };
@@ -260,6 +340,65 @@ function patchJsproxyBaseUrl(configPath) {
         console.warn(`[openclaw] Failed to patch jsproxy baseUrl in ${configPath}: ${e.message}`);
     }
 }
+/** Known private/internal hostnames used by JishuShell's local proxy. */
+const PRIVATE_NETWORK_HOSTS = ["host.docker.internal", "127.0.0.1", "localhost", "0.0.0.0"];
+export function isPrivateNetworkBaseUrl(baseUrl) {
+    try {
+        const url = new URL(baseUrl);
+        if (PRIVATE_NETWORK_HOSTS.includes(url.hostname))
+            return true;
+        if (url.hostname.startsWith("10."))
+            return true;
+        if (url.hostname.startsWith("192.168."))
+            return true;
+        // RFC 1918: 172.16.0.0/12 → 172.16.x.x through 172.31.x.x
+        const m = url.hostname.match(/^172\.(\d+)\./);
+        if (m) {
+            const second = parseInt(m[1], 10);
+            if (second >= 16 && second <= 31)
+                return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ensure `request.allowPrivateNetwork: true` is set on providers whose baseUrl
+ * targets a private/internal host (e.g. host.docker.internal). Without this,
+ * OpenClaw's SSRF guard blocks requests to the JishuShell local proxy.
+ */
+export function patchPrivateNetworkAllowFlag(configPath) {
+    try {
+        const raw = readFileSync(configPath, "utf-8");
+        const config = JSON.parse(raw);
+        const providers = config?.models?.providers;
+        if (!providers || typeof providers !== "object")
+            return;
+        let changed = false;
+        for (const [, provider] of Object.entries(providers)) {
+            if (typeof provider !== "object" || provider === null)
+                continue;
+            const p = provider;
+            if (typeof p.baseUrl !== "string")
+                continue;
+            if (!isPrivateNetworkBaseUrl(p.baseUrl))
+                continue;
+            if (p.request?.allowPrivateNetwork === true)
+                continue;
+            p.request = { ...(p.request || {}), allowPrivateNetwork: true };
+            changed = true;
+        }
+        if (changed) {
+            writeConfigFile(configPath, JSON.stringify(config, null, 2));
+            console.log(`[openclaw] Patched request.allowPrivateNetwork in ${configPath} for private-network providers`);
+        }
+    }
+    catch (e) {
+        console.warn(`[openclaw] Failed to patch allowPrivateNetwork 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
@@ -435,6 +574,429 @@ export function clearSearxngConnectionFromConfig(configPath) {
     }
     safeWriteJson(configPath, existing);
 }
+/** Profile name used in `browser.profiles` for jishushell-managed Browserless bindings. */
+const BROWSERLESS_PROFILE = "browserless";
+/**
+ * Default `color` for the jishushell-managed browserless profile. OpenClaw's
+ * profile schema treats `color` as required (the field shows up as the
+ * profile chip tint in the UI); omitting it triggers
+ *   "browser.profiles.browserless.color: Invalid input: expected string,
+ *    received undefined"
+ * on every config reload, which crashloops the gateway. Verified against
+ * the runtime image `ghcr.io/x-aijishu/openclaw-runtime:2026.4.15` on Pi 2
+ * (2026-05-07). The tone is Browserless brand green; users can override it
+ * once and we preserve their override on re-bind via the `prior` spread.
+ */
+const BROWSERLESS_DEFAULT_COLOR = "#00AA66";
+/**
+ * Deep-merge a Browserless CDP connection into an OpenClaw config file at
+ * `configPath`. Mirrors `applySearxngConnectionToConfig` for the browser slot.
+ *
+ * Writes:
+ *   browser.profiles.browserless.cdpUrl     = cdpUrl            // ws:// or wss://
+ *   browser.profiles.browserless.attachOnly = true              // since v2026.3.2
+ *   browser.profiles.browserless.color      = "#00AA66"         // required by schema
+ *   browser.defaultProfile                  = "browserless"     // only if unset
+ *   browser.enabled                         = true              // only if unset
+ *   gateway.nodes.browser.mode              = "off"             // only if unset
+ *
+ * Why per-profile `attachOnly` and not global `browser.attachOnly`: global
+ * attachOnly forces every profile to skip launch — that breaks the user's
+ * other manually-configured profiles. Per-profile attachOnly was added in
+ * OpenClaw v2026.3.2; older versions silently ignore the extra field and
+ * fall back to attach-via-cdpUrl semantics (which `cdpUrl` triggers on its
+ * own from v2.0.0-beta5), so the schema is forward-compatible all the way
+ * back to the first remote-CDP release.
+ *
+ * Why `gateway.nodes.browser.mode = "off"`: in OpenClaw 2026.5.6 the
+ * gateway only registers the `browser.request` WS method when this config
+ * block exists. Without it, `openclaw browser …` CLI and the gateway
+ * canvas tool both fail with `unknown method: browser.request` or
+ * `node required`. Setting `mode: "off"` forces gateway-local CDP
+ * dispatch (use `cdpUrl` directly, never look for paired nodes), which
+ * matches jishushell's intent: Browserless is a service-style provider,
+ * not a node-style provider. Verified end-to-end on Pi 2 (2026-05-07):
+ * Browserless `/sessions` shows `numbConnected: 1` and `openclaw browser
+ * navigate <allowed-host>` succeeds + screenshots render correctly.
+ *
+ * `defaultProfile`, `enabled`, and `gateway.nodes.browser.mode` are all
+ * set only when absent so user-customized values survive a re-bind. The
+ * `enabled` flag is never flipped off — Browserless binding shouldn't
+ * override a user who explicitly disabled the browser tool tree.
+ *
+ * SSRF policy is intentionally NOT touched here: `browser.ssrfPolicy`
+ * (`dangerouslyAllowPrivateNetwork`, `allowedHostnames`) is a user-level
+ * security decision (default deny-all is correct for an LLM-driven
+ * browser); jishushell would be over-reaching to silently widen it on
+ * binding. Users who want the agent to reach a specific host configure
+ * the allowlist themselves.
+ *
+ * No-op when the config file is absent (instance not yet started).
+ */
+export function applyBrowserlessConnectionToConfig(configPath, cdpUrl) {
+    if (!existsSync(configPath))
+        return;
+    const existing = JSON.parse(readFileSync(configPath, "utf-8"));
+    const browser = (existing.browser ??= {});
+    if (browser.enabled === undefined)
+        browser.enabled = true;
+    if (!browser.defaultProfile)
+        browser.defaultProfile = BROWSERLESS_PROFILE;
+    const profiles = (browser.profiles ??= {});
+    const prior = profiles[BROWSERLESS_PROFILE] ?? {};
+    profiles[BROWSERLESS_PROFILE] = {
+        ...prior,
+        cdpUrl,
+        attachOnly: true,
+        color: typeof prior.color === "string" && prior.color ? prior.color : BROWSERLESS_DEFAULT_COLOR,
+    };
+    const gateway = (existing.gateway ??= {});
+    const nodes = (gateway.nodes ??= {});
+    const browserPolicy = (nodes.browser ??= {});
+    if (browserPolicy.mode === undefined)
+        browserPolicy.mode = "off";
+    safeWriteJson(configPath, existing);
+}
+/**
+ * Counterpart to `applyBrowserlessConnectionToConfig` — invoked when the user
+ * unbinds the BROWSER slot in the Connections tab. Removes the
+ * jishushell-managed `browserless` profile and clears `defaultProfile` only
+ * if it still points at that profile (so user-set defaults pointing at their
+ * own profiles survive). Other profiles and `browser.enabled` are left alone.
+ *
+ * No-op when the config file is absent.
+ */
+export function clearBrowserlessConnectionFromConfig(configPath) {
+    if (!existsSync(configPath))
+        return;
+    const existing = JSON.parse(readFileSync(configPath, "utf-8"));
+    const browser = existing?.browser;
+    if (!browser || typeof browser !== "object")
+        return;
+    if (browser.profiles && typeof browser.profiles === "object") {
+        delete browser.profiles[BROWSERLESS_PROFILE];
+    }
+    if (browser.defaultProfile === BROWSERLESS_PROFILE) {
+        delete browser.defaultProfile;
+    }
+    safeWriteJson(configPath, existing);
+}
+/**
+ * Bump when a panel-side change invalidates the agent's prior reasoning
+ * within an existing chat session — e.g., a mount fix that turns prior
+ * "I can't read this file" tool failures into stale conclusions. The
+ * first onBeforeStart after the bump rotates the instance's session
+ * jsonl files (`<file>.jsonl` → `<file>.jsonl.reset.<ts>`), so the next
+ * user message lands on a clean context window. Old transcripts are
+ * preserved as .reset.* siblings — never deleted, just archived.
+ *
+ * Concrete history:
+ *   2026.5.11.1 — buildVolumes root-mount fix: empty-path FileMount
+ *                  finally binds FILES_ROOT into docker containers. Prior
+ *                  sessions had agent conclude "drive only has metadata,
+ *                  no file content" after ENOENT — that reasoning is
+ *                  poisoned post-fix.
+ *   2026.5.11.2 — WeChat target-format rule in TOOLS.md: agent was
+ *                  extrapolating Feishu's `user:` prefix onto WeChat
+ *                  chat_ids that don't carry it, causing WeChat's
+ *                  getuploadurl to return ret:-1. Prior sessions need
+ *                  rotation so the agent re-reads the corrected target
+ *                  rule and stops adding the prefix.
+ *
+ * Format: YYYY.M.D.N (date + same-day bump counter). Compare as strings;
+ * any difference means rotate. Stored per-instance at
+ *   `<instanceDir>/runtime-contract.txt`
+ */
+const RUNTIME_CONTRACT_VERSION = "2026.5.11.2";
+const JISHUSHELL_DRIVE_HINT_BEGIN = "<!-- jishushell-drive: BEGIN auto-generated -->";
+const JISHUSHELL_DRIVE_HINT_END = "<!-- jishushell-drive: END -->";
+const JISHUSHELL_KB_HINT_BEGIN = "<!-- jishushell-kb: BEGIN auto-generated -->";
+const JISHUSHELL_KB_HINT_END = "<!-- jishushell-kb: END -->";
+/**
+ * Rotate session jsonl files when the runtime contract version has bumped
+ * since this instance last started. Matches OpenClaw's own .reset.<ts>
+ * naming convention so its existing UI/cleanup paths still apply.
+ *
+ * Why this exists: when a panel upgrade fixes a runtime bug (e.g. the
+ * 2026-05-11 mount-bind fix), the agent's prior turn-by-turn reasoning
+ * inside an existing session is anchored to the broken behaviour. Even
+ * after the fix is deployed and the alloc restarted, the LLM keeps
+ * citing past tool failures and refusing to retry. Rotating the session
+ * jsonl(s) gives the next user message a clean context where the agent
+ * sees fresh TOOLS.md + fresh tool outputs.
+ *
+ * Side effect: the user loses chat scrollback in IM/web. Acceptable
+ * because (a) the rotated file is preserved on disk, (b) panel upgrades
+ * are infrequent, (c) the alternative — agent stuck in old reasoning —
+ * is worse UX.
+ */
+function rotateSessionsIfContractChanged(instanceId, openclawHome) {
+    try {
+        const markerPath = join(framework_instanceDir(instanceId), "runtime-contract.txt");
+        let previous = "";
+        try {
+            previous = readFileSync(markerPath, "utf-8").trim();
+        }
+        catch (e) {
+            if (e?.code !== "ENOENT")
+                throw e;
+        }
+        if (previous === RUNTIME_CONTRACT_VERSION)
+            return;
+        const sessionsDir = join(openclawHome, ".openclaw", "agents", "main", "sessions");
+        if (existsSync(sessionsDir)) {
+            const ts = new Date()
+                .toISOString()
+                .replace(/:/g, "-")
+                .replace(/\.\d+Z$/, ".000Z");
+            const entries = readdirSync(sessionsDir);
+            let rotated = 0;
+            for (const name of entries) {
+                if (!name.endsWith(".jsonl"))
+                    continue; // skip already-rotated
+                const from = join(sessionsDir, name);
+                const to = `${from}.reset.${ts}`;
+                try {
+                    renameSync(from, to);
+                    rotated++;
+                }
+                catch (e) {
+                    console.warn(`[openclaw] session rotate failed for ${from}: ${e?.message ?? e}`);
+                }
+            }
+            if (rotated > 0) {
+                console.log(`[openclaw] runtime contract ${previous || "(none)"} → ${RUNTIME_CONTRACT_VERSION}: rotated ${rotated} session(s) under ${sessionsDir}`);
+            }
+        }
+        writeConfigFile(markerPath, RUNTIME_CONTRACT_VERSION + "\n");
+    }
+    catch (e) {
+        console.warn(`[openclaw] rotateSessionsIfContractChanged failed: ${e?.message ?? e}`);
+    }
+}
+/**
+ * Inject a guarded section into the agent's TOOLS.md telling the LLM that
+ * user files live on the local filesystem (host==container bind mount),
+ * not on some remote "drive server", and showing the concrete
+ * resolve-then-send chain for IM channels (Feishu / WeChat).
+ *
+ * Why this exists: the LLM defaults to interpreting `drive` as a remote
+ * service, then refuses to send NAS files via IM with "I can't access the
+ * cloud drive" — even when `drive_list` literally just enumerated them.
+ * Verified on pi2 2026-05-11: claw1 saw `文档/宇树G1-D...xlsx` via
+ * drive_list, then told the user to "open Feishu cloud space and forward
+ * it back" because nothing in TOOLS.md tied drive paths to filesystem
+ * paths. This patcher closes that gap by spelling it out.
+ *
+ * Idempotent: section is bracketed by HTML markers; content between them
+ * is rewritten on every call. User edits OUTSIDE the markers are kept.
+ *
+ * filesRoot is baked in so the example abs path matches the actual install
+ * — third-party users on `/home/alice/.jishushell/files/` see their own
+ * root, not pi's.
+ */
+export function patchToolsMdDriveHint(workspaceDir, filesRoot) {
+    try {
+        const toolsPath = join(workspaceDir, "TOOLS.md");
+        let original = "";
+        try {
+            original = readFileSync(toolsPath, "utf-8");
+        }
+        catch (e) {
+            if (e?.code !== "ENOENT")
+                throw e;
+        }
+        const section = [
+            JISHUSHELL_DRIVE_HINT_BEGIN,
+            "",
+            "### 📁 用户的 NAS / 文件库",
+            "",
+            "⚠️ **用户文件操作硬路由 — 必读**",
+            "",
+            "**单一规则（语言无关）**：用户用任何语言（中文 / English / 日本語 / ...）说「**我的 / 我的 / my / mine / our / the user's / 私の**」+ 任何文件/目录/资料/笔记/文档/代码/data/notes/docs/files → **CRUD 全部走 `drive.*` 工具，禁止用 shell 在 cwd 上操作**。判定按**语义**不按**字面**，本表只是举例。",
+            "",
+            "动作 ↔ 工具映射表（用户文件场景，中英混排示例）：",
+            "",
+            "| 用户意图（多语言示例） | ✅ 必须用 | ❌ 禁止 |",
+            "|---|---|---|",
+            "| list / show / 「列一下 / 我有什么 / 看看我的 / what files do I have / show me my docs / list my files」 | `drive_list` | `ls`, `find`, `pwd` |",
+            "| read / open / 「打开 / 看看 / 念一下 / 内容是啥 / open my X / read the content of / what's in」 | `drive_read_preview` / `drive_read_full` | `cat`, `head`, `tail` |",
+            "| search / find / 「搜 / 找一下 / 哪里提到 / search my docs for / find X in my files / where did I write about」 | `drive_search` | `grep`, `rg` |",
+            "| write / save / create / 「写 / 存 / 记一下 / 新建 / save this as / write a note / create a file」 | `drive_write_text` / `drive_write_binary` | `echo >`, `cat <<EOF`, `tee` |",
+            "| delete / remove / 「删 / 扔掉 / delete X / remove the file」 | `drive_delete` | `rm` |",
+            "| rename / move / 「改名 / 挪到 / 移到 / rename X to Y / move X to」 | `drive_move` | `mv` |",
+            "| mkdir / 「建文件夹 / create a folder / make a directory」 | `drive_mkdir` | `mkdir` |",
+            "| quota / space / 「配额 / 空间 / how much space / quota / disk usage」 | `drive_quota` | `df`, `du` |",
+            "| send / share / 「发给我 / 把 X 发出去 / send me X / share the file with me」 | `drive_resolve_local_path` → IM `send_file` | （拒绝 / refuse） |",
+            "",
+            "**触发词不完全列表（再次强调：语义优先）**：",
+            "- 中文：我的、我那份、我之前的、我刚刚的、用户的、咱们的、文件、文档、资料、笔记、报告、合同、PDF、Excel、附件",
+            "- English: my, mine, our, the user's, files, file, doc(s), document(s), note(s), paper(s), report(s), spreadsheet(s), pdf(s), attachment(s)",
+            "- 其它语言：私の (ja) / mes (fr) / mein (de) / 我的 (variants) — 含义相同时同等处理",
+            "",
+            "**为什么硬规定**：cwd 是你自己的运行骨架（`AGENTS.md`、`TOOLS.md`、`memory/`、`state/`、`config/`），跟用户**毫无关系**。",
+            "- 用户问「我有什么文件 / what files do I have」你 `ls` cwd → 列出 `AGENTS.md`、`memory/` → 用户懵 + 觉得 jishushell 装错了",
+            "- 用户说「帮我写笔记 notes.md / save a note for me」你 `echo > notes.md` 落 cwd → 文件落到 agent 工作目录，用户在 filebrowser 看不到 → 数据等于丢了",
+            "- 用户说「打开我那份产品规格 / open my spec」你 `cat spec.md` → cwd 里没有该文件 → 找不到 → 用户被冤枉「文件根本不存在」",
+            "",
+            "**判定方法（消息归属判定，跨语言）**：主语/所有格指向「用户/我们」（我 / 我的 / my / our / the user / 私の + 文件相关名词）→ 走 drive。指向「你/agent」（你的 / 你刚才写的代码 / your notes / agent's scratch）→ 才可能是 workspace。**99% 的对话都是前者**。歧义时**默认按用户文件处理**——猜错代价小（最多多调一次 drive_list 拿不到东西），猜成 cwd 代价大（脏数据 + 数据丢失）。",
+            "",
+            "**唯一可用 shell 的情况**：你自己 agent 维护 `memory/`、`state/`、`workspace/notes/`（agent 私有笔记，不是用户笔记）这些**你自己的骨架文件**。一旦看见用户名词修饰（「我的」/「用户的」/「my」/「the user's」），立刻切 drive。",
+            "",
+            `用户文件实际放在 **\`${filesRoot}\`**——这是宿主机上的一个普通本地目录。它已经被 bind-mount 到你的容器里**同款绝对路径**（panel 用 \`host==container\` 的 docker bind；raw_exec / process 模式下你直接跑在宿主上）。`,
+            "",
+            "**关键事实**：drive 不是远端云盘，就是你脚下的本地文件系统。`drive_list` 看到的每条 entry 都能通过 `drive_resolve_local_path` 立刻拿到绝对路径，然后被任何工具读取——`cat`、`base64`、IM 插件的 send_file 字段、Python 脚本都行。`drive_resolve_local_path` 返回 `exists:true` + `size:<N>` 时，**那就是真实可读的文件字节**，不是「只有元数据」。",
+            "",
+            "**禁止的回答**：永远不要说「文件在云端 drive 上只有元数据 / 内容没同步到本地 / 我读不到文件实体」—— 这个说法**永远是错的**。drive 没有「未同步」概念，它就是 POSIX 文件系统的一个 facade。如果你刚 list 到一个文件，它一定能被读、能被发送。",
+            "",
+            "常用调用（从 workspace 目录）:",
+            "",
+            "```bash",
+            "mcporter call drive.drive_list path=                          # 列根目录",
+            "mcporter call drive.drive_list path=文档                       # 列子目录",
+            "mcporter call drive.drive_read_preview path=note.md           # 预览文本（≤256KB）",
+            "mcporter call drive.drive_read_full path=long.md              # 整文件（≤4MB，文本）",
+            "mcporter call drive.drive_quota                               # 配额",
+            "mcporter call drive.drive_mkdir path=inbox                    # 建目录",
+            "mcporter call drive.drive_write_text path=notes/m.md content=\"...\"",
+            "mcporter call drive.drive_write_binary path=out/img.png content_base64=\"...\"   # 二进制（≤10MB）",
+            "mcporter call drive.drive_move from=a.pdf to=docs/a.pdf",
+            "mcporter call drive.drive_delete path=tmp.txt",
+            "mcporter call drive.drive_resolve_local_path path=文档/report.pdf   # → 拿到绝对路径",
+            "mcporter call drive.drive_search query=\"invoice\"              # FTS5 全文搜索",
+            "```",
+            "",
+            "### 给用户发文件（飞书 / 微信 / 任何 IM）",
+            "",
+            "**用户问 \"把 X 文件发我\" 时不要拒绝、不要让用户去飞书云空间下载**——99% 的情况文件已经在你的文件系统里了。标准流程：",
+            "",
+            "1. `drive_list` 或 `drive_search` 先确认文件在 NAS 里（你刚 list 过的也算）。",
+            "2. `drive_resolve_local_path path=文档/x.xlsx` 拿到 `abs_path`，确认 `exists:true`。",
+            "3. 把 `abs_path` 传给**当前会话所在 IM 通道**的发送工具。**`target` 字段一律原样照搬当前消息 `Conversation info` 里的 `chat_id`——一个字符都不要加、不要改、不要补前缀**。各通道 chat_id 形态本来就不一样，照搬就对。",
+            "   - **飞书 DM**：metadata 给 `\"chat_id\":\"user:ou_xxx\"`（自带 `user:` 前缀，**这是飞书的格式不是通用约定**）→ `target=\"user:ou_xxx\"`。工具用 `message` (channel=feishu, msg_type=file, path=<abs_path>) 或 `openclaw-lark` 的 `feishu_im_user_message`。",
+            "   - **微信 DM**：metadata 给 `\"chat_id\":\"o9cq...@im.wechat\"`（**裸 ID，没有 `user:` 前缀**）→ `target=\"o9cq...@im.wechat\"`。工具用 `message` (channel=openclaw-weixin, msg_type=file, path=<abs_path>)。**千万别照搬飞书的 `user:` 加上去**——会让微信服务端的 `getuploadurl` 返 `ret:-1`，文件传不出去。",
+            "   - 通用规则：当前 inbound 消息的 `from` 就是回复 target。打开你刚收到的那条 user message 里 `Conversation info` 的 JSON，把 `chat_id` 整段复制就行。",
+            "4. 失败先查 `exists` 字段、文件大小、IM 通道大小上限（飞书典型 30MB、微信 20MB），再决定降级方案。",
+            "",
+            "**ENOENT / \"no such file or directory\" 处理**：IM 插件返回 ENOENT 但 `drive_resolve_local_path` 刚刚 `exists:true`，**99% 是 panel 刚升级 / mount 刚刷新，但你这个 alloc 用的是旧 spec**。无脑重试一次。还是 ENOENT 才提示用户去 panel 重启实例（stop+start，不是 restart）——但**永远不要**回答 \"文件只是元数据所以读不到\"，那是错的。",
+            "",
+            "要发**新生成**的文件（PDF、图片、报表）：先 `drive_write_binary path=agent-data/<instance>/outbox/x.pdf content_base64=...` 落盘，再 resolve → 发送。",
+            "",
+            "### 用户给你发文件",
+            "",
+            "目前飞书/微信通道不会自动把附件落盘到 NAS。当用户说\"文件给你了\"但你 `drive_list inbox` 看不到：",
+            "- 优先让用户走 panel 的 Filebrowser（`/apps/filebrowser/`）或 WebDAV 把文件上传到 `inbox/`，再告诉你路径。",
+            "- 飞书附件流：如果飞书 app 已配 `im:resource` 权限，可以用 `feishu_im_user_fetch_resource` 取 file_key、落到 `inbox/feishu/<date>/`。",
+            "",
+            "权限：在 panel \"关联 agent\" UI 里给实例授 ro/rw。403 时让用户去 panel 加。",
+            "",
+            JISHUSHELL_DRIVE_HINT_END,
+            "",
+        ].join("\n");
+        let next;
+        const beginIdx = original.indexOf(JISHUSHELL_DRIVE_HINT_BEGIN);
+        const endIdx = original.indexOf(JISHUSHELL_DRIVE_HINT_END);
+        if (beginIdx >= 0 && endIdx > beginIdx) {
+            const tail = endIdx + JISHUSHELL_DRIVE_HINT_END.length;
+            const after = original
+                .slice(tail)
+                .replace(/^\n+/, "\n");
+            next = original.slice(0, beginIdx) + section + after;
+        }
+        else {
+            const sep = original && !original.endsWith("\n") ? "\n\n" : "\n";
+            next = (original ? original + sep : "") + section;
+        }
+        if (next === original)
+            return;
+        writeConfigFile(toolsPath, next);
+        console.log(`[openclaw] Patched drive hint into ${toolsPath}`);
+    }
+    catch (e) {
+        console.warn(`[openclaw] Failed to patch TOOLS.md drive hint: ${e.message}`);
+    }
+}
+/**
+ * Inject a guarded section into TOOLS.md describing the kb_search MCP
+ * tool — only when an AnythingLLM-backed knowledge base is wired into
+ * this instance. Mirrors patchToolsMdDriveHint's marker model so an
+ * uninstall / unbind can cleanly strip the section.
+ *
+ * `mode === "install"` writes the kb hint between the markers
+ * (overwriting any previous content there). `mode === "remove"`
+ * deletes the entire bracketed section, leaving the user's
+ * surrounding content intact.
+ */
+export function patchToolsMdKbHint(workspaceDir, mode) {
+    try {
+        const toolsPath = join(workspaceDir, "TOOLS.md");
+        let original = "";
+        try {
+            original = readFileSync(toolsPath, "utf-8");
+        }
+        catch (e) {
+            if (e?.code !== "ENOENT")
+                throw e;
+            if (mode === "remove")
+                return; // nothing to strip
+        }
+        // Strip every existing kb section first — tolerant of legacy variants
+        // (e.g. early manual injections that used "END auto-generated -->"
+        // instead of the current "END -->" marker). Without this, repeated
+        // re-patches would accumulate sections in TOOLS.md.
+        const STRIP_RE = /\n*<!-- jishushell-kb: BEGIN[^>]*-->[\s\S]*?<!-- jishushell-kb: END[^>]*-->\n*/g;
+        const stripped = original.replace(STRIP_RE, "\n");
+        let next;
+        if (mode === "remove") {
+            if (stripped === original)
+                return;
+            next = stripped;
+        }
+        else {
+            const section = [
+                JISHUSHELL_KB_HINT_BEGIN,
+                "",
+                "### 📚 知识库（AnythingLLM）",
+                "",
+                "用户长期投递的文档（手册、PDF、内部笔记、过往会议纪要等）由 **AnythingLLM** 维护索引（本地 LanceDB 向量库 + 内置 Xenova ONNX embedder），通过 `kb.kb_search` 一次调用拿「答案 + 引用来源」。",
+                "",
+                "**两个工具**：",
+                "",
+                "- `mcporter call kb.kb_search query=\"<用户原话>\"` — 在已索引文档里检索，返回答案 + 最多 5 条引用源",
+                "- `mcporter call kb.kb_ingest path=\"<绝对路径>\"` — 把 drive 里的文件加入知识库并 embed（用户说「加进知识库 / index this / 学习这份」时调）",
+                "",
+                "**ingest 标准链**（drive 里的文件 → 知识库）：",
+                "1. `mcporter call drive.drive_resolve_local_path path=inbox/contract.pdf` → 拿 `abs_path`",
+                "2. `mcporter call kb.kb_ingest path=<abs_path>` → AnythingLLM 自动 embed",
+                "3. 几秒后用户问相关问题，`kb_search` 命中",
+                "",
+                "**search 什么时候调**：用户问的东西像在已上传文档里能找到——「那个 X 的手册里怎么说」、「我们之前关于 Y 的讨论」、「产品规格」、「合同条款」、「what does the doc say about X」等。",
+                "",
+                "**什么时候不要调**：寒暄、纯代码生成、数学计算、实时信息（天气/股票/新闻）、**操作 NAS 文件**（那是 `drive.*`，不是 kb）、纯创作类。",
+                "",
+                "**与 drive 的分工**：",
+                "- `drive.*` = 文件系统 facade（列目录、读字节、发文件）—— 要的是**文件本体**用 drive",
+                "- `kb.kb_search` / `kb.kb_ingest` = 语义检索 + RAG 入库 —— 要的是**答案/知识**用 kb",
+                "",
+                "两者数据**不共享**：drive 看到 `manual.pdf` ≠ kb 一定能搜到它。要让 kb 能搜到 → 先 `kb_ingest`。",
+                "",
+                "**搜不到时的标准回复**：`kb_search` 回答里说「无相关文档」或 sources 为空 → 先确认 drive 里有没有相关文件，如果有，主动建议「要我把它加入知识库吗」（用户同意就 `drive_resolve_local_path` + `kb_ingest`）；drive 也没有，告诉用户「我在你的知识库里没找到相关内容」，然后**不要继续幻想答案**。",
+                "",
+                JISHUSHELL_KB_HINT_END,
+                "",
+            ].join("\n");
+            const sep = stripped && !stripped.endsWith("\n") ? "\n\n" : "\n";
+            next = (stripped ? stripped + sep : "") + section;
+        }
+        if (next === original)
+            return;
+        writeConfigFile(toolsPath, next);
+        console.log(`[openclaw] ${mode === "remove" ? "Removed" : "Patched"} kb hint in ${toolsPath}`);
+    }
+    catch (e) {
+        console.warn(`[openclaw] Failed to ${mode} TOOLS.md kb hint: ${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
@@ -466,7 +1028,368 @@ function ensureOpenclawUpdateSeed(openclawHome, instanceId) {
         console.warn(`[openclaw] update-seed ${instanceId}: failed to create seed: ${err?.message ?? err}`);
     }
 }
-// ── Resource helpers (migrated from nomad-manager.ts) ─────────────────
+// ── Session fence patch (OpenClaw >= 5.19 regression) ─────────────────
+/**
+ * The minimum OpenClaw version where the session fence bug exists.
+ * The bug was introduced in v2026.5.19 — `eventMayReachTranscriptWriters()`
+ * doesn't recognize `"message"` / `"custom_message"` event types, causing
+ * session writes to bypass `withSessionWriteLock`, which in turn leaves
+ * the file fingerprint stale and triggers `EmbeddedAttemptSessionTakeoverError`
+ * on the next prompt.
+ *
+ * Additionally, on virtiofs mounts (macOS → Colima VM → Docker), file
+ * metadata (mtime/ctime) can drift between `releaseForPrompt()` and
+ * `assertSessionFileFence()` even without actual writes, due to the
+ * multi-layer filesystem stack timing. Patching `assertSessionFileFence`
+ * to a no-op fully disables the flawed fence check.
+ */
+const SESSION_FENCE_BUG_MIN_VERSION = [2026, 5, 19];
+/**
+ * Maximum version (exclusive) to apply the patch. Once OpenClaw ships a fix
+ * upstream, set a concrete version here to stop patching newer releases.
+ * For now, no upper bound — patch all versions >= MIN.
+ */
+/**
+ * Safety limit: if the extracted function body exceeds this many characters,
+ * skip the patch to avoid corrupting the bundle (e.g. brace-depth counter
+ * fooled by string literals containing braces in a future refactored version).
+ */
+const MAX_PATCH_TARGET_BODY_LENGTH = 5000;
+/**
+ * Patch targets: each entry defines a function to replace.
+ * - `eventMayReachTranscriptWriters`: broad return prevents events from
+ *   bypassing the write lock (necessary but not sufficient on virtiofs).
+ * - `assertSessionFileFence`: no-op disables the fingerprint comparison
+ *   that false-triggers due to virtiofs stat drift.
+ */
+const SESSION_FENCE_PATCH_TARGETS = [
+    {
+        fnName: "function assertSessionFileFence()",
+        litNeedle: "sameSessionFileFingerprint",
+        replacement: "function assertSessionFileFence() { return; }",
+    },
+    {
+        fnName: "function eventMayReachTranscriptWriters",
+        litNeedle: '"message_update"',
+        replacement: 'function eventMayReachTranscriptWriters(session, event) { return typeof event?.type === "string"; }',
+    },
+];
+/**
+ * Patch the session fence bug in OpenClaw >= 5.19 by replacing the
+ * `eventMayReachTranscriptWriters` function in the minified bundle.
+ *
+ * Idempotent: uses a marker file containing the SHA-256 of the patched
+ * file. Skips if already patched or if the pattern is not found (future
+ * fixed version or different bundle layout).
+ *
+ * Docker-only: the bug manifests through the virtiofs mount timing
+ * discrepancy between container and host — raw_exec/process modes are
+ * unaffected in practice.
+ */
+export function patchSessionFenceBug(openclawHome, instanceId) {
+    if (getNomadDriver() !== "docker")
+        return;
+    // 1. Read installed version from npm-global package.json
+    const pkgPath = join(openclawHome, ".npm-global", "lib", "node_modules", "openclaw", "package.json");
+    let versionStr;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        versionStr = pkg.version || "";
+    }
+    catch {
+        return; // no npm-global install or unreadable — skip
+    }
+    // 2. Parse version and check minimum threshold
+    const parts = versionStr.split(".").map(Number);
+    if (parts.length < 3 || parts.some(Number.isNaN))
+        return;
+    const [major, minor, patch] = parts;
+    const [minMajor, minMinor, minPatch] = SESSION_FENCE_BUG_MIN_VERSION;
+    if (major < minMajor ||
+        (major === minMajor && minor < minMinor) ||
+        (major === minMajor && minor === minMinor && patch < minPatch)) {
+        return; // version predates the bug
+    }
+    // 3. Find the selection-*.js bundle that contains the target function.
+    //    There may be multiple selection-*.js files in dist/; only one holds
+    //    the session management code.
+    const distDir = join(openclawHome, ".npm-global", "lib", "node_modules", "openclaw", "dist");
+    let bundleFiles;
+    try {
+        const entries = readdirSync(distDir);
+        bundleFiles = entries.filter((f) => f.startsWith("selection-") && f.endsWith(".js"));
+    }
+    catch {
+        return; // dist dir missing or unreadable
+    }
+    if (bundleFiles.length === 0)
+        return;
+    // Scan each candidate for any of the patch target signatures
+    let bundlePath;
+    let bundleContent;
+    for (const file of bundleFiles) {
+        const candidatePath = join(distDir, file);
+        let content;
+        try {
+            content = readFileSync(candidatePath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        // Match if any target's fnName or litNeedle is present
+        const hasTarget = SESSION_FENCE_PATCH_TARGETS.some((t) => content.includes(t.fnName) || content.includes(t.litNeedle));
+        if (hasTarget) {
+            bundlePath = candidatePath;
+            bundleContent = content;
+            break;
+        }
+    }
+    if (!bundlePath || !bundleContent)
+        return;
+    // 4. Check marker file for idempotency
+    const markerPath = join(distDir, `.session-fence-patched`);
+    const currentHash = createHash("sha256").update(bundleContent).digest("hex");
+    try {
+        const marker = readFileSync(markerPath, "utf-8").trim();
+        if (marker === currentHash)
+            return; // already patched, hash matches
+    }
+    catch {
+        // marker missing — proceed
+    }
+    // 5. Apply each patch target using brace-depth counting to extract and
+    //    replace function bodies. Process targets in order; earlier patches
+    //    shift offsets so we re-search after each replacement.
+    let patched = bundleContent;
+    let patchCount = 0;
+    for (const target of SESSION_FENCE_PATCH_TARGETS) {
+        let fnStart = patched.indexOf(target.fnName);
+        // Fallback for eventMayReachTranscriptWriters: locate by unique literal
+        // combination ("message_update" near "message_end" and "agent_end")
+        if (fnStart === -1 && target.litNeedle === '"message_update"') {
+            let scanPos = 0;
+            while (scanPos < patched.length) {
+                const litIdx = patched.indexOf(target.litNeedle, scanPos);
+                if (litIdx === -1)
+                    break;
+                const window = patched.slice(litIdx, litIdx + 200);
+                if (window.includes('"message_end"') && window.includes('"agent_end"')) {
+                    const searchStart = Math.max(0, litIdx - 300);
+                    const prefix = patched.slice(searchStart, litIdx);
+                    const fnKeywordIdx = prefix.lastIndexOf("function ");
+                    if (fnKeywordIdx !== -1) {
+                        fnStart = searchStart + fnKeywordIdx;
+                        break;
+                    }
+                }
+                scanPos = litIdx + 1;
+            }
+        }
+        if (fnStart === -1)
+            continue; // target not found (already patched or fixed version)
+        // Check if already patched (replacement is short and contains `return;`)
+        const peekEnd = Math.min(fnStart + target.replacement.length + 10, patched.length);
+        const peek = patched.slice(fnStart, peekEnd);
+        if (peek.startsWith(target.replacement))
+            continue;
+        // Extract function body with brace-depth counting
+        const braceStart = patched.indexOf("{", fnStart);
+        if (braceStart === -1)
+            continue;
+        let depth = 0;
+        let fnEnd = -1;
+        for (let i = braceStart; i < patched.length; i++) {
+            if (patched[i] === "{")
+                depth++;
+            else if (patched[i] === "}") {
+                depth--;
+                if (depth === 0) {
+                    fnEnd = i + 1;
+                    break;
+                }
+            }
+        }
+        if (fnEnd === -1)
+            continue;
+        // Safety: if extracted body is suspiciously large, skip to avoid corrupting
+        // the bundle (brace counter may have been fooled by string contents).
+        if (fnEnd - fnStart > MAX_PATCH_TARGET_BODY_LENGTH) {
+            console.warn(`[openclaw] session-fence-patch ${instanceId}: skipping ${target.fnName} — body too large (${fnEnd - fnStart} chars)`);
+            continue;
+        }
+        patched = patched.slice(0, fnStart) + target.replacement + patched.slice(fnEnd);
+        patchCount++;
+    }
+    if (patchCount === 0) {
+        // No targets needed patching — write marker for current state
+        try {
+            writeFileSync(markerPath, currentHash + "\n", "utf-8");
+        }
+        catch {
+            /* best effort */
+        }
+        return;
+    }
+    // 7. Atomic write: temp file → rename
+    const tmpPath = bundlePath + `.tmp.${randomBytes(4).toString("hex")}`;
+    try {
+        writeFileSync(tmpPath, patched, "utf-8");
+        renameSync(tmpPath, bundlePath);
+    }
+    catch (err) {
+        // Clean up temp file on failure
+        try {
+            unlinkSync(tmpPath);
+        }
+        catch {
+            /* ignore */
+        }
+        console.warn(`[openclaw] session-fence-patch ${instanceId}: atomic write failed: ${err?.message ?? err}`);
+        return;
+    }
+    // 8. Write marker with hash of the PATCHED file
+    const patchedHash = createHash("sha256").update(patched).digest("hex");
+    try {
+        writeFileSync(markerPath, patchedHash + "\n", "utf-8");
+    }
+    catch {
+        // Non-fatal — patch was applied, marker just helps idempotency
+    }
+    console.log(`[openclaw] session-fence-patch ${instanceId}: patched ${bundlePath.split("/").pop()} (v${versionStr})`);
+}
+// ── Container-side patch script ───────────────────────────────────────────
+/**
+ * Self-contained Node.js script that patches the session fence bug from
+ * INSIDE the container. Written to `$OPENCLAW_HOME/.jishushell/session-fence-patch.mjs`
+ * by onBeforeStart and executed by the custom entrypoint wrapper before
+ * the OpenClaw gateway starts.
+ *
+ * This covers the case where an in-container `npm install openclaw@latest`
+ * upgrades to a buggy version (>= 5.19) after the container was created
+ * with a clean image (5.7). The host-side `patchSessionFenceBug` cannot
+ * patch at onBeforeStart time because the npm-global directory may not yet
+ * contain the upgraded bundle (it's a dangling symlink to a container-only path).
+ */
+const CONTAINER_PATCH_SCRIPT = `#!/usr/bin/env node
+// Session fence patch — auto-generated by JishuShell.
+// Patches assertSessionFileFence + eventMayReachTranscriptWriters
+// in OpenClaw >= 2026.5.19 to work around virtiofs stat drift.
+import { readFileSync, writeFileSync, readdirSync, renameSync, existsSync } from "fs";
+import { join } from "path";
+import { createHash } from "crypto";
+
+const home = process.env.HOME || process.env.OPENCLAW_HOME || "/home/openclaw";
+const distDir = join(home, ".npm-global", "lib", "node_modules", "openclaw", "dist");
+const pkgPath = join(home, ".npm-global", "lib", "node_modules", "openclaw", "package.json");
+
+try {
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+  const parts = (pkg.version || "").split(".").map(Number);
+  if (parts.length < 3 || parts[0] < 2026 || (parts[0] === 2026 && parts[1] < 5) ||
+      (parts[0] === 2026 && parts[1] === 5 && parts[2] < 19)) process.exit(0);
+  // No upper version cap for now — patch all versions >= 5.19
+} catch { process.exit(0); }
+
+const markerPath = join(distDir, ".session-fence-patched");
+let files;
+try { files = readdirSync(distDir).filter(f => f.startsWith("selection-") && f.endsWith(".js")); }
+catch { process.exit(0); }
+
+const targets = [
+  { fn: "function assertSessionFileFence()", repl: "function assertSessionFileFence() { return; }" },
+  { fn: "function eventMayReachTranscriptWriters", repl: 'function eventMayReachTranscriptWriters(session, event) { return typeof event?.type === "string"; }' },
+];
+
+for (const file of files) {
+  const p = join(distDir, file);
+  let src;
+  try { src = readFileSync(p, "utf-8"); } catch { continue; }
+  if (!targets.some(t => src.includes(t.fn) || src.includes("sameSessionFileFingerprint"))) continue;
+
+  const hash = createHash("sha256").update(src).digest("hex");
+  try { if (readFileSync(markerPath, "utf-8").trim() === hash) process.exit(0); } catch {}
+
+  let modified = src;
+  let count = 0;
+  for (const t of targets) {
+    const idx = modified.indexOf(t.fn);
+    if (idx === -1) continue;
+    if (modified.slice(idx, idx + t.repl.length + 5).startsWith(t.repl)) continue;
+    const braceStart = modified.indexOf("{", idx);
+    if (braceStart === -1) continue;
+    let d = 0, end = -1;
+    for (let i = braceStart; i < modified.length; i++) {
+      if (modified[i] === "{") d++;
+      else if (modified[i] === "}") { d--; if (d === 0) { end = i + 1; break; } }
+    }
+    if (end === -1) continue;
+    if (end - idx > 5000) continue; // safety: skip if body suspiciously large
+    modified = modified.slice(0, idx) + t.repl + modified.slice(end);
+    count++;
+  }
+  if (count === 0) {
+    try { writeFileSync(markerPath, hash + "\\n"); } catch {}
+    process.exit(0);
+  }
+  const tmp = p + ".tmp." + Math.random().toString(36).slice(2, 8);
+  writeFileSync(tmp, modified);
+  renameSync(tmp, p);
+  const newHash = createHash("sha256").update(modified).digest("hex");
+  try { writeFileSync(markerPath, newHash + "\\n"); } catch {}
+  console.log("[session-fence-patch] patched " + file);
+  break;
+}
+`;
+/**
+ * The custom entrypoint wrapper that executes the patch script before
+ * deferring to the image's original entrypoint.
+ */
+const CONTAINER_ENTRYPOINT_WRAPPER = `#!/bin/sh
+# JishuShell session-fence-patch entrypoint wrapper
+PATCH="$HOME/.jishushell/session-fence-patch.mjs"
+if [ -f "$PATCH" ]; then
+  node "$PATCH" 2>/dev/null || true
+fi
+exec /usr/local/bin/openclaw-entry.sh "$@"
+`;
+/**
+ * Write the container-side patch script and entrypoint wrapper to the
+ * openclaw-home directory so they are available inside the container
+ * via the bind mount.
+ *
+ * Called from onBeforeStart. Idempotent — only writes if content changed.
+ */
+export function writeContainerPatchScript(openclawHome) {
+    const scriptDir = join(openclawHome, ".jishushell");
+    try {
+        mkdirSync(scriptDir, { recursive: true });
+    }
+    catch {
+        return;
+    }
+    const scriptPath = join(scriptDir, "session-fence-patch.mjs");
+    const wrapperPath = join(scriptDir, "entrypoint.sh");
+    // Write patch script (idempotent)
+    try {
+        const existing = readFileSync(scriptPath, "utf-8");
+        if (existing === CONTAINER_PATCH_SCRIPT) {
+            // Also check wrapper
+            const existingWrapper = readFileSync(wrapperPath, "utf-8");
+            if (existingWrapper === CONTAINER_ENTRYPOINT_WRAPPER)
+                return;
+        }
+    }
+    catch {
+        // file missing — write it
+    }
+    try {
+        writeFileSync(scriptPath, CONTAINER_PATCH_SCRIPT, { mode: 0o755 });
+        writeFileSync(wrapperPath, CONTAINER_ENTRYPOINT_WRAPPER, { mode: 0o755 });
+    }
+    catch {
+        /* best effort */
+    }
+}
 function resolveUidGid(username) {
     try {
         if (!VALID_USER_RE.test(username)) {
@@ -538,7 +1461,7 @@ 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) {
+async function _ensureDockerBaseImage(invocation, task) {
     try {
         execFileSync(invocation.cmd, [...invocation.argsPrefix, "image", "inspect", DOCKER_BASE_IMAGE], {
             timeout: 5000,
@@ -827,6 +1750,7 @@ class OpenClawAdapter {
                 // 3. Docker bridge patches
                 patchDockerBridgeGatewayBind(configPath);
                 patchJsproxyBaseUrl(configPath);
+                patchPrivateNetworkAllowFlag(configPath);
             }
             // Driver-agnostic: enable the OpenAI-compatible endpoints on every
             // start so the `llm-agent` capability advertised by openclaw-*.yaml
@@ -842,6 +1766,374 @@ class OpenClawAdapter {
             catch {
                 /* best effort */
             }
+            // 4a. Patch session fence bug in OpenClaw >= 5.19
+            try {
+                const home = openclawAdapter.resolveAgentHome(instanceId);
+                if (home) {
+                    patchSessionFenceBug(home, instanceId);
+                    // Also write the container-side patch script so that even if
+                    // the host-side patch couldn't apply (e.g. symlink to container
+                    // path), the container will self-patch on startup.
+                    if (getNomadDriver() === "docker") {
+                        writeContainerPatchScript(home);
+                    }
+                }
+            }
+            catch {
+                /* best effort — patch failure must not prevent start */
+            }
+            // 4b. Build the workspace symlink layout from this instance's
+            //     fileMounts (M1 W2). For docker mode, the corresponding
+            //     volume bindings are added in buildNomadTask below; for
+            //     raw_exec / process modes, the symlinks are sufficient
+            //     (no container layer between agent and host fs).
+            try {
+                const home = openclawAdapter.resolveAgentHome(instanceId);
+                const im = await lazyIm();
+                const runtime = im.getInstanceRuntime(instanceId);
+                const mounts = readFileMounts(runtime);
+                if (home) {
+                    const { rebuildWorkspace } = await import("../../workspace-builder.js");
+                    rebuildWorkspace({
+                        openclawHome: home,
+                        filesRoot: FILES_ROOT,
+                        mounts,
+                        instanceId,
+                    });
+                }
+            }
+            catch (e) {
+                // Surface migration-required clearly; otherwise fall back to a
+                // warning so a misconfigured mount cannot prevent instance start.
+                if (e?.reason === "needs-migration") {
+                    throw new Error(`instance ${instanceId} workspace contains pre-W2 user data; run legacy migration first (${e.message})`);
+                }
+                console.warn(`[openclaw] workspace rebuild skipped: ${e?.message ?? e}`);
+            }
+            // 4b-bis. Patch TOOLS.md with the drive-shim hint so the agent
+            //      understands user files are local (host==container bind) and
+            //      knows the resolve→send chain for IM channels. Without this,
+            //      the LLM defaults to "drive = remote cloud service" and
+            //      refuses to send NAS files via Feishu/WeChat. Runs after the
+            //      workspace rebuild because that step creates the workspace
+            //      tree if missing.
+            try {
+                const home = openclawAdapter.resolveAgentHome(instanceId);
+                if (home) {
+                    patchToolsMdDriveHint(join(home, ".openclaw", "workspace"), FILES_ROOT);
+                }
+            }
+            catch (e) {
+                console.warn(`[openclaw] TOOLS.md drive hint skipped: ${e?.message ?? e}`);
+            }
+            // 4b-ter. Rotate stale session jsonl(s) when the runtime contract
+            //      bumps. This is the auto-recovery path for panel upgrades
+            //      that fix runtime bugs the agent has already "concluded
+            //      around" inside an existing session — without rotation the
+            //      LLM keeps citing past failures and refusing to retry even
+            //      after the underlying bug is fixed. Idempotent: after the
+            //      first onBeforeStart post-upgrade writes the new marker,
+            //      subsequent starts are no-ops.
+            try {
+                const home = openclawAdapter.resolveAgentHome(instanceId);
+                if (home)
+                    rotateSessionsIfContractChanged(instanceId, home);
+            }
+            catch (e) {
+                console.warn(`[openclaw] session rotation skipped: ${e?.message ?? e}`);
+            }
+            // 4c. Install the drive MCP shim so the agent can call panel
+            //     file/organize APIs from chat (M1 W1.6). Idempotent — we
+            //     overwrite the shim file every start to pick up fixes, and
+            //     mergeMcporterServers marks the entry with __source so user-
+            //     managed mcporter entries are preserved untouched.
+            try {
+                const home = openclawAdapter.resolveAgentHome(instanceId);
+                if (home) {
+                    const { substituteDriveShimPlaceholders } = await import("../mcp-shims/drive-shim.js");
+                    const { mergeMcporterServers } = await import("./openclaw-mcporter.js");
+                    const { getInternalMcpToken } = await import("../../../config.js");
+                    // Pick the panel URL based on how THIS instance will actually run.
+                    // For a containerized instance (raw_exec/docker via Nomad with a
+                    // docker image), `host.docker.internal:8090` resolves through the
+                    // bridge gateway. For a host-process / binary spec under Nomad
+                    // raw_exec, the task gets its own network namespace where
+                    // 127.0.0.1 only reaches the task itself — must use the host's
+                    // LAN IPv4 so the shim's fetch crosses back into the host netns.
+                    // Detected via the instance's resolved runtime: container tasks
+                    // carry `runtime.image`, binary tasks carry only `runtime.command`.
+                    let drivePanelUrl = "http://host.docker.internal:8090";
+                    try {
+                        const im2 = await lazyIm();
+                        const rt = im2.getInstanceRuntime(instanceId);
+                        if (!rt?.image) {
+                            const { getPanelLanHost, getPanelPort } = await import("../../../config.js");
+                            drivePanelUrl = `http://${getPanelLanHost()}:${getPanelPort()}`;
+                        }
+                    }
+                    catch {
+                        // Best effort — fall through to host.docker.internal default
+                    }
+                    const shimDir = join(home, "__mcp_shims__", "drive");
+                    ensureDirContainer(shimDir);
+                    const shimPath = join(shimDir, "drive-shim.mjs");
+                    // Bake panelUrl/token/instanceId into the shim source so it works
+                    // even when OpenClaw scrubs env on MCP subprocess spawn (verified
+                    // 2026-05-11 on pi2: env scrub made the shim default to the
+                    // unreachable host.docker.internal and surface as "fetch failed").
+                    const internalToken = getInternalMcpToken();
+                    const shimSource = substituteDriveShimPlaceholders({
+                        panelUrl: drivePanelUrl,
+                        token: internalToken,
+                        instanceId,
+                    });
+                    writeFileSync(shimPath, shimSource, { mode: 0o755 });
+                    mergeMcporterServers(instanceId, {
+                        drive: {
+                            command: "node",
+                            args: [shimPath],
+                            env: {
+                                // Env still set as a belt-and-suspenders. With baked-in
+                                // values in the shim source itself, these become a fallback
+                                // for dev/manual testing — production never depends on them.
+                                JISHUSHELL_INTERNAL_TOKEN: internalToken,
+                                JISHUSHELL_INSTANCE_ID: instanceId,
+                                JISHUSHELL_PANEL_URL: drivePanelUrl,
+                            },
+                            __source: {
+                                kind: "connection",
+                                slot: "drive",
+                                consumerInstanceId: instanceId,
+                            },
+                        },
+                    });
+                }
+            }
+            catch (e) {
+                console.warn(`[openclaw] drive shim install skipped: ${e?.message ?? e}`);
+            }
+            // 4c-quater. Auto-wire AnythingLLM kb shim. The Connections-tab
+            //      knowledge slot (declared as `requires: knowledge` on the
+            //      OpenClaw spec, persisted under `instance.connections.KNOWLEDGE_BASE_URL`)
+            //      is honored here, so unbinding in the UI actually takes effect.
+            //      Three states (matching connection-resolver.ts):
+            //
+            //        - `null`             → user explicitly disconnected → DO NOT
+            //                               inject (and strip any prior shim).
+            //        - explicit binding   → inject only if it points at the
+            //                               anythingllm-container provider; any
+            //                               other choice means user wants a
+            //                               different kb provider that we don't
+            //                               yet ship a shim for.
+            //        - undefined          → no opinion → fall back to the
+            //                               historical "auto-on when AnythingLLM
+            //                               credentials.json exists" UX.
+            //
+            //      Secrets handling (defense-in-depth):
+            //        - shim source (mode 0o644) carries baseUrl + workspace only;
+            //          the API key lives in a sibling `secret.json` (0o600).
+            //        - mcporter.json (0o644) env carries only non-secret hints
+            //          for hand-running. Production shim reads the secret file.
+            try {
+                const home = openclawAdapter.resolveAgentHome(instanceId);
+                if (home) {
+                    const instMeta = getInstance(instanceId);
+                    const kbBinding = instMeta?.connections?.KNOWLEDGE_BASE_URL;
+                    let bindingAllowsInject = true;
+                    if (kbBinding === null) {
+                        bindingAllowsInject = false;
+                    }
+                    else if (kbBinding && typeof kbBinding === "object") {
+                        if (kbBinding.kind === "single") {
+                            bindingAllowsInject = kbBinding.providerId === "anythingllm-container";
+                        }
+                        else if (kbBinding.kind === "many") {
+                            const providers = Array.isArray(kbBinding.providers) ? kbBinding.providers : [];
+                            bindingAllowsInject = providers.some((p) => p?.providerId === "anythingllm-container");
+                        }
+                    }
+                    const credPath = join(JISHUSHELL_HOME, "apps", "anythingllm-container", "credentials.json");
+                    let kbCreds = null;
+                    if (bindingAllowsInject && existsSync(credPath)) {
+                        try {
+                            kbCreds = JSON.parse(readFileSync(credPath, "utf-8"));
+                        }
+                        catch (e) {
+                            console.warn(`[openclaw] kb: invalid credentials.json: ${e?.message ?? e}`);
+                        }
+                    }
+                    const wsDir = join(home, ".openclaw", "workspace");
+                    const shimDir = join(home, "__mcp_shims__", "anythingllm");
+                    const shimPath = join(shimDir, "anythingllm-shim.js");
+                    const secretPath = join(shimDir, "secret.json");
+                    const { mergeMcporterServers, removeMcporterServers } = await import("./openclaw-mcporter.js");
+                    if (kbCreds?.apiKey && kbCreds?.baseUrl) {
+                        const { substituteAnythingllmShimPlaceholders } = await import("../mcp-shims/anythingllm-shim.js");
+                        ensureDirContainer(shimDir);
+                        const shimSource = substituteAnythingllmShimPlaceholders({
+                            baseUrl: kbCreds.baseUrl,
+                            workspace: kbCreds.workspace || "default",
+                        });
+                        writeFileSync(shimPath, shimSource, { mode: 0o644 });
+                        // chmod after write to dodge umask; secret.json must be 0o600.
+                        writeFileSync(secretPath, JSON.stringify({ apiKey: kbCreds.apiKey }), { mode: 0o600 });
+                        try {
+                            chmodSync(secretPath, 0o600);
+                        }
+                        catch { /* best effort */ }
+                        mergeMcporterServers(instanceId, {
+                            kb: {
+                                command: "node",
+                                args: [shimPath],
+                                env: {
+                                    // Belt-and-suspenders fallback for hand-running. Baked
+                                    // values in the shim source are the production source
+                                    // of truth for baseUrl + workspace; the API key is
+                                    // intentionally NOT placed here — it lives in
+                                    // `secret.json` (0o600) next to the shim so this 0o644
+                                    // file stays free of secrets.
+                                    ANYTHINGLLM_BASE_URL: kbCreds.baseUrl,
+                                    ANYTHINGLLM_WORKSPACE: kbCreds.workspace || "default",
+                                },
+                                __source: {
+                                    kind: "connection",
+                                    slot: "knowledge",
+                                    consumerInstanceId: instanceId,
+                                },
+                            },
+                        });
+                        patchToolsMdKbHint(wsDir, "install");
+                    }
+                    else {
+                        // Clean removal path (covers "AnythingLLM uninstalled / not
+                        // yet ready" AND "user explicitly unbound knowledge in
+                        // Connections tab" AND "user bound a different kb provider").
+                        removeMcporterServers(instanceId, {
+                            source: { kind: "connection", slot: "knowledge", consumerInstanceId: instanceId },
+                        });
+                        patchToolsMdKbHint(wsDir, "remove");
+                        try {
+                            if (existsSync(shimPath)) {
+                                writeFileSync(shimPath, "// removed: AnythingLLM not installed or knowledge unbound\n", { mode: 0o644 });
+                            }
+                        }
+                        catch { /* best effort */ }
+                        try {
+                            if (existsSync(secretPath))
+                                unlinkSync(secretPath);
+                        }
+                        catch { /* best effort */ }
+                    }
+                }
+            }
+            catch (e) {
+                console.warn(`[openclaw] kb shim wiring skipped: ${e?.message ?? e}`);
+            }
+            // 4c-bis. Self-heal MCPORTER_CONFIG env on existing instances. Without
+            //      this, mcporter can't find its config when invoked from the
+            //      gateway's CWD (openclaw-home/) or from the workspace symlink
+            //      (which points at user files, also no config/), so every drive
+            //      tool call fails with "Unknown MCP server 'drive'" and the agent
+            //      degrades into reporting a generic "network error". New instances
+            //      get this env via the binary/container runtime template; this
+            //      block back-fills it for instances created before that template
+            //      update so users don't have to recreate them.
+            try {
+                const im2 = await lazyIm();
+                const rt = im2.getInstanceRuntime(instanceId);
+                const home = openclawAdapter.resolveAgentHome(instanceId);
+                if (home && rt && (!rt.env || !rt.env.MCPORTER_CONFIG)) {
+                    const desired = `${home}/.openclaw/workspace/config/mcporter.json`;
+                    const nextEnv = { ...(rt.env || {}), MCPORTER_CONFIG: desired };
+                    im2.updateInstanceMeta(instanceId, { runtime: { ...rt, env: nextEnv } });
+                    console.log(`[openclaw] self-healed MCPORTER_CONFIG env for ${instanceId}`);
+                }
+            }
+            catch (e) {
+                console.warn(`[openclaw] MCPORTER_CONFIG self-heal failed: ${e?.message ?? e}`);
+            }
+            // 4d. Self-heal mcporter bin: chmod cli.js + replace the npm-installed
+            //      symlink at .npm-global/bin/mcporter with a wrapper that pins
+            //      `--config <abs path>`. The wrapper is required because:
+            //        (a) npm install on Pi/ARM64 sometimes leaves cli.js as 0644
+            //            instead of 0755 (despite a valid shebang). Without +x,
+            //            spawning the bin returns "Permission denied".
+            //        (b) The OpenClaw bash tool scrubs env when spawning agent tool
+            //            subprocesses, so MCPORTER_CONFIG env doesn't reach mcporter,
+            //            and mcporter falls back to CWD-relative `config/mcporter.json`.
+            //            The agent's CWD is openclaw-home/ (no config/) or the
+            //            workspace symlink (also no config/) → "Unknown MCP server
+            //            'drive'" → user sees "drive not configured" / "network
+            //            error" in chat.
+            //      The wrapper hardcodes both the cli.js path and the config path,
+            //      so it works regardless of CWD or env state.
+            //      Marker in wrapper body (`# jishushell mcporter wrapper`) lets us
+            //      detect when it's already installed and skip the rewrite.
+            try {
+                const home = openclawAdapter.resolveAgentHome(instanceId);
+                if (home) {
+                    const mcporterCli = join(home, ".npm-global", "lib", "node_modules", "mcporter", "dist", "cli.js");
+                    const mcporterBin = join(home, ".npm-global", "bin", "mcporter");
+                    const mcporterConfig = join(home, ".openclaw", "workspace", "config", "mcporter.json");
+                    if (existsSync(mcporterCli)) {
+                        const st = statSync(mcporterCli);
+                        if (!(st.mode & 0o111)) {
+                            chmodSync(mcporterCli, 0o755);
+                            console.log(`[openclaw] +x ${mcporterCli} (mcporter cli.js self-heal)`);
+                        }
+                    }
+                    // Wrapper install: only proceed when cli.js exists; otherwise
+                    // mcporter isn't installed and there's nothing to wrap.
+                    if (existsSync(mcporterCli)) {
+                        const wrapperMarker = "# jishushell mcporter wrapper";
+                        let needsInstall = true;
+                        try {
+                            if (existsSync(mcporterBin)) {
+                                const lst = lstatSync(mcporterBin);
+                                if (lst.isFile() && !lst.isSymbolicLink()) {
+                                    const first200 = readFileSync(mcporterBin, "utf8").slice(0, 200);
+                                    if (first200.includes(wrapperMarker))
+                                        needsInstall = false;
+                                }
+                            }
+                        }
+                        catch { /* fall through to install */ }
+                        if (needsInstall) {
+                            const wrapperSrc = `#!/bin/bash\n` +
+                                `${wrapperMarker} — pins --config so OpenClaw bash-tool env\n` +
+                                `# scrubbing or unexpected CWD cannot detach mcporter from the\n` +
+                                `# drive MCP server.  Auto-installed by adapter onBeforeStart\n` +
+                                `# (src/services/runtime/adapters/openclaw.ts).\n` +
+                                `exec node ${JSON.stringify(mcporterCli)} --config ${JSON.stringify(mcporterConfig)} "$@"\n`;
+                            // Remove first to handle symlink → regular file transition cleanly.
+                            try {
+                                unlinkSync(mcporterBin);
+                            }
+                            catch { /* may not exist */ }
+                            writeFileSync(mcporterBin, wrapperSrc, { mode: 0o755 });
+                            console.log(`[openclaw] installed mcporter wrapper at ${mcporterBin}`);
+                        }
+                        // UNCONDITIONAL chmod regardless of whether we just wrote or
+                        // detected an existing wrapper. writeFileSync's mode option is
+                        // ignored when the file already exists, and a prior run that
+                        // hit an umask issue may have left it 0644. Always force 0755
+                        // so the agent can exec the wrapper.
+                        try {
+                            if (existsSync(mcporterBin)) {
+                                const wst = statSync(mcporterBin);
+                                if (!(wst.mode & 0o111)) {
+                                    chmodSync(mcporterBin, 0o755);
+                                    console.log(`[openclaw] +x ${mcporterBin} (wrapper chmod self-heal)`);
+                                }
+                            }
+                        }
+                        catch { /* best effort */ }
+                    }
+                }
+            }
+            catch (e) {
+                console.warn(`[openclaw] mcporter self-heal failed: ${e?.message ?? e}`);
+            }
             // 5. Docker image validation + background pull fallback
             if (getNomadDriver() === "docker") {
                 const image = getOpenclawDockerImage();
@@ -1041,6 +2333,21 @@ class OpenClawAdapter {
                 runtime = { ...baseRuntime, ...compiled };
             }
         }
+        // W2: every new instance gets a default rw mount on its own
+        // agent-data/{id} subtree (alias _out). Cloned instances inherit
+        // their source's mounts but have agent-data path rewritten to the
+        // new instance id; we keep this simple here and just plant the
+        // default — clone-from semantics for additional mounts can be
+        // tightened in PR-7+ when migration arrives.
+        if (!runtime.fileMounts && !runtime.file_mounts) {
+            runtime.fileMounts = defaultMountsForNewInstance(instanceId);
+        }
+        try {
+            ensureMountTargets(FILES_ROOT, readFileMounts(runtime));
+        }
+        catch (e) {
+            console.warn(`[openclaw] could not pre-create mount targets for ${instanceId}: ${e?.message ?? e}`);
+        }
         const allocatedPort = extractGatewayPort(runtime);
         try {
             const meta = {
@@ -1323,12 +2630,14 @@ class OpenClawAdapter {
             throw new Error(`Invalid runtime user: ${rawRuntime.user}`);
         }
         const image = rawRuntime.image || getOpenclawDockerImage();
-        const command = String(rawRuntime.command || DEFAULT_COMMAND);
+        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));
+        decryptRuntimeProviderEnv(env);
+        injectProviderHostEnv(env, instanceId);
         delete env.JSPROXY_API_KEY; // supplied via Nomad Template from Variables
         env.OPENCLAW_HOME = openclawHome;
         env.OPENCLAW_INSTANCE_ID = instanceId;
@@ -1387,9 +2696,14 @@ class OpenClawAdapter {
                 // timeout is too short for Pi-class networks pulling a 1+ GiB
                 // openclaw runtime image; bump to 15 minutes.
                 image_pull_timeout: "15m",
+                // Use the JishuShell entrypoint wrapper that applies the session
+                // fence patch before deferring to the image's original entrypoint.
+                // The wrapper script is written to $HOME/.jishushell/entrypoint.sh
+                // by onBeforeStart (writeContainerPatchScript).
+                entrypoint: [`${openclawHome}/.jishushell/entrypoint.sh`],
                 args,
                 work_dir: openclawHome,
-                volumes: [`${openclawHome}:${openclawHome}:rw`],
+                volumes: buildVolumes(openclawHome, im.getInstanceRuntime(instanceId)),
                 // Tell the docker driver to publish the labeled "gateway" port so
                 // it routes via the host_network IP rather than the 127.0.0.1
                 // default.
@@ -1583,47 +2897,71 @@ class OpenClawAdapter {
      * dist bundle).
      */
     async applyConnectionEnv(instanceId, env) {
+        const configPath = openclawConfigPath(instanceId);
         const searchUrl = env.SEARCH_API_BASE_URL;
-        if (typeof searchUrl !== "string")
-            return;
-        if (searchUrl === "") {
-            // Empty value — connection-transactor's UNPERSIST_HOOKS uses this as
-            // the "unbind" signal. Clear the searxng plugin config so the next
-            // start doesn't keep routing web_search through a now-disconnected
-            // provider.
-            try {
-                clearSearxngConnectionFromConfig(openclawConfigPath(instanceId));
+        if (typeof searchUrl === "string") {
+            if (searchUrl === "") {
+                // Empty value — connection-transactor's UNPERSIST_HOOKS uses this as
+                // the "unbind" signal. Clear the searxng plugin config so the next
+                // start doesn't keep routing web_search through a now-disconnected
+                // provider.
+                try {
+                    clearSearxngConnectionFromConfig(configPath);
+                }
+                catch (e) {
+                    console.warn(`[openclaw] applyConnectionEnv search unbind failed for ${instanceId}: ${e.message}`);
+                }
             }
-            catch (e) {
-                console.warn(`[openclaw] applyConnectionEnv unbind failed for ${instanceId}: ${e.message}`);
+            else {
+                // SEARCH_API_BASE_URL points at "<base>/search" (the SearXNG search
+                // endpoint). The plugin's webSearch.baseUrl wants the bare origin —
+                // strip the trailing "/search" path segment if present.
+                // baseUrl stays at the registry-resolved host:port snapshot from
+                // when the user PUT /connections; the framework re-runs this hook
+                // on every instance start (PR 9 phaseRefreshConnections), so host
+                // IP changes propagate automatically on next agent restart.
+                let baseUrl = searchUrl;
+                try {
+                    const u = new URL(searchUrl);
+                    if (u.pathname === "/search" || u.pathname === "/search/") {
+                        u.pathname = "";
+                        baseUrl = u.toString().replace(/\/$/, "");
+                    }
+                    try {
+                        applySearxngConnectionToConfig(configPath, baseUrl);
+                    }
+                    catch (e) {
+                        console.warn(`[openclaw] applyConnectionEnv search merge failed for ${instanceId}: ${e.message}`);
+                    }
+                }
+                catch {
+                    // not a URL — skip silently; the openclaw plugin would break
+                    // with a non-URL baseUrl, and start should still proceed.
+                }
             }
-            return;
         }
-        // SEARCH_API_BASE_URL points at "<base>/search" (the SearXNG search
-        // endpoint). The plugin's webSearch.baseUrl wants the bare origin —
-        // strip the trailing "/search" path segment if present.
-        // baseUrl stays at the registry-resolved host:port snapshot from
-        // when the user PUT /connections; the framework re-runs this hook
-        // on every instance start (PR 9 phaseRefreshConnections), so host
-        // IP changes propagate automatically on next agent restart.
-        let baseUrl = searchUrl;
-        try {
-            const u = new URL(searchUrl);
-            if (u.pathname === "/search" || u.pathname === "/search/") {
-                u.pathname = "";
-                baseUrl = u.toString().replace(/\/$/, "");
+        const cdpUrl = env.BROWSER_CDP_URL;
+        if (typeof cdpUrl === "string") {
+            if (cdpUrl === "") {
+                try {
+                    clearBrowserlessConnectionFromConfig(configPath);
+                }
+                catch (e) {
+                    console.warn(`[openclaw] applyConnectionEnv browser unbind failed for ${instanceId}: ${e.message}`);
+                }
             }
-        }
-        catch {
-            // not a URL — abort, the openclaw plugin would silently break with
-            // a non-URL baseUrl and the instance still starts but search fails.
-            return;
-        }
-        try {
-            applySearxngConnectionToConfig(openclawConfigPath(instanceId), baseUrl);
-        }
-        catch (e) {
-            console.warn(`[openclaw] applyConnectionEnv merge failed for ${instanceId}: ${e.message}`);
+            else if (/^wss?:\/\//.test(cdpUrl)) {
+                try {
+                    applyBrowserlessConnectionToConfig(configPath, cdpUrl);
+                }
+                catch (e) {
+                    console.warn(`[openclaw] applyConnectionEnv browser merge failed for ${instanceId}: ${e.message}`);
+                }
+            }
+            // Non-ws scheme: skip silently. The connection-apply browser hook
+            // already builds ws:// from the capability protocol; an http:// here
+            // would mean a misconfigured provider — better to no-op than to
+            // write a URL OpenClaw can't dial.
         }
     }
     // ── Path resolvers (physically migrated) ───────────────────────────
@@ -2112,6 +3450,10 @@ function prepareConfigForSave(instanceId, config) {
         if (typeof p.api === "string" && p.api in LEGACY_PROVIDER_API_ALIASES) {
             p.api = LEGACY_PROVIDER_API_ALIASES[p.api];
         }
+        // Ensure allowPrivateNetwork for providers targeting the local proxy
+        if (typeof p.baseUrl === "string" && isPrivateNetworkBaseUrl(p.baseUrl)) {
+            p.request = { ...(p.request || {}), allowPrivateNetwork: true };
+        }
         if (!("apiKey" in p))
             continue;
         if (typeof p.baseUrl === "string" && p.baseUrl.includes("/proxy/"))
@@ -2119,7 +3461,7 @@ function prepareConfigForSave(instanceId, config) {
         const apiKey = p.apiKey;
         delete p.apiKey;
         if (envFiles.length) {
-            envUpdates[inferProviderApiKeyEnvName(providerId)] = String(apiKey || "");
+            envUpdates[inferProviderApiKeyEnvName(providerId)] = decryptRuntimeProviderApiKey(apiKey);
         }
         else {
             p.apiKey = apiKey;
@@ -2142,6 +3484,56 @@ function prepareConfigForSave(instanceId, config) {
     }
     return [configToWrite, envUpdates];
 }
+function decryptRuntimeProviderApiKey(apiKey) {
+    const value = String(apiKey || "");
+    return value.startsWith("enc:") ? decryptApiKey(value) : value;
+}
+function decryptRuntimeProviderEnv(env) {
+    for (const [key, value] of Object.entries(env)) {
+        if (!key.endsWith("_API_KEY"))
+            continue;
+        if (!String(value || "").startsWith("enc:"))
+            continue;
+        env[key] = decryptApiKey(value);
+    }
+}
+/**
+ * Auto-injects provider-specific host env vars that OpenClaw tools need
+ * at runtime, if the user hasn't already set them explicitly.
+ *
+ * Currently handles:
+ * - MINIMAX_API_HOST: Derived from MINIMAX_BASE_URL or upstream proxy config
+ *   to ensure the VLM tool calls the correct MiniMax API domain.
+ *
+ * Note: Only MiniMax needs this because its VLM tool reads MINIMAX_API_HOST
+ * to determine the endpoint. DeepSeek does not have a dedicated VLM tool
+ * in OpenClaw that requires a similar host env var.
+ */
+function injectProviderHostEnv(env, instanceId) {
+    // MINIMAX_API_HOST — needed by OpenClaw's VLM tool to call the correct domain
+    if (!env.MINIMAX_API_HOST) {
+        const baseUrl = env.MINIMAX_BASE_URL || "";
+        if (baseUrl) {
+            try {
+                const parsed = new URL(baseUrl);
+                env.MINIMAX_API_HOST = `${parsed.protocol}//${parsed.host}`;
+            }
+            catch { /* invalid URL, skip */ }
+        }
+        else {
+            // Infer from upstream proxy config if available
+            const config = getProxyInstanceConfig(instanceId);
+            const upstream = config?.["x-jishushell"]?.proxy?.upstream;
+            if (upstream?.providerId === "minimax" && upstream.baseUrl) {
+                try {
+                    const parsed = new URL(upstream.baseUrl);
+                    env.MINIMAX_API_HOST = `${parsed.protocol}//${parsed.host}`;
+                }
+                catch { /* invalid URL, skip */ }
+            }
+        }
+    }
+}
 /**
  * Dissociate a cloned/imported config from its source instance's IM bindings.
  * Physically migrated from `instance-manager.stripImBindings` so framework
@@ -2172,9 +3564,27 @@ function getStockExtensionsDir() {
 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))));
+    if (existsSync(join(getChannelExtensionsDir(instanceId), extDirName)))
+        return true;
+    if (existsSync(join(stockExtDir, extDirName)))
+        return true;
+    if (extDirName !== channelId && existsSync(join(stockExtDir, channelId)))
+        return true;
+    // OpenClaw's npm-backed plugin store lives at
+    // `<home>/.openclaw/npm/node_modules/<pkg>`. The CLI refuses to reinstall
+    // when that path is present ("plugin already exists ... delete it first"),
+    // even if the per-instance extensions/<name> dir is missing (e.g. the
+    // first install was interrupted, or the dir was manually cleaned). Treat
+    // the npm path as authoritative so re-saves stay idempotent.
+    const pkg = CHANNEL_PLUGIN_MAP[channelId];
+    if (pkg) {
+        const home = getInstance(instanceId)?.openclaw_home ||
+            defaultOpenclawHome(instanceId);
+        const npmPath = join(home, OPENCLAW_STATE_DIRNAME, "npm", "node_modules", ...pkg.split("/"));
+        if (existsSync(npmPath))
+            return true;
+    }
+    return false;
 }
 /**
  * Install a single channel plugin. Docker mode → `docker exec` inside the