jishushell 0.5.22 → 0.6.5

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

@@ -38,8 +38,7 @@ import { accessSync, chmodSync, chownSync, copyFileSync, cpSync, constants, exis
 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, decryptApiKey, getInstanceConfig as getProxyInstanceConfig } 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,
@@ -702,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 -->";
@@ -795,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 = "";
@@ -806,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,
             "",
@@ -852,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% 的情况文件已经在你的文件系统里了。标准流程：",
@@ -880,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 → 发送。`,
             "",
             "### 用户给你发文件",
             "",
@@ -916,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.
  *
- * `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.
+ * 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.
+ *
+ * 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 = "";
@@ -953,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;
         }
@@ -1261,8 +1412,8 @@ export function patchSessionFenceBug(openclawHome, instanceId) {
 /**
  * Self-contained Node.js script that patches the session fence bug from
  * INSIDE the container. Written to `$OPENCLAW_HOME/.jishushell/session-fence-patch.mjs`
- * by onBeforeStart and executed by the custom entrypoint wrapper before
- * the OpenClaw gateway starts.
+ * 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
@@ -1340,54 +1491,35 @@ for (const file of files) {
   break;
 }
 `;
+const CONTAINER_PATCH_ENTRYPOINT_COMMAND = 'node "$HOME/.jishushell/session-fence-patch.mjs" 2>/dev/null || true; exec /usr/local/bin/openclaw-entry.sh "$@"';
 /**
- * The custom entrypoint wrapper that executes the patch script before
- * deferring to the image's original entrypoint.
- */
-const CONTAINER_ENTRYPOINT_WRAPPER = `#!/bin/sh
-# JishuShell session-fence-patch entrypoint wrapper
-PATCH="$HOME/.jishushell/session-fence-patch.mjs"
-if [ -f "$PATCH" ]; then
-  node "$PATCH" 2>/dev/null || true
-fi
-exec /usr/local/bin/openclaw-entry.sh "$@"
-`;
-/**
- * Write the container-side patch script and entrypoint wrapper to the
- * openclaw-home directory so they are available inside the container
- * via the bind mount.
+ * 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 writes if content changed.
+ * Called from onBeforeStart. Idempotent — only rewrites if content changed.
  */
 export function writeContainerPatchScript(openclawHome) {
     const scriptDir = join(openclawHome, ".jishushell");
     try {
-        mkdirSync(scriptDir, { recursive: true });
+        ensureDirContainer(scriptDir);
     }
-    catch {
+    catch (err) {
+        console.warn(`[openclaw] Failed to prepare container patch directory ${scriptDir}: ${err?.message ?? err}`);
         return;
     }
     const scriptPath = join(scriptDir, "session-fence-patch.mjs");
-    const wrapperPath = join(scriptDir, "entrypoint.sh");
-    // Write patch script (idempotent)
+    ensureReadableContent(scriptPath, CONTAINER_PATCH_SCRIPT);
+}
+function ensureReadableContent(path, content) {
     try {
-        const existing = readFileSync(scriptPath, "utf-8");
-        if (existing === CONTAINER_PATCH_SCRIPT) {
-            // Also check wrapper
-            const existingWrapper = readFileSync(wrapperPath, "utf-8");
-            if (existingWrapper === CONTAINER_ENTRYPOINT_WRAPPER)
-                return;
+        if (existsSync(path) && readFileSync(path, "utf-8") === content) {
+            chmodSync(path, 0o644);
+            return;
         }
+        writeConfigFile(path, content);
     }
-    catch {
-        // file missing — write it
-    }
-    try {
-        writeFileSync(scriptPath, CONTAINER_PATCH_SCRIPT, { mode: 0o755 });
-        writeFileSync(wrapperPath, CONTAINER_ENTRYPOINT_WRAPPER, { mode: 0o755 });
-    }
-    catch {
-        /* best effort */
+    catch (err) {
+        console.warn(`[openclaw] Failed to write patch script ${path}: ${err?.message ?? err}`);
     }
 }
 function resolveUidGid(username) {
@@ -1414,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;
@@ -1820,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) {
@@ -1853,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,
                     });
@@ -1898,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",
@@ -1912,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).
-            //        - 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.
+            //        - `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).
             //
-            //      Secrets handling (defense-in-depth):
+            //      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, 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");
                     }
                 }
             }
@@ -2052,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) {
@@ -2140,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) {
@@ -2461,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 });
                 }
@@ -2648,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;
@@ -2676,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
@@ -2696,11 +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",
-                // Use the JishuShell entrypoint wrapper that applies the session
-                // fence patch before deferring to the image's original entrypoint.
-                // The wrapper script is written to $HOME/.jishushell/entrypoint.sh
-                // by onBeforeStart (writeContainerPatchScript).
-                entrypoint: [`${openclawHome}/.jishushell/entrypoint.sh`],
+                // 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)),
@@ -2799,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);
     }
@@ -3258,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;
@@ -3386,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;
@@ -3447,9 +3571,7 @@ 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 };