openclaw-openviking-setup-helper 0.2.9-dev.0 → 0.2.9-dev.2

package/install.js

@@ -10,7 +10,7 @@
  *   openclaw-openviking-install
  *
  * Direct run:
- *   node install.js [ -y | --yes ] [ --zh ] [ --workdir PATH ]
+ *   node install.js [ -y | --yes ] [ --zh ] [ --workdir PATH ] [ --upgrade-plugin ]
  *                   [ --plugin-version=TAG ] [ --openviking-version=V ] [ --repo=PATH ]
  *
  * Environment variables:
@@ -23,9 +23,9 @@
  */
 
 import { spawn } from "node:child_process";
-import { cp, mkdir, rm, writeFile } from "node:fs/promises";
-import { existsSync, readdirSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
+import { cp, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 
@@ -35,7 +35,7 @@ let REPO = process.env.REPO || "volcengine/OpenViking";
 // PLUGIN_VERSION takes precedence over BRANCH (legacy)
 let PLUGIN_VERSION = process.env.PLUGIN_VERSION || process.env.BRANCH || "main";
 const NPM_REGISTRY = process.env.NPM_REGISTRY || "https://registry.npmmirror.com";
-const PIP_INDEX_URL = process.env.PIP_INDEX_URL || "https://mirrors.volces.com/pypi/simple/";
+const PIP_INDEX_URL = process.env.PIP_INDEX_URL || "https://mirrors.volces.com/pypi/simple/";
 
 const IS_WIN = process.platform === "win32";
 const HOME = process.env.HOME || process.env.USERPROFILE || "";
@@ -61,38 +61,49 @@ const FALLBACK_LEGACY = {
   optional: ["package-lock.json", ".gitignore"],
 };
 
-const FALLBACK_CURRENT = {
-  dir: "openclaw-plugin",
-  id: "openviking",
-  kind: "context-engine",
-  slot: "contextEngine",
-  required: ["index.ts", "context-engine.ts", "config.ts", "client.ts", "process-manager.ts", "memory-ranking.ts", "text-utils.ts", "session-transcript-repair.ts", "tool-call-id.ts", "openclaw.plugin.json", "package.json", "tsconfig.json"],
-  optional: ["package-lock.json", ".gitignore"],
-};
+const FALLBACK_CURRENT = {
+  dir: "openclaw-plugin",
+  id: "openviking",
+  kind: "context-engine",
+  slot: "contextEngine",
+  required: ["index.ts", "config.ts", "openclaw.plugin.json", "package.json"],
+  optional: ["context-engine.ts", "client.ts", "process-manager.ts", "memory-ranking.ts", "text-utils.ts", "session-transcript-repair.ts", "tool-call-id.ts", "tsconfig.json", "package-lock.json", ".gitignore"],
+};
+
+const PLUGIN_VARIANTS = [
+  { ...FALLBACK_LEGACY, generation: "legacy", slotFallback: "none" },
+  { ...FALLBACK_CURRENT, generation: "current", slotFallback: "legacy" },
+];
 
 // Resolved plugin config (set by resolvePluginConfig)
 let resolvedPluginDir = "";
 let resolvedPluginId = "";
 let resolvedPluginKind = "";
 let resolvedPluginSlot = "";
-let resolvedFilesRequired = [];
+let resolvedFilesRequired = [];
 let resolvedFilesOptional = [];
 let resolvedNpmOmitDev = true;
 let resolvedMinOpenclawVersion = "";
 let resolvedMinOpenvikingVersion = "";
+let resolvedPluginReleaseId = "";
 
-let installYes = process.env.OPENVIKING_INSTALL_YES === "1";
-let langZh = false;
-let openvikingVersion = process.env.OPENVIKING_VERSION || "";
-let openvikingRepo = process.env.OPENVIKING_REPO || "";
-let workdirExplicit = false;
+let installYes = process.env.OPENVIKING_INSTALL_YES === "1";
+let langZh = false;
+let openvikingVersion = process.env.OPENVIKING_VERSION || "";
+let openvikingRepo = process.env.OPENVIKING_REPO || "";
+let workdirExplicit = false;
+let upgradePluginOnly = false;
+let rollbackLastUpgrade = false;
 
 let selectedMode = "local";
 let selectedServerPort = DEFAULT_SERVER_PORT;
-let remoteBaseUrl = "http://127.0.0.1:1933";
-let remoteApiKey = "";
-let remoteAgentId = "";
-let openvikingPythonPath = "";
+let remoteBaseUrl = "http://127.0.0.1:1933";
+let remoteApiKey = "";
+let remoteAgentId = "";
+let openvikingPythonPath = "";
+let upgradeRuntimeConfig = null;
+let installedUpgradeState = null;
+let upgradeAudit = null;
 
 const argv = process.argv.slice(2);
 for (let i = 0; i < argv.length; i++) {
@@ -101,11 +112,19 @@ for (let i = 0; i < argv.length; i++) {
     installYes = true;
     continue;
   }
-  if (arg === "--zh") {
-    langZh = true;
-    continue;
-  }
-  if (arg === "--workdir") {
+  if (arg === "--zh") {
+    langZh = true;
+    continue;
+  }
+  if (arg === "--upgrade-plugin" || arg === "--update" || arg === "--upgrade") {
+    upgradePluginOnly = true;
+    continue;
+  }
+  if (arg === "--rollback" || arg === "--rollback-last-upgrade") {
+    rollbackLastUpgrade = true;
+    continue;
+  }
+  if (arg === "--workdir") {
     const workdir = argv[i + 1]?.trim();
     if (!workdir) {
       console.error("--workdir requires a path");
@@ -178,12 +197,16 @@ function printHelp() {
   console.log("Options:");
   console.log("  --github-repo=OWNER/REPO GitHub repository (default: volcengine/OpenViking)");
   console.log("  --plugin-version=TAG     Plugin version (Git tag, e.g. v0.2.9, default: main)");
-  console.log("  --openviking-version=V   OpenViking PyPI version (e.g. 0.2.9, default: latest)");
-  console.log("  --workdir PATH           OpenClaw config directory (default: ~/.openclaw)");
-  console.log("  --repo=PATH              Use local OpenViking repo at PATH (pip -e + local plugin)");
-  console.log("  -y, --yes                Non-interactive (use defaults)");
-  console.log("  --zh                     Chinese prompts");
-  console.log("  -h, --help               This help");
+  console.log("  --openviking-version=V   OpenViking PyPI version (e.g. 0.2.9, default: latest)");
+  console.log("  --workdir PATH           OpenClaw config directory (default: ~/.openclaw)");
+  console.log("  --repo=PATH              Use local OpenViking repo at PATH (pip -e + local plugin)");
+  console.log("  --update, --upgrade-plugin");
+  console.log("                           Backup old plugin, clean only OpenViking plugin config, keep ov.conf");
+  console.log("  --rollback, --rollback-last-upgrade");
+  console.log("                           Roll back the last plugin upgrade using the saved audit/backup files");
+  console.log("  -y, --yes                Non-interactive (use defaults)");
+  console.log("  --zh                     Chinese prompts");
+  console.log("  -h, --help               This help");
   console.log("");
   console.log("Examples:");
   console.log("  # Install latest version");
@@ -191,12 +214,18 @@ function printHelp() {
   console.log("");
   console.log("  # Install from a fork repository");
   console.log("  node install.js --github-repo=yourname/OpenViking --plugin-version=dev-branch");
-  console.log("");
-  console.log("  # Install specific plugin version");
-  console.log("  node install.js --plugin-version=v0.2.8");
-  console.log("");
-  console.log("Env: REPO, PLUGIN_VERSION, OPENVIKING_VERSION, SKIP_OPENCLAW, SKIP_OPENVIKING, NPM_REGISTRY, PIP_INDEX_URL");
-}
+  console.log("");
+  console.log("  # Install specific plugin version");
+  console.log("  node install.js --plugin-version=v0.2.8");
+  console.log("");
+  console.log("  # Upgrade only the plugin files");
+  console.log("  node install.js --update --plugin-version=main");
+  console.log("");
+  console.log("  # Roll back the last plugin upgrade");
+  console.log("  node install.js --rollback");
+  console.log("");
+  console.log("Env: REPO, PLUGIN_VERSION, OPENVIKING_VERSION, SKIP_OPENCLAW, SKIP_OPENVIKING, NPM_REGISTRY, PIP_INDEX_URL");
+}
 
 function tr(en, zh) {
   return langZh ? zh : en;
@@ -296,8 +325,19 @@ function question(prompt, defaultValue = "") {
   });
 }
 
+async function resolveAbsoluteCommand(cmd) {
+  if (cmd.startsWith("/") || (IS_WIN && /^[A-Za-z]:[/\\]/.test(cmd))) return cmd;
+  if (IS_WIN) {
+    const r = await runCapture("where", [cmd], { shell: true });
+    return r.out.split(/\r?\n/)[0]?.trim() || cmd;
+  }
+  const r = await runCapture("which", [cmd], { shell: false });
+  return r.out.trim() || cmd;
+}
+
 async function checkPython() {
-  const py = process.env.OPENVIKING_PYTHON || (IS_WIN ? "python" : "python3");
+  const raw = process.env.OPENVIKING_PYTHON || (IS_WIN ? "python" : "python3");
+  const py = await resolveAbsoluteCommand(raw);
   const result = await runCapture(py, ["-c", "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')"]);
   if (result.code !== 0 || !result.out) {
     return {
@@ -452,7 +492,7 @@ async function checkOpenClaw() {
 }
 
 // Compare versions: returns true if v1 >= v2
-function versionGte(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);
@@ -463,15 +503,28 @@ function versionGte(v1, v2) {
   const [b1, b2, b3] = parseVersion(v2);
   if (a1 !== b1) return a1 > b1;
   if (a2 !== b2) return a2 > b2;
-  return a3 >= b3;
-}
-
+  return a3 >= b3;
+}
+
 function isSemverLike(value) {
   return /^v?\d+(\.\d+){1,2}$/.test(value);
 }
-
-// Detect OpenClaw version
-async function detectOpenClawVersion() {
+
+function validateRequestedPluginVersion() {
+  if (!isSemverLike(PLUGIN_VERSION)) return;
+  if (versionGte(PLUGIN_VERSION, "v0.2.7") && !versionGte(PLUGIN_VERSION, "v0.2.8")) {
+    err(tr("Plugin version v0.2.7 does not exist.", "插件版本 v0.2.7 不存在。"));
+    process.exit(1);
+  }
+}
+
+if (upgradePluginOnly && rollbackLastUpgrade) {
+  console.error("--update/--upgrade-plugin and --rollback cannot be used together");
+  process.exit(1);
+}
+
+// Detect OpenClaw version
+async function detectOpenClawVersion() {
   try {
     const result = await runCapture("openclaw", ["--version"], { shell: IS_WIN });
     if (result.code === 0 && result.out) {
@@ -545,21 +598,45 @@ async function resolvePluginConfig() {
     }
   }
 
-  resolvedPluginDir = pluginDir;
-
+  resolvedPluginDir = pluginDir;
+  resolvedPluginReleaseId = "";
+
   if (manifestData) {
     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 || "";
     resolvedNpmOmitDev = manifestData.npm?.omitDev !== false;
     resolvedFilesRequired = manifestData.files?.required || [];
     resolvedFilesOptional = manifestData.files?.optional || [];
   } else {
-    // Use fallback config
-    const fallback = pluginDir === "openclaw-memory-plugin" ? FALLBACK_LEGACY : FALLBACK_CURRENT;
-    resolvedPluginDir = fallback.dir;
+    // No manifest — determine plugin identity by package.json name
+    let fallbackKey = pluginDir === "openclaw-memory-plugin" ? "legacy" : "current";
+    let compatVer = "";
+
+    const pkgJson = await tryFetch(`${ghRaw}/examples/${pluginDir}/package.json`);
+    if (pkgJson) {
+      try {
+        const pkg = JSON.parse(pkgJson);
+        const pkgName = pkg.name || "";
+        resolvedPluginReleaseId = pkg.version || "";
+        if (pkgName && pkgName !== "@openclaw/openviking") {
+          fallbackKey = "legacy";
+          info(tr(`Detected legacy plugin by package name: ${pkgName}`, `通过 package.json 名称检测到旧版插件: ${pkgName}`));
+        } else if (pkgName) {
+          fallbackKey = "current";
+        }
+        compatVer = (pkg.engines?.openclaw || "").replace(/^>=?\s*/, "").trim();
+        if (compatVer) {
+          info(tr(`Read minOpenclawVersion from package.json engines.openclaw: >=${compatVer}`, `从 package.json engines.openclaw 读取到最低版本: >=${compatVer}`));
+        }
+      } catch {}
+    }
+
+    const fallback = fallbackKey === "legacy" ? FALLBACK_LEGACY : FALLBACK_CURRENT;
+    resolvedPluginDir = pluginDir;
     resolvedPluginId = fallback.id;
     resolvedPluginKind = fallback.kind;
     resolvedPluginSlot = fallback.slot;
@@ -567,13 +644,24 @@ async function resolvePluginConfig() {
     resolvedFilesOptional = fallback.optional;
     resolvedNpmOmitDev = true;
 
-    if (pluginDir === "openclaw-plugin") {
-      resolvedMinOpenclawVersion = "3.7";
-    } else {
-      resolvedMinOpenclawVersion = "";
-    }
-    resolvedMinOpenvikingVersion = "";
-  }
+    // 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`);
+      if (mainManifest) {
+        try {
+          const m = JSON.parse(mainManifest);
+          compatVer = m.compatibility?.minOpenclawVersion || "";
+          if (compatVer) {
+            info(tr(`Read minOpenclawVersion from main branch manifest: >=${compatVer}`, `从 main 分支 manifest 读取到最低版本: >=${compatVer}`));
+          }
+        } catch {}
+      }
+    }
+
+    resolvedMinOpenclawVersion = compatVer || "2026.3.7";
+    resolvedMinOpenvikingVersion = "";
+  }
 
   // Set plugin destination
   PLUGIN_DEST = join(OPENCLAW_DIR, "extensions", resolvedPluginId);
@@ -596,7 +684,7 @@ async function checkOpenClawCompatibility() {
   }
 
   // If user explicitly requested an old version, pass
-  if (PLUGIN_VERSION !== "main" && isSemverLike(PLUGIN_VERSION) && !versionGte(PLUGIN_VERSION, "v0.2.9")) {
+  if (PLUGIN_VERSION !== "main" && isSemverLike(PLUGIN_VERSION) && !versionGte(PLUGIN_VERSION, "v0.2.8")) {
     return;
   }
 
@@ -610,32 +698,32 @@ async function checkOpenClawCompatibility() {
     bold(tr("Please choose one of the following options:", "请选择以下方案之一："));
     console.log("");
     console.log(`  ${tr("Option 1: Upgrade OpenClaw", "方案 1：升级 OpenClaw")}`);
-    console.log(`    npm update -g openclaw --registry ${NPM_REGISTRY}`);
+    console.log(`    npm update -g openclaw --registry ${NPM_REGISTRY}`);
     console.log("");
     console.log(`  ${tr("Option 2: Install legacy plugin (v0.2.8)", "方案 2：安装旧版插件 (v0.2.8)")}`);
-    console.log(`    node install.js --plugin-version=v0.2.8${langZh ? " --zh" : ""}`);
+    console.log(`    node install.js --plugin-version=v0.2.6${langZh ? " --zh" : ""}`);
     console.log("");
     process.exit(1);
   }
-}
-
-function checkRequestedOpenVikingCompatibility() {
-  if (!resolvedMinOpenvikingVersion || !openvikingVersion) return;
-  if (versionGte(openvikingVersion, resolvedMinOpenvikingVersion)) return;
-
-  err(tr(
-    `OpenViking ${openvikingVersion} does not support this plugin (requires >= ${resolvedMinOpenvikingVersion})`,
-    `OpenViking ${openvikingVersion} 不支持此插件（需要 >= ${resolvedMinOpenvikingVersion}）`,
-  ));
-  console.log("");
-  console.log(tr(
-    "Use a newer OpenViking version, or omit --openviking-version to install the latest release.",
-    "请使用更新版本的 OpenViking，或省略 --openviking-version 以安装最新版本。",
-  ));
-  process.exit(1);
-}
-
-async function installOpenViking() {
+}
+
+function checkRequestedOpenVikingCompatibility() {
+  if (!resolvedMinOpenvikingVersion || !openvikingVersion) return;
+  if (versionGte(openvikingVersion, resolvedMinOpenvikingVersion)) return;
+
+  err(tr(
+    `OpenViking ${openvikingVersion} does not support this plugin (requires >= ${resolvedMinOpenvikingVersion})`,
+    `OpenViking ${openvikingVersion} 不支持此插件（需要 >= ${resolvedMinOpenvikingVersion}）`,
+  ));
+  console.log("");
+  console.log(tr(
+    "Use a newer OpenViking version, or omit --openviking-version to install the latest release.",
+    "请使用更新版本的 OpenViking，或省略 --openviking-version 以安装最新版本。",
+  ));
+  process.exit(1);
+}
+
+async function installOpenViking() {
   if (process.env.SKIP_OPENVIKING === "1") {
     info(tr("Skipping OpenViking install (SKIP_OPENVIKING=1)", "跳过 OpenViking 安装 (SKIP_OPENVIKING=1)"));
     return;
@@ -646,6 +734,12 @@ async function installOpenViking() {
     err(tr("Python check failed.", "Python 校验失败"));
     process.exit(1);
   }
+  if (!python.ok) {
+    warn(tr(
+      `${python.detail}. Will attempt to find a suitable Python for pip install.`,
+      `${python.detail}。将尝试查找合适的 Python 进行 pip 安装。`,
+    ));
+  }
 
   const py = python.cmd;
 
@@ -809,20 +903,20 @@ async function configureOvConf() {
       rotation_days: 3,
       rotation_interval: "midnight",
     },
-    embedding: {
-      dense: {
-        provider: "volcengine",
-        api_key: embeddingApiKey || null,
-        model: embeddingModel,
-        api_base: "https://ark.cn-beijing.volces.com/api/v3",
+    embedding: {
+      dense: {
+        provider: "volcengine",
+        api_key: embeddingApiKey || null,
+        model: embeddingModel,
+        api_base: "https://ark.cn-beijing.volces.com/api/v3",
         dimension: 1024,
         input: "multimodal",
       },
-    },
-    vlm: {
-      provider: "volcengine",
-      api_key: vlmApiKey || null,
-      model: vlmModel,
+    },
+    vlm: {
+      provider: "volcengine",
+      api_key: vlmApiKey || null,
+      model: vlmModel,
       api_base: "https://ark.cn-beijing.volces.com/api/v3",
       temperature: 0.1,
       max_retries: 3,
@@ -834,8 +928,507 @@ async function configureOvConf() {
   info(tr(`Config generated: ${configPath}`, `已生成配置: ${configPath}`));
 }
 
-async function downloadPluginFile(fileName, url, required, index, total) {
-  const maxRetries = 3;
+function getOpenClawConfigPath() {
+  return join(OPENCLAW_DIR, "openclaw.json");
+}
+
+function getOpenClawEnv() {
+  if (OPENCLAW_DIR === DEFAULT_OPENCLAW_DIR) {
+    return { ...process.env };
+  }
+  return { ...process.env, OPENCLAW_STATE_DIR: OPENCLAW_DIR };
+}
+
+async function readJsonFileIfExists(filePath) {
+  if (!existsSync(filePath)) return null;
+  const raw = await readFile(filePath, "utf8");
+  return JSON.parse(raw);
+}
+
+function getInstallStatePathForPlugin(pluginId) {
+  return join(OPENCLAW_DIR, "extensions", pluginId, ".ov-install-state.json");
+}
+
+function getUpgradeAuditDir() {
+  return join(OPENCLAW_DIR, ".openviking-upgrade-backup");
+}
+
+function getUpgradeAuditPath() {
+  return join(getUpgradeAuditDir(), "last-upgrade.json");
+}
+
+function getOpenClawConfigBackupPath() {
+  return join(getUpgradeAuditDir(), "openclaw.json.bak");
+}
+
+function normalizePluginMode(value) {
+  return value === "remote" ? "remote" : "local";
+}
+
+function getPluginVariantById(pluginId) {
+  return PLUGIN_VARIANTS.find((variant) => variant.id === pluginId) || null;
+}
+
+function detectPluginPresence(config, variant) {
+  const plugins = config?.plugins;
+  const reasons = [];
+  if (!plugins) {
+    return { variant, present: false, reasons };
+  }
+
+  if (plugins.entries && Object.prototype.hasOwnProperty.call(plugins.entries, variant.id)) {
+    reasons.push("entry");
+  }
+  if (plugins.slots?.[variant.slot] === variant.id) {
+    reasons.push("slot");
+  }
+  if (Array.isArray(plugins.allow) && plugins.allow.includes(variant.id)) {
+    reasons.push("allow");
+  }
+  if (
+    Array.isArray(plugins.load?.paths)
+    && plugins.load.paths.some((item) => typeof item === "string" && (item.includes(variant.id) || item.includes(variant.dir)))
+  ) {
+    reasons.push("loadPath");
+  }
+  if (existsSync(join(OPENCLAW_DIR, "extensions", variant.id))) {
+    reasons.push("dir");
+  }
+
+  return { variant, present: reasons.length > 0, reasons };
+}
+
+async function detectInstalledPluginState() {
+  const configPath = getOpenClawConfigPath();
+  const config = await readJsonFileIfExists(configPath);
+  const detections = [];
+  for (const variant of PLUGIN_VARIANTS) {
+    const detection = detectPluginPresence(config, variant);
+    if (!detection.present) continue;
+    detection.installState = await readJsonFileIfExists(getInstallStatePathForPlugin(variant.id));
+    detections.push(detection);
+  }
+
+  let generation = "none";
+  if (detections.length === 1) {
+    generation = detections[0].variant.generation;
+  } else if (detections.length > 1) {
+    generation = "mixed";
+  }
+
+  return {
+    config,
+    configPath,
+    detections,
+    generation,
+  };
+}
+
+function formatInstalledDetectionLabel(detection) {
+  const requestedRef = detection.installState?.requestedRef;
+  const releaseId = detection.installState?.releaseId;
+  if (requestedRef) return `${detection.variant.id}@${requestedRef}`;
+  if (releaseId) return `${detection.variant.id}#${releaseId}`;
+  return `${detection.variant.id} (${detection.variant.generation}, exact version unknown)`;
+}
+
+function formatInstalledStateLabel(installedState) {
+  if (!installedState?.detections?.length) {
+    return "not-installed";
+  }
+  return installedState.detections.map(formatInstalledDetectionLabel).join(" + ");
+}
+
+function formatTargetVersionLabel() {
+  const base = `${resolvedPluginId || "openviking"}@${PLUGIN_VERSION}`;
+  if (resolvedPluginReleaseId && resolvedPluginReleaseId !== PLUGIN_VERSION) {
+    return `${base} (${resolvedPluginReleaseId})`;
+  }
+  return base;
+}
+
+function extractRuntimeConfigFromPluginEntry(entryConfig) {
+  if (!entryConfig || typeof entryConfig !== "object") return null;
+
+  const mode = normalizePluginMode(entryConfig.mode);
+  const runtime = { mode };
+
+  if (mode === "remote") {
+    if (typeof entryConfig.baseUrl === "string" && entryConfig.baseUrl.trim()) {
+      runtime.baseUrl = entryConfig.baseUrl.trim();
+    }
+    if (typeof entryConfig.apiKey === "string" && entryConfig.apiKey.trim()) {
+      runtime.apiKey = entryConfig.apiKey;
+    }
+    if (typeof entryConfig.agentId === "string" && entryConfig.agentId.trim()) {
+      runtime.agentId = entryConfig.agentId.trim();
+    }
+    return runtime;
+  }
+
+  if (typeof entryConfig.configPath === "string" && entryConfig.configPath.trim()) {
+    runtime.configPath = entryConfig.configPath.trim();
+  }
+  if (entryConfig.port !== undefined && entryConfig.port !== null && `${entryConfig.port}`.trim()) {
+    const parsedPort = Number.parseInt(String(entryConfig.port), 10);
+    if (Number.isFinite(parsedPort) && parsedPort > 0) {
+      runtime.port = parsedPort;
+    }
+  }
+  return runtime;
+}
+
+async function readPortFromOvConf(configPath) {
+  const filePath = configPath || join(OPENVIKING_DIR, "ov.conf");
+  if (!existsSync(filePath)) return null;
+  try {
+    const ovConf = await readJsonFileIfExists(filePath);
+    const parsedPort = Number.parseInt(String(ovConf?.server?.port ?? ""), 10);
+    return Number.isFinite(parsedPort) && parsedPort > 0 ? parsedPort : null;
+  } catch {
+    return null;
+  }
+}
+
+async function backupOpenClawConfig(configPath) {
+  await mkdir(getUpgradeAuditDir(), { recursive: true });
+  const backupPath = getOpenClawConfigBackupPath();
+  const configText = await readFile(configPath, "utf8");
+  await writeFile(backupPath, configText, "utf8");
+  return backupPath;
+}
+
+async function writeUpgradeAuditFile(data) {
+  await mkdir(getUpgradeAuditDir(), { recursive: true });
+  await writeFile(getUpgradeAuditPath(), `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}
+
+async function writeInstallStateFile({ operation, fromVersion, configBackupPath, pluginBackups }) {
+  const installStatePath = getInstallStatePathForPlugin(resolvedPluginId || "openviking");
+  const state = {
+    pluginId: resolvedPluginId || "openviking",
+    generation: getPluginVariantById(resolvedPluginId || "openviking")?.generation || "unknown",
+    requestedRef: PLUGIN_VERSION,
+    releaseId: resolvedPluginReleaseId || "",
+    operation,
+    fromVersion: fromVersion || "",
+    configBackupPath: configBackupPath || "",
+    pluginBackups: pluginBackups || [],
+    installedAt: new Date().toISOString(),
+    repo: REPO,
+  };
+  await writeFile(installStatePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+async function moveDirWithFallback(sourceDir, destDir) {
+  try {
+    await rename(sourceDir, destDir);
+  } catch {
+    await cp(sourceDir, destDir, { recursive: true, force: true });
+    await rm(sourceDir, { recursive: true, force: true });
+  }
+}
+
+async function rollbackLastUpgradeOperation() {
+  const auditPath = getUpgradeAuditPath();
+  const audit = await readJsonFileIfExists(auditPath);
+  if (!audit) {
+    err(
+      tr(
+        `No rollback audit file found at ${auditPath}.`,
+        `未找到回滚审计文件: ${auditPath}`,
+      ),
+    );
+    process.exit(1);
+  }
+
+  if (audit.rolledBackAt) {
+    warn(
+      tr(
+        `The last recorded upgrade was already rolled back at ${audit.rolledBackAt}.`,
+        `最近一次升级已在 ${audit.rolledBackAt} 回滚。`,
+      ),
+    );
+  }
+
+  const configBackupPath = audit.configBackupPath || getOpenClawConfigBackupPath();
+  if (!existsSync(configBackupPath)) {
+    err(
+      tr(
+        `Rollback config backup is missing: ${configBackupPath}`,
+        `回滚配置备份缺失: ${configBackupPath}`,
+      ),
+    );
+    process.exit(1);
+  }
+
+  const pluginBackups = Array.isArray(audit.pluginBackups) ? audit.pluginBackups : [];
+  if (pluginBackups.length === 0) {
+    err(tr("Rollback audit file contains no plugin backups.", "回滚审计文件中没有插件备份信息。"));
+    process.exit(1);
+  }
+  for (const pluginBackup of pluginBackups) {
+    if (!pluginBackup?.pluginId || !pluginBackup?.backupDir || !existsSync(pluginBackup.backupDir)) {
+      err(
+        tr(
+          `Rollback plugin backup is missing: ${pluginBackup?.backupDir || "<unknown>"}`,
+          `回滚插件备份缺失: ${pluginBackup?.backupDir || "<unknown>"}`,
+        ),
+      );
+      process.exit(1);
+    }
+  }
+
+  info(tr(`Rolling back last upgrade: ${audit.fromVersion || "unknown"} <- ${audit.toVersion || "unknown"}`, `开始回滚最近一次升级: ${audit.fromVersion || "unknown"} <- ${audit.toVersion || "unknown"}`));
+  await stopOpenClawGatewayForUpgrade();
+
+  const configText = await readFile(configBackupPath, "utf8");
+  await writeFile(getOpenClawConfigPath(), configText, "utf8");
+  info(tr(`Restored openclaw.json from backup: ${configBackupPath}`, `已从备份恢复 openclaw.json: ${configBackupPath}`));
+
+  const extensionsDir = join(OPENCLAW_DIR, "extensions");
+  await mkdir(extensionsDir, { recursive: true });
+  for (const variant of PLUGIN_VARIANTS) {
+    const liveDir = join(extensionsDir, variant.id);
+    if (existsSync(liveDir)) {
+      await rm(liveDir, { recursive: true, force: true });
+    }
+  }
+
+  for (const pluginBackup of pluginBackups) {
+    if (!pluginBackup?.pluginId || !pluginBackup?.backupDir) continue;
+    if (!existsSync(pluginBackup.backupDir)) {
+      err(
+        tr(
+          `Rollback plugin backup is missing: ${pluginBackup.backupDir}`,
+          `回滚插件备份缺失: ${pluginBackup.backupDir}`,
+        ),
+      );
+      process.exit(1);
+    }
+    const destDir = join(extensionsDir, pluginBackup.pluginId);
+    await moveDirWithFallback(pluginBackup.backupDir, destDir);
+    info(tr(`Restored plugin directory: ${destDir}`, `已恢复插件目录: ${destDir}`));
+  }
+
+  audit.rolledBackAt = new Date().toISOString();
+  audit.rollbackConfigPath = configBackupPath;
+  await writeUpgradeAuditFile(audit);
+
+  console.log("");
+  bold(tr("Rollback complete!", "回滚完成！"));
+  console.log("");
+  info(tr(`Rollback audit file: ${auditPath}`, `回滚审计文件: ${auditPath}`));
+  info(tr("Run `openclaw gateway` and `openclaw status` to verify the restored plugin state.", "请运行 `openclaw gateway` 和 `openclaw status` 验证恢复后的插件状态。"));
+}
+
+async function prepareUpgradeRuntimeConfig(installedState) {
+  const plugins = installedState.config?.plugins ?? {};
+  const candidateOrder = installedState.detections
+    .map((item) => item.variant)
+    .sort((left, right) => (right.generation === "current" ? 1 : 0) - (left.generation === "current" ? 1 : 0));
+
+  let runtime = null;
+  for (const variant of candidateOrder) {
+    const entryConfig = extractRuntimeConfigFromPluginEntry(plugins.entries?.[variant.id]?.config);
+    if (entryConfig) {
+      runtime = entryConfig;
+      break;
+    }
+  }
+
+  if (!runtime) {
+    runtime = { mode: "local" };
+  }
+
+  if (runtime.mode === "remote") {
+    runtime.baseUrl = runtime.baseUrl || remoteBaseUrl;
+    return runtime;
+  }
+
+  runtime.configPath = runtime.configPath || join(OPENVIKING_DIR, "ov.conf");
+  runtime.port = runtime.port || await readPortFromOvConf(runtime.configPath) || DEFAULT_SERVER_PORT;
+  return runtime;
+}
+
+function removePluginConfig(config, variant) {
+  const plugins = config?.plugins;
+  if (!plugins) return false;
+
+  let changed = false;
+
+  if (Array.isArray(plugins.allow)) {
+    const nextAllow = plugins.allow.filter((item) => item !== variant.id);
+    changed = changed || nextAllow.length !== plugins.allow.length;
+    plugins.allow = nextAllow;
+  }
+
+  if (Array.isArray(plugins.load?.paths)) {
+    const nextPaths = plugins.load.paths.filter(
+      (item) => typeof item !== "string" || (!item.includes(variant.id) && !item.includes(variant.dir)),
+    );
+    changed = changed || nextPaths.length !== plugins.load.paths.length;
+    plugins.load.paths = nextPaths;
+  }
+
+  if (plugins.entries && Object.prototype.hasOwnProperty.call(plugins.entries, variant.id)) {
+    delete plugins.entries[variant.id];
+    changed = true;
+  }
+
+  if (plugins.slots?.[variant.slot] === variant.id) {
+    plugins.slots[variant.slot] = variant.slotFallback;
+    changed = true;
+  }
+
+  return changed;
+}
+
+async function prunePreviousUpgradeBackups(disabledDir, variant, keepDir) {
+  if (!existsSync(disabledDir)) return;
+
+  const prefix = `${variant.id}-upgrade-backup-`;
+  const keepName = keepDir ? keepDir.split(/[\\/]/).pop() : "";
+  const entries = readdirSync(disabledDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (!entry.name.startsWith(prefix)) continue;
+    if (keepName && entry.name === keepName) continue;
+    await rm(join(disabledDir, entry.name), { recursive: true, force: true });
+  }
+}
+
+async function backupPluginDirectory(variant) {
+  const pluginDir = join(OPENCLAW_DIR, "extensions", variant.id);
+  if (!existsSync(pluginDir)) return null;
+
+  const disabledDir = join(OPENCLAW_DIR, "disabled-extensions");
+  const backupDir = join(disabledDir, `${variant.id}-upgrade-backup-${Date.now()}`);
+  await mkdir(disabledDir, { recursive: true });
+  try {
+    await rename(pluginDir, backupDir);
+  } catch {
+    await cp(pluginDir, backupDir, { recursive: true, force: true });
+    await rm(pluginDir, { recursive: true, force: true });
+  }
+  info(tr(`Backed up plugin directory: ${backupDir}`, `已备份插件目录: ${backupDir}`));
+  await prunePreviousUpgradeBackups(disabledDir, variant, backupDir);
+  return backupDir;
+}
+
+async function stopOpenClawGatewayForUpgrade() {
+  const result = await runCapture("openclaw", ["gateway", "stop"], {
+    env: getOpenClawEnv(),
+    shell: IS_WIN,
+  });
+  if (result.code === 0) {
+    info(tr("Stopped OpenClaw gateway before plugin upgrade", "升级插件前已停止 OpenClaw gateway"));
+  } else {
+    warn(tr("OpenClaw gateway may not be running; continuing", "OpenClaw gateway 可能未在运行，继续执行"));
+  }
+}
+
+function shouldClaimTargetSlot(installedState) {
+  const currentOwner = installedState.config?.plugins?.slots?.[resolvedPluginSlot];
+  if (!currentOwner || currentOwner === "none" || currentOwner === "legacy" || currentOwner === resolvedPluginId) {
+    return true;
+  }
+  const currentOwnerVariant = getPluginVariantById(currentOwner);
+  if (currentOwnerVariant && installedState.detections.some((item) => item.variant.id === currentOwnerVariant.id)) {
+    return true;
+  }
+  return false;
+}
+
+async function cleanupInstalledPluginConfig(installedState) {
+  if (!installedState.config || !installedState.config.plugins) {
+    warn(tr("openclaw.json has no plugins section; skipped targeted plugin cleanup", "openclaw.json 中没有 plugins 配置，已跳过定向插件清理"));
+    return;
+  }
+
+  const nextConfig = structuredClone(installedState.config);
+  let changed = false;
+  for (const detection of installedState.detections) {
+    changed = removePluginConfig(nextConfig, detection.variant) || changed;
+  }
+
+  if (!changed) {
+    info(tr("No OpenViking plugin config changes were required", "无需修改 OpenViking 插件配置"));
+    return;
+  }
+
+  await writeFile(installedState.configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");
+  info(tr("Cleaned existing OpenViking plugin config only", "已仅清理 OpenViking 自身插件配置"));
+}
+
+async function prepareStrongPluginUpgrade() {
+  const installedState = await detectInstalledPluginState();
+  if (installedState.generation === "none") {
+    err(
+      tr(
+        "Plugin upgrade mode requires an existing OpenViking plugin entry in openclaw.json.",
+        "插件升级模式要求 openclaw.json 中已经存在 OpenViking 插件记录。",
+      ),
+    );
+    process.exit(1);
+  }
+
+  installedUpgradeState = installedState;
+  upgradeRuntimeConfig = await prepareUpgradeRuntimeConfig(installedState);
+  const fromVersion = formatInstalledStateLabel(installedState);
+  const toVersion = formatTargetVersionLabel();
+  selectedMode = upgradeRuntimeConfig.mode;
+  info(
+    tr(
+      `Detected installed OpenViking plugin state: ${installedState.generation}`,
+      `检测到已安装 OpenViking 插件状态: ${installedState.generation}`,
+    ),
+  );
+  if (upgradeRuntimeConfig.mode === "remote") {
+    remoteBaseUrl = upgradeRuntimeConfig.baseUrl || remoteBaseUrl;
+    remoteApiKey = upgradeRuntimeConfig.apiKey || "";
+    remoteAgentId = upgradeRuntimeConfig.agentId || "";
+  } else {
+    selectedServerPort = upgradeRuntimeConfig.port || DEFAULT_SERVER_PORT;
+  }
+  info(tr(`Upgrade runtime mode: ${selectedMode}`, `升级运行模式: ${selectedMode}`));
+
+  info(tr(`Upgrade path: ${fromVersion} -> ${toVersion}`, `升级路径: ${fromVersion} -> ${toVersion}`));
+
+  await stopOpenClawGatewayForUpgrade();
+  const configBackupPath = await backupOpenClawConfig(installedState.configPath);
+  info(tr(`Backed up openclaw.json: ${configBackupPath}`, `已备份 openclaw.json: ${configBackupPath}`));
+  const pluginBackups = [];
+  for (const detection of installedState.detections) {
+    const backupDir = await backupPluginDirectory(detection.variant);
+    if (backupDir) {
+      pluginBackups.push({ pluginId: detection.variant.id, backupDir });
+    }
+  }
+  upgradeAudit = {
+    operation: "upgrade",
+    createdAt: new Date().toISOString(),
+    fromVersion,
+    toVersion,
+    configBackupPath,
+    pluginBackups,
+    runtimeMode: selectedMode,
+  };
+  await writeUpgradeAuditFile(upgradeAudit);
+  await cleanupInstalledPluginConfig(installedState);
+
+  info(
+    tr(
+      "Upgrade will keep the existing OpenViking runtime file and re-apply only the minimum plugin runtime settings.",
+      "升级将保留现有 OpenViking 运行时文件，并只回填最小插件运行配置。",
+    ),
+  );
+  info(tr(`Upgrade audit file: ${getUpgradeAuditPath()}`, `升级审计文件: ${getUpgradeAuditPath()}`));
+}
+
+async function downloadPluginFile(destDir, fileName, url, required, index, total) {
+  const maxRetries = 3;
+  const destPath = join(destDir, fileName);
 
   process.stdout.write(`  [${index}/${total}] ${fileName} `);
 
@@ -844,7 +1437,8 @@ async function downloadPluginFile(fileName, url, required, index, total) {
       const response = await fetch(url);
       if (response.ok) {
         const buffer = Buffer.from(await response.arrayBuffer());
-        await writeFile(join(PLUGIN_DEST, fileName), buffer);
+        await mkdir(dirname(destPath), { recursive: true });
+        await writeFile(destPath, buffer);
         console.log("✓");
         return;
       }
@@ -861,7 +1455,8 @@ async function downloadPluginFile(fileName, url, required, index, total) {
 
   if (fileName === ".gitignore") {
     console.log(tr("(retries failed, using minimal .gitignore)", "（重试失败，使用最小 .gitignore）"));
-    await writeFile(join(PLUGIN_DEST, fileName), "node_modules/\n", "utf8");
+    await mkdir(dirname(destPath), { recursive: true });
+    await writeFile(destPath, "node_modules/\n", "utf8");
     return;
   }
 
@@ -875,12 +1470,12 @@ async function downloadPluginFile(fileName, url, required, index, total) {
   process.exit(1);
 }
 
-async function downloadPlugin() {
+async function downloadPlugin(destDir) {
   const ghRaw = `https://raw.githubusercontent.com/${REPO}/${PLUGIN_VERSION}`;
   const pluginDir = resolvedPluginDir;
   const total = resolvedFilesRequired.length + resolvedFilesOptional.length;
 
-  await mkdir(PLUGIN_DEST, { recursive: true });
+  await mkdir(destDir, { recursive: true });
 
   info(tr(`Downloading plugin from ${REPO}@${PLUGIN_VERSION} (${total} files)...`, `正在从 ${REPO}@${PLUGIN_VERSION} 下载插件（共 ${total} 个文件）...`));
 
@@ -890,7 +1485,7 @@ async function downloadPlugin() {
     if (!name) continue;
     i++;
     const url = `${ghRaw}/examples/${pluginDir}/${name}`;
-    await downloadPluginFile(name, url, true, i, total);
+    await downloadPluginFile(destDir, name, url, true, i, total);
   }
 
   // Download optional files
@@ -898,93 +1493,187 @@ async function downloadPlugin() {
     if (!name) continue;
     i++;
     const url = `${ghRaw}/examples/${pluginDir}/${name}`;
-    await downloadPluginFile(name, url, false, i, total);
+    await downloadPluginFile(destDir, name, url, false, i, total);
   }
 
   // npm install
   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: PLUGIN_DEST, silent: false });
+  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 });
   info(tr(`Plugin deployed: ${PLUGIN_DEST}`, `插件部署完成: ${PLUGIN_DEST}`));
 }
 
-async function deployLocalPlugin(localPluginDir) {
-  await rm(PLUGIN_DEST, { recursive: true, force: true });
-  await mkdir(PLUGIN_DEST, { recursive: true });
-  await cp(localPluginDir, PLUGIN_DEST, {
-    recursive: true,
-    force: true,
-    filter: (sourcePath) => {
-      const rel = relative(localPluginDir, sourcePath);
-      if (!rel) return true;
-      const firstSegment = rel.split(/[\\/]/)[0];
+async function deployLocalPlugin(localPluginDir, destDir) {
+  await rm(destDir, { recursive: true, force: true });
+  await mkdir(destDir, { recursive: true });
+  await cp(localPluginDir, destDir, {
+    recursive: true,
+    force: true,
+    filter: (sourcePath) => {
+      const rel = relative(localPluginDir, sourcePath);
+      if (!rel) return true;
+      const firstSegment = rel.split(/[\\/]/)[0];
       return firstSegment !== "node_modules" && firstSegment !== ".git";
     },
   });
 }
 
-async function configureOpenClawPlugin() {
+async function installPluginDependencies(destDir) {
+  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(`Plugin prepared: ${destDir}`);
+}
+
+async function createPluginStagingDir() {
+  const pluginId = resolvedPluginId || "openviking";
+  const extensionsDir = join(OPENCLAW_DIR, "extensions");
+  const stagingDir = join(extensionsDir, `.${pluginId}.staging-${process.pid}-${Date.now()}`);
+  await mkdir(extensionsDir, { recursive: true });
+  await rm(stagingDir, { recursive: true, force: true });
+  await mkdir(stagingDir, { recursive: true });
+  return stagingDir;
+}
+
+async function finalizePluginDeployment(stagingDir) {
+  await rm(PLUGIN_DEST, { recursive: true, force: true });
+  try {
+    await rename(stagingDir, PLUGIN_DEST);
+  } catch {
+    await cp(stagingDir, PLUGIN_DEST, { recursive: true, force: true });
+    await rm(stagingDir, { recursive: true, force: true });
+  }
+  return info(`Plugin deployed: ${PLUGIN_DEST}`);
+  info(tr(`Plugin prepared: ${destDir}`, `鎻掍欢宸插噯澶? ${destDir}`));
+}
+
+async function deployPluginFromRemote() {
+  const stagingDir = await createPluginStagingDir();
+  try {
+    await downloadPlugin(stagingDir);
+    await finalizePluginDeployment(stagingDir);
+  } catch (error) {
+    await rm(stagingDir, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+async function deployPluginFromLocal(localPluginDir) {
+  const stagingDir = await createPluginStagingDir();
+  try {
+    await deployLocalPlugin(localPluginDir, stagingDir);
+    await installPluginDependencies(stagingDir);
+    await finalizePluginDeployment(stagingDir);
+  } catch (error) {
+    await rm(stagingDir, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+async function configureOpenClawPlugin({
+  preserveExistingConfig = false,
+  runtimeConfig = null,
+  skipGatewayMode = false,
+  claimSlot = true,
+} = {}) {
   info(tr("Configuring OpenClaw plugin...", "正在配置 OpenClaw 插件..."));
 
   const pluginId = resolvedPluginId;
   const pluginSlot = resolvedPluginSlot;
 
-  const ocEnv = { ...process.env };
-  if (OPENCLAW_DIR !== DEFAULT_OPENCLAW_DIR) {
-    ocEnv.OPENCLAW_STATE_DIR = OPENCLAW_DIR;
-  }
+  const ocEnv = getOpenClawEnv();
+
+  const oc = async (args) => {
+    const result = await runCapture("openclaw", args, { env: ocEnv, shell: IS_WIN });
+    if (result.code !== 0) {
+      const detail = result.err || result.out;
+      throw new Error(`openclaw ${args.join(" ")} failed (exit code ${result.code})${detail ? `: ${detail}` : ""}`);
+    }
+    return result;
+  };
 
-  const oc = async (args) => {
-    const result = await runCapture("openclaw", args, { env: ocEnv, shell: IS_WIN });
-    if (result.code !== 0) {
-      const detail = result.err || result.out;
-      throw new Error(`openclaw ${args.join(" ")} failed (exit code ${result.code})${detail ? `: ${detail}` : ""}`);
-    }
-    return result;
-  };
-
   // Enable plugin (files already deployed to extensions dir by deployPlugin)
   await oc(["plugins", "enable", pluginId]);
-  await oc(["config", "set", `plugins.slots.${pluginSlot}`, pluginId]);
-
-  // Set gateway mode
-  await oc(["config", "set", "gateway.mode", "local"]);
+  if (claimSlot) {
+    await oc(["config", "set", `plugins.slots.${pluginSlot}`, pluginId]);
+  } else {
+    warn(
+      tr(
+        `Skipped claiming plugins.slots.${pluginSlot}; it is currently owned by another plugin.`,
+        `已跳过设置 plugins.slots.${pluginSlot}，当前该 slot 由其他插件占用。`,
+      ),
+    );
+  }
+
+  if (preserveExistingConfig) {
+    info(
+      tr(
+        `Preserved existing plugin runtime config for ${pluginId}`,
+        `宸蹭繚鐣?${pluginId} 鐨勭幇鏈夋彃浠惰繍琛岄厤缃?`,
+      ),
+    );
+    return;
+  }
+
+  const effectiveRuntimeConfig = runtimeConfig || (
+    selectedMode === "remote"
+      ? { mode: "remote", baseUrl: remoteBaseUrl, apiKey: remoteApiKey, agentId: remoteAgentId }
+      : { mode: "local", configPath: join(OPENVIKING_DIR, "ov.conf"), port: selectedServerPort }
+  );
+
+  if (!skipGatewayMode) {
+    await oc(["config", "set", "gateway.mode", effectiveRuntimeConfig.mode === "remote" ? "remote" : "local"]);
+  }
+
+  // Set plugin config for the selected mode
+  if (effectiveRuntimeConfig.mode === "local") {
+    const ovConfPath = effectiveRuntimeConfig.configPath || join(OPENVIKING_DIR, "ov.conf");
+    await oc(["config", "set", `plugins.entries.${pluginId}.config.mode`, "local"]);
+    await oc(["config", "set", `plugins.entries.${pluginId}.config.configPath`, ovConfPath]);
+    await oc(["config", "set", `plugins.entries.${pluginId}.config.port`, String(effectiveRuntimeConfig.port || DEFAULT_SERVER_PORT)]);
+  } else {
+    await oc(["config", "set", `plugins.entries.${pluginId}.config.mode`, "remote"]);
+    await oc(["config", "set", `plugins.entries.${pluginId}.config.baseUrl`, effectiveRuntimeConfig.baseUrl || remoteBaseUrl]);
+    if (effectiveRuntimeConfig.apiKey) {
+      await oc(["config", "set", `plugins.entries.${pluginId}.config.apiKey`, effectiveRuntimeConfig.apiKey]);
+    }
+    if (effectiveRuntimeConfig.agentId) {
+      await oc(["config", "set", `plugins.entries.${pluginId}.config.agentId`, effectiveRuntimeConfig.agentId]);
+    }
+  }
 
-  // Set plugin config for the selected mode
-  if (selectedMode === "local") {
-    const ovConfPath = join(OPENVIKING_DIR, "ov.conf");
-    await oc(["config", "set", `plugins.entries.${pluginId}.config.mode`, "local"]);
-    await oc(["config", "set", `plugins.entries.${pluginId}.config.configPath`, ovConfPath]);
-    await oc(["config", "set", `plugins.entries.${pluginId}.config.port`, String(selectedServerPort)]);
-  } else {
-    await oc(["config", "set", `plugins.entries.${pluginId}.config.mode`, "remote"]);
-    await oc(["config", "set", `plugins.entries.${pluginId}.config.baseUrl`, remoteBaseUrl]);
-    if (remoteApiKey) {
-      await oc(["config", "set", `plugins.entries.${pluginId}.config.apiKey`, remoteApiKey]);
-    }
-    if (remoteAgentId) {
-      await oc(["config", "set", `plugins.entries.${pluginId}.config.agentId`, remoteAgentId]);
-    }
+  // Legacy (memory) plugins need explicit targetUri/autoRecall/autoCapture (new version has defaults in config.ts)
+  if (resolvedPluginKind === "memory") {
+    await oc(["config", "set", `plugins.entries.${pluginId}.config.targetUri`, "viking://user/memories"]);
+    await oc(["config", "set", `plugins.entries.${pluginId}.config.autoRecall`, "true", "--json"]);
+    await oc(["config", "set", `plugins.entries.${pluginId}.config.autoCapture`, "true", "--json"]);
   }
 
   info(tr("OpenClaw plugin configured", "OpenClaw 插件配置完成"));
 }
 
+async function discoverOpenvikingPython(failedPy) {
+  const candidates = IS_WIN
+    ? ["python3", "python", "py -3"]
+    : ["python3.13", "python3.12", "python3.11", "python3.10", "python3", "python"];
+  for (const candidate of candidates) {
+    if (candidate === failedPy) continue;
+    const resolved = await resolveAbsoluteCommand(candidate);
+    if (!resolved || resolved === candidate || resolved === failedPy) continue;
+    const check = await runCapture(resolved, ["-c", "import openviking"], { shell: false });
+    if (check.code === 0) return resolved;
+  }
+  return "";
+}
+
 async function resolvePythonPath() {
   if (openvikingPythonPath) return openvikingPythonPath;
   const python = await checkPython();
-  const py = python.cmd;
-  if (!py) return "";
-
-  if (IS_WIN) {
-    const result = await runCapture("where", [py], { shell: true });
-    return result.out.split(/\r?\n/)[0]?.trim() || py;
-  }
-
-  const result = await runCapture("which", [py], { shell: false });
-  return result.out.trim() || py;
+  return python.cmd || "";
 }
 
 async function writeOpenvikingEnv({ includePython }) {
@@ -1001,6 +1690,37 @@ async function writeOpenvikingEnv({ includePython }) {
         ),
       );
     }
+
+    // Verify the resolved Python can actually import openviking
+    if (pythonPath) {
+      const verify = await runCapture(pythonPath, ["-c", "import openviking"], { shell: false });
+      if (verify.code !== 0) {
+        warn(
+          tr(
+            `Resolved Python (${pythonPath}) cannot import openviking. The pip install target may differ from the runtime python3.`,
+            `解析到的 Python（${pythonPath}）无法 import openviking。pip 安装目标可能与运行时的 python3 不一致。`,
+          ),
+        );
+        // Try to discover the correct Python via pip show
+        const corrected = await discoverOpenvikingPython(pythonPath);
+        if (corrected) {
+          info(
+            tr(
+              `Auto-corrected OPENVIKING_PYTHON to ${corrected}`,
+              `已自动修正 OPENVIKING_PYTHON 为 ${corrected}`,
+            ),
+          );
+          pythonPath = corrected;
+        } else {
+          warn(
+            tr(
+              `Could not auto-detect the correct Python. Edit OPENVIKING_PYTHON in the env file manually.`,
+              `无法自动检测正确的 Python。请手动修改 env 文件中的 OPENVIKING_PYTHON。`,
+            ),
+          );
+        }
+      }
+    }
   }
 
   // Remote mode + default state dir + no python line → nothing to persist
@@ -1044,18 +1764,59 @@ async function writeOpenvikingEnv({ includePython }) {
   return { shellPath: envPath };
 }
 
-function wrapCommand(command, envFiles) {
-  if (!envFiles) return command;
-  if (IS_WIN) return `call "${envFiles.shellPath}" && ${command}`;
-  return `source '${envFiles.shellPath.replace(/'/g, "'\"'\"'")}' && ${command}`;
-}
-
-async function main() {
+function wrapCommand(command, envFiles) {
+  if (!envFiles) return command;
+  if (IS_WIN) return `call "${envFiles.shellPath}" && ${command}`;
+  return `source '${envFiles.shellPath.replace(/'/g, "'\"'\"'")}' && ${command}`;
+}
+
+function getExistingEnvFiles() {
+  if (IS_WIN) {
+    const batPath = join(OPENCLAW_DIR, "openviking.env.bat");
+    const ps1Path = join(OPENCLAW_DIR, "openviking.env.ps1");
+    if (existsSync(batPath)) {
+      return { shellPath: batPath, powershellPath: existsSync(ps1Path) ? ps1Path : undefined };
+    }
+    if (existsSync(ps1Path)) {
+      return { shellPath: ps1Path, powershellPath: ps1Path };
+    }
+    return null;
+  }
+
+  const envPath = join(OPENCLAW_DIR, "openviking.env");
+  return existsSync(envPath) ? { shellPath: envPath } : null;
+}
+
+function ensureExistingPluginForUpgrade() {
+  if (!existsSync(PLUGIN_DEST)) {
+    err(
+      tr(
+        `Plugin upgrade mode expects an existing plugin at ${PLUGIN_DEST}. Run the full installer first if this is a fresh install.`,
+        `鎻掍欢鍗囩骇妯″紡瑕佹眰鐜版湁鎻掍欢宸插畨瑁呭湪 ${PLUGIN_DEST}銆傚鏄娆″畨瑁咃紝璇疯繍琛屽叏閲忓畨瑁呮祦绋嬨€?`,
+      ),
+    );
+    process.exit(1);
+  }
+}
+
+async function main() {
   console.log("");
   bold(tr("🦣 OpenClaw + OpenViking Installer", "🦣 OpenClaw + OpenViking 一键安装"));
   console.log("");
 
-  await selectWorkdir();
+  await selectWorkdir();
+  if (rollbackLastUpgrade) {
+    info(tr("Mode: rollback last plugin upgrade", "模式: 回滚最近一次插件升级"));
+    if (PLUGIN_VERSION !== "main") {
+      warn("--plugin-version is ignored in --rollback mode.");
+    }
+    if (openvikingVersion) {
+      warn("--openviking-version is ignored in --rollback mode.");
+    }
+    await rollbackLastUpgradeOperation();
+    return;
+  }
+  validateRequestedPluginVersion();
   info(tr(`Target: ${OPENCLAW_DIR}`, `目标实例: ${OPENCLAW_DIR}`));
   info(tr(`Repository: ${REPO}`, `仓库: ${REPO}`));
   info(tr(`Plugin version: ${PLUGIN_VERSION}`, `插件版本: ${PLUGIN_VERSION}`));
@@ -1063,18 +1824,31 @@ async function main() {
     info(tr(`OpenViking version: ${openvikingVersion}`, `OpenViking 版本: ${openvikingVersion}`));
   }
 
-  await selectMode();
+  if (upgradePluginOnly) {
+    selectedMode = "local";
+    info("Mode: plugin upgrade only (backup old plugin, clean only OpenViking plugin config, keep ov.conf)");
+    if (openvikingVersion) {
+      warn("--openviking-version is ignored in --upgrade-plugin mode.");
+    }
+  } else {
+    await selectMode();
+  }
   info(tr(`Mode: ${selectedMode}`, `模式: ${selectedMode}`));
 
-  if (selectedMode === "local") {
-    await validateEnvironment();
-    await checkOpenClaw();
+  if (upgradePluginOnly) {
+    await checkOpenClaw();
+    await resolvePluginConfig();
+    await checkOpenClawCompatibility();
+    await prepareStrongPluginUpgrade();
+  } else if (selectedMode === "local") {
+    await validateEnvironment();
+    await checkOpenClaw();
     // Resolve plugin config after OpenClaw is available (for version detection)
     await resolvePluginConfig();
     await checkOpenClawCompatibility();
     checkRequestedOpenVikingCompatibility();
     await installOpenViking();
-    await configureOvConf();
+    await configureOvConf();
   } else {
     await checkOpenClaw();
     await resolvePluginConfig();
@@ -1088,22 +1862,41 @@ async function main() {
     pluginPath = localPluginDir;
     PLUGIN_DEST = join(OPENCLAW_DIR, "extensions", resolvedPluginId || "openviking");
     info(tr(`Using local plugin from repo: ${pluginPath}`, `使用仓库内插件: ${pluginPath}`));
-    await deployLocalPlugin(pluginPath);
+    await deployPluginFromLocal(pluginPath);
       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: PLUGIN_DEST, silent: false });
-    pluginPath = PLUGIN_DEST;
+    pluginPath = PLUGIN_DEST;
   } else {
-    await downloadPlugin();
+    await deployPluginFromRemote();
     pluginPath = PLUGIN_DEST;
   }
 
-  await configureOpenClawPlugin();
-  const envFiles = await writeOpenvikingEnv({
-    includePython: selectedMode === "local",
-  });
+  await configureOpenClawPlugin(
+    upgradePluginOnly
+      ? {
+          runtimeConfig: upgradeRuntimeConfig,
+          skipGatewayMode: true,
+          claimSlot: installedUpgradeState ? shouldClaimTargetSlot(installedUpgradeState) : true,
+        }
+      : { preserveExistingConfig: false },
+  );
+  await writeInstallStateFile({
+    operation: upgradePluginOnly ? "upgrade" : "install",
+    fromVersion: upgradeAudit?.fromVersion || "",
+    configBackupPath: upgradeAudit?.configBackupPath || "",
+    pluginBackups: upgradeAudit?.pluginBackups || [],
+  });
+  if (upgradeAudit) {
+    upgradeAudit.completedAt = new Date().toISOString();
+    await writeUpgradeAuditFile(upgradeAudit);
+  }
+  let envFiles = getExistingEnvFiles();
+  if (!upgradePluginOnly) {
+    envFiles = await writeOpenvikingEnv({
+      includePython: selectedMode === "local",
+    });
+  } else if (!envFiles && OPENCLAW_DIR !== DEFAULT_OPENCLAW_DIR) {
+    envFiles = await writeOpenvikingEnv({ includePython: false });
+  }
 
   console.log("");
   bold("═══════════════════════════════════════════════════════════");
@@ -1111,7 +1904,17 @@ async function main() {
   bold("═══════════════════════════════════════════════════════════");
   console.log("");
 
-  if (selectedMode === "local") {
+  if (upgradeAudit) {
+    info(tr(`Upgrade path recorded: ${upgradeAudit.fromVersion} -> ${upgradeAudit.toVersion}`, `已记录升级路径: ${upgradeAudit.fromVersion} -> ${upgradeAudit.toVersion}`));
+    info(tr(`Rollback config backup: ${upgradeAudit.configBackupPath}`, `回滚配置备份: ${upgradeAudit.configBackupPath}`));
+    for (const pluginBackup of upgradeAudit.pluginBackups || []) {
+      info(tr(`Rollback plugin backup: ${pluginBackup.backupDir}`, `回滚插件备份: ${pluginBackup.backupDir}`));
+    }
+    info(tr(`Rollback audit file: ${getUpgradeAuditPath()}`, `回滚审计文件: ${getUpgradeAuditPath()}`));
+    console.log("");
+  }
+
+  if (selectedMode === "local") {
     info(tr("Run these commands to start OpenClaw + OpenViking:", "请按以下命令启动 OpenClaw + OpenViking："));
   } else {
     info(tr("Run these commands to start OpenClaw:", "请按以下命令启动 OpenClaw："));