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

package/install.js

@@ -3,18 +3,18 @@
  * 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 ]
+ *   node install.js [ --base-url URL ] [ --api-key KEY ] [ --zh ] [ --workdir PATH ] [ --upgrade-plugin ]
  *                   [ --plugin-version=TAG ]
  *
  * Environment variables:
- *   REPO, PLUGIN_VERSION (or BRANCH), OPENVIKING_INSTALL_YES, SKIP_OPENCLAW
+ *   REPO, PLUGIN_VERSION (or BRANCH), OPENVIKING_BASE_URL, OPENVIKING_API_KEY, SKIP_OPENCLAW
  *   NPM_REGISTRY
  */
 
@@ -33,6 +33,8 @@ const pluginVersionEnv = (process.env.PLUGIN_VERSION || process.env.BRANCH || ""
 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 +49,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 +60,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 +92,31 @@ let resolvedPluginSlot = "";
 let resolvedFilesRequired = [];
 let resolvedFilesOptional = [];
 let resolvedNpmOmitDev = true;
+let resolvedNpmBuild = false;
+let resolvedNpmBuildMinOpenclawVersion = DEFAULT_NPM_BUILD_MIN_OPENCLAW_VERSION;
+let resolvedNpmBuildScript = "build";
+let resolvedNpmPruneAfterBuild = true;
 let resolvedMinOpenclawVersion = "";
 let resolvedMinOpenvikingVersion = "";
 let resolvedPluginReleaseId = "";
+let detectedOpenClawVersion = "";
 
-let 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 uninstallPlugin = 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 +125,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,6 +147,10 @@ for (let i = 0; i < argv.length; i++) {
     rollbackLastUpgrade = true;
     continue;
   }
+  if (arg === "--uninstall" || arg === "--remove") {
+    uninstallPlugin = true;
+    continue;
+  }
   if (arg === "--workdir") {
     const workdir = argv[i + 1]?.trim();
     if (!workdir) {
@@ -173,12 +197,71 @@ for (let i = 0; i < argv.length; i++) {
     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("--base-url=")) {
+    remoteBaseUrl = arg.slice("--base-url=".length).trim();
+    baseUrlExplicit = true;
+    continue;
+  }
+  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;
 }
@@ -195,7 +278,12 @@ function printHelp() {
   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("  --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("  --zh                     Chinese prompts");
   console.log("  -h, --help               This help");
   console.log("");
@@ -326,6 +414,48 @@ function question(prompt, defaultValue = "") {
   });
 }
 
+function isValidAgentPrefixInput(value) {
+  const trimmed = String(value || "").trim();
+  return !trimmed || /^[a-zA-Z0-9_-]+$/.test(trimmed);
+}
+
+function parseJsonObjectFromOutput(output) {
+  const text = String(output || "").trim();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    // OpenClaw may print plugin registration logs before --json output.
+  }
+  for (let index = text.lastIndexOf("{"); index >= 0; index = text.lastIndexOf("{", index - 1)) {
+    try {
+      const parsed = JSON.parse(text.slice(index).trim());
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed;
+      }
+    } catch {
+      // Keep scanning earlier braces until the outer JSON object is found.
+    }
+  }
+  return null;
+}
+
+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() {
   const instances = [];
   try {
@@ -349,7 +479,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 +499,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 +544,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 +606,29 @@ if (upgradePluginOnly && rollbackLastUpgrade) {
   process.exit(1);
 }
 
+if (uninstallPlugin && (upgradePluginOnly || rollbackLastUpgrade)) {
+  console.error("--uninstall cannot be used with --upgrade-plugin or --rollback");
+  process.exit(1);
+}
+
 // 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
@@ -589,6 +777,12 @@ async function resolvePluginConfig() {
 
   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 +824,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 +871,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 +891,7 @@ async function resolvePluginConfig() {
       }
     }
 
-    resolvedMinOpenclawVersion = compatVer || "2026.3.7";
+    resolvedMinOpenclawVersion = compatVer || fallback.minOpenclawVersion || "2026.3.7";
     resolvedMinOpenvikingVersion = "";
   }
 
@@ -699,6 +909,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 +922,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}）`
@@ -1270,6 +1481,103 @@ async function downloadPluginFile(destDir, fileName, url, required, index, total
   process.exit(1);
 }
 
+function runtimeOutputCandidatesForEntry(entry) {
+  const normalized = String(entry || "").replace(/\\/g, "/").replace(/^\.\//, "");
+  if (!normalized.endsWith(".ts")) {
+    return [];
+  }
+  const withoutExt = normalized.slice(0, -3);
+  return [
+    `dist/${withoutExt}.js`,
+    `dist/${withoutExt}.mjs`,
+    `dist/${withoutExt}.cjs`,
+    `${withoutExt}.js`,
+    `${withoutExt}.mjs`,
+    `${withoutExt}.cjs`,
+  ];
+}
+
+async function assertBuiltRuntimeOutputs(destDir) {
+  let pkg = null;
+  try {
+    pkg = JSON.parse(await readFile(join(destDir, "package.json"), "utf8"));
+  } catch {
+    return;
+  }
+
+  const entries = [];
+  const extensions = pkg?.openclaw?.extensions;
+  if (Array.isArray(extensions)) {
+    for (const entry of extensions) {
+      if (typeof entry === "string") entries.push(entry);
+    }
+  }
+  if (typeof pkg?.openclaw?.setupEntry === "string") {
+    entries.push(pkg.openclaw.setupEntry);
+  }
+
+  const missing = [];
+  for (const entry of entries) {
+    const candidates = runtimeOutputCandidatesForEntry(entry);
+    if (candidates.length === 0) continue;
+    const found = candidates.some((candidate) => existsSync(join(destDir, ...candidate.split("/"))));
+    if (!found) {
+      missing.push(`${entry} (expected one of: ${candidates.join(", ")})`);
+    }
+  }
+
+  if (missing.length === 0) {
+    return;
+  }
+
+  err(tr(
+    `Plugin build did not create required runtime output:\n  - ${missing.join("\n  - ")}`,
+    `插件构建未生成必需的运行时产物：\n  - ${missing.join("\n  - ")}`,
+  ));
+  process.exit(1);
+}
+
+async function installPluginNpmDependencies(destDir) {
+  if (!resolvedNpmBuild) {
+    info(tr("Installing plugin npm dependencies...", "正在安装插件 npm 依赖..."));
+    const npmArgs = resolvedNpmOmitDev
+      ? ["install", "--omit=dev", "--no-audit", "--no-fund", "--registry", NPM_REGISTRY]
+      : ["install", "--no-audit", "--no-fund", "--registry", NPM_REGISTRY];
+    await run("npm", npmArgs, { cwd: destDir, silent: false });
+    return;
+  }
+
+  info(tr(
+    "Installing plugin npm dependencies for source build...",
+    "正在安装插件源码构建所需的 npm 依赖...",
+  ));
+  await run("npm", [
+    "install",
+    "--include=dev",
+    "--no-audit",
+    "--no-fund",
+    "--registry",
+    NPM_REGISTRY,
+  ], { cwd: destDir, silent: false });
+
+  info(tr(
+    `Building plugin runtime output with npm run ${resolvedNpmBuildScript}...`,
+    `正在执行 npm run ${resolvedNpmBuildScript} 构建插件运行时产物...`,
+  ));
+  await run("npm", ["run", resolvedNpmBuildScript], { cwd: destDir, silent: false });
+  await assertBuiltRuntimeOutputs(destDir);
+
+  if (resolvedNpmOmitDev && resolvedNpmPruneAfterBuild) {
+    info(tr("Pruning plugin dev dependencies...", "正在裁剪插件开发依赖..."));
+    await run("npm", [
+      "prune",
+      "--omit=dev",
+      "--no-audit",
+      "--no-fund",
+    ], { cwd: destDir, silent: false });
+  }
+}
+
 async function downloadPlugin(destDir) {
   const ghRaw = `https://raw.githubusercontent.com/${REPO}/${PLUGIN_VERSION}`;
   const pluginDir = resolvedPluginDir;
@@ -1296,12 +1604,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}`));
 }
 
@@ -1407,6 +1710,64 @@ 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", "冲突的插件变体已清理"));
+}
+
 async function configureOpenClawPlugin({
   preserveExistingConfig = false,
   runtimeConfig = null,
@@ -1447,12 +1808,15 @@ 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();
   }
@@ -1488,7 +1852,7 @@ async function configureOpenClawPlugin({
         `已保留 ${pluginId} 的现有插件运行时配置`,
       ),
     );
-    return;
+    return { runtimeConfigOk: true };
   }
 
   const writeConfigDirect = async (pluginConfig, slotValue) => {
@@ -1507,19 +1871,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,38 +1917,60 @@ 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");
-  }
+  // Detect if the installed plugin supports `setup --json` by checking the deployed setup.ts
+  let setupJsonSupported = false;
+  try {
+    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 */ }
 
-  info(tr(
-    "Delegating configuration to: openclaw openviking setup --json",
-    "委托配置给: openclaw openviking setup --json",
-  ));
+  let setupResult = null;
+  if (setupJsonSupported) {
+    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 (claimSlot) {
+      setupArgs.push("--force-slot");
+    }
+    if (nonInteractive) {
+      setupArgs.push("--allow-offline");
+    }
 
-  const setupResult = await runCapture("openclaw", setupArgs, { env: ocEnv, shell: IS_WIN });
+    info(tr(
+      "Delegating configuration to: openclaw openviking setup --json",
+      "委托配置给: openclaw openviking setup --json",
+    ));
+
+    setupResult = await runCapture("openclaw", setupArgs, { env: ocEnv, shell: IS_WIN });
+  } else {
+    info(tr(
+      "Installed plugin does not support setup --json, using direct config write",
+      "已安装的插件不支持 setup --json，使用直接配置写入",
+    ));
+  }
 
   let parsed = null;
-  try {
-    parsed = JSON.parse(setupResult.out.trim());
-  } catch {
-    // If JSON parse fails, fall back to checking exit code
+  if (setupResult) {
+    parsed = parseJsonObjectFromOutput(`${setupResult.out || ""}\n${setupResult.err || ""}`);
   }
 
   if (parsed) {
@@ -1593,34 +2003,67 @@ async function configureOpenClawPlugin({
           `Setup failed: ${parsed.error || "unknown error"}`,
           `配置失败: ${parsed.error || "未知错误"}`,
         ));
+        return {
+          runtimeConfigOk: false,
+          error: parsed.error || parsed.action || "unknown error",
+        };
       }
     }
-  } else if (setupResult.code !== 0) {
-    // JSON parse failed and non-zero exit — setup CLI not available (old plugin version)
+  } else if (setupResult && setupResult.code !== 0) {
     warn(tr(
       `openclaw openviking setup exited with code ${setupResult.code}. Falling back to direct JSON config write.`,
       `openclaw openviking setup 退出码 ${setupResult.code}，回退到直接写入 JSON 配置。`,
     ));
-    const pluginConfig = {
+  }
+
+  if (!parsed) {
+    // 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));
+        }
+      }
+    } 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 +2121,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 (answer.toLowerCase() !== "y" && answer.toLowerCase() !== "yes") {
+      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 +2250,10 @@ async function main() {
     await printCurrentVersionInfo();
     return;
   }
+  if (uninstallPlugin) {
+    await performUninstall();
+    return;
+  }
   if (rollbackLastUpgrade) {
     info(tr("Mode: rollback last plugin upgrade", "模式: 回滚最近一次插件升级"));
     if (pluginVersionExplicit) {
@@ -1721,7 +2287,7 @@ async function main() {
 
   await deployPluginFromRemote();
 
-  await configureOpenClawPlugin(
+  const configResult = await configureOpenClawPlugin(
     upgradePluginOnly
       ? {
           runtimeConfig: upgradeRuntimeConfig,
@@ -1729,15 +2295,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 +2321,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("");
   }
 

package/package.json

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