jishushell 0.5.15 → 0.6.5

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

@@ -35,11 +35,10 @@
  */
 import { execFile, execFileSync } from "child_process";
 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 { createHash, randomBytes } from "crypto";
 import { homedir, userInfo } from "os";
 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 { getNomadDriver, getOpenclawDockerImage, JISHUSHELL_HOME, getCoreLanHost, getCorePort, getMaxAppMemoryMB, } from "../../../config.js";
 import { ensureDirContainer, ensureDirHost, writeConfigFile } from "../../../utils/fs.js";
 import { safeWriteJson } from "../../../utils/safe-json.js";
 import { compileTaskRuntime } from "../../app/app-compiler.js";
@@ -48,9 +47,13 @@ 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 { inspectDockerImage, toDockerInspectUserError } from "../../../utils/docker-inspect.js";
+import { decryptApiKey } from "../../llm-proxy/encryption.js";
+import { getDefaultLlmProvider, normalizeProviderApi } from "../../llm-proxy/providers.js";
+import { bootstrapInstanceProxy, getInstanceConfig as getProxyInstanceConfig, } from "../../llm-proxy/instance-proxy.js";
+import { renderStandaloneMcporterSource } from "../mcp-shims/mcporter-lite.js";
+import { resolveNomadJobId } from "../job-id.js";
 import { registerAdapter } from "../registry.js";
-import { registerOpenclawRoutes } from "./openclaw-routes.js";
 // ── Constants physically migrated from nomad-manager.ts ───────────────
 //
 // These used to live as module-scope constants in nomad-manager.ts and were
@@ -75,8 +78,7 @@ const DEFAULT_PIDS_LIMIT = 512;
 // misconfigured or malicious instance config from exhausting scheduler
 // resources on the host (no Nomad Enterprise Resource Quotas in OSS).
 const MAX_CPU_MHZ = 4000;
-const MAX_MEMORY_MB = 4096;
-const MAX_MEMORY_MAX_MB = 4096;
+// Memory ceilings read from core.json at runtime via getMaxAppMemoryMB().
 // Path inside the openclaw-runtime Docker image where the baked-in openclaw
 // npm package lives. Referenced by the entrypoint shim as the fallback and
 // used by the control-UI "Update now" path through a pre-seeded symlink in
@@ -144,25 +146,37 @@ function readFileMounts(runtime) {
  */
 function buildVolumes(openclawHome, runtime) {
     const list = [`${openclawHome}:${openclawHome}:rw`];
+    for (const abs of listMountedHostPaths(runtime)) {
+        const mode = readFileMounts(runtime).find((m) => !m.path || join(FILES_ROOT, m.path) === abs)?.mode === "ro" ? "ro" : "rw";
+        list.push(`${abs}:${abs}:${mode}`);
+    }
+    return list;
+}
+function listMountedHostPaths(runtime) {
     let rootBound = false;
+    const list = [];
     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}`);
+            list.push(FILES_ROOT);
             rootBound = true;
             continue;
         }
         if (rootBound)
             continue; // root already covers every subtree
-        const abs = join(FILES_ROOT, m.path);
-        list.push(`${abs}:${abs}:${mode}`);
+        list.push(join(FILES_ROOT, m.path));
     }
     return list;
 }
+function listJishukbUploadRoots(runtime, openclawHome) {
+    return Array.from(new Set([
+        ...listMountedHostPaths(runtime),
+        join(openclawHome, ".openclaw", "media", "inbound"),
+    ]));
+}
 // ── Path helpers (physically migrated from instance-manager.ts) ───────
 const INSTANCE_OPENCLAW_HOME_DIRNAME = "openclaw-home";
 const INSTANCE_MODEL_ENV_FILENAME = "model.env";
@@ -274,7 +288,7 @@ function buildDefaultRuntime(instanceId, port, openclawHome) {
     };
 }
 function starterConfig() {
-    const dp = getPanelConfig().default_provider;
+    const dp = getDefaultLlmProvider();
     let providerName = "minimax";
     let providerConfig = {
         baseUrl: "https://api.minimaxi.com/v1",
@@ -282,11 +296,11 @@ function starterConfig() {
         models: [{ id: "MiniMax-M2.7", name: "MiniMax M2.7", contextWindow: 204800 }],
     };
     let defaultModel = "minimax/MiniMax-M2.7";
-    if (dp?.providerId) {
-        providerName = dp.providerId;
+    if (dp?.id) {
+        providerName = dp.id;
         providerConfig = {
             baseUrl: dp.baseUrl,
-            api: dp.api,
+            api: normalizeProviderApi(dp.api),
             ...(dp.authHeader ? { authHeader: true } : {}),
             models: dp.models || [],
         };
@@ -304,14 +318,14 @@ function starterConfig() {
         },
         plugins: { entries: { feishu: { enabled: false } } },
     };
-    if (dp?.providerId) {
+    if (dp?.id) {
         config["x-jishushell"] = {
             proxy: {
                 upstream: {
-                    providerId: dp.providerId,
+                    providerId: dp.id,
                     baseUrl: dp.baseUrl,
-                    api: dp.api,
-                    authHeader: dp.authHeader || false,
+                    api: normalizeProviderApi(dp.api),
+                    authHeader: dp.authHeader === true || typeof dp.authHeader === "string",
                     models: dp.models || [],
                     selectedModelId: dp.selectedModelId || dp.models?.[0]?.id || "",
                     hasApiKey: !!dp.apiKey,
@@ -340,6 +354,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
@@ -643,12 +716,24 @@ export function clearBrowserlessConnectionFromConfig(configPath) {
  *                  getuploadurl to return ret:-1. Prior sessions need
  *                  rotation so the agent re-reads the corrected target
  *                  rule and stops adding the prefix.
+ *   2026.6.4.2 — jishu-kb citations response + mcporter fallback shebang:
+ *                  agent was concluding KB was empty because the shim only
+ *                  recognized `chunks/results/hits`, while current jishu-kb
+ *                  returns `citations`. The fallback wrapper also baked a
+ *                  host-specific node shebang that some OpenClaw runtimes
+ *                  could not execute directly. Prior sessions need rotation
+ *                  so the agent retries with the fixed tool behavior.
+ *   2026.6.4.3 — jishu-kb multi-tool surface: KB management/upload/delete
+ *                  tools and handbook/config reads are now available.
+ *                  Prior sessions need rotation so the model re-reads the
+ *                  expanded tool instructions instead of the old search-only
+ *                  guidance.
  *
  * 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 RUNTIME_CONTRACT_VERSION = "2026.6.4.3";
 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 -->";
@@ -736,7 +821,7 @@ function rotateSessionsIfContractChanged(instanceId, openclawHome) {
  * — third-party users on `/home/alice/.jishushell/files/` see their own
  * root, not pi's.
  */
-export function patchToolsMdDriveHint(workspaceDir, filesRoot) {
+export function patchToolsMdDriveHint(workspaceDir, filesRoot, mcporterCommand = "mcporter", instanceId) {
     try {
         const toolsPath = join(workspaceDir, "TOOLS.md");
         let original = "";
@@ -747,6 +832,10 @@ export function patchToolsMdDriveHint(workspaceDir, filesRoot) {
             if (e?.code !== "ENOENT")
                 throw e;
         }
+        const cli = mcporterCommand === "mcporter" ? "mcporter" : JSON.stringify(mcporterCommand);
+        const generatedOutboxPath = instanceId
+            ? `agent-data/${instanceId}/outbox/x.pdf`
+            : "agent-data/<instance>/outbox/x.pdf";
         const section = [
             JISHUSHELL_DRIVE_HINT_BEGIN,
             "",
@@ -793,20 +882,22 @@ export function patchToolsMdDriveHint(workspaceDir, filesRoot) {
             "常用调用（从 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 全文搜索",
+            `${cli} call drive.drive_list path=                          # 列根目录`,
+            `${cli} call drive.drive_list path=文档                       # 列子目录`,
+            `${cli} call drive.drive_read_preview path=note.md           # 预览文本（≤256KB）`,
+            `${cli} call drive.drive_read_full path=long.md              # 整文件（≤4MB，文本）`,
+            `${cli} call drive.drive_quota                               # 配额`,
+            `${cli} call drive.drive_mkdir path=inbox                    # 建目录`,
+            `${cli} call drive.drive_write_text path=notes/m.md content="..."`,
+            `${cli} call drive.drive_write_binary path=out/img.png content_base64="..."   # 二进制（≤10MB）`,
+            `${cli} call drive.drive_move from=a.pdf to=docs/a.pdf`,
+            `${cli} call drive.drive_delete path=tmp.txt`,
+            `${cli} call drive.drive_resolve_local_path path=文档/report.pdf   # → 拿到绝对路径`,
+            `${cli} call drive.drive_search query="发票"                 # 子串检索（中英文，大小写不敏感）`,
             "```",
             "",
+            "**检索策略（`drive_search` 是高召回但不精确的笨工具）**：整句问题先拆成关键词再搜——「找我去年三亚海边的照片」→ 搜 `三亚`、`海边`、`照片`（或空格分隔 `三亚 海边 照片`，空格 = OR）。它是连续子串匹配、不懂语义；命中后用 `drive_read_full` 读候选、自己判断与精排，召回不够就换同义词多搜几次。",
+            "",
             "### 给用户发文件（飞书 / 微信 / 任何 IM）",
             "",
             "**用户问 \"把 X 文件发我\" 时不要拒绝、不要让用户去飞书云空间下载**——99% 的情况文件已经在你的文件系统里了。标准流程：",
@@ -821,7 +912,7 @@ export function patchToolsMdDriveHint(workspaceDir, filesRoot) {
             "",
             "**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 → 发送。",
+            `要发**新生成**的文件（PDF、图片、报表）：先 \`drive_write_binary path=${generatedOutboxPath} content_base64=...\` 落盘，再 resolve → 发送。`,
             "",
             "### 用户给你发文件",
             "",
@@ -857,18 +948,88 @@ export function patchToolsMdDriveHint(workspaceDir, filesRoot) {
         console.warn(`[openclaw] Failed to patch TOOLS.md drive hint: ${e.message}`);
     }
 }
+export function resolveKbProvider(kbBinding) {
+    const PROVIDER_ANYLLM = "anythingllm-container";
+    const PROVIDER_JISHUKB = "jishu-kb-container";
+    const idToTag = (id) => {
+        if (id === PROVIDER_JISHUKB)
+            return "jishukb";
+        if (id === PROVIDER_ANYLLM)
+            return "anythingllm";
+        return null;
+    };
+    if (kbBinding === null)
+        return null;
+    if (kbBinding && typeof kbBinding === "object") {
+        const b = kbBinding;
+        if (b.kind === "single") {
+            return idToTag(b.providerId);
+        }
+        if (b.kind === "many") {
+            // User selected the "many" mode but the providers array is malformed
+            // or empty → treat as "no known provider bound", same as a list of
+            // only-unknown providers. Avoids the surprise where a malformed
+            // array silently falls back to legacy auto-anythingllm.
+            if (!Array.isArray(b.providers))
+                return null;
+            // First known match in the user's order wins — the UI lets users
+            // drag to reorder; we honor that order rather than imposing our own.
+            for (const p of b.providers) {
+                const tag = idToTag(p?.providerId);
+                if (tag !== null)
+                    return tag;
+            }
+            return null;
+        }
+        return "anythingllm"; // unknown binding shape → legacy default
+    }
+    return "anythingllm"; // undefined → legacy default
+}
 /**
- * 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.
+ * Per-provider kb-shim residue cleanup. Wipes the shim source (replacing
+ * the bytes with a removal marker rather than `unlink`-ing — the latter
+ * would race with a concurrent `node <shim>` that already opened it) and
+ * `unlink`s the sibling `secret.json` if any. Idempotent and safe to call
+ * even if no shim was ever installed.
+ *
+ * Called by EVERY branch of the kb auto-wire block so a rebind from
+ * anythingllm ↔ jishukb (or → null) never leaves stale shim files or
+ * 0o600 secrets on disk. The "wipe by overwrite" pattern matches what
+ * the old anythingllm-only branch did before the dispatch refactor.
  *
- * `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.
+ * agentHome is the OpenClaw container's `$HOME` (the value returned by
+ * `openclawAdapter.resolveAgentHome(instanceId)`). `which` selects the
+ * provider: each gets its own `__mcp_shims__/<which>/` subtree.
+ *
+ * Exported so the security-critical secret-deletion behavior can be
+ * covered by a focused unit test without standing up the full start hook.
  */
-export function patchToolsMdKbHint(workspaceDir, mode) {
+export function wipeKbShimDir(agentHome, which) {
+    const dir = join(agentHome, "__mcp_shims__", which);
+    const shimPath = join(dir, `${which}-shim.js`);
+    const removalMarker = which === "anythingllm"
+        ? "// removed: AnythingLLM not bound as knowledge provider\n"
+        : "// removed: jishu-kb not bound as knowledge provider\n";
+    try {
+        if (existsSync(shimPath)) {
+            writeFileSync(shimPath, removalMarker, { mode: 0o644 });
+        }
+    }
+    catch { /* best effort */ }
+    // AnythingLLM's shim has a sibling 0o600 secret.json (API key). v1
+    // jishu-kb ships without auth so no secret to wipe — when jishu-kb
+    // adds JISHU_KB_AUTH_TOKEN_FILE we'll start writing a secret.json
+    // here too and the unlink must be added below.
+    if (which === "anythingllm") {
+        const secretPath = join(dir, "secret.json");
+        try {
+            if (existsSync(secretPath))
+                unlinkSync(secretPath);
+        }
+        catch { /* best effort */ }
+    }
+}
+export function patchToolsMdKbHint(workspaceDir, mode, provider, mcporterCommand = "mcporter", instanceId, mediaInboundRoot) {
     try {
         const toolsPath = join(workspaceDir, "TOOLS.md");
         let original = "";
@@ -894,38 +1055,87 @@ export function patchToolsMdKbHint(workspaceDir, mode) {
             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");
+            if (!provider) {
+                throw new Error("provider is required when installing KB hint");
+            }
+            const cli = mcporterCommand === "mcporter" ? "mcporter" : JSON.stringify(mcporterCommand);
+            const generatedOutboxPath = instanceId
+                ? `agent-data/${instanceId}/outbox/report.md`
+                : "agent-data/<instance>/outbox/report.md";
+            const attachmentInboxPath = mediaInboundRoot || "<openclawHome>/.openclaw/media/inbound";
+            const section = provider === "jishukb"
+                ? [
+                    JISHUSHELL_KB_HINT_BEGIN,
+                    "",
+                    "### 📚 知识库（JishuShell-KB）",
+                    "",
+                    "用户长期投递并已经导入到 **JishuShell-KB** 的文档（手册、PDF、内部笔记、会议纪要等）可以检索；你也可以列知识库、创建知识库、把 drive 文件上传入库、查看已索引文档、查看 handbook、读取**脱敏后的**当前配置，以及在用户明确确认时删除文档/知识库。",
+                    "",
+                    "**当前 provider 暴露的工具**：",
+                    "",
+                    `- \`${cli} call kb.kb_list\` — 列出所有知识库（拿 id / name / chunks 数）`,
+                    `- \`${cli} call kb.kb_create name="产品文档" description="可选"\` — 新建知识库`,
+                    `- \`${cli} call kb.kb_search query="<用户原话>" kbId=<可选> topK=<可选>\` — 检索指定或默认知识库`,
+                    `- \`${cli} call kb.kb_upload path="<drive_resolve_local_path 返回的绝对路径>" kbId="<目标知识库 id>"\` — 上传并索引文件到指定知识库`,
+                    `- \`${cli} call kb.kb_list_documents kbId=<可选>\` — 列出指定或默认知识库里的已索引文档`,
+                    `- \`${cli} call kb.kb_read_handbook section="设置 → 知识库"\` — 读取 handbook 全文或指定章节`,
+                    `- \`${cli} call kb.kb_get_config\` — 读取当前**脱敏后的**知识库配置摘要`,
+                    `- \`${cli} call kb.kb_delete_document kbId="<知识库 id>" documentId="<文档 id>" confirmDocumentId="<同一个文档 id>"\` — 删除文档（危险操作，必须显式确认）`,
+                    `- \`${cli} call kb.kb_delete_kb kbId="<知识库 id>" confirmKbId="<同一个知识库 id>"\` — 删除知识库（危险操作，必须显式确认）`,
+                    "",
+                    "**推荐调用顺序**：",
+                    "1. 用户提到“某个指定知识库 / 某个库里”但你不知道 id → 先 `kb_list`。",
+                    "2. 用户要把 drive 里的文件加入知识库 → 先 `drive_resolve_local_path`，再 `kb_upload path=<abs_path> kbId=<显式 id>`。",
+                    `3. 用户当前消息已经附了文件，而且消息里给了宿主机绝对路径（通常在 \`${attachmentInboxPath}/...\`）→ 直接把这个绝对路径传给 \`kb_upload\`；不要先把内容重写到 \`files/\` 根目录，也不要自己猜 \`agent-data/agent1/...\` 这种路径。`,
+                    `4. 用户要上传你**新生成**的文件 → 先 \`drive_write_text\` / \`drive_write_binary\` 到 \`${generatedOutboxPath}\`，再 \`drive_resolve_local_path\` → \`kb_upload\`。`,
+                    "5. 用户要新建库并马上上传 → `kb_create` → 记住返回的 id → `kb_upload`。",
+                    "6. 用户要解释某个设置项怎么用 → 先 `kb_read_handbook`，必要时再 `kb_get_config` 看当前值。",
+                    "",
+                    `**安全规则**：写操作和删除操作不要猜目标知识库；拿不准就先 \`kb_list\`。删除必须是用户明确要求，且把 confirm 字段原样填成同一个 id。 \`kb_get_config\` 只返回脱敏摘要，不会给你密钥。 \`kb_upload\` 只接受来自当前实例已挂载文件目录，或当前实例附件 inbox（\`${attachmentInboxPath}/...\`）的绝对路径。**`,
+                    "",
+                    "**与 drive 的分工**：",
+                    "- `drive.*` = 文件系统 facade（列目录、读字节、拿绝对路径）—— 要的是**文件本体**用 drive",
+                    "- `kb.*` = 知识库检索/管理/上传 —— 要的是**知识库里的内容和状态**用 kb",
+                    "",
+                    "两者数据不共享：drive 里有文件 ≠ 某个知识库已经索引了它。",
+                    "",
+                    "**搜不到时的标准回复**：如果 `kb_search` 没结果，就直接说「我在当前知识库里没找到相关内容」。如果用户问的是 drive 里已有文件，可进一步建议「要我把它上传到某个知识库吗？」—— 但上传前先确认目标 kbId，不要自己猜默认库。",
+                    "",
+                    JISHUSHELL_KB_HINT_END,
+                    "",
+                ].join("\n")
+                : [
+                    JISHUSHELL_KB_HINT_BEGIN,
+                    "",
+                    "### 📚 知识库（AnythingLLM）",
+                    "",
+                    "用户长期投递的文档（手册、PDF、内部笔记、过往会议纪要等）由 **AnythingLLM** 维护索引（本地 LanceDB 向量库 + 内置 Xenova ONNX embedder），通过 `kb.kb_search` 一次调用拿「答案 + 引用来源」。",
+                    "",
+                    "**两个工具**：",
+                    "",
+                    `- \`${cli} call kb.kb_search query="<用户原话>"\` — 在已索引文档里检索，返回答案 + 最多 5 条引用源`,
+                    `- \`${cli} call kb.kb_ingest path="<绝对路径>"\` — 把 drive 里的文件加入知识库并 embed（用户说「加进知识库 / index this / 学习这份」时调）`,
+                    "",
+                    "**ingest 标准链**（drive 里的文件 → 知识库）：",
+                    `1. \`${cli} call drive.drive_resolve_local_path path=inbox/contract.pdf\` → 拿 \`abs_path\``,
+                    `2. \`${cli} 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;
         }
@@ -969,7 +1179,349 @@ 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 inline Docker entrypoint 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;
+}
+`;
+const CONTAINER_PATCH_ENTRYPOINT_COMMAND = 'node "$HOME/.jishushell/session-fence-patch.mjs" 2>/dev/null || true; exec /usr/local/bin/openclaw-entry.sh "$@"';
+/**
+ * Write the container-side patch script to the openclaw-home directory so it
+ * is available inside the container via the bind mount.
+ *
+ * Called from onBeforeStart. Idempotent — only rewrites if content changed.
+ */
+export function writeContainerPatchScript(openclawHome) {
+    const scriptDir = join(openclawHome, ".jishushell");
+    try {
+        ensureDirContainer(scriptDir);
+    }
+    catch (err) {
+        console.warn(`[openclaw] Failed to prepare container patch directory ${scriptDir}: ${err?.message ?? err}`);
+        return;
+    }
+    const scriptPath = join(scriptDir, "session-fence-patch.mjs");
+    ensureReadableContent(scriptPath, CONTAINER_PATCH_SCRIPT);
+}
+function ensureReadableContent(path, content) {
+    try {
+        if (existsSync(path) && readFileSync(path, "utf-8") === content) {
+            chmodSync(path, 0o644);
+            return;
+        }
+        writeConfigFile(path, content);
+    }
+    catch (err) {
+        console.warn(`[openclaw] Failed to write patch script ${path}: ${err?.message ?? err}`);
+    }
+}
 function resolveUidGid(username) {
     try {
         if (!VALID_USER_RE.test(username)) {
@@ -994,7 +1546,7 @@ function resolveUidGid(username) {
 function normalizeDockerResources(instanceId, resources) {
     const requestedMemoryMB = Number(resources.MemoryMB ?? DEFAULT_RESOURCES.MemoryMB);
     let effectiveMemoryMB = requestedMemoryMB;
-    let effectiveMemoryMaxMB = Math.min(Number(resources.MemoryMaxMB ?? requestedMemoryMB), MAX_MEMORY_MAX_MB);
+    let effectiveMemoryMaxMB = Math.min(Number(resources.MemoryMaxMB ?? requestedMemoryMB), getMaxAppMemoryMB());
     if (effectiveMemoryMaxMB < effectiveMemoryMB) {
         console.warn(`[openclaw] ${instanceId}: MemoryMaxMB (${effectiveMemoryMaxMB}) is below MemoryMB (${effectiveMemoryMB}); clamping.`);
         effectiveMemoryMaxMB = effectiveMemoryMB;
@@ -1330,6 +1882,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
@@ -1345,6 +1898,22 @@ 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
@@ -1383,7 +1952,7 @@ class OpenClawAdapter {
             try {
                 const home = openclawAdapter.resolveAgentHome(instanceId);
                 if (home) {
-                    patchToolsMdDriveHint(join(home, ".openclaw", "workspace"), FILES_ROOT);
+                    patchToolsMdDriveHint(join(home, ".openclaw", "workspace"), FILES_ROOT, join(home, ".npm-global", "bin", "jishushell-mcporter"), instanceId);
                 }
             }
             catch (e) {
@@ -1416,37 +1985,38 @@ class OpenClawAdapter {
                     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.
+                    // Pick the core 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
+                    // docker image), `host.docker.internal:<corePort>` 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";
+                    const corePort = getCorePort();
+                    let driveCoreHost = "host.docker.internal";
                     try {
                         const im2 = await lazyIm();
                         const rt = im2.getInstanceRuntime(instanceId);
                         if (!rt?.image) {
-                            const { getPanelLanHost, getPanelPort } = await import("../../../config.js");
-                            drivePanelUrl = `http://${getPanelLanHost()}:${getPanelPort()}`;
+                            driveCoreHost = getCoreLanHost();
                         }
                     }
-                    catch {
-                        // Best effort — fall through to host.docker.internal default
+                    catch (e) {
+                        console.warn(`[openclaw] drive shim runtime detection failed for ${instanceId}; using container-reachable core host:`, e);
                     }
+                    const driveCoreUrl = `http://${driveCoreHost}:${corePort}`;
                     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
+                    // Bake coreUrl/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,
+                        coreUrl: driveCoreUrl,
                         token: internalToken,
                         instanceId,
                     });
@@ -1461,7 +2031,8 @@ class OpenClawAdapter {
                                 // for dev/manual testing — production never depends on them.
                                 JISHUSHELL_INTERNAL_TOKEN: internalToken,
                                 JISHUSHELL_INSTANCE_ID: instanceId,
-                                JISHUSHELL_PANEL_URL: drivePanelUrl,
+                                JISHUSHELL_CORE_URL: driveCoreUrl,
+                                JISHUSHELL_CORE_PORT: String(corePort),
                             },
                             __source: {
                                 kind: "connection",
@@ -1475,117 +2046,170 @@ class OpenClawAdapter {
             catch (e) {
                 console.warn(`[openclaw] drive shim install skipped: ${e?.message ?? e}`);
             }
-            // 4c-quater. Auto-wire AnythingLLM kb shim. The Connections-tab
+            // 4c-quater. Auto-wire knowledge MCP 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):
+            //      Provider resolution (matching connection-resolver.ts):
+            //
+            //        - `null`                     → user explicitly disconnected →
+            //                                       DO NOT inject (and strip any prior shim).
+            //        - kind=single + providerId   → use that provider's shim.
+            //        - kind=many                  → first match wins (jishukb > anythingllm
+            //                                       to be explicit and stable across rebinds).
+            //        - undefined                  → no opinion → fall back to the
+            //                                       historical "auto-on when AnythingLLM
+            //                                       credentials.json exists" UX (legacy default).
             //
-            //        - `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.
+            //      Mutual cleanup: rebinding from anythingllm → jishukb (or
+            //      vice versa, or → null) wipes the OTHER provider's shim dir
+            //      in EVERY branch. Leaving a 0o600 secret.json + bearer-
+            //      prefilled shim source on disk after unbind would be a
+            //      lingering security smell.
             //
-            //      Secrets handling (defense-in-depth):
+            //      Secrets handling (defense-in-depth, anythingllm only):
             //        - 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.
+            //      jishu-kb v1 ships without auth, so no secret.json.
             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 provider = resolveKbProvider(instMeta?.connections?.KNOWLEDGE_BASE_URL);
+                    const mcporterCommand = join(home, ".npm-global", "bin", "jishushell-mcporter");
+                    const wsDir = join(home, ".openclaw", "workspace");
+                    const anyllmShimDir = join(home, "__mcp_shims__", "anythingllm");
+                    const anyllmShimPath = join(anyllmShimDir, "anythingllm-shim.js");
+                    const anyllmSecretPath = join(anyllmShimDir, "secret.json");
+                    const jishukbShimDir = join(home, "__mcp_shims__", "jishukb");
+                    const jishukbShimPath = join(jishukbShimDir, "jishukb-shim.js");
+                    const { mergeMcporterServers, removeMcporterServers } = await import("./openclaw-mcporter.js");
+                    if (provider === "jishukb") {
+                        // Wipe the OTHER provider's residue first (including its
+                        // 0o600 secret.json). Security smell to leave it on disk.
+                        wipeKbShimDir(home, "anythingllm");
+                        const credPath = join(JISHUSHELL_HOME, "apps", "jishu-kb-container", "credentials.json");
+                        let creds = null;
+                        if (existsSync(credPath)) {
+                            try {
+                                creds = JSON.parse(readFileSync(credPath, "utf-8"));
+                            }
+                            catch (e) {
+                                console.warn(`[openclaw] kb: invalid jishu-kb credentials.json: ${e?.message ?? e}`);
+                            }
                         }
-                    }
-                    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"));
+                        if (creds?.baseUrl) {
+                            const { substituteJishukbShimPlaceholders } = await import("../mcp-shims/jishukb-shim.js");
+                            ensureDirContainer(jishukbShimDir);
+                            const shimSource = substituteJishukbShimPlaceholders({
+                                baseUrl: creds.baseUrl,
+                                kbId: creds.kbId,
+                                allowedUploadRoots: listJishukbUploadRoots(instMeta?.runtime ?? {}, home),
+                            });
+                            writeFileSync(jishukbShimPath, shimSource, { mode: 0o644 });
+                            mergeMcporterServers(instanceId, {
+                                kb: {
+                                    command: "node",
+                                    args: [jishukbShimPath],
+                                    env: {
+                                        // Belt-and-suspenders fallback for hand-running.
+                                        // Baked values in the shim source are the production
+                                        // source of truth. No secret in v1.
+                                        JISHUKB_BASE_URL: creds.baseUrl,
+                                        JISHUKB_KB_ID: creds.kbId || "",
+                                    },
+                                    __source: {
+                                        kind: "connection",
+                                        slot: "knowledge",
+                                        consumerInstanceId: instanceId,
+                                    },
+                                },
+                            });
+                            patchToolsMdKbHint(wsDir, "install", "jishukb", mcporterCommand, instanceId, join(home, ".openclaw", "media", "inbound"));
                         }
-                        catch (e) {
-                            console.warn(`[openclaw] kb: invalid credentials.json: ${e?.message ?? e}`);
+                        else {
+                            // jishu-kb bound but baseUrl not yet ready / credentials missing.
+                            // Remove any prior kb registration so the agent doesn't
+                            // call a stale shim, and wipe our own shim dir for hygiene.
+                            console.warn(`[openclaw] kb: jishu-kb bound but baseUrl missing at ${credPath} — skipping shim install`);
+                            removeMcporterServers(instanceId, {
+                                source: { kind: "connection", slot: "knowledge", consumerInstanceId: instanceId },
+                            });
+                            patchToolsMdKbHint(wsDir, "remove");
+                            wipeKbShimDir(home, "jishukb");
                         }
                     }
-                    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);
+                    else if (provider === "anythingllm") {
+                        // Wipe the OTHER provider's residue first.
+                        wipeKbShimDir(home, "jishukb");
+                        const credPath = join(JISHUSHELL_HOME, "apps", "anythingllm-container", "credentials.json");
+                        let kbCreds = null;
+                        if (existsSync(credPath)) {
+                            try {
+                                kbCreds = JSON.parse(readFileSync(credPath, "utf-8"));
+                            }
+                            catch (e) {
+                                console.warn(`[openclaw] kb: invalid credentials.json: ${e?.message ?? e}`);
+                            }
                         }
-                        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,
+                        if (kbCreds?.apiKey && kbCreds?.baseUrl) {
+                            const { substituteAnythingllmShimPlaceholders } = await import("../mcp-shims/anythingllm-shim.js");
+                            ensureDirContainer(anyllmShimDir);
+                            const shimSource = substituteAnythingllmShimPlaceholders({
+                                baseUrl: kbCreds.baseUrl,
+                                workspace: kbCreds.workspace || "default",
+                            });
+                            writeFileSync(anyllmShimPath, shimSource, { mode: 0o644 });
+                            // chmod after write to dodge umask; secret.json must be 0o600.
+                            writeFileSync(anyllmSecretPath, JSON.stringify({ apiKey: kbCreds.apiKey }), { mode: 0o600 });
+                            try {
+                                chmodSync(anyllmSecretPath, 0o600);
+                            }
+                            catch { /* best effort */ }
+                            mergeMcporterServers(instanceId, {
+                                kb: {
+                                    command: "node",
+                                    args: [anyllmShimPath],
+                                    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");
+                            });
+                            patchToolsMdKbHint(wsDir, "install", "anythingllm", mcporterCommand);
+                        }
+                        else {
+                            // AnythingLLM bound but creds missing → strip and clean.
+                            removeMcporterServers(instanceId, {
+                                source: { kind: "connection", slot: "knowledge", consumerInstanceId: instanceId },
+                            });
+                            patchToolsMdKbHint(wsDir, "remove");
+                            wipeKbShimDir(home, "anythingllm");
+                        }
                     }
                     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").
+                        // provider === null → user explicitly unbound, or bound to
+                        // an unknown/unsupported provider. Strip kb server and wipe
+                        // both shim dirs.
                         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 */ }
+                        wipeKbShimDir(home, "anythingllm");
+                        wipeKbShimDir(home, "jishukb");
                     }
                 }
             }
@@ -1615,83 +2239,24 @@ class OpenClawAdapter {
             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.
+            // 4d. Install a standalone mcporter-compatible FALLBACK wrapper at
+            //      `$OPENCLAW_HOME/.npm-global/bin/jishushell-mcporter`. Fresh
+            //      instances often do not carry an actual mcporter npm install, yet
+            //      TOOLS.md asks the model to shell out for drive/kb access. Keep
+            //      the fallback on a distinct path so we do NOT clobber a real
+            //      mcporter install that may support transports/features beyond this
+            //      wrapper's narrow built-in scope.
             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 */ }
+                    const mcporterBin = join(home, ".npm-global", "bin", "jishushell-mcporter");
+                    ensureDirContainer(join(home, ".npm-global", "bin"));
+                    writeFileSync(mcporterBin, renderStandaloneMcporterSource(), { mode: 0o755 });
+                    try {
+                        chmodSync(mcporterBin, 0o755);
                     }
+                    catch { /* best effort */ }
+                    console.log(`[openclaw] installed standalone mcporter fallback at ${mcporterBin}`);
                 }
             }
             catch (e) {
@@ -1703,19 +2268,23 @@ class OpenClawAdapter {
                 if (!DOCKER_IMAGE_RE.test(image) || image.length > MAX_DOCKER_IMAGE_NAME_LEN) {
                     throw new Error(`Invalid Docker image name: "${image}"`);
                 }
-                try {
-                    execFileSync("docker", ["image", "inspect", image], {
-                        timeout: 10000,
-                        stdio: "ignore",
-                    });
-                }
-                catch {
+                const imageCheck = inspectDockerImage(image, { timeout: 10000 });
+                if (!imageCheck.ok) {
+                    const inspectError = toDockerInspectUserError(image, imageCheck);
+                    if (imageCheck.reason !== "not_found") {
+                        const err = new Error(inspectError.message);
+                        err.code = inspectError.code;
+                        err.statusCode = inspectError.statusCode;
+                        throw err;
+                    }
                     console.log(`[openclaw] Docker image ${image} not found, starting background pull`);
                     try {
                         const result = openclawAdapter.startBuildRuntimeImage({ tag: image });
-                        const err = new Error(`Docker image ${image} not found. Pull started in background.`);
+                        const err = new Error(`${inspectError.message} Pull started in background.`);
                         err.building = true;
                         err.taskId = result.taskId;
+                        err.code = inspectError.code;
+                        err.statusCode = 202;
                         throw err;
                     }
                     catch (e) {
@@ -2024,11 +2593,11 @@ class OpenClawAdapter {
             }
             if (!existsSync(configPath)) {
                 writeConfigFile(configPath, JSON.stringify(starterConfig(), null, 2));
-                // Inject default provider API key from setup into both env files
-                const dp = getPanelConfig().default_provider;
-                if (dp?.apiKey && dp?.providerId && envFiles.length) {
-                    const envKey = inferProviderApiKeyEnvName(dp.providerId);
-                    updateEnvFile(envFiles[0], { [envKey]: dp.apiKey });
+                // Inject the configured default provider API key into both env files.
+                const dp = getDefaultLlmProvider();
+                if (dp?.apiKey && dp?.id && envFiles.length) {
+                    const envKey = inferProviderApiKeyEnvName(dp.id);
+                    updateEnvFile(envFiles[0], { [envKey]: decryptRuntimeProviderApiKey(dp.apiKey) });
                     const providerEnv = join(dirname(envFiles[0]), "provider.env");
                     updateEnvFile(providerEnv, { UPSTREAM_API_KEY: dp.apiKey });
                 }
@@ -2199,6 +2768,8 @@ class OpenClawAdapter {
             : [...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;
@@ -2209,7 +2780,7 @@ class OpenClawAdapter {
                 rawResources[k] = Number(v);
         }
         rawResources.CPU = Math.max(1, Math.min(rawResources.CPU, MAX_CPU_MHZ));
-        rawResources.MemoryMB = Math.max(1, Math.min(rawResources.MemoryMB, MAX_MEMORY_MB));
+        rawResources.MemoryMB = Math.max(1, Math.min(rawResources.MemoryMB, getMaxAppMemoryMB()));
         // Container env — OpenClaw-specific HOME / NODE_PATH / PATH / npm cfg
         const containerEnv = { ...env };
         containerEnv.HOME = openclawHome;
@@ -2237,8 +2808,12 @@ class OpenClawAdapter {
             "/bin",
         ].join(":");
         const gatewayPort = im.getGatewayPort(instanceId);
-        const safeJobId = `${this.nomadJobPrefix}${instanceId}`;
+        const safeJobId = resolveNomadJobId(instanceId, this.nomadJobPrefix);
         assertSafeTemplateId(safeJobId);
+        // Signal to OpenClaw that Nomad manages process lifecycle (restart on exit).
+        // Without this, OpenClaw >= 2026.5.20 refuses self-updates because
+        // detectRespawnSupervisor() finds no systemd/launchd markers.
+        containerEnv.OPENCLAW_SYSTEMD_UNIT = `nomad-${safeJobId}.service`;
         const normalizedResources = normalizeDockerResources(instanceId, rawResources);
         // Same rationale as hermes.ts:nomadHasExternalHostNetwork — without
         // HostNetwork, Nomad's docker driver publishes the gateway port to
@@ -2257,6 +2832,10 @@ 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",
+                // Inline the temporary session-fence patch launcher so Nomad does not
+                // depend on a host-side executable wrapper. Once OpenClaw no longer
+                // needs this workaround, this custom entrypoint can be removed.
+                entrypoint: ["/bin/sh", "-c", CONTAINER_PATCH_ENTRYPOINT_COMMAND, "--"],
                 args,
                 work_dir: openclawHome,
                 volumes: buildVolumes(openclawHome, im.getInstanceRuntime(instanceId)),
@@ -2355,7 +2934,7 @@ class OpenClawAdapter {
         // function internally calls instanceManager.saveConfig, which
         // dispatches back to this adapter's saveNativeConfig() for the
         // raw disk write (distinct method, no recursion).
-        const { saveInstanceConfig } = await import("../../llm-proxy/index.js");
+        const { saveInstanceConfig } = await import("../../llm-proxy/instance-proxy.js");
         await saveInstanceConfig(instanceId, doc.content);
         return this.readConfig(instanceId);
     }
@@ -2814,14 +3393,6 @@ class OpenClawAdapter {
         });
         return { ok: true, message: "Docker image pull started", taskId: task.id };
     }
-    /**
-     * §32.2.5 — register OpenClaw-specific HTTP endpoints. Called from
-     * `routes/instances.ts` at server startup via the generic adapter
-     * dispatch loop.
-     */
-    registerRoutes(app) {
-        registerOpenclawRoutes(app);
-    }
     /**
      * Return OpenClaw's readiness for spawning instances. Docker image
      * presence is the gating factor in the default docker-mode deployment;
@@ -2942,10 +3513,7 @@ function injectProviderApiKeys(instanceId, config) {
         if (typeof provider !== "object" || provider === null)
             continue;
         const p = provider;
-        const api = p.api;
-        if (typeof api === "string" && api in LEGACY_PROVIDER_API_ALIASES) {
-            p.api = LEGACY_PROVIDER_API_ALIASES[api];
-        }
+        p.api = normalizeProviderApi(typeof p.api === "string" ? p.api : undefined);
         const apiKey = runtimeEnv[inferProviderApiKeyEnvName(providerId)];
         if (apiKey)
             p.apiKey = apiKey;
@@ -3003,8 +3571,10 @@ function prepareConfigForSave(instanceId, config) {
         if (typeof provider !== "object" || provider === null)
             continue;
         const p = provider;
-        if (typeof p.api === "string" && p.api in LEGACY_PROVIDER_API_ALIASES) {
-            p.api = LEGACY_PROVIDER_API_ALIASES[p.api];
+        p.api = normalizeProviderApi(typeof p.api === "string" ? p.api : undefined);
+        // 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;
@@ -3013,7 +3583,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;
@@ -3036,6 +3606,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