openclaw-openviking-setup-helper 0.3.0-beta.9 → 0.3.1-beta.0

package/install.js

@@ -3,36 +3,43 @@
  * OpenClaw OpenViking plugin installer (remote OpenViking server — does not install Python/OpenViking server).
  *
  * One-liner (after npm publish; use package name + bin name):
- *   npx -p openclaw-openviking-setup-helper ov-install [ -y ] [ --zh ] [ --workdir PATH ]
+ *   npx -p openclaw-openviking-setup-helper ov-install [ --base-url URL ] [ --api-key KEY ] [ --zh ] [ --workdir PATH ]
  * Or install globally then run:
  *   npm i -g openclaw-openviking-setup-helper
  *   ov-install
  *   openclaw-openviking-install
  *
- * Direct run:
- *   node install.js [ -y | --yes ] [ --zh ] [ --workdir PATH ] [ --upgrade-plugin ]
- *                   [ --plugin-version=TAG ]
- *
- * Environment variables:
- *   REPO, PLUGIN_VERSION (or BRANCH), OPENVIKING_INSTALL_YES, SKIP_OPENCLAW
- *   NPM_REGISTRY
- */
+ * Direct run:
+ *   node install.js [ --base-url URL ] [ --api-key KEY ] [ --zh ] [ --workdir PATH ] [ --upgrade-plugin ]
+ *                   [ --plugin-version=VERSION ] [ --plugin-source=npm|github ]
+ *
+ * Environment variables:
+ *   PLUGIN_SOURCE, PLUGIN_NPM_PACKAGE, REPO, PLUGIN_VERSION (or BRANCH),
+ *   OPENVIKING_BASE_URL, OPENVIKING_API_KEY, SKIP_OPENCLAW, NPM_REGISTRY
+ */
 
 import { spawn } from "node:child_process";
-import { cp, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { existsSync, readdirSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
-import { createInterface } from "node:readline";
-import { fileURLToPath } from "node:url";
+import { cp, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { existsSync, readdirSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
 
 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);
+let REPO = process.env.REPO || "volcengine/OpenViking";
+const DEFAULT_PLUGIN_NPM_PACKAGE = "@openviking/openclaw-plugin";
+let pluginNpmPackage = (process.env.PLUGIN_NPM_PACKAGE || DEFAULT_PLUGIN_NPM_PACKAGE).trim();
+let pluginSource = (process.env.PLUGIN_SOURCE || "npm").trim().toLowerCase();
+let pluginSourceExplicit = Boolean(process.env.PLUGIN_SOURCE);
+// PLUGIN_VERSION takes precedence over BRANCH (legacy). If omitted, resolve the latest npm dist-tag or GitHub tag.
+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 || "";
@@ -47,8 +54,9 @@ const FALLBACK_LEGACY = {
   id: "memory-openviking",
   kind: "memory",
   slot: "memory",
-  required: ["index.ts", "config.ts", "openclaw.plugin.json", "package.json"],
-  optional: ["package-lock.json", ".gitignore"],
+  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).
@@ -57,15 +65,19 @@ const FALLBACK_CURRENT = {
   id: "openviking",
   kind: "context-engine",
   slot: "contextEngine",
+  minOpenclawVersion: "2026.4.8",
   required: ["index.ts", "config.ts", "package.json", "openclaw.plugin.json"],
   optional: [
     "context-engine.ts",
+    "auto-recall.ts",
     "client.ts",
     "process-manager.ts",
     "memory-ranking.ts",
     "text-utils.ts",
     "tool-call-id.ts",
     "session-transcript-repair.ts",
+    "runtime-utils.ts",
+    "commands/setup.ts",
     "tsconfig.json",
     "package-lock.json",
     ".gitignore",
@@ -85,21 +97,35 @@ 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 resolvedMinOpenvikingVersion = "";
+let resolvedPluginReleaseId = "";
+let detectedOpenClawVersion = "";
+let npmPackageTempDir = "";
+let npmPackageExtractDir = "";
 
-let installYes = process.env.OPENVIKING_INSTALL_YES === "1";
+let nonInteractive = false;
 let langZh = false;
 let workdirExplicit = false;
 let upgradePluginOnly = false;
 let rollbackLastUpgrade = false;
-let showCurrentVersion = false;
+let showCurrentVersion = false;
+let uninstallPlugin = false;
+let forceSlotExplicit = false;
+let allowOfflineExplicit = false;
 
 const selectedMode = "remote";
+const baseUrlFromEnv = !!process.env.OPENVIKING_BASE_URL;
 let remoteBaseUrl = (process.env.OPENVIKING_BASE_URL || "http://127.0.0.1:1933").trim();
 let remoteApiKey = (process.env.OPENVIKING_API_KEY || "").trim();
 let remoteAgentPrefix = (process.env.OPENVIKING_AGENT_PREFIX || "").trim();
+let remoteAccountId = (process.env.OPENVIKING_ACCOUNT_ID || "").trim();
+let remoteUserId = (process.env.OPENVIKING_USER_ID || "").trim();
+let baseUrlExplicit = baseUrlFromEnv;
 let upgradeRuntimeConfig = null;
 let installedUpgradeState = null;
 let upgradeAudit = null;
@@ -108,8 +134,11 @@ const argv = process.argv.slice(2);
 for (let i = 0; i < argv.length; i++) {
   const arg = argv[i];
   if (arg === "-y" || arg === "--yes") {
-    installYes = true;
-    continue;
+    err(tr(
+      "-y/--yes has been removed. Use --base-url <URL> [--api-key <KEY>] for non-interactive mode.",
+      "-y/--yes 已移除。使用 --base-url <URL> [--api-key <KEY>] 进入非交互模式。",
+    ));
+    process.exit(1);
   }
   if (arg === "--zh") {
     langZh = true;
@@ -127,7 +156,19 @@ for (let i = 0; i < argv.length; i++) {
     rollbackLastUpgrade = 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");
@@ -144,59 +185,174 @@ for (let i = 0; i < argv.length; i++) {
       console.error("--plugin-version requires a value");
       process.exit(1);
     }
-    PLUGIN_VERSION = version;
-    pluginVersionExplicit = true;
-    continue;
-  }
+    PLUGIN_VERSION = version;
+    pluginVersionExplicit = true;
+    continue;
+  }
   if (arg === "--plugin-version") {
     const version = argv[i + 1]?.trim();
     if (!version) {
       console.error("--plugin-version requires a value");
       process.exit(1);
     }
-    PLUGIN_VERSION = version;
-    pluginVersionExplicit = true;
+    PLUGIN_VERSION = version;
+    pluginVersionExplicit = true;
+    i += 1;
+    continue;
+  }
+  if (arg.startsWith("--github-repo=")) {
+    REPO = arg.slice("--github-repo=".length).trim();
+    if (!pluginSourceExplicit) {
+      pluginSource = "github";
+    }
+    continue;
+  }
+  if (arg === "--github-repo") {
+    const repo = argv[i + 1]?.trim();
+    if (!repo) {
+      console.error("--github-repo requires a value (e.g. owner/repo)");
+      process.exit(1);
+    }
+    REPO = repo;
+    if (!pluginSourceExplicit) {
+      pluginSource = "github";
+    }
+    i += 1;
+    continue;
+  }
+  if (arg.startsWith("--plugin-source=") || arg.startsWith("--source=")) {
+    const value = arg.includes("--plugin-source=")
+      ? arg.slice("--plugin-source=".length).trim()
+      : arg.slice("--source=".length).trim();
+    pluginSource = value.toLowerCase();
+    pluginSourceExplicit = true;
+    continue;
+  }
+  if (arg === "--plugin-source" || arg === "--source") {
+    const value = argv[i + 1]?.trim();
+    if (!value) {
+      console.error(`${arg} requires a value (npm or github)`);
+      process.exit(1);
+    }
+    pluginSource = value.toLowerCase();
+    pluginSourceExplicit = true;
+    i += 1;
+    continue;
+  }
+  if (arg.startsWith("--plugin-package=") || arg.startsWith("--npm-package=")) {
+    const value = arg.includes("--plugin-package=")
+      ? arg.slice("--plugin-package=".length).trim()
+      : arg.slice("--npm-package=".length).trim();
+    if (!value) {
+      console.error("--plugin-package requires a package name");
+      process.exit(1);
+    }
+    pluginNpmPackage = value;
+    continue;
+  }
+  if (arg === "--plugin-package" || arg === "--npm-package") {
+    const value = argv[i + 1]?.trim();
+    if (!value) {
+      console.error(`${arg} requires a package name`);
+      process.exit(1);
+    }
+    pluginNpmPackage = value;
+    i += 1;
+    continue;
+  }
+  if (arg === "--base-url") {
+    const val = argv[i + 1]?.trim();
+    if (!val) { console.error("--base-url requires a URL"); process.exit(1); }
+    remoteBaseUrl = val;
+    baseUrlExplicit = true;
     i += 1;
     continue;
   }
-  if (arg.startsWith("--github-repo=")) {
-    REPO = arg.slice("--github-repo=".length).trim();
+  if (arg.startsWith("--base-url=")) {
+    remoteBaseUrl = arg.slice("--base-url=".length).trim();
+    baseUrlExplicit = true;
     continue;
   }
-  if (arg === "--github-repo") {
-    const repo = argv[i + 1]?.trim();
-    if (!repo) {
-      console.error("--github-repo requires a value (e.g. owner/repo)");
-      process.exit(1);
-    }
-    REPO = repo;
+  if (arg === "--api-key") {
+    const val = argv[i + 1]?.trim();
+    if (!val) { console.error("--api-key requires a value"); process.exit(1); }
+    remoteApiKey = val;
     i += 1;
     continue;
   }
+  if (arg.startsWith("--api-key=")) {
+    remoteApiKey = arg.slice("--api-key=".length).trim();
+    continue;
+  }
+  if (arg === "--agent-prefix") {
+    const val = argv[i + 1]?.trim();
+    if (!val) { console.error("--agent-prefix requires a value"); process.exit(1); }
+    remoteAgentPrefix = val;
+    i += 1;
+    continue;
+  }
+  if (arg.startsWith("--agent-prefix=")) {
+    remoteAgentPrefix = arg.slice("--agent-prefix=".length).trim();
+    continue;
+  }
+  if (arg === "--account-id") {
+    const val = argv[i + 1]?.trim();
+    if (!val) { console.error("--account-id requires a value"); process.exit(1); }
+    remoteAccountId = val;
+    i += 1;
+    continue;
+  }
+  if (arg.startsWith("--account-id=")) {
+    remoteAccountId = arg.slice("--account-id=".length).trim();
+    continue;
+  }
+  if (arg === "--user-id") {
+    const val = argv[i + 1]?.trim();
+    if (!val) { console.error("--user-id requires a value"); process.exit(1); }
+    remoteUserId = val;
+    i += 1;
+    continue;
+  }
+  if (arg.startsWith("--user-id=")) {
+    remoteUserId = arg.slice("--user-id=".length).trim();
+    continue;
+  }
   if (arg === "-h" || arg === "--help") {
     printHelp();
     process.exit(0);
   }
 }
 
+nonInteractive = baseUrlExplicit;
+
 function setOpenClawDir(dir) {
   OPENCLAW_DIR = dir;
 }
 
 function printHelp() {
   console.log("Usage: node install.js [ OPTIONS ]");
-  console.log("");
-  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: latest tag)");
+  console.log("");
+  console.log("Options:");
+  console.log("  --plugin-source=npm|github");
+  console.log("                           Plugin download source (default: npm)");
+  console.log("  --plugin-package=NAME    npm plugin package (default: @openviking/openclaw-plugin)");
+  console.log("  --github-repo=OWNER/REPO GitHub repository (implies --plugin-source=github unless source is set)");
+  console.log("  --plugin-version=VERSION Plugin version (npm version/tag or Git tag; default: npm latest)");
   console.log("  --workdir PATH           OpenClaw config directory (default: ~/.openclaw)");
   console.log("  --current-version        Print installed plugin version and exit");
   console.log("  --update, --upgrade-plugin");
   console.log("                           Upgrade only the plugin to the requested --plugin-version; keeps existing plugin runtime config");
   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("  --uninstall, --remove    Uninstall OpenViking plugin from OpenClaw (backup config, remove plugin entries)");
+  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("  --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:");
@@ -206,11 +362,11 @@ function printHelp() {
   console.log("  # Show installed versions");
   console.log("  node install.js --current-version");
   console.log("");
-  console.log("  # Install a specific release version");
-  console.log("  node install.js --plugin-version=v0.2.9");
-  console.log("");
-  console.log("  # Install from a fork repository");
-  console.log("  node install.js --github-repo=yourname/OpenViking --plugin-version=dev-branch");
+  console.log("  # Install a specific release version");
+  console.log("  node install.js --plugin-version=2026.5.8");
+  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");
@@ -221,8 +377,8 @@ function printHelp() {
   console.log("  # Roll back the last plugin upgrade");
   console.log("  node install.js --rollback");
   console.log("");
-  console.log("Env: REPO, PLUGIN_VERSION, SKIP_OPENCLAW, NPM_REGISTRY");
-}
+  console.log("Env: PLUGIN_SOURCE, PLUGIN_NPM_PACKAGE, REPO, PLUGIN_VERSION, SKIP_OPENCLAW, NPM_REGISTRY");
+}
 
 function formatCliArg(value) {
   if (!value) {
@@ -315,15 +471,62 @@ 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 isYes(answer) {
+  const normalized = String(answer || "").trim().toLowerCase();
+  return normalized === "y" || normalized === "yes";
+}
+
+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)) {
+      return answer;
+    }
+    warn(tr(
+      "Agent Prefix may only contain letters, digits, underscores, and hyphens, or be empty.",
+      "Agent Prefix 只能包含字母、数字、下划线和连字符，或留空。",
+    ));
+  }
 }
 
 function detectOpenClawInstances() {
@@ -349,7 +552,7 @@ async function selectWorkdir() {
     setOpenClawDir(instances[0]);
     return;
   }
-  if (installYes) return;
+  if (nonInteractive) return;
 
   console.log("");
   bold(tr("Found multiple OpenClaw instances:", "发现多个 OpenClaw 实例："));
@@ -369,10 +572,10 @@ async function selectWorkdir() {
 }
 
 async function collectRemoteConfig() {
-  if (installYes) return;
+  if (nonInteractive) return;
   remoteBaseUrl = await question(tr("OpenViking server URL", "OpenViking 服务器地址"), remoteBaseUrl);
   remoteApiKey = await question(tr("API Key (optional)", "API Key（可选）"), remoteApiKey);
-  remoteAgentPrefix = await question(tr("Agent Prefix (optional)", "Agent Prefix（可选）"), remoteAgentPrefix);
+  remoteAgentPrefix = await questionAgentPrefix(remoteAgentPrefix);
 }
 
 async function checkOpenClaw() {
@@ -414,6 +617,51 @@ function versionGte(v1, v2) {
   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);
 }
@@ -431,16 +679,46 @@ if (upgradePluginOnly && rollbackLastUpgrade) {
   process.exit(1);
 }
 
-// Detect OpenClaw version
-async function detectOpenClawVersion() {
+if (uninstallPlugin && (upgradePluginOnly || rollbackLastUpgrade)) {
+  console.error("--uninstall cannot be used with --upgrade-plugin or --rollback");
+  process.exit(1);
+}
+
+if (!["npm", "github"].includes(pluginSource)) {
+  console.error("--plugin-source must be either npm or github");
+  process.exit(1);
+}
+
+function looksLikeLegacyGitHubRef(value) {
+  const ref = String(value || "").trim();
+  if (!ref) return false;
+  if (/^v\d+(\.\d+){1,2}([-.].*)?$/i.test(ref)) return true;
+  if (["main", "master"].includes(ref.toLowerCase())) return true;
+  return false;
+}
+
+if (!pluginSourceExplicit && pluginVersionExplicit && looksLikeLegacyGitHubRef(PLUGIN_VERSION)) {
+  pluginSource = "github";
+}
+
+// Detect OpenClaw version
+async function detectOpenClawVersion() {
+  if (detectedOpenClawVersion) {
+    return detectedOpenClawVersion;
+  }
   try {
     const result = await runCapture("openclaw", ["--version"], { shell: IS_WIN });
-    if (result.code === 0 && result.out) {
-      const match = result.out.match(/\d+\.\d+(\.\d+)?/);
-      if (match) return match[0];
+    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 {}
-  return "0.0.0";
+  detectedOpenClawVersion = "0.0.0";
+  return detectedOpenClawVersion;
 }
 
 // Try to fetch a URL, return response text or null
@@ -476,10 +754,10 @@ function compareSemverDesc(a, b) {
   return versionGte(a, b) ? -1 : 1;
 }
 
-function pickLatestPluginTag(tagNames) {
-  const normalized = tagNames
-    .map((tag) => String(tag ?? "").trim())
-    .filter(Boolean);
+function pickLatestPluginTag(tagNames) {
+  const normalized = tagNames
+    .map((tag) => String(tag ?? "").trim())
+    .filter(Boolean);
 
   const semverTags = normalized
     .filter((tag) => isSemverLike(tag))
@@ -488,9 +766,118 @@ function pickLatestPluginTag(tagNames) {
   if (semverTags.length > 0) {
     return semverTags[0];
   }
-
-  return normalized[0] || "";
-}
+
+  return normalized[0] || "";
+}
+
+function npmPackageSpec(version = PLUGIN_VERSION) {
+  return version ? `${pluginNpmPackage}@${version}` : pluginNpmPackage;
+}
+
+function parseNpmJsonOutput(output) {
+  const text = String(output || "").trim();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    const firstArray = text.indexOf("[");
+    const lastArray = text.lastIndexOf("]");
+    if (firstArray >= 0 && lastArray > firstArray) {
+      try {
+        return JSON.parse(text.slice(firstArray, lastArray + 1));
+      } catch {}
+    }
+    const firstObject = text.indexOf("{");
+    const lastObject = text.lastIndexOf("}");
+    if (firstObject >= 0 && lastObject > firstObject) {
+      try {
+        return JSON.parse(text.slice(firstObject, lastObject + 1));
+      } catch {}
+    }
+  }
+  return null;
+}
+
+async function resolveDefaultPluginVersionFromNpm() {
+  info(tr(
+    `No plugin version specified; resolving latest npm version from ${pluginNpmPackage}...`,
+    `No plugin version specified; resolving latest npm version from ${pluginNpmPackage}...`,
+  ));
+
+  const result = await runCapture("npm", [
+    "view",
+    `${pluginNpmPackage}@latest`,
+    "version",
+    "--json",
+    "--registry",
+    NPM_REGISTRY,
+  ], { shell: IS_WIN });
+
+  if (result.code === 0) {
+    const parsed = parseNpmJsonOutput(result.out);
+    const version = typeof parsed === "string" ? parsed : String(result.out || "").trim().replace(/^"|"$/g, "");
+    if (version) {
+      PLUGIN_VERSION = version;
+      info(tr(
+        `Resolved default plugin version to npm latest: ${PLUGIN_VERSION}`,
+        `Resolved default plugin version to npm latest: ${PLUGIN_VERSION}`,
+      ));
+      return true;
+    }
+  }
+
+  warn(tr(
+    `Could not resolve npm latest for ${pluginNpmPackage}${result.err ? `: ${result.err}` : ""}`,
+    `Could not resolve npm latest for ${pluginNpmPackage}${result.err ? `: ${result.err}` : ""}`,
+  ));
+  return false;
+}
+
+async function ensureNpmPackageExtracted() {
+  if (npmPackageExtractDir && existsSync(npmPackageExtractDir)) {
+    return npmPackageExtractDir;
+  }
+
+  npmPackageTempDir = await mkdtemp(join(tmpdir(), "ov-plugin-npm-"));
+  info(tr(
+    `Downloading plugin package from npm: ${npmPackageSpec()}`,
+    `Downloading plugin package from npm: ${npmPackageSpec()}`,
+  ));
+
+  const packResult = await runCapture("npm", [
+    "pack",
+    npmPackageSpec(),
+    "--pack-destination",
+    npmPackageTempDir,
+    "--json",
+    "--registry",
+    NPM_REGISTRY,
+  ], { shell: IS_WIN });
+
+  if (packResult.code !== 0) {
+    throw new Error(`npm pack failed for ${npmPackageSpec()}${packResult.err ? `: ${packResult.err}` : ""}`);
+  }
+
+  const parsed = parseNpmJsonOutput(packResult.out);
+  const first = Array.isArray(parsed) ? parsed[0] : parsed;
+  const filename = first?.filename || readdirSync(npmPackageTempDir).find((name) => name.endsWith(".tgz"));
+  if (!filename) {
+    throw new Error(`npm pack did not produce a tarball for ${npmPackageSpec()}`);
+  }
+
+  const tarballPath = join(npmPackageTempDir, filename);
+  const extractRoot = join(npmPackageTempDir, "extract");
+  await mkdir(extractRoot, { recursive: true });
+  await run("tar", ["-xzf", tarballPath, "-C", extractRoot], { silent: true, shell: IS_WIN });
+
+  const packageDir = join(extractRoot, "package");
+  if (!existsSync(packageDir)) {
+    throw new Error(`npm package ${npmPackageSpec()} did not contain the expected package directory`);
+  }
+
+  npmPackageExtractDir = packageDir;
+  return npmPackageExtractDir;
+}
 
 function parseGitLsRemoteTags(output) {
   return String(output ?? "")
@@ -502,13 +889,23 @@ function parseGitLsRemoteTags(output) {
     .filter(Boolean);
 }
 
-async function resolveDefaultPluginVersion() {
-  if (PLUGIN_VERSION) {
-    return;
-  }
-
-  info(tr(
-    `No plugin version specified; resolving latest tag from ${REPO}...`,
+async function resolveDefaultPluginVersion() {
+  if (PLUGIN_VERSION) {
+    return;
+  }
+
+  if (pluginSource === "npm") {
+    if (await resolveDefaultPluginVersionFromNpm()) {
+      return;
+    }
+    warn(tr(
+      "Falling back to GitHub tag resolution.",
+      "Falling back to GitHub tag resolution.",
+    ));
+  }
+
+  info(tr(
+    `No plugin version specified; resolving latest tag from ${REPO}...`,
     `未指定插件版本，正在解析 ${REPO} 的最新 tag...`,
   ));
 
@@ -580,15 +977,126 @@ async function resolveDefaultPluginVersion() {
   if (failures.length > 0) {
     warn(failures.join(" | "));
   }
-  process.exit(1);
-}
-
-// Resolve plugin configuration from manifest or fallback
-async function resolvePluginConfig() {
-  const ghRaw = `https://raw.githubusercontent.com/${REPO}/${PLUGIN_VERSION}`;
+  process.exit(1);
+}
+
+function applyManifestConfig(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 || "";
+  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 || [];
+}
+
+function hasPrebuiltRuntimeOutputs(packageDir) {
+  return existsSync(join(packageDir, "dist", "index.js"));
+}
+
+async function resolvePluginConfigFromNpm() {
+  info(tr(
+    `Resolving plugin configuration from npm package: ${npmPackageSpec()}`,
+    `Resolving plugin configuration from npm package: ${npmPackageSpec()}`,
+  ));
+
+  const packageDir = await ensureNpmPackageExtracted();
+  const manifestPath = join(packageDir, "install-manifest.json");
+  const packageJsonPath = join(packageDir, "package.json");
+  let manifestData = null;
+  let packageJson = null;
+
+  if (existsSync(packageJsonPath)) {
+    try {
+      packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+      resolvedPluginReleaseId = packageJson.version || "";
+    } catch {}
+  }
+
+  if (existsSync(manifestPath)) {
+    try {
+      manifestData = JSON.parse(await readFile(manifestPath, "utf8"));
+      info(tr("Found manifest in npm package", "Found manifest in npm package"));
+    } catch {}
+  }
+
+  resolvedPluginDir = ".";
+  if (manifestData) {
+    applyManifestConfig(manifestData);
+  } else {
+    const pkgName = packageJson?.name || "";
+    const fallback = pkgName && pkgName !== DEFAULT_PLUGIN_NPM_PACKAGE ? FALLBACK_LEGACY : FALLBACK_CURRENT;
+    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;
+    resolvedMinOpenclawVersion = (packageJson?.engines?.openclaw || "").replace(/^>=?\s*/, "").trim()
+      || fallback.minOpenclawVersion
+      || "2026.3.7";
+    resolvedMinOpenvikingVersion = "";
+  }
+
+  if (hasPrebuiltRuntimeOutputs(packageDir)) {
+    resolvedNpmBuild = false;
+    info(tr(
+      "npm package contains prebuilt runtime output; skipping source build.",
+      "npm package contains prebuilt runtime output; skipping source build.",
+    ));
+  }
+
+  PLUGIN_DEST = join(OPENCLAW_DIR, "extensions", resolvedPluginId || "openviking");
+  info(tr(`Plugin: ${resolvedPluginId} (${resolvedPluginKind})`, `Plugin: ${resolvedPluginId} (${resolvedPluginKind})`));
+}
+
+// Resolve plugin configuration from manifest or fallback
+async function resolvePluginConfig() {
+  if (pluginSource === "npm") {
+    try {
+      await resolvePluginConfigFromNpm();
+      return;
+    } catch (error) {
+      warn(tr(
+        `npm plugin resolution failed: ${error?.message || error}`,
+        `npm plugin resolution failed: ${error?.message || error}`,
+      ));
+      warn(tr(
+        "Falling back to GitHub plugin download.",
+        "Falling back to GitHub plugin download.",
+      ));
+      pluginSource = "github";
+    }
+  }
+
+  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;
 
@@ -630,7 +1138,19 @@ async function resolvePluginConfig() {
     resolvedMinOpenclawVersion = manifestData.compatibility?.minOpenclawVersion || "";
     resolvedMinOpenvikingVersion = manifestData.compatibility?.minOpenvikingVersion || "";
     resolvedPluginReleaseId = manifestData.pluginVersion || manifestData.release?.id || "";
-    resolvedNpmOmitDev = manifestData.npm?.omitDev !== false;
+    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 {
@@ -665,6 +1185,10 @@ async function resolvePluginConfig() {
     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") {
@@ -681,7 +1205,7 @@ async function resolvePluginConfig() {
       }
     }
 
-    resolvedMinOpenclawVersion = compatVer || "2026.3.7";
+    resolvedMinOpenclawVersion = compatVer || fallback.minOpenclawVersion || "2026.3.7";
     resolvedMinOpenvikingVersion = "";
   }
 
@@ -699,6 +1223,7 @@ async function checkOpenClawCompatibility() {
 
   const ocVersion = await detectOpenClawVersion();
   info(tr(`Detected OpenClaw version: ${ocVersion}`, `检测到 OpenClaw 版本: ${ocVersion}`));
+  applyOpenClawBuildPolicy(ocVersion);
 
   // If no minimum version required, pass
   if (!resolvedMinOpenclawVersion) {
@@ -711,7 +1236,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}）`
@@ -875,11 +1400,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 });
@@ -1169,10 +1700,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}`));
 
@@ -1270,9 +1803,134 @@ async function downloadPluginFile(destDir, fileName, url, required, index, total
   process.exit(1);
 }
 
-async function downloadPlugin(destDir) {
-  const ghRaw = `https://raw.githubusercontent.com/${REPO}/${PLUGIN_VERSION}`;
-  const pluginDir = resolvedPluginDir;
+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 copyNpmPackageToDest(destDir) {
+  const packageDir = await ensureNpmPackageExtracted();
+  await mkdir(destDir, { recursive: true });
+  const entries = readdirSync(packageDir, { withFileTypes: true });
+  for (const entry of entries) {
+    await cp(join(packageDir, entry.name), join(destDir, entry.name), { recursive: true, force: true });
+  }
+}
+
+async function cleanupNpmPackageTemp() {
+  if (!npmPackageTempDir) return;
+  await rm(npmPackageTempDir, { recursive: true, force: true });
+  npmPackageTempDir = "";
+  npmPackageExtractDir = "";
+}
+
+async function downloadPlugin(destDir) {
+  if (pluginSource === "npm") {
+    await mkdir(destDir, { recursive: true });
+    info(tr(
+      `Installing plugin from npm package ${npmPackageSpec()}...`,
+      `Installing plugin from npm package ${npmPackageSpec()}...`,
+    ));
+    await copyNpmPackageToDest(destDir);
+    await installPluginNpmDependencies(destDir);
+    info(tr(`Plugin deployed: ${PLUGIN_DEST}`, `Plugin deployed: ${PLUGIN_DEST}`));
+    return;
+  }
+
+  const ghRaw = `https://raw.githubusercontent.com/${REPO}/${PLUGIN_VERSION}`;
+  const pluginDir = resolvedPluginDir;
   const total = resolvedFilesRequired.length + resolvedFilesOptional.length;
 
   await mkdir(destDir, { recursive: true });
@@ -1296,12 +1954,7 @@ async function downloadPlugin(destDir) {
     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: destDir, silent: false });
+  await installPluginNpmDependencies(destDir);
   info(tr(`Plugin deployed: ${PLUGIN_DEST}`, `插件部署完成: ${PLUGIN_DEST}`));
 }
 
@@ -1334,16 +1987,18 @@ async function finalizePluginDeployment(stagingDir) {
   return info(tr(`Plugin deployed: ${PLUGIN_DEST}`, `插件部署完成: ${PLUGIN_DEST}`));
 }
 
-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 deployPluginFromRemote() {
+  const stagingDir = await createPluginStagingDir();
+  try {
+    await downloadPlugin(stagingDir);
+    await finalizePluginDeployment(stagingDir);
+  } catch (error) {
+    await rm(stagingDir, { recursive: true, force: true });
+    throw error;
+  } finally {
+    await cleanupNpmPackageTemp();
+  }
+}
 
 /** Same as INSTALL*.md manual cleanup: stale entries block `plugins.slots.*` validation after reinstall. */
 function resolvedPluginSlotFallback() {
@@ -1407,6 +2062,111 @@ async function scrubStaleOpenClawPluginRegistration() {
   await rename(tmp, configPath);
 }
 
+async function cleanupConflictingPluginVariants() {
+  const configPath = getOpenClawConfigPath();
+  if (!existsSync(configPath)) return;
+  let cfg;
+  try {
+    cfg = JSON.parse(await readFile(configPath, "utf8"));
+  } catch { return; }
+  if (!cfg.plugins) return;
+  const p = cfg.plugins;
+  let changed = false;
+  for (const variant of PLUGIN_VARIANTS) {
+    if (variant.id === resolvedPluginId) continue;
+    if (p.entries && Object.prototype.hasOwnProperty.call(p.entries, variant.id)) {
+      info(tr(`Removing conflicting plugin variant: ${variant.id}`, `正在移除冲突的插件变体: ${variant.id}`));
+      delete p.entries[variant.id];
+      changed = true;
+    }
+    if (Array.isArray(p.allow)) {
+      const next = p.allow.filter((id) => id !== variant.id);
+      if (next.length !== p.allow.length) {
+        p.allow = next;
+        changed = true;
+      }
+    }
+    if (p.installs && Object.prototype.hasOwnProperty.call(p.installs, variant.id)) {
+      delete p.installs[variant.id];
+      changed = true;
+    }
+    if (p.slots && p.slots[variant.slot] === variant.id) {
+      p.slots[variant.slot] = variant.slotFallback || "none";
+      changed = true;
+    }
+    if (p.load && Array.isArray(p.load.paths)) {
+      const norm = (s) => String(s).replace(/\\/g, "/");
+      const extNeedle = `/extensions/${variant.id}`;
+      const next = p.load.paths.filter((path) => {
+        if (typeof path !== "string") return true;
+        return !norm(path).includes(extNeedle);
+      });
+      if (next.length !== p.load.paths.length) {
+        p.load.paths = next;
+        changed = true;
+      }
+    }
+    const variantDir = join(OPENCLAW_DIR, "extensions", variant.id);
+    if (existsSync(variantDir)) {
+      info(tr(`Removing conflicting plugin directory: ${variantDir}`, `正在移除冲突的插件目录: ${variantDir}`));
+      await rm(variantDir, { recursive: true, force: true });
+    }
+  }
+  if (!changed) return;
+  const out = JSON.stringify(cfg, null, 2) + "\n";
+  const tmp = `${configPath}.ov-install-tmp.${process.pid}`;
+  await writeFile(tmp, out, "utf8");
+  await rename(tmp, configPath);
+  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,
@@ -1447,16 +2207,21 @@ async function configureOpenClawPlugin({
     const p = cfg.plugins;
     if (!p.entries) p.entries = {};
     if (!p.entries[pluginId]) p.entries[pluginId] = {};
+    p.entries[pluginId].enabled = true;
     if (!p.entries[pluginId].config) p.entries[pluginId].config = {};
     if (!Array.isArray(p.allow)) p.allow = [];
     if (!p.allow.includes(pluginId)) p.allow.push(pluginId);
     return cfg;
   };
 
+  await cleanupConflictingPluginVariants();
+
   if (!preserveExistingConfig) {
     await scrubStaleOpenClawPluginRegistration();
   }
 
+  await ensureOpenClawPluginLoadPath();
+
   // Enable plugin: try CLI first (default path), fall back to direct file for --workdir
   if (!needWorkdirFlag) {
     try {
@@ -1488,7 +2253,7 @@ async function configureOpenClawPlugin({
         `已保留 ${pluginId} 的现有插件运行时配置`,
       ),
     );
-    return;
+    return { runtimeConfigOk: true };
   }
 
   const writeConfigDirect = async (pluginConfig, slotValue) => {
@@ -1507,19 +2272,43 @@ async function configureOpenClawPlugin({
     const effectiveRuntimeConfig = runtimeConfig || {
       baseUrl: remoteBaseUrl,
       apiKey: remoteApiKey,
+      agent_prefix: remoteAgentPrefix,
     };
-    const pluginConfig = {
+
+    let allowedPropsLegacy = null;
+    try {
+      const manifestPath = join(PLUGIN_DEST, "openclaw.plugin.json");
+      if (existsSync(manifestPath)) {
+        const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+        const schema = manifest?.configSchema;
+        if (schema?.properties && typeof schema.properties === "object") {
+          allowedPropsLegacy = new Set(Object.keys(schema.properties));
+        }
+      }
+    } catch { /* ignore parse errors */ }
+
+    const agentVal = effectiveRuntimeConfig.agent_prefix || "";
+    const candidates = {
+      mode: "remote",
       baseUrl: effectiveRuntimeConfig.baseUrl || remoteBaseUrl,
       targetUri: "viking://user/memories",
       autoRecall: true,
       autoCapture: true,
+      apiKey: effectiveRuntimeConfig.apiKey || undefined,
+      agentId: agentVal || undefined,
     };
-    if (effectiveRuntimeConfig.apiKey) {
-      pluginConfig.apiKey = effectiveRuntimeConfig.apiKey;
+
+    const pluginConfig = {};
+    for (const [key, val] of Object.entries(candidates)) {
+      if (val === undefined) continue;
+      if (allowedPropsLegacy && !allowedPropsLegacy.has(key)) continue;
+      pluginConfig[key] = val;
     }
+    if (!pluginConfig.baseUrl) pluginConfig.baseUrl = effectiveRuntimeConfig.baseUrl || remoteBaseUrl;
+
     await writeConfigDirect(pluginConfig, claimSlot ? pluginId : null);
-    info(tr("OpenClaw plugin configured (legacy mode)", "OpenClaw 插件配置完成（旧版模式）"));
-    return;
+    info(tr("OpenClaw plugin configured (legacy mode, remote)", "OpenClaw 插件配置完成（旧版模式，远程连接）"));
+    return { runtimeConfigOk: true };
   }
 
   // Current (context-engine) plugins: delegate to `openclaw openviking setup --json`
@@ -1529,41 +2318,96 @@ async function configureOpenClawPlugin({
     baseUrl: remoteBaseUrl,
     apiKey: remoteApiKey,
     agent_prefix: remoteAgentPrefix,
+    accountId: remoteAccountId,
+    userId: remoteUserId,
   };
 
-  const setupArgs = needWorkdirFlag
-    ? ["--workdir", OPENCLAW_DIR, "openviking", "setup"]
-    : ["openviking", "setup"];
-  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-id", effectiveRuntimeConfig.agent_prefix);
-  }
-  if (claimSlot) {
-    setupArgs.push("--force-slot");
-  }
-  if (installYes) {
-    setupArgs.push("--allow-offline");
-  }
-
-  info(tr(
-    "Delegating configuration to: openclaw openviking setup --json",
-    "委托配置给: openclaw openviking setup --json",
-  ));
-
-  const setupResult = await runCapture("openclaw", setupArgs, { env: ocEnv, shell: IS_WIN });
-
-  let parsed = null;
+  // Detect if the installed plugin supports `setup --json` by checking the deployed setup.ts
+  let setupJsonSupported = false;
   try {
-    parsed = JSON.parse(setupResult.out.trim());
-  } catch {
-    // If JSON parse fails, fall back to checking exit code
-  }
-
-  if (parsed) {
+    const setupTsPath = join(PLUGIN_DEST, "commands", "setup.ts");
+    if (existsSync(setupTsPath)) {
+      const setupSrc = await readFile(setupTsPath, "utf8");
+      setupJsonSupported = setupSrc.includes('"--json"') || setupSrc.includes("'--json'");
+    }
+  } catch { /* ignore read errors */ }
+
+  let setupResult = null;
+  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);
+    }
+    if (effectiveRuntimeConfig.agent_prefix) {
+      setupArgs.push("--agent-prefix", effectiveRuntimeConfig.agent_prefix);
+    }
+    if (effectiveRuntimeConfig.accountId) {
+      setupArgs.push("--account-id", effectiveRuntimeConfig.accountId);
+    }
+    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 && !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) {
@@ -1581,46 +2425,84 @@ 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 || "未知错误"}`,
-        ));
+    } 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.
+    let allowedProps = null;
+    try {
+      const manifestPath = join(PLUGIN_DEST, "openclaw.plugin.json");
+      if (existsSync(manifestPath)) {
+        const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+        const schema = manifest?.configSchema;
+        if (schema?.properties && typeof schema.properties === "object") {
+          allowedProps = new Set(Object.keys(schema.properties));
+        }
       }
-    }
-  } else if (setupResult.code !== 0) {
-    // JSON parse failed and non-zero exit — setup CLI not available (old plugin version)
-    warn(tr(
-      `openclaw openviking setup exited with code ${setupResult.code}. Falling back to direct JSON config write.`,
-      `openclaw openviking setup 退出码 ${setupResult.code}，回退到直接写入 JSON 配置。`,
-    ));
-    const pluginConfig = {
+    } catch { /* ignore parse errors, write all fields */ }
+
+    const agentVal = effectiveRuntimeConfig.agent_prefix || "";
+    const useAgentPrefix = !allowedProps || allowedProps.has("agent_prefix");
+    const candidates = {
+      mode: "remote",
       baseUrl: effectiveRuntimeConfig.baseUrl || remoteBaseUrl,
+      apiKey: effectiveRuntimeConfig.apiKey || "",
+      accountId: effectiveRuntimeConfig.accountId || undefined,
+      userId: effectiveRuntimeConfig.userId || undefined,
     };
-    if (effectiveRuntimeConfig.apiKey) {
-      pluginConfig.apiKey = effectiveRuntimeConfig.apiKey;
+    if (useAgentPrefix) {
+      candidates.agent_prefix = agentVal;
+    } else {
+      candidates.agentId = agentVal;
     }
-    if (effectiveRuntimeConfig.agent_prefix) {
-      pluginConfig.agent_prefix = effectiveRuntimeConfig.agent_prefix;
+
+    const pluginConfig = {};
+    for (const [key, val] of Object.entries(candidates)) {
+      if (val === undefined) continue;
+      if (allowedProps && !allowedProps.has(key)) continue;
+      pluginConfig[key] = val;
     }
+    if (!pluginConfig.baseUrl) pluginConfig.baseUrl = effectiveRuntimeConfig.baseUrl || remoteBaseUrl;
+    if (!("apiKey" in pluginConfig)) pluginConfig.apiKey = effectiveRuntimeConfig.apiKey || "";
+
     await writeConfigDirect(pluginConfig, claimSlot ? pluginId : null);
-    info(tr("OpenClaw plugin configured (direct write)", "OpenClaw 插件配置完成（直接写入）"));
-    if (effectiveRuntimeConfig.apiKey) {
-      info(tr(
-        "Note: Root API key detection and tenant context are only available via `openclaw openviking setup`. If using a root API key, upgrade the plugin and re-run setup.",
-        "提示：Root API Key 检测和租户上下文仅在 `openclaw openviking setup` 中可用。如果使用 root API key，请升级插件后重新执行 setup。",
-      ));
-    }
-  } else {
-    info(tr("OpenClaw plugin configured", "OpenClaw 插件配置完成"));
+    info(tr(
+      `OpenClaw plugin configured (direct write): baseUrl=${pluginConfig.baseUrl}, apiKey=${pluginConfig.apiKey ? "***" : "(empty)"}`,
+      `OpenClaw 插件配置完成（直接写入）: baseUrl=${pluginConfig.baseUrl}, apiKey=${pluginConfig.apiKey ? "***" : "(空)"}`,
+    ));
   }
+
+  return { runtimeConfigOk: true };
 }
 
 async function writeOpenvikingEnv() {
@@ -1678,6 +2560,125 @@ function getExistingEnvFiles() {
   return existsSync(envPath) ? { shellPath: envPath } : null;
 }
 
+async function performUninstall() {
+  info(tr("Mode: uninstall plugin", "模式: 卸载插件"));
+  info(tr(`Target: ${OPENCLAW_DIR}`, `目标实例: ${OPENCLAW_DIR}`));
+
+  const configPath = getOpenClawConfigPath();
+  if (!existsSync(configPath)) {
+    info(tr(
+      "No openclaw.json found. Nothing to uninstall.",
+      "未找到 openclaw.json，无需卸载。",
+    ));
+    return;
+  }
+
+  const installedState = await detectInstalledPluginState();
+  if (installedState.generation === "none") {
+    info(tr(
+      "No OpenViking plugin entries found in openclaw.json. Nothing to uninstall.",
+      "openclaw.json 中未找到 OpenViking 插件配置，无需卸载。",
+    ));
+    return;
+  }
+
+  info(tr(
+    `Detected installed plugin: ${formatInstalledStateLabel(installedState)}`,
+    `检测到已安装插件: ${formatInstalledStateLabel(installedState)}`,
+  ));
+
+  if (!nonInteractive) {
+    const answer = await question(
+      tr("Confirm uninstall? (y/N)", "确认卸载？(y/N)"),
+      "N",
+    );
+    if (!isYes(answer)) {
+      info(tr("Cancelled.", "已取消。"));
+      return;
+    }
+  }
+
+  // Step 1: Stop gateway
+  info(tr("Step 1: Stopping OpenClaw gateway...", "步骤 1: 停止 OpenClaw gateway..."));
+  await stopOpenClawGatewayForUpgrade();
+
+  // Step 2: Backup config
+  info(tr("Step 2: Backing up configuration...", "步骤 2: 备份配置..."));
+  const configBackupPath = await backupOpenClawConfig(configPath);
+  info(tr(`Config backed up to: ${configBackupPath}`, `配置已备份至: ${configBackupPath}`));
+
+  // Step 3: Clean plugin config from openclaw.json
+  info(tr("Step 3: Cleaning plugin configuration...", "步骤 3: 清理插件配置..."));
+  await cleanupInstalledPluginConfig(installedState);
+
+  // Step 4: Backup and remove plugin directories
+  info(tr("Step 4: Backing up plugin directories...", "步骤 4: 备份插件目录..."));
+  const pluginBackups = [];
+  for (const detection of installedState.detections) {
+    const backupDir = await backupPluginDirectory(detection.variant);
+    if (backupDir) {
+      pluginBackups.push({ pluginId: detection.variant.id, backupDir });
+    }
+  }
+
+  // Step 5: Remove env files
+  info(tr("Step 5: Removing environment files...", "步骤 5: 移除环境文件..."));
+  const envFilesToRemove = IS_WIN
+    ? [
+        join(OPENCLAW_DIR, "openviking.env.bat"),
+        join(OPENCLAW_DIR, "openviking.env.ps1"),
+      ]
+    : [join(OPENCLAW_DIR, "openviking.env")];
+  let removedEnvCount = 0;
+  for (const f of envFilesToRemove) {
+    if (existsSync(f)) {
+      try {
+        await rm(f);
+        removedEnvCount++;
+        info(tr(`Removed: ${f}`, `已移除: ${f}`));
+      } catch { /* ignore */ }
+    }
+  }
+  if (removedEnvCount === 0) {
+    info(tr("No environment files found.", "未找到环境文件。"));
+  }
+
+  // Step 6: Write uninstall audit
+  const auditDir = getUpgradeAuditDir();
+  await mkdir(auditDir, { recursive: true });
+  const auditData = {
+    operation: "uninstall",
+    createdAt: new Date().toISOString(),
+    fromVersion: formatInstalledStateLabel(installedState),
+    configBackupPath,
+    pluginBackups,
+  };
+  await writeUpgradeAuditFile(auditData);
+
+  // Done
+  console.log("");
+  bold("═══════════════════════════════════════════════════════════");
+  bold(`  ${tr("Uninstall complete!", "卸载完成！")}`);
+  bold("═══════════════════════════════════════════════════════════");
+  console.log("");
+
+  info(tr("OpenViking server/runtime is preserved (not uninstalled).", "OpenViking 服务端/运行时已保留（未卸载）。"));
+  console.log("");
+
+  info(tr("To restore the plugin configuration:", "如需恢复插件配置："));
+  console.log(`  1) ${tr("Stop gateway:", "停止 gateway:")} openclaw gateway stop`);
+  console.log(`  2) ${tr("Restore config:", "恢复配置:")} ${IS_WIN ? "copy" : "cp"} "${configBackupPath}" "${configPath}"`);
+  for (const pb of pluginBackups) {
+    const liveDir = join(OPENCLAW_DIR, "extensions", pb.pluginId);
+    console.log(`  3) ${tr("Restore plugin:", "恢复插件:")} ${IS_WIN ? "move" : "mv"} "${pb.backupDir}" "${liveDir}"`);
+  }
+  console.log("");
+
+  info(tr("To reinstall:", "重新安装："));
+  console.log("  ov-install");
+  console.log("");
+}
+
 async function main() {
   console.log("");
   bold(tr("🦣 OpenClaw OpenViking plugin installer", "🦣 OpenClaw OpenViking 插件安装"));
@@ -1688,6 +2689,10 @@ async function main() {
     await printCurrentVersionInfo();
     return;
   }
+  if (uninstallPlugin) {
+    await performUninstall();
+    return;
+  }
   if (rollbackLastUpgrade) {
     info(tr("Mode: rollback last plugin upgrade", "模式: 回滚最近一次插件升级"));
     if (pluginVersionExplicit) {
@@ -1696,11 +2701,16 @@ async function main() {
     await rollbackLastUpgradeOperation();
     return;
   }
-  await resolveDefaultPluginVersion();
-  validateRequestedPluginVersion();
-  info(tr(`Target: ${OPENCLAW_DIR}`, `目标实例: ${OPENCLAW_DIR}`));
-  info(tr(`Repository: ${REPO}`, `仓库: ${REPO}`));
-  info(tr(`Plugin version: ${PLUGIN_VERSION}`, `插件版本: ${PLUGIN_VERSION}`));
+  await resolveDefaultPluginVersion();
+  validateRequestedPluginVersion();
+  info(tr(`Target: ${OPENCLAW_DIR}`, `目标实例: ${OPENCLAW_DIR}`));
+  info(tr(`Plugin source: ${pluginSource}`, `Plugin source: ${pluginSource}`));
+  if (pluginSource === "npm") {
+    info(tr(`Plugin package: ${pluginNpmPackage}`, `Plugin package: ${pluginNpmPackage}`));
+  } else {
+    info(tr(`Repository: ${REPO}`, `仓库: ${REPO}`));
+  }
+  info(tr(`Plugin version: ${PLUGIN_VERSION}`, `插件版本: ${PLUGIN_VERSION}`));
 
   if (upgradePluginOnly) {
     info(tr("Mode: plugin upgrade only", "模式: 仅升级插件"));
@@ -1721,7 +2731,7 @@ async function main() {
 
   await deployPluginFromRemote();
 
-  await configureOpenClawPlugin(
+  const configResult = await configureOpenClawPlugin(
     upgradePluginOnly
       ? {
           runtimeConfig: upgradeRuntimeConfig,
@@ -1729,15 +2739,23 @@ async function main() {
         }
       : { 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);
+  const runtimeConfigOk = configResult?.runtimeConfigOk !== false;
+  const runtimeConfigError = configResult?.error || "";
+
+  // Only mark the install as completed (state file + upgrade audit) when the
+  // runtime config was actually applied. Plugin files are already on disk
+  // either way, so subsequent runs can pick up from here.
+  if (runtimeConfigOk) {
+    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) {
@@ -1747,18 +2765,33 @@ async function main() {
   }
 
   console.log("");
-  bold("═══════════════════════════════════════════════════════════");
-  bold(`  ${tr("Installation complete!", "安装完成！")}`);
-  bold("═══════════════════════════════════════════════════════════");
-  console.log("");
+  if (runtimeConfigOk) {
+    bold("═══════════════════════════════════════════════════════════");
+    bold(`  ${tr("Installation complete!", "安装完成！")}`);
+    bold("═══════════════════════════════════════════════════════════");
+    console.log("");
 
-  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}`));
+    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("");
     }
-    info(tr(`Rollback audit file: ${getUpgradeAuditPath()}`, `回滚审计文件: ${getUpgradeAuditPath()}`));
+  } else {
+    bold("═══════════════════════════════════════════════════════════");
+    bold(`  ${tr(
+      "Plugin files installed, but runtime configuration was NOT applied",
+      "插件文件已安装，但运行时配置未生效",
+    )}`);
+    bold(`  ${tr(`Reason: ${runtimeConfigError}`, `原因: ${runtimeConfigError}`)}`);
+    bold(`  ${tr(
+      "Re-run: openclaw openviking setup --reconfigure",
+      "重新运行: openclaw openviking setup --reconfigure",
+    )}`);
+    bold("═══════════════════════════════════════════════════════════");
     console.log("");
   }