jishushell 0.4.24 → 0.5.15

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 { accessSync, chmodSync, chownSync, copyFileSync, cpSync, constants, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync, } from "fs";
 import { 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";
@@ -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 },
     };
@@ -265,6 +345,20 @@ function patchJsproxyBaseUrl(configPath) {
  * container loopback. Normalize default/loopback gateway binds to `lan` so
  * Nomad's published host port can reach the gateway.
  */
+// Mirrors hermes.ts:nomadHasExternalHostNetwork. When the host nomad.hcl
+// declares `host_network "external" { ... }`, the legacy openclaw job
+// attaches it to its ReservedPorts so docker publishes the gateway to
+// the LAN address instead of 127.0.0.1. Without this, OpenWebUI in a
+// sibling container can't reach openclaw at all.
+function nomadHasExternalHostNetwork() {
+    const path = join(JISHUSHELL_HOME, "nomad", "nomad.hcl");
+    try {
+        return /host_network\s+"external"\s*\{/.test(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return false;
+    }
+}
 function patchDockerBridgeGatewayBind(configPath) {
     try {
         const raw = readFileSync(configPath, "utf-8");
@@ -290,6 +384,560 @@ function patchDockerBridgeGatewayBind(configPath) {
         console.warn(`[openclaw] Failed to patch gateway.bind in ${configPath}: ${e.message}`);
     }
 }
+/**
+ * Ensure the `llm-agent` capability advertised by openclaw-*.yaml works for
+ * every instance, including ones created before this code shipped: enable
+ * OpenClaw's OpenAI-compatible endpoints in `openclaw.json` on every start.
+ *
+ * Runs idempotently next to `patchDockerBridgeGatewayBind`. The OpenAI
+ * routes (`/v1/chat/completions`, `/v1/responses`, `/v1/models`,
+ * `/v1/embeddings`) live in openclaw's bundled server.impl and are gated
+ * behind `gateway.http.endpoints.{chatCompletions,responses}.enabled` —
+ * default false, so a fresh OpenClaw install would 404 those paths even
+ * though OpenWebUI binds it through the connections page.
+ */
+export function patchOpenAIEndpointsEnabled(configPath) {
+    try {
+        const raw = readFileSync(configPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return;
+        const root = parsed;
+        const gateway = root.gateway && typeof root.gateway === "object" && !Array.isArray(root.gateway)
+            ? root.gateway
+            : (root.gateway = {});
+        const http = gateway.http && typeof gateway.http === "object" && !Array.isArray(gateway.http)
+            ? gateway.http
+            : (gateway.http = {});
+        const endpoints = http.endpoints && typeof http.endpoints === "object" && !Array.isArray(http.endpoints)
+            ? http.endpoints
+            : (http.endpoints = {});
+        let changed = false;
+        for (const key of ["chatCompletions", "responses"]) {
+            const ep = endpoints[key] && typeof endpoints[key] === "object" && !Array.isArray(endpoints[key])
+                ? endpoints[key]
+                : (endpoints[key] = {});
+            if (ep.enabled !== true) {
+                ep.enabled = true;
+                changed = true;
+            }
+        }
+        if (!changed)
+            return;
+        const next = JSON.stringify(parsed, null, 2);
+        const output = raw.endsWith("\n") ? `${next}\n` : next;
+        writeConfigFile(configPath, output);
+        console.log(`[openclaw] Enabled gateway.http.endpoints.{chatCompletions,responses} in ${configPath} for llm-agent capability`);
+    }
+    catch (e) {
+        console.warn(`[openclaw] Failed to patch OpenAI endpoints in ${configPath}: ${e.message}`);
+    }
+}
+/**
+ * Deep-merge a SearXNG connection into an OpenClaw config file at `configPath`.
+ *
+ * Writes both halves of the wiring required for the `web_search` tool to use
+ * the registry-resolved SearXNG instance:
+ *
+ *   plugins.entries.searxng.enabled                       = true
+ *   plugins.entries.searxng.config.webSearch.baseUrl      = baseUrl
+ *   tools.web.search.provider                             = "searxng"
+ *
+ * The provider selector is required because OpenClaw's built-in default is
+ * `"brave"`; without it the tool fails with `missing_brave_api_key` even when
+ * the searxng plugin is otherwise correctly configured (verified on Pi
+ * 2026-04-29: claw11 had the plugin block right but the selector unset).
+ *
+ * Why a partial deep-merge instead of `saveNativeConfig`: the latter is
+ * destructive — it replaces top-level keys wholesale and only preserves a
+ * hardcoded subset (`plugins.installs`, `plugins.entries` per-key, partial
+ * `channels` merge). A partial patch through it would wipe `models.providers`
+ * / `agents.defaults` / etc., bricking the instance with `No API key found
+ * for provider "openai"` on the next chat. So we read, merge, write back.
+ *
+ * No-op when the config file is absent (instance not yet started).
+ */
+export function applySearxngConnectionToConfig(configPath, baseUrl) {
+    if (!existsSync(configPath))
+        return;
+    const existing = JSON.parse(readFileSync(configPath, "utf-8"));
+    existing.plugins = existing.plugins ?? {};
+    existing.plugins.entries = existing.plugins.entries ?? {};
+    const prior = existing.plugins.entries.searxng ?? {};
+    existing.plugins.entries.searxng = {
+        ...prior,
+        enabled: true,
+        config: {
+            ...(prior.config ?? {}),
+            webSearch: {
+                ...((prior.config ?? {}).webSearch ?? {}),
+                baseUrl,
+            },
+        },
+    };
+    existing.tools = existing.tools ?? {};
+    existing.tools.web = existing.tools.web ?? {};
+    existing.tools.web.search = existing.tools.web.search ?? {};
+    existing.tools.web.search.provider = "searxng";
+    safeWriteJson(configPath, existing);
+}
+/**
+ * Counterpart to `applySearxngConnectionToConfig` — invoked when the user
+ * unbinds the SEARCH slot in the Connections tab. Without this, unbinding
+ * left the plugin entry enabled with a baseUrl pointing at the now-gone
+ * searxng provider, and `tools.web.search.provider="searxng"` kept routing
+ * the agent's `web_search` tool through that dead URL on every chat.
+ *
+ * Conservative cleanup so a future re-bind (or user-customized plugin
+ * settings) survives:
+ *   - flip the searxng plugin to enabled:false (don't delete the entry —
+ *     user may have hand-tuned it and we want re-bind to re-enable cheaply)
+ *   - drop the stale `webSearch.baseUrl` so nothing reads it as still-live
+ *   - clear `tools.web.search.provider` so the runtime falls back to its
+ *     built-in default (which today errors out with `missing_brave_api_key`
+ *     — the right outcome: search was unbound, web_search shouldn't work)
+ *
+ * No-op when the config file is absent.
+ */
+export function clearSearxngConnectionFromConfig(configPath) {
+    if (!existsSync(configPath))
+        return;
+    const existing = JSON.parse(readFileSync(configPath, "utf-8"));
+    const sx = existing?.plugins?.entries?.searxng;
+    if (sx && typeof sx === "object") {
+        sx.enabled = false;
+        if (sx.config?.webSearch && typeof sx.config.webSearch === "object") {
+            delete sx.config.webSearch.baseUrl;
+        }
+    }
+    if (existing?.tools?.web?.search && typeof existing.tools.web.search === "object") {
+        delete existing.tools.web.search.provider;
+    }
+    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
@@ -393,7 +1041,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,
@@ -513,7 +1161,7 @@ async function pullOrBuildOpenclawImageWithTask(task, tag) {
         const invocation = resolveDockerInvocation();
         // Always attempt pull — when the image is already local and in sync
         // with upstream, docker returns within seconds after a digest check.
-        // The "skip if image present" early exit was making "重新安装" feel
+        // The "skip if image present" early exit was making "reinstall" feel
         // like a no-op; explicit re-pull matches user intent better. On pull
         // failure we still fall back to local build below.
         emitTask(task, { type: "progress", message: `正在拉取镜像: ${targetTag} ...`, progress: 10 });
@@ -683,6 +1331,11 @@ class OpenClawAdapter {
                 patchDockerBridgeGatewayBind(configPath);
                 patchJsproxyBaseUrl(configPath);
             }
+            // Driver-agnostic: enable the OpenAI-compatible endpoints on every
+            // start so the `llm-agent` capability advertised by openclaw-*.yaml
+            // works for both fresh installs and instances created before this
+            // patcher shipped. Idempotent — bails out fast if already enabled.
+            patchOpenAIEndpointsEnabled(configPath);
             // 4. npm update-seed — use local resolver
             try {
                 const home = openclawAdapter.resolveAgentHome(instanceId);
@@ -692,6 +1345,358 @@ class OpenClawAdapter {
             catch {
                 /* best effort */
             }
+            // 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();
@@ -891,6 +1896,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 = {
@@ -1173,7 +2193,7 @@ 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];
@@ -1220,6 +2240,12 @@ class OpenClawAdapter {
         const safeJobId = `${this.nomadJobPrefix}${instanceId}`;
         assertSafeTemplateId(safeJobId);
         const normalizedResources = normalizeDockerResources(instanceId, rawResources);
+        // Same rationale as hermes.ts:nomadHasExternalHostNetwork — without
+        // HostNetwork, Nomad's docker driver publishes the gateway port to
+        // 127.0.0.1, breaking cross-container consumers (e.g. OpenWebUI
+        // binding openclaw via the llm-agent capability). Bring the legacy
+        // openclaw job in line with the unified app-spec path.
+        const hostNetwork = nomadHasExternalHostNetwork() ? "external" : undefined;
         return {
             Name: "gateway",
             Driver: "docker",
@@ -1227,9 +2253,17 @@ class OpenClawAdapter {
             Config: {
                 image,
                 force_pull: false,
+                // Match nomad-manager.ts:buildAppTask — default 5-minute pull
+                // timeout is too short for Pi-class networks pulling a 1+ GiB
+                // openclaw runtime image; bump to 15 minutes.
+                image_pull_timeout: "15m",
                 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.
+                ports: ["gateway"],
                 extra_hosts: ["host.docker.internal:host-gateway"],
                 cap_drop: ["ALL"],
                 security_opt: ["no-new-privileges"],
@@ -1244,7 +2278,18 @@ class OpenClawAdapter {
             Env: containerEnv,
             Resources: {
                 ...normalizedResources,
-                Networks: [{ ReservedPorts: [{ Label: "gateway", Value: gatewayPort }] }],
+                Networks: [
+                    {
+                        ReservedPorts: [
+                            {
+                                Label: "gateway",
+                                Value: gatewayPort,
+                                To: gatewayPort,
+                                ...(hostNetwork ? { HostNetwork: hostNetwork } : {}),
+                            },
+                        ],
+                    },
+                ],
             },
             LogConfig: { MaxFiles: 3, MaxFileSizeMB: 10 },
             Templates: [
@@ -1378,6 +2423,103 @@ class OpenClawAdapter {
     saveNativeConfig(instanceId, config) {
         return saveNativeConfigImpl(instanceId, config);
     }
+    /**
+     * Connection-apply hook (§7 of app-interconnect-design): translate
+     * resolved `inject_as` env vars into OpenClaw-native plugin config and
+     * persist them into `openclaw.json`. Without this, the runtime env
+     * injected by `nomad-manager.injectConnectionsRuntimeEnv` (PR 8) sits
+     * in the container unused — the OpenClaw agent reads tool config from
+     * `openclaw.json`, not from environment variables.
+     *
+     * Currently wired:
+     *   SEARCH_API_BASE_URL → plugins.entries.searxng.config.webSearch.baseUrl
+     *   SEARCH_API_BASE_URL → tools.web.search.provider = "searxng"
+     *
+     * The provider selector at `tools.web.search.provider` is required: without
+     * it the `web_search` tool defaults to Brave and fails with
+     * `missing_brave_api_key` even when the searxng plugin is fully configured.
+     *
+     * Browser / LLM / MCP wiring lands in PR 9b — they need their own
+     * config-shape mapping (browser → tools.browser, llm → models.providers,
+     * mcp already wired via openclaw-mcporter).
+     *
+     * The write goes through `saveNativeConfig` which deep-merges with the
+     * existing on-disk config, so user-managed plugin entries (e.g.
+     * openclaw-lark) are preserved. Plugin auto-enable then promotes the
+     * searxng entry into `plugins.allow` automatically on next start
+     * because we set `enabled:true` and provide config (the openclaw
+     * runtime treats the presence of `config.webSearch.baseUrl` as a
+     * "configured" signal — see `plugin-auto-enable` in the openclaw
+     * dist bundle).
+     */
+    async applyConnectionEnv(instanceId, env) {
+        const configPath = openclawConfigPath(instanceId);
+        const searchUrl = env.SEARCH_API_BASE_URL;
+        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}`);
+                }
+            }
+            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.
+                }
+            }
+        }
+        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}`);
+                }
+            }
+            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) ───────────────────────────
     resolveBin() {
         return resolveOpenclawBin();
@@ -1924,9 +3066,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