openclaw-openviking-setup-helper 0.3.0-beta.24 → 0.3.0-beta.26

package/install.js

@@ -29,12 +29,12 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 
 let REPO = process.env.REPO || "volcengine/OpenViking";
 // PLUGIN_VERSION takes precedence over BRANCH (legacy). If omitted, resolve the latest tag from GitHub.
-const pluginVersionEnv = (process.env.PLUGIN_VERSION || process.env.BRANCH || "").trim();
-let PLUGIN_VERSION = pluginVersionEnv;
-let pluginVersionExplicit = Boolean(pluginVersionEnv);
-const NPM_REGISTRY = process.env.NPM_REGISTRY || "https://registry.npmmirror.com";
-const DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION = "2026.5.3";
-const OPENCLAW_SHORT_VERSION_YEAR = 2026;
+const pluginVersionEnv = (process.env.PLUGIN_VERSION || process.env.BRANCH || "").trim();
+let PLUGIN_VERSION = pluginVersionEnv;
+let pluginVersionExplicit = Boolean(pluginVersionEnv);
+const NPM_REGISTRY = process.env.NPM_REGISTRY || "https://registry.npmmirror.com";
+const DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION = "2026.5.3";
+const OPENCLAW_SHORT_VERSION_YEAR = 2026;
 
 const IS_WIN = process.platform === "win32";
 const HOME = process.env.HOME || process.env.USERPROFILE || "";
@@ -46,13 +46,13 @@ let PLUGIN_DEST = "";  // Will be set after resolving plugin config
 // Fallback configs for old versions without manifest
 const FALLBACK_LEGACY = {
   dir: "openclaw-memory-plugin",
-  id: "memory-openviking",
-  kind: "memory",
-  slot: "memory",
-  minOpenclawVersion: "2026.3.7",
-  required: ["index.ts", "config.ts", "client.ts", "openclaw.plugin.json", "package.json"],
-  optional: ["package-lock.json", ".gitignore", "memory-ranking.ts", "text-utils.ts", "process-manager.ts", "tsconfig.json"],
-};
+  id: "memory-openviking",
+  kind: "memory",
+  slot: "memory",
+  minOpenclawVersion: "2026.3.7",
+  required: ["index.ts", "config.ts", "client.ts", "openclaw.plugin.json", "package.json"],
+  optional: ["package-lock.json", ".gitignore", "memory-ranking.ts", "text-utils.ts", "process-manager.ts", "tsconfig.json"],
+};
 
 // Must match examples/openclaw-plugin/install-manifest.json (npm only installs package deps, not these .ts files).
 const FALLBACK_CURRENT = {
@@ -60,7 +60,7 @@ const FALLBACK_CURRENT = {
   id: "openviking",
   kind: "context-engine",
   slot: "contextEngine",
-  minOpenclawVersion: "2026.4.8",
+  minOpenclawVersion: "2026.4.8",
   required: ["index.ts", "config.ts", "package.json", "openclaw.plugin.json"],
   optional: [
     "context-engine.ts",
@@ -89,25 +89,27 @@ let resolvedPluginDir = "";
 let resolvedPluginId = "";
 let resolvedPluginKind = "";
 let resolvedPluginSlot = "";
-let resolvedFilesRequired = [];
-let resolvedFilesOptional = [];
-let resolvedNpmOmitDev = true;
-let resolvedNpmBuild = false;
-let resolvedNpmBuildMinOpenclawVersion = DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION;
-let resolvedNpmBuildScript = "build";
-let resolvedNpmPruneAfterBuild = true;
-let resolvedMinOpenclawVersion = "";
-let resolvedMinOpenvikingVersion = "";
-let resolvedPluginReleaseId = "";
-let detectedOpenClawVersion = "";
+let resolvedFilesRequired = [];
+let resolvedFilesOptional = [];
+let resolvedNpmOmitDev = true;
+let resolvedNpmBuild = false;
+let resolvedNpmBuildMinOpenclawVersion = DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION;
+let resolvedNpmBuildScript = "build";
+let resolvedNpmPruneAfterBuild = true;
+let resolvedMinOpenclawVersion = "";
+let resolvedMinOpenvikingVersion = "";
+let resolvedPluginReleaseId = "";
+let detectedOpenClawVersion = "";
 
 let nonInteractive = false;
 let langZh = false;
 let workdirExplicit = false;
 let upgradePluginOnly = false;
 let rollbackLastUpgrade = false;
-let showCurrentVersion = false;
-let uninstallPlugin = false;
+let showCurrentVersion = false;
+let uninstallPlugin = false;
+let forceSlotExplicit = false;
+let allowOfflineExplicit = false;
 
 const selectedMode = "remote";
 const baseUrlFromEnv = !!process.env.OPENVIKING_BASE_URL;
@@ -147,11 +149,19 @@ for (let i = 0; i < argv.length; i++) {
     rollbackLastUpgrade = true;
     continue;
   }
-  if (arg === "--uninstall" || arg === "--remove") {
-    uninstallPlugin = true;
-    continue;
-  }
-  if (arg === "--workdir") {
+  if (arg === "--uninstall" || arg === "--remove") {
+    uninstallPlugin = true;
+    continue;
+  }
+  if (arg === "--force-slot") {
+    forceSlotExplicit = true;
+    continue;
+  }
+  if (arg === "--allow-offline") {
+    allowOfflineExplicit = true;
+    continue;
+  }
+  if (arg === "--workdir") {
     const workdir = argv[i + 1]?.trim();
     if (!workdir) {
       console.error("--workdir requires a path");
@@ -282,9 +292,11 @@ function printHelp() {
   console.log("  --base-url=URL           OpenViking server URL (default: $OPENVIKING_BASE_URL or http://127.0.0.1:1933)");
   console.log("  --api-key=KEY            OpenViking API key (default: $OPENVIKING_API_KEY)");
   console.log("  --agent-prefix=PREFIX    Agent routing prefix (default: $OPENVIKING_AGENT_PREFIX)");
-  console.log("  --account-id=ID          Account ID for root API key (default: $OPENVIKING_ACCOUNT_ID)");
-  console.log("  --user-id=ID             User ID for root API key (default: $OPENVIKING_USER_ID)");
-  console.log("  --zh                     Chinese prompts");
+  console.log("  --account-id=ID          Account ID for root API key (default: $OPENVIKING_ACCOUNT_ID)");
+  console.log("  --user-id=ID             User ID for root API key (default: $OPENVIKING_USER_ID)");
+  console.log("  --force-slot             Explicitly replace an existing contextEngine slot owner");
+  console.log("  --allow-offline          Explicitly save config when the OpenViking server is unreachable");
+  console.log("  --zh                     Chinese prompts");
   console.log("  -h, --help               This help");
   console.log("");
   console.log("Examples:");
@@ -403,47 +415,52 @@ function runCapture(cmd, args, opts = {}) {
   });
 }
 
-function question(prompt, defaultValue = "") {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const suffix = defaultValue ? ` [${defaultValue}]` : "";
-  return new Promise((resolve) => {
-    rl.question(`${prompt}${suffix}: `, (answer) => {
+function question(prompt, defaultValue = "") {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const suffix = defaultValue ? ` [${defaultValue}]` : "";
+  return new Promise((resolve) => {
+    rl.question(`${prompt}${suffix}: `, (answer) => {
       rl.close();
       resolve((answer ?? defaultValue).trim() || defaultValue);
     });
-  });
-}
-
-function isValidAgentPrefixInput(value) {
-  const trimmed = String(value || "").trim();
-  return !trimmed || /^[a-zA-Z0-9_-]+$/.test(trimmed);
+  });
 }
 
-function parseJsonObjectFromOutput(output) {
-  const text = String(output || "").trim();
-  if (!text) return null;
-  try {
-    return JSON.parse(text);
-  } catch {
-    // OpenClaw may print plugin registration logs before --json output.
-  }
-  for (let index = text.lastIndexOf("{"); index >= 0; index = text.lastIndexOf("{", index - 1)) {
-    try {
-      const parsed = JSON.parse(text.slice(index).trim());
-      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-        return parsed;
-      }
-    } catch {
-      // Keep scanning earlier braces until the outer JSON object is found.
-    }
-  }
-  return null;
+function isYes(answer) {
+  const normalized = String(answer || "").trim().toLowerCase();
+  return normalized === "y" || normalized === "yes";
 }
 
-async function questionAgentPrefix(defaultValue = "") {
-  while (true) {
-    const answer = (await question(
-      tr("Agent Prefix (optional)", "Agent Prefix（可选）"),
+function isValidAgentPrefixInput(value) {
+  const trimmed = String(value || "").trim();
+  return !trimmed || /^[a-zA-Z0-9_-]+$/.test(trimmed);
+}
+
+function parseJsonObjectFromOutput(output) {
+  const text = String(output || "").trim();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    // OpenClaw may print plugin registration logs before --json output.
+  }
+  for (let index = text.lastIndexOf("{"); index >= 0; index = text.lastIndexOf("{", index - 1)) {
+    try {
+      const parsed = JSON.parse(text.slice(index).trim());
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed;
+      }
+    } catch {
+      // Keep scanning earlier braces until the outer JSON object is found.
+    }
+  }
+  return null;
+}
+
+async function questionAgentPrefix(defaultValue = "") {
+  while (true) {
+    const answer = (await question(
+      tr("Agent Prefix (optional)", "Agent Prefix（可选）"),
       defaultValue,
     )).trim();
     if (isValidAgentPrefixInput(answer)) {
@@ -530,68 +547,68 @@ async function checkOpenClaw() {
 }
 
 // Compare versions: returns true if v1 >= v2
-function versionGte(v1, v2) {
-  const parseVersion = (v) => {
-    const cleaned = v.replace(/^v/, "").replace(/-.*$/, "");
-    const parts = cleaned.split(".").map((p) => Number.parseInt(p, 10) || 0);
-    while (parts.length < 3) parts.push(0);
+function versionGte(v1, v2) {
+  const parseVersion = (v) => {
+    const cleaned = v.replace(/^v/, "").replace(/-.*$/, "");
+    const parts = cleaned.split(".").map((p) => Number.parseInt(p, 10) || 0);
+    while (parts.length < 3) parts.push(0);
     return parts;
   };
   const [a1, a2, a3] = parseVersion(v1);
   const [b1, b2, b3] = parseVersion(v2);
   if (a1 !== b1) return a1 > b1;
-  if (a2 !== b2) return a2 > b2;
-  return a3 >= b3;
-}
-
-function parseOpenClawPolicyVersion(value) {
-  const parts = String(value || "")
-    .match(/\d+/g)
-    ?.map((part) => Number.parseInt(part, 10) || 0) || [];
-  if (parts.length === 0) return [0, 0, 0];
-  if (parts[0] >= 2000) {
-    return [parts[0], parts[1] || 0, parts[2] || 0];
-  }
-  return [OPENCLAW_SHORT_VERSION_YEAR, parts[0] || 0, parts[1] || 0];
-}
-
-function openClawPolicyVersionGte(v1, v2) {
-  const a = parseOpenClawPolicyVersion(v1);
-  const b = parseOpenClawPolicyVersion(v2);
-  for (let i = 0; i < 3; i++) {
-    if (a[i] !== b[i]) return a[i] > b[i];
-  }
-  return true;
-}
-
-function applyOpenClawBuildPolicy(openClawVersion) {
-  if (!resolvedNpmBuild || !resolvedNpmBuildMinOpenclawVersion) {
-    return;
-  }
-  if (!openClawVersion || openClawVersion === "0.0.0") {
-    warn(tr(
-      "Could not determine OpenClaw version; keeping plugin source build enabled.",
-      "无法确定 OpenClaw 版本，保持插件源码构建开启。",
-    ));
-    return;
-  }
-  if (openClawPolicyVersionGte(openClawVersion, resolvedNpmBuildMinOpenclawVersion)) {
-    info(tr(
-      `OpenClaw ${openClawVersion} requires plugin source build (>= ${resolvedNpmBuildMinOpenclawVersion})`,
-      `OpenClaw ${openClawVersion} 需要插件源码构建（>= ${resolvedNpmBuildMinOpenclawVersion}）`,
-    ));
-    return;
-  }
-  resolvedNpmBuild = false;
-  info(tr(
-    `OpenClaw ${openClawVersion} is below ${resolvedNpmBuildMinOpenclawVersion}; skipping plugin source build`,
-    `OpenClaw ${openClawVersion} 低于 ${resolvedNpmBuildMinOpenclawVersion}，跳过插件源码构建`,
-  ));
-}
-
-function isSemverLike(value) {
-  return /^v?\d+(\.\d+){1,2}$/.test(value);
-}
+  if (a2 !== b2) return a2 > b2;
+  return a3 >= b3;
+}
+
+function parseOpenClawPolicyVersion(value) {
+  const parts = String(value || "")
+    .match(/\d+/g)
+    ?.map((part) => Number.parseInt(part, 10) || 0) || [];
+  if (parts.length === 0) return [0, 0, 0];
+  if (parts[0] >= 2000) {
+    return [parts[0], parts[1] || 0, parts[2] || 0];
+  }
+  return [OPENCLAW_SHORT_VERSION_YEAR, parts[0] || 0, parts[1] || 0];
+}
+
+function openClawPolicyVersionGte(v1, v2) {
+  const a = parseOpenClawPolicyVersion(v1);
+  const b = parseOpenClawPolicyVersion(v2);
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] > b[i];
+  }
+  return true;
+}
+
+function applyOpenClawBuildPolicy(openClawVersion) {
+  if (!resolvedNpmBuild || !resolvedNpmBuildMinOpenclawVersion) {
+    return;
+  }
+  if (!openClawVersion || openClawVersion === "0.0.0") {
+    warn(tr(
+      "Could not determine OpenClaw version; keeping plugin source build enabled.",
+      "无法确定 OpenClaw 版本，保持插件源码构建开启。",
+    ));
+    return;
+  }
+  if (openClawPolicyVersionGte(openClawVersion, resolvedNpmBuildMinOpenclawVersion)) {
+    info(tr(
+      `OpenClaw ${openClawVersion} requires plugin source build (>= ${resolvedNpmBuildMinOpenclawVersion})`,
+      `OpenClaw ${openClawVersion} 需要插件源码构建（>= ${resolvedNpmBuildMinOpenclawVersion}）`,
+    ));
+    return;
+  }
+  resolvedNpmBuild = false;
+  info(tr(
+    `OpenClaw ${openClawVersion} is below ${resolvedNpmBuildMinOpenclawVersion}; skipping plugin source build`,
+    `OpenClaw ${openClawVersion} 低于 ${resolvedNpmBuildMinOpenclawVersion}，跳过插件源码构建`,
+  ));
+}
+
+function isSemverLike(value) {
+  return /^v?\d+(\.\d+){1,2}$/.test(value);
+}
 
 function validateRequestedPluginVersion() {
   if (!isSemverLike(PLUGIN_VERSION)) return;
@@ -612,24 +629,24 @@ if (uninstallPlugin && (upgradePluginOnly || rollbackLastUpgrade)) {
 }
 
 // Detect OpenClaw version
-async function detectOpenClawVersion() {
-  if (detectedOpenClawVersion) {
-    return detectedOpenClawVersion;
-  }
-  try {
-    const result = await runCapture("openclaw", ["--version"], { shell: IS_WIN });
-    const output = `${result.out || ""}\n${result.err || ""}`;
-    if (result.code === 0 && output) {
-      const match = output.match(/\d+\.\d+(\.\d+)?/);
-      if (match) {
-        detectedOpenClawVersion = match[0];
-        return detectedOpenClawVersion;
-      }
-    }
-  } catch {}
-  detectedOpenClawVersion = "0.0.0";
-  return detectedOpenClawVersion;
-}
+async function detectOpenClawVersion() {
+  if (detectedOpenClawVersion) {
+    return detectedOpenClawVersion;
+  }
+  try {
+    const result = await runCapture("openclaw", ["--version"], { shell: IS_WIN });
+    const output = `${result.out || ""}\n${result.err || ""}`;
+    if (result.code === 0 && output) {
+      const match = output.match(/\d+\.\d+(\.\d+)?/);
+      if (match) {
+        detectedOpenClawVersion = match[0];
+        return detectedOpenClawVersion;
+      }
+    }
+  } catch {}
+  detectedOpenClawVersion = "0.0.0";
+  return detectedOpenClawVersion;
+}
 
 // Try to fetch a URL, return response text or null
 async function tryFetch(url, timeout = 15000) {
@@ -772,19 +789,19 @@ async function resolveDefaultPluginVersion() {
 }
 
 // Resolve plugin configuration from manifest or fallback
-async function resolvePluginConfig() {
-  const ghRaw = `https://raw.githubusercontent.com/${REPO}/${PLUGIN_VERSION}`;
-
-  info(tr(`Resolving plugin configuration for version: ${PLUGIN_VERSION}`, `正在解析插件配置，版本: ${PLUGIN_VERSION}`));
-
-  resolvedNpmOmitDev = true;
-  resolvedNpmBuild = false;
-  resolvedNpmBuildMinOpenclawVersion = DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION;
-  resolvedNpmBuildScript = "build";
-  resolvedNpmPruneAfterBuild = true;
-
-  let pluginDir = "";
-  let manifestData = null;
+async function resolvePluginConfig() {
+  const ghRaw = `https://raw.githubusercontent.com/${REPO}/${PLUGIN_VERSION}`;
+
+  info(tr(`Resolving plugin configuration for version: ${PLUGIN_VERSION}`, `正在解析插件配置，版本: ${PLUGIN_VERSION}`));
+
+  resolvedNpmOmitDev = true;
+  resolvedNpmBuild = false;
+  resolvedNpmBuildMinOpenclawVersion = DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION;
+  resolvedNpmBuildScript = "build";
+  resolvedNpmPruneAfterBuild = true;
+
+  let pluginDir = "";
+  let manifestData = null;
 
   // Try to detect plugin directory and download manifest
   const manifestCurrent = await tryFetch(`${ghRaw}/examples/openclaw-plugin/install-manifest.json`);
@@ -821,25 +838,25 @@ async function resolvePluginConfig() {
     resolvedPluginId = manifestData.plugin?.id || "";
     resolvedPluginKind = manifestData.plugin?.kind || "";
     resolvedPluginSlot = manifestData.plugin?.slot || "";
-    resolvedMinOpenclawVersion = manifestData.compatibility?.minOpenclawVersion || "";
-    resolvedMinOpenvikingVersion = manifestData.compatibility?.minOpenvikingVersion || "";
-    resolvedPluginReleaseId = manifestData.pluginVersion || manifestData.release?.id || "";
-    const npmConfig = manifestData.npm && typeof manifestData.npm === "object"
-      ? manifestData.npm
-      : {};
-    resolvedNpmOmitDev = npmConfig.omitDev !== false;
-    resolvedNpmBuild = npmConfig.build === true || npmConfig.buildFromSource === true;
-    resolvedNpmBuildMinOpenclawVersion =
-      typeof npmConfig.buildMinOpenclawVersion === "string" && npmConfig.buildMinOpenclawVersion.trim()
-        ? npmConfig.buildMinOpenclawVersion.trim()
-        : DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION;
-    resolvedNpmBuildScript = typeof npmConfig.buildScript === "string" && npmConfig.buildScript.trim()
-      ? npmConfig.buildScript.trim()
-      : "build";
-    resolvedNpmPruneAfterBuild = npmConfig.pruneAfterBuild !== false;
-    resolvedFilesRequired = manifestData.files?.required || [];
-    resolvedFilesOptional = manifestData.files?.optional || [];
-  } else {
+    resolvedMinOpenclawVersion = manifestData.compatibility?.minOpenclawVersion || "";
+    resolvedMinOpenvikingVersion = manifestData.compatibility?.minOpenvikingVersion || "";
+    resolvedPluginReleaseId = manifestData.pluginVersion || manifestData.release?.id || "";
+    const npmConfig = manifestData.npm && typeof manifestData.npm === "object"
+      ? manifestData.npm
+      : {};
+    resolvedNpmOmitDev = npmConfig.omitDev !== false;
+    resolvedNpmBuild = npmConfig.build === true || npmConfig.buildFromSource === true;
+    resolvedNpmBuildMinOpenclawVersion =
+      typeof npmConfig.buildMinOpenclawVersion === "string" && npmConfig.buildMinOpenclawVersion.trim()
+        ? npmConfig.buildMinOpenclawVersion.trim()
+        : DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION;
+    resolvedNpmBuildScript = typeof npmConfig.buildScript === "string" && npmConfig.buildScript.trim()
+      ? npmConfig.buildScript.trim()
+      : "build";
+    resolvedNpmPruneAfterBuild = npmConfig.pruneAfterBuild !== false;
+    resolvedFilesRequired = manifestData.files?.required || [];
+    resolvedFilesOptional = manifestData.files?.optional || [];
+  } else {
     // No manifest — determine plugin identity by package.json name
     let fallbackKey = pluginDir === "openclaw-memory-plugin" ? "legacy" : "current";
     let compatVer = "";
@@ -868,15 +885,15 @@ async function resolvePluginConfig() {
     resolvedPluginId = fallback.id;
     resolvedPluginKind = fallback.kind;
     resolvedPluginSlot = fallback.slot;
-    resolvedFilesRequired = fallback.required;
-    resolvedFilesOptional = fallback.optional;
-    resolvedNpmOmitDev = true;
-    resolvedNpmBuild = false;
-    resolvedNpmBuildMinOpenclawVersion = DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION;
-    resolvedNpmBuildScript = "build";
-    resolvedNpmPruneAfterBuild = true;
-
-    // If no compatVer from package.json, try main branch manifest
+    resolvedFilesRequired = fallback.required;
+    resolvedFilesOptional = fallback.optional;
+    resolvedNpmOmitDev = true;
+    resolvedNpmBuild = false;
+    resolvedNpmBuildMinOpenclawVersion = DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION;
+    resolvedNpmBuildScript = "build";
+    resolvedNpmPruneAfterBuild = true;
+
+    // If no compatVer from package.json, try main branch manifest
     if (!compatVer && PLUGIN_VERSION !== "main") {
       const mainRaw = `https://raw.githubusercontent.com/${REPO}/main`;
       const mainManifest = await tryFetch(`${mainRaw}/examples/openclaw-plugin/install-manifest.json`);
@@ -907,12 +924,12 @@ async function checkOpenClawCompatibility() {
     return;
   }
 
-  const ocVersion = await detectOpenClawVersion();
-  info(tr(`Detected OpenClaw version: ${ocVersion}`, `检测到 OpenClaw 版本: ${ocVersion}`));
-  applyOpenClawBuildPolicy(ocVersion);
-
-  // If no minimum version required, pass
-  if (!resolvedMinOpenclawVersion) {
+  const ocVersion = await detectOpenClawVersion();
+  info(tr(`Detected OpenClaw version: ${ocVersion}`, `检测到 OpenClaw 版本: ${ocVersion}`));
+  applyOpenClawBuildPolicy(ocVersion);
+
+  // If no minimum version required, pass
+  if (!resolvedMinOpenclawVersion) {
     return;
   }
 
@@ -922,7 +939,7 @@ async function checkOpenClawCompatibility() {
   }
 
   // Check compatibility
-  if (!versionGte(ocVersion, resolvedMinOpenclawVersion)) {
+  if (!openClawPolicyVersionGte(ocVersion, resolvedMinOpenclawVersion)) {
     err(tr(
       `OpenClaw ${ocVersion} does not support this plugin (requires >= ${resolvedMinOpenclawVersion})`,
       `OpenClaw ${ocVersion} 不支持此插件（需要 >= ${resolvedMinOpenclawVersion}）`
@@ -1086,11 +1103,17 @@ function extractRuntimeConfigFromPluginEntry(entryConfig) {
     runtime.apiKey = entryConfig.apiKey;
   }
   const prefix = entryConfig.agent_prefix || entryConfig.agentId;
-  if (typeof prefix === "string" && prefix.trim()) {
-    runtime.agent_prefix = prefix.trim();
-  }
-  return runtime;
-}
+  if (typeof prefix === "string" && prefix.trim()) {
+    runtime.agent_prefix = prefix.trim();
+  }
+  if (typeof entryConfig.accountId === "string" && entryConfig.accountId.trim()) {
+    runtime.accountId = entryConfig.accountId.trim();
+  }
+  if (typeof entryConfig.userId === "string" && entryConfig.userId.trim()) {
+    runtime.userId = entryConfig.userId.trim();
+  }
+  return runtime;
+}
 
 async function backupOpenClawConfig(configPath) {
   await mkdir(getUpgradeAuditDir(), { recursive: true });
@@ -1380,10 +1403,12 @@ async function prepareStrongPluginUpgrade() {
       `检测到已安装 OpenViking 插件状态: ${installedState.generation}`,
     ),
   );
-  remoteBaseUrl = upgradeRuntimeConfig.baseUrl || remoteBaseUrl;
-  remoteApiKey = upgradeRuntimeConfig.apiKey || "";
-  remoteAgentPrefix = upgradeRuntimeConfig.agent_prefix || "";
-  info(tr(`Upgrade runtime mode: ${selectedMode} (remote OpenViking server)`, `升级运行模式: ${selectedMode}（远程 OpenViking 服务）`));
+  remoteBaseUrl = upgradeRuntimeConfig.baseUrl || remoteBaseUrl;
+  remoteApiKey = upgradeRuntimeConfig.apiKey || "";
+  remoteAgentPrefix = upgradeRuntimeConfig.agent_prefix || "";
+  remoteAccountId = upgradeRuntimeConfig.accountId || "";
+  remoteUserId = upgradeRuntimeConfig.userId || "";
+  info(tr(`Upgrade runtime mode: ${selectedMode} (remote OpenViking server)`, `升级运行模式: ${selectedMode}（远程 OpenViking 服务）`));
 
   info(tr(`Upgrade path: ${fromVersion} -> ${toVersion}`, `升级路径: ${fromVersion} -> ${toVersion}`));
 
@@ -1418,7 +1443,7 @@ async function prepareStrongPluginUpgrade() {
   info(tr(`Upgrade audit file: ${getUpgradeAuditPath()}`, `升级审计文件: ${getUpgradeAuditPath()}`));
 }
 
-async function downloadPluginFile(destDir, fileName, url, required, index, total) {
+async function downloadPluginFile(destDir, fileName, url, required, index, total) {
   const maxRetries = 3;
   const destPath = join(destDir, fileName);
 
@@ -1478,109 +1503,109 @@ async function downloadPluginFile(destDir, fileName, url, required, index, total
 
   console.log("");
   err(tr(`Download failed after ${maxRetries} retries: ${url}`, `下载失败（已重试 ${maxRetries} 次）: ${url}`));
-  process.exit(1);
-}
-
-function runtimeOutputCandidatesForEntry(entry) {
-  const normalized = String(entry || "").replace(/\\/g, "/").replace(/^\.\//, "");
-  if (!normalized.endsWith(".ts")) {
-    return [];
-  }
-  const withoutExt = normalized.slice(0, -3);
-  return [
-    `dist/${withoutExt}.js`,
-    `dist/${withoutExt}.mjs`,
-    `dist/${withoutExt}.cjs`,
-    `${withoutExt}.js`,
-    `${withoutExt}.mjs`,
-    `${withoutExt}.cjs`,
-  ];
-}
-
-async function assertBuiltRuntimeOutputs(destDir) {
-  let pkg = null;
-  try {
-    pkg = JSON.parse(await readFile(join(destDir, "package.json"), "utf8"));
-  } catch {
-    return;
-  }
-
-  const entries = [];
-  const extensions = pkg?.openclaw?.extensions;
-  if (Array.isArray(extensions)) {
-    for (const entry of extensions) {
-      if (typeof entry === "string") entries.push(entry);
-    }
-  }
-  if (typeof pkg?.openclaw?.setupEntry === "string") {
-    entries.push(pkg.openclaw.setupEntry);
-  }
-
-  const missing = [];
-  for (const entry of entries) {
-    const candidates = runtimeOutputCandidatesForEntry(entry);
-    if (candidates.length === 0) continue;
-    const found = candidates.some((candidate) => existsSync(join(destDir, ...candidate.split("/"))));
-    if (!found) {
-      missing.push(`${entry} (expected one of: ${candidates.join(", ")})`);
-    }
-  }
-
-  if (missing.length === 0) {
-    return;
-  }
-
-  err(tr(
-    `Plugin build did not create required runtime output:\n  - ${missing.join("\n  - ")}`,
-    `插件构建未生成必需的运行时产物：\n  - ${missing.join("\n  - ")}`,
-  ));
-  process.exit(1);
-}
-
-async function installPluginNpmDependencies(destDir) {
-  if (!resolvedNpmBuild) {
-    info(tr("Installing plugin npm dependencies...", "正在安装插件 npm 依赖..."));
-    const npmArgs = resolvedNpmOmitDev
-      ? ["install", "--omit=dev", "--no-audit", "--no-fund", "--registry", NPM_REGISTRY]
-      : ["install", "--no-audit", "--no-fund", "--registry", NPM_REGISTRY];
-    await run("npm", npmArgs, { cwd: destDir, silent: false });
-    return;
-  }
-
-  info(tr(
-    "Installing plugin npm dependencies for source build...",
-    "正在安装插件源码构建所需的 npm 依赖...",
-  ));
-  await run("npm", [
-    "install",
-    "--include=dev",
-    "--no-audit",
-    "--no-fund",
-    "--registry",
-    NPM_REGISTRY,
-  ], { cwd: destDir, silent: false });
-
-  info(tr(
-    `Building plugin runtime output with npm run ${resolvedNpmBuildScript}...`,
-    `正在执行 npm run ${resolvedNpmBuildScript} 构建插件运行时产物...`,
-  ));
-  await run("npm", ["run", resolvedNpmBuildScript], { cwd: destDir, silent: false });
-  await assertBuiltRuntimeOutputs(destDir);
-
-  if (resolvedNpmOmitDev && resolvedNpmPruneAfterBuild) {
-    info(tr("Pruning plugin dev dependencies...", "正在裁剪插件开发依赖..."));
-    await run("npm", [
-      "prune",
-      "--omit=dev",
-      "--no-audit",
-      "--no-fund",
-    ], { cwd: destDir, silent: false });
-  }
-}
-
-async function downloadPlugin(destDir) {
-  const ghRaw = `https://raw.githubusercontent.com/${REPO}/${PLUGIN_VERSION}`;
-  const pluginDir = resolvedPluginDir;
+  process.exit(1);
+}
+
+function runtimeOutputCandidatesForEntry(entry) {
+  const normalized = String(entry || "").replace(/\\/g, "/").replace(/^\.\//, "");
+  if (!normalized.endsWith(".ts")) {
+    return [];
+  }
+  const withoutExt = normalized.slice(0, -3);
+  return [
+    `dist/${withoutExt}.js`,
+    `dist/${withoutExt}.mjs`,
+    `dist/${withoutExt}.cjs`,
+    `${withoutExt}.js`,
+    `${withoutExt}.mjs`,
+    `${withoutExt}.cjs`,
+  ];
+}
+
+async function assertBuiltRuntimeOutputs(destDir) {
+  let pkg = null;
+  try {
+    pkg = JSON.parse(await readFile(join(destDir, "package.json"), "utf8"));
+  } catch {
+    return;
+  }
+
+  const entries = [];
+  const extensions = pkg?.openclaw?.extensions;
+  if (Array.isArray(extensions)) {
+    for (const entry of extensions) {
+      if (typeof entry === "string") entries.push(entry);
+    }
+  }
+  if (typeof pkg?.openclaw?.setupEntry === "string") {
+    entries.push(pkg.openclaw.setupEntry);
+  }
+
+  const missing = [];
+  for (const entry of entries) {
+    const candidates = runtimeOutputCandidatesForEntry(entry);
+    if (candidates.length === 0) continue;
+    const found = candidates.some((candidate) => existsSync(join(destDir, ...candidate.split("/"))));
+    if (!found) {
+      missing.push(`${entry} (expected one of: ${candidates.join(", ")})`);
+    }
+  }
+
+  if (missing.length === 0) {
+    return;
+  }
+
+  err(tr(
+    `Plugin build did not create required runtime output:\n  - ${missing.join("\n  - ")}`,
+    `插件构建未生成必需的运行时产物：\n  - ${missing.join("\n  - ")}`,
+  ));
+  process.exit(1);
+}
+
+async function installPluginNpmDependencies(destDir) {
+  if (!resolvedNpmBuild) {
+    info(tr("Installing plugin npm dependencies...", "正在安装插件 npm 依赖..."));
+    const npmArgs = resolvedNpmOmitDev
+      ? ["install", "--omit=dev", "--no-audit", "--no-fund", "--registry", NPM_REGISTRY]
+      : ["install", "--no-audit", "--no-fund", "--registry", NPM_REGISTRY];
+    await run("npm", npmArgs, { cwd: destDir, silent: false });
+    return;
+  }
+
+  info(tr(
+    "Installing plugin npm dependencies for source build...",
+    "正在安装插件源码构建所需的 npm 依赖...",
+  ));
+  await run("npm", [
+    "install",
+    "--include=dev",
+    "--no-audit",
+    "--no-fund",
+    "--registry",
+    NPM_REGISTRY,
+  ], { cwd: destDir, silent: false });
+
+  info(tr(
+    `Building plugin runtime output with npm run ${resolvedNpmBuildScript}...`,
+    `正在执行 npm run ${resolvedNpmBuildScript} 构建插件运行时产物...`,
+  ));
+  await run("npm", ["run", resolvedNpmBuildScript], { cwd: destDir, silent: false });
+  await assertBuiltRuntimeOutputs(destDir);
+
+  if (resolvedNpmOmitDev && resolvedNpmPruneAfterBuild) {
+    info(tr("Pruning plugin dev dependencies...", "正在裁剪插件开发依赖..."));
+    await run("npm", [
+      "prune",
+      "--omit=dev",
+      "--no-audit",
+      "--no-fund",
+    ], { cwd: destDir, silent: false });
+  }
+}
+
+async function downloadPlugin(destDir) {
+  const ghRaw = `https://raw.githubusercontent.com/${REPO}/${PLUGIN_VERSION}`;
+  const pluginDir = resolvedPluginDir;
   const total = resolvedFilesRequired.length + resolvedFilesOptional.length;
 
   await mkdir(destDir, { recursive: true });
@@ -1604,9 +1629,9 @@ async function downloadPlugin(destDir) {
     await downloadPluginFile(destDir, name, url, false, i, total);
   }
 
-  await installPluginNpmDependencies(destDir);
-  info(tr(`Plugin deployed: ${PLUGIN_DEST}`, `插件部署完成: ${PLUGIN_DEST}`));
-}
+  await installPluginNpmDependencies(destDir);
+  info(tr(`Plugin deployed: ${PLUGIN_DEST}`, `插件部署完成: ${PLUGIN_DEST}`));
+}
 
 async function createPluginStagingDir() {
   const pluginId = resolvedPluginId || "openviking";
@@ -1768,6 +1793,53 @@ async function cleanupConflictingPluginVariants() {
   info(tr("Conflicting plugin variants cleaned up", "冲突的插件变体已清理"));
 }
 
+function normalizeOpenClawLoadPath(filePath) {
+  return String(filePath || "")
+    .replace(/\\/g, "/")
+    .replace(/\/+$/g, "");
+}
+
+async function ensureOpenClawPluginLoadPath() {
+  const configPath = getOpenClawConfigPath();
+  let cfg = {};
+  if (existsSync(configPath)) {
+    try {
+      cfg = JSON.parse(await readFile(configPath, "utf8"));
+    } catch {
+      return;
+    }
+  }
+
+  const pluginPath = PLUGIN_DEST;
+  const normalizedPluginPath = normalizeOpenClawLoadPath(pluginPath);
+  const plugins = cfg.plugins && typeof cfg.plugins === "object" && !Array.isArray(cfg.plugins)
+    ? cfg.plugins
+    : {};
+  const load = plugins.load && typeof plugins.load === "object" && !Array.isArray(plugins.load)
+    ? plugins.load
+    : {};
+  const paths = Array.isArray(load.paths) ? load.paths : [];
+  if (paths.some((item) => normalizeOpenClawLoadPath(item) === normalizedPluginPath)) {
+    return;
+  }
+
+  const next = {
+    ...cfg,
+    plugins: {
+      ...plugins,
+      load: {
+        ...load,
+        paths: [...paths, pluginPath],
+      },
+    },
+  };
+  await mkdir(dirname(configPath), { recursive: true });
+  const tmp = `${configPath}.ov-install-tmp.${process.pid}`;
+  await writeFile(tmp, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+  await rename(tmp, configPath);
+  info(tr(`Added OpenClaw plugin load path: ${pluginPath}`, `已添加 OpenClaw 插件加载路径: ${pluginPath}`));
+}
+
 async function configureOpenClawPlugin({
   preserveExistingConfig = false,
   runtimeConfig = null,
@@ -1821,6 +1893,8 @@ async function configureOpenClawPlugin({
     await scrubStaleOpenClawPluginRegistration();
   }
 
+  await ensureOpenClawPluginLoadPath();
+
   // Enable plugin: try CLI first (default path), fall back to direct file for --workdir
   if (!needWorkdirFlag) {
     try {
@@ -1932,12 +2006,13 @@ async function configureOpenClawPlugin({
   } catch { /* ignore read errors */ }
 
   let setupResult = null;
-  if (setupJsonSupported) {
+  let parsed = null;
+  const runSetupJson = async (extraArgs = []) => {
     const setupArgs = ["openviking", "setup"];
-    setupArgs.push("--base-url", effectiveRuntimeConfig.baseUrl || remoteBaseUrl);
-    setupArgs.push("--json");
-    if (effectiveRuntimeConfig.apiKey) {
-      setupArgs.push("--api-key", effectiveRuntimeConfig.apiKey);
+    setupArgs.push("--base-url", effectiveRuntimeConfig.baseUrl || remoteBaseUrl);
+    setupArgs.push("--json");
+    if (effectiveRuntimeConfig.apiKey) {
+      setupArgs.push("--api-key", effectiveRuntimeConfig.apiKey);
     }
     if (effectiveRuntimeConfig.agent_prefix) {
       setupArgs.push("--agent-prefix", effectiveRuntimeConfig.agent_prefix);
@@ -1945,35 +2020,67 @@ async function configureOpenClawPlugin({
     if (effectiveRuntimeConfig.accountId) {
       setupArgs.push("--account-id", effectiveRuntimeConfig.accountId);
     }
-    if (effectiveRuntimeConfig.userId) {
-      setupArgs.push("--user-id", effectiveRuntimeConfig.userId);
-    }
-    if (claimSlot) {
-      setupArgs.push("--force-slot");
-    }
-    if (nonInteractive) {
-      setupArgs.push("--allow-offline");
-    }
-
-    info(tr(
-      "Delegating configuration to: openclaw openviking setup --json",
-      "委托配置给: openclaw openviking setup --json",
-    ));
-
-    setupResult = await runCapture("openclaw", setupArgs, { env: ocEnv, shell: IS_WIN });
-  } else {
-    info(tr(
-      "Installed plugin does not support setup --json, using direct config write",
-      "已安装的插件不支持 setup --json，使用直接配置写入",
-    ));
-  }
-
-  let parsed = null;
-  if (setupResult) {
-    parsed = parseJsonObjectFromOutput(`${setupResult.out || ""}\n${setupResult.err || ""}`);
+    if (effectiveRuntimeConfig.userId) {
+      setupArgs.push("--user-id", effectiveRuntimeConfig.userId);
+    }
+    if (forceSlotExplicit) {
+      setupArgs.push("--force-slot");
+    }
+    if (allowOfflineExplicit) {
+      setupArgs.push("--allow-offline");
+    }
+    setupArgs.push(...extraArgs);
+
+    const result = await runCapture("openclaw", setupArgs, { env: ocEnv, shell: IS_WIN });
+    return {
+      result,
+      parsed: parseJsonObjectFromOutput(`${result.out || ""}\n${result.err || ""}`),
+    };
+  };
+
+  if (setupJsonSupported) {
+    info(tr(
+      "Delegating configuration to: openclaw openviking setup --json",
+      "委托配置给: openclaw openviking setup --json",
+    ));
+
+    ({ result: setupResult, parsed } = await runSetupJson());
+  } else {
+    info(tr(
+      "Installed plugin does not support setup --json, using direct config write",
+      "已安装的插件不支持 setup --json，使用直接配置写入",
+    ));
   }
 
-  if (parsed) {
+  if (parsed && !parsed.success && !nonInteractive) {
+    if (parsed.action === "slot_blocked" && !forceSlotExplicit) {
+      const answer = await question(
+        tr(
+          `contextEngine slot is owned by "${parsed.slot?.previousOwner}". Replace it with OpenViking? (y/N)`,
+          `contextEngine slot is owned by "${parsed.slot?.previousOwner}". Replace it with OpenViking? (y/N)`,
+        ),
+      );
+      if (isYes(answer)) {
+        ({ result: setupResult, parsed } = await runSetupJson(["--force-slot"]));
+      }
+    } else if (
+      typeof parsed.error === "string" &&
+      parsed.error.includes("Server unreachable") &&
+      !allowOfflineExplicit
+    ) {
+      const answer = await question(
+        tr(
+          "OpenViking server is unreachable. Save config offline anyway? (y/N)",
+          "OpenViking server is unreachable. Save config offline anyway? (y/N)",
+        ),
+      );
+      if (isYes(answer)) {
+        ({ result: setupResult, parsed } = await runSetupJson(["--allow-offline"]));
+      }
+    }
+  }
+
+  if (parsed) {
     if (parsed.success) {
       info(tr("OpenClaw plugin configured via setup", "OpenClaw 插件通过 setup 配置完成"));
       if (parsed.health?.ok) {
@@ -1991,32 +2098,37 @@ async function configureOpenClawPlugin({
       if (parsed.slot?.activated) {
         info(tr(`contextEngine slot activated`, `contextEngine slot 已激活`));
       }
-    } else {
-      // Setup returned success: false
-      if (parsed.action === "slot_blocked") {
-        warn(tr(
-          `Config saved but contextEngine slot is owned by "${parsed.slot?.previousOwner}". Use --force-slot to override.`,
-          `配置已保存，但 contextEngine slot 被 "${parsed.slot?.previousOwner}" 占用。使用 --force-slot 覆盖。`,
-        ));
-      } else {
-        err(tr(
-          `Setup failed: ${parsed.error || "unknown error"}`,
-          `配置失败: ${parsed.error || "未知错误"}`,
-        ));
-        return {
-          runtimeConfigOk: false,
-          error: parsed.error || parsed.action || "unknown error",
-        };
-      }
-    }
-  } else if (setupResult && setupResult.code !== 0) {
-    warn(tr(
-      `openclaw openviking setup exited with code ${setupResult.code}. Falling back to direct JSON config write.`,
-      `openclaw openviking setup 退出码 ${setupResult.code}，回退到直接写入 JSON 配置。`,
-    ));
-  }
-
-  if (!parsed) {
+    } else {
+      // Setup returned success: false
+      const setupError = parsed.error || parsed.action || "unknown error";
+      if (parsed.action === "slot_blocked") {
+        warn(tr(
+          `Config saved but contextEngine slot is owned by "${parsed.slot?.previousOwner}". Use --force-slot to override.`,
+          `配置已保存，但 contextEngine slot 被 "${parsed.slot?.previousOwner}" 占用。使用 --force-slot 覆盖。`,
+        ));
+      } else {
+        err(tr(
+          `Setup failed: ${setupError}`,
+          `配置失败: ${setupError}`,
+        ));
+      }
+      return {
+        runtimeConfigOk: false,
+        error: setupError,
+      };
+    }
+  } else if (setupJsonSupported) {
+    const setupError = setupResult
+      ? `openclaw openviking setup did not return JSON (exit code ${setupResult.code})`
+      : "openclaw openviking setup did not run";
+    err(tr(`Setup failed: ${setupError}`, `配置失败: ${setupError}`));
+    return {
+      runtimeConfigOk: false,
+      error: setupError,
+    };
+  }
+
+  if (!setupJsonSupported) {
     // Direct write: only used when the installed plugin doesn't support `setup --json` (old version).
     // Read the deployed configSchema to determine which fields are allowed, avoiding
     // "additionalProperties" validation failures when writing new fields to old schemas.
@@ -2153,7 +2265,7 @@ async function performUninstall() {
       tr("Confirm uninstall? (y/N)", "确认卸载？(y/N)"),
       "N",
     );
-    if (answer.toLowerCase() !== "y" && answer.toLowerCase() !== "yes") {
+    if (!isYes(answer)) {
       info(tr("Cancelled.", "已取消。"));
       return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-openviking-setup-helper",
-  "version": "0.3.0-beta.24",
+  "version": "0.3.0-beta.26",
   "description": "Setup helper for installing OpenViking memory plugin into OpenClaw",
   "type": "module",
   "bin": {