openclaw-openviking-setup-helper 0.1.0

package/cli.js

@@ -0,0 +1,835 @@
+#!/usr/bin/env node
+/**
+ * OpenClaw + OpenViking setup helper
+ * Usage: npx openclaw-openviking-setup-helper
+ * Or: npx openclaw-openviking-setup-helper --help
+ */
+
+import { spawn } from "node:child_process";
+import { mkdir, writeFile, access, readFile, rm } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const GITHUB_RAW =
+  process.env.OPENVIKING_GITHUB_RAW ||
+  "https://raw.githubusercontent.com/OpenViking/OpenViking/main";
+
+const IS_WIN = process.platform === "win32";
+const IS_LINUX = process.platform === "linux";
+const HOME = process.env.HOME || process.env.USERPROFILE || "";
+const OPENCLAW_DIR = join(HOME, ".openclaw");
+const OPENVIKING_DIR = join(HOME, ".openviking");
+const EXT_DIR = join(OPENCLAW_DIR, "extensions");
+const PLUGIN_DEST = join(EXT_DIR, "memory-openviking");
+
+// ─── Utility helpers ───
+
+function log(msg, level = "info") {
+  const icons = { info: "\u2139", ok: "\u2713", err: "\u2717", warn: "\u26A0" };
+  console.log(`${icons[level] || ""} ${msg}`);
+}
+
+function run(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const p = spawn(cmd, args, {
+      stdio: opts.silent ? "pipe" : "inherit",
+      shell: opts.shell ?? true,
+      ...opts,
+    });
+    p.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`exit ${code}`))));
+  });
+}
+
+function runCapture(cmd, args, opts = {}) {
+  return new Promise((resolve) => {
+    const p = spawn(cmd, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: opts.shell ?? false,
+      ...opts,
+    });
+    let out = "";
+    let err = "";
+    p.stdout?.on("data", (d) => (out += d));
+    p.stderr?.on("data", (d) => (err += d));
+    p.on("error", (e) => {
+      if (e.code === "ENOENT") resolve({ code: -1, out: "", err: `command not found: ${cmd}` });
+      else resolve({ code: -1, out: "", err: String(e) });
+    });
+    p.on("close", (code) => resolve({ code, out: out.trim(), err: err.trim() }));
+  });
+}
+
+function runCaptureWithTimeout(cmd, args, timeoutMs, opts = {}) {
+  return new Promise((resolve) => {
+    const p = spawn(cmd, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: opts.shell ?? false,
+      ...opts,
+    });
+    let out = "";
+    let err = "";
+    let settled = false;
+    const done = (result) => { if (!settled) { settled = true; resolve(result); } };
+    const timer = setTimeout(() => { p.kill(); done({ code: out ? 0 : -1, out: out.trim(), err: err.trim() }); }, timeoutMs);
+    p.stdout?.on("data", (d) => (out += d));
+    p.stderr?.on("data", (d) => (err += d));
+    p.on("error", (e) => { clearTimeout(timer); done({ code: -1, out: "", err: String(e) }); });
+    p.on("close", (code) => { clearTimeout(timer); done({ code, out: out.trim(), err: err.trim() }); });
+  });
+}
+
+async function question(prompt, defaultValue = "") {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const def = defaultValue ? ` [${defaultValue}]` : "";
+  return new Promise((resolve) => {
+    rl.question(`${prompt}${def}: `, (answer) => {
+      rl.close();
+      resolve((answer ?? defaultValue).trim() || defaultValue);
+    });
+  });
+}
+
+async function questionApiKey(prompt) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve((answer ?? "").trim());
+    });
+  });
+}
+
+// ─── Distro detection ───
+
+async function detectDistro() {
+  if (IS_WIN) return "windows";
+  try {
+    const { out } = await runCapture("sh", ["-c", "cat /etc/os-release 2>/dev/null"]);
+    const lower = out.toLowerCase();
+    if (lower.includes("ubuntu") || lower.includes("debian")) return "debian";
+    if (lower.includes("centos") || lower.includes("rhel") || lower.includes("openeuler") || lower.includes("fedora") || lower.includes("rocky") || lower.includes("alma")) return "rhel";
+  } catch {}
+  const { code: aptCode } = await runCapture("sh", ["-c", "command -v apt"]);
+  if (aptCode === 0) return "debian";
+  const { code: dnfCode } = await runCapture("sh", ["-c", "command -v dnf || command -v yum"]);
+  if (dnfCode === 0) return "rhel";
+  return "unknown";
+}
+
+// ─── Environment checks ───
+
+const DEFAULT_PYTHON = IS_WIN ? "python" : "python3";
+
+async function checkOpenclaw() {
+  if (IS_WIN) {
+    const { code } = await runCaptureWithTimeout("openclaw", ["--version"], 10000, { shell: true });
+    return code === 0 ? { ok: true } : { ok: false };
+  }
+  const { code } = await runCapture("openclaw", ["--version"]);
+  return code === 0 ? { ok: true } : { ok: false };
+}
+
+async function checkPython() {
+  const py = process.env.OPENVIKING_PYTHON || DEFAULT_PYTHON;
+  const { code, out } = await runCapture(py, ["-c", "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')"]);
+  if (code !== 0) return { ok: false, version: null, cmd: py, msg: `Python not found (tried: ${py})` };
+  const [major, minor] = out.split(".").map(Number);
+  if (major < 3 || (major === 3 && minor < 10))
+    return { ok: false, version: out, cmd: py, msg: `Python ${out} too old, need >= 3.10` };
+  return { ok: true, version: out, cmd: py, msg: `${out} (${py})` };
+}
+
+async function checkGo() {
+  const goDir = process.env.OPENVIKING_GO_PATH?.replace(/^~/, HOME);
+  const goCmd = goDir ? join(goDir, "go") : "go";
+  const { code, out } = await runCapture(goCmd, ["version"]);
+  if (code !== 0) return { ok: false, version: null, msg: "Go not found" };
+  const m = out.match(/go([0-9]+)\.([0-9]+)/);
+  if (!m) return { ok: false, version: null, msg: "Cannot parse Go version" };
+  const [, major, minor] = m.map(Number);
+  if (major < 1 || (major === 1 && minor < 19))
+    return { ok: false, version: `${major}.${minor}`, msg: `Go ${major}.${minor} too old, need >= 1.19` };
+  return { ok: true, version: `${major}.${minor}`, msg: `${major}.${minor}` };
+}
+
+async function checkCmake() {
+  const { code } = await runCapture("cmake", ["--version"]);
+  return { ok: code === 0 };
+}
+
+async function checkGpp() {
+  const { code } = await runCapture("g++", ["--version"]);
+  return { ok: code === 0 };
+}
+
+async function checkOpenvikingModule() {
+  const py = process.env.OPENVIKING_PYTHON || DEFAULT_PYTHON;
+  const { code } = await runCapture(py, ["-c", "import openviking"]);
+  return code === 0 ? { ok: true } : { ok: false };
+}
+
+async function checkOvvConf() {
+  const cfg = process.env.OPENVIKING_CONFIG_FILE || join(OPENVIKING_DIR, "ov.conf");
+  try {
+    await access(cfg);
+    return { ok: true, path: cfg };
+  } catch {
+    return { ok: false, path: cfg };
+  }
+}
+
+// ─── Config helpers ───
+
+const DEFAULT_SERVER_PORT = 1933;
+const DEFAULT_AGFS_PORT = 1833;
+const DEFAULT_VLM_MODEL = "doubao-seed-2-0-pro-260215";
+const DEFAULT_EMBEDDING_MODEL = "doubao-embedding-vision-250615";
+
+const DEFAULT_WORKSPACE = join(HOME, ".openviking", "data");
+
+function buildOvvConfJson(opts = {}) {
+  const {
+    apiKey = "",
+    serverPort = DEFAULT_SERVER_PORT,
+    agfsPort = DEFAULT_AGFS_PORT,
+    vlmModel = DEFAULT_VLM_MODEL,
+    embeddingModel = DEFAULT_EMBEDDING_MODEL,
+    workspace = DEFAULT_WORKSPACE,
+  } = opts;
+  return JSON.stringify({
+    server: {
+      host: "127.0.0.1",
+      port: serverPort,
+      root_api_key: null,
+      cors_origins: ["*"],
+    },
+    storage: {
+      workspace,
+      vectordb: { name: "context", backend: "local", project: "default" },
+      agfs: { port: agfsPort, log_level: "warn", backend: "local", timeout: 10, retry_times: 3 },
+    },
+    embedding: {
+      dense: {
+        backend: "volcengine",
+        api_key: apiKey || null,
+        model: embeddingModel,
+        api_base: "https://ark.cn-beijing.volces.com/api/v3",
+        dimension: 1024,
+        input: "multimodal",
+      },
+    },
+    vlm: {
+      backend: "volcengine",
+      api_key: apiKey || null,
+      model: vlmModel,
+      api_base: "https://ark.cn-beijing.volces.com/api/v3",
+      temperature: 0.1,
+      max_retries: 3,
+    },
+  }, null, 2);
+}
+
+function parsePort(val, defaultVal) {
+  const n = parseInt(val, 10);
+  return Number.isFinite(n) && n >= 1 && n <= 65535 ? n : defaultVal;
+}
+
+async function ensureOvvConf(cfgPath, opts = {}) {
+  await mkdir(dirname(cfgPath), { recursive: true });
+  await writeFile(cfgPath, buildOvvConfJson(opts));
+  log(`Created config: ${cfgPath}`, "ok");
+  if (!opts.apiKey) {
+    log("API Key not set; memory features may be unavailable. Edit ov.conf to add later.", "warn");
+  }
+}
+
+async function getApiKeyFromOvvConf(cfgPath) {
+  let raw;
+  try {
+    raw = await readFile(cfgPath, "utf-8");
+    const cfg = JSON.parse(raw);
+    return cfg?.embedding?.dense?.api_key || "";
+  } catch {
+    const m = raw?.match(/api_key\s*:\s*["']?([^"'\s#]+)["']?/);
+    return m ? m[1].trim() : "";
+  }
+}
+
+async function getOvvConfPorts(cfgPath) {
+  try {
+    const raw = await readFile(cfgPath, "utf-8");
+    const cfg = JSON.parse(raw);
+    return {
+      serverPort: cfg?.server?.port ?? DEFAULT_SERVER_PORT,
+      agfsPort: cfg?.storage?.agfs?.port ?? DEFAULT_AGFS_PORT,
+    };
+  } catch {
+    return { serverPort: DEFAULT_SERVER_PORT, agfsPort: DEFAULT_AGFS_PORT };
+  }
+}
+
+async function isOvvConfInvalid(cfgPath) {
+  try {
+    JSON.parse(await readFile(cfgPath, "utf-8"));
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+async function updateOvvConf(cfgPath, opts = {}) {
+  let cfg;
+  try {
+    cfg = JSON.parse(await readFile(cfgPath, "utf-8"));
+  } catch {
+    log("ov.conf is not valid JSON, will create new config", "warn");
+    await ensureOvvConf(cfgPath, opts);
+    return;
+  }
+  if (opts.apiKey !== undefined) {
+    if (!cfg.embedding) cfg.embedding = {};
+    if (!cfg.embedding.dense) cfg.embedding.dense = {};
+    cfg.embedding.dense.api_key = opts.apiKey || null;
+    if (!cfg.vlm) cfg.vlm = {};
+    cfg.vlm.api_key = opts.apiKey || null;
+  }
+  if (opts.vlmModel !== undefined) {
+    if (!cfg.vlm) cfg.vlm = {};
+    cfg.vlm.model = opts.vlmModel;
+    if (!cfg.vlm.api_base) cfg.vlm.api_base = "https://ark.cn-beijing.volces.com/api/v3";
+    if (!cfg.vlm.backend) cfg.vlm.backend = "volcengine";
+  }
+  if (opts.embeddingModel !== undefined) {
+    if (!cfg.embedding) cfg.embedding = {};
+    if (!cfg.embedding.dense) cfg.embedding.dense = {};
+    cfg.embedding.dense.model = opts.embeddingModel;
+  }
+  if (opts.serverPort !== undefined && cfg.server) cfg.server.port = opts.serverPort;
+  if (opts.agfsPort !== undefined && cfg.storage?.agfs) cfg.storage.agfs.port = opts.agfsPort;
+  await writeFile(cfgPath, JSON.stringify(cfg, null, 2));
+}
+
+// ─── Interactive config collection ───
+
+async function collectOvvConfInteractive(nonInteractive) {
+  const opts = {
+    apiKey: process.env.OPENVIKING_ARK_API_KEY || "",
+    serverPort: DEFAULT_SERVER_PORT,
+    agfsPort: DEFAULT_AGFS_PORT,
+    vlmModel: DEFAULT_VLM_MODEL,
+    embeddingModel: DEFAULT_EMBEDDING_MODEL,
+    workspace: DEFAULT_WORKSPACE,
+  };
+  if (nonInteractive) return opts;
+
+  console.log("\n╔══════════════════════════════════════════════════════════╗");
+  console.log("║           OpenViking Configuration (ov.conf)            ║");
+  console.log("╚══════════════════════════════════════════════════════════╝");
+
+  console.log("\n--- Data Storage ---");
+  console.log("Workspace is where OpenViking stores all data (vector database, files, etc.).");
+  opts.workspace = await question(`Workspace path`, DEFAULT_WORKSPACE);
+
+  console.log("\nOpenViking requires a Volcengine Ark API Key for:");
+  console.log("  - Embedding model: vectorizes text for semantic search");
+  console.log("  - VLM model: analyzes conversations to extract memories");
+  console.log("\nGet your API Key at: https://console.volcengine.com/ark\n");
+
+  opts.apiKey = (await questionApiKey("Volcengine Ark API Key (leave blank to skip, configure later): ")) || opts.apiKey;
+
+  console.log("\n--- Model Configuration ---");
+  console.log("VLM model is used to extract and analyze memories from conversations.");
+  opts.vlmModel = await question(`VLM model name`, DEFAULT_VLM_MODEL);
+
+  console.log("\nEmbedding model is used to vectorize text for semantic search.");
+  opts.embeddingModel = await question(`Embedding model name`, DEFAULT_EMBEDDING_MODEL);
+
+  console.log("\n--- Server Ports ---");
+  const serverPortStr = await question(`OpenViking HTTP port`, String(DEFAULT_SERVER_PORT));
+  opts.serverPort = parsePort(serverPortStr, DEFAULT_SERVER_PORT);
+  const agfsPortStr = await question(`AGFS port`, String(DEFAULT_AGFS_PORT));
+  opts.agfsPort = parsePort(agfsPortStr, DEFAULT_AGFS_PORT);
+
+  return opts;
+}
+
+// ─── Installation helpers ───
+
+async function installOpenviking(repoRoot) {
+  const py = process.env.OPENVIKING_PYTHON || DEFAULT_PYTHON;
+  log(`Installing openviking (using ${py})...`);
+  if (repoRoot && existsSync(join(repoRoot, "pyproject.toml"))) {
+    await run(py, ["-m", "pip", "install", "-e", repoRoot]);
+    return;
+  }
+  await run(py, ["-m", "pip", "install", "openviking"]);
+}
+
+async function fetchPluginFromGitHub(dest) {
+  log("Downloading memory-openviking plugin from GitHub...");
+  const files = [
+    "examples/openclaw-memory-plugin/index.ts",
+    "examples/openclaw-memory-plugin/config.ts",
+    "examples/openclaw-memory-plugin/openclaw.plugin.json",
+    "examples/openclaw-memory-plugin/package.json",
+    "examples/openclaw-memory-plugin/package-lock.json",
+    "examples/openclaw-memory-plugin/.gitignore",
+  ];
+  await mkdir(dest, { recursive: true });
+  for (let i = 0; i < files.length; i++) {
+    const rel = files[i];
+    const name = rel.split("/").pop();
+    process.stdout.write(`  Downloading ${i + 1}/${files.length}: ${name} ... `);
+    const url = `${GITHUB_RAW}/${rel}`;
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`Download failed: ${url}`);
+    const buf = await res.arrayBuffer();
+    await writeFile(join(dest, name), Buffer.from(buf));
+    process.stdout.write("\u2713\n");
+  }
+  log(`Plugin downloaded to ${dest}`, "ok");
+  process.stdout.write("  Installing plugin deps (npm install)... ");
+  await run("npm", ["install", "--no-audit", "--no-fund"], { cwd: dest, silent: true });
+  process.stdout.write("\u2713\n");
+  log("Plugin deps installed", "ok");
+}
+
+async function fixStalePluginPaths(pluginPath) {
+  const cfgPath = join(OPENCLAW_DIR, "openclaw.json");
+  if (!existsSync(cfgPath)) return;
+  try {
+    const cfg = JSON.parse(await readFile(cfgPath, "utf8"));
+    let changed = false;
+    const paths = cfg?.plugins?.load?.paths;
+    if (Array.isArray(paths)) {
+      const cleaned = paths.filter((p) => existsSync(p));
+      if (!cleaned.includes(pluginPath)) cleaned.push(pluginPath);
+      if (JSON.stringify(cleaned) !== JSON.stringify(paths)) {
+        cfg.plugins.load.paths = cleaned;
+        changed = true;
+      }
+    }
+    const installs = cfg?.plugins?.installs;
+    if (installs) {
+      for (const [k, v] of Object.entries(installs)) {
+        if (v?.installPath && !existsSync(v.installPath)) {
+          delete installs[k];
+          changed = true;
+        }
+      }
+    }
+    if (changed) {
+      await writeFile(cfgPath, JSON.stringify(cfg, null, 2) + "\n");
+      log("Cleaned stale plugin paths from openclaw.json", "ok");
+    }
+  } catch {}
+}
+
+async function configureOpenclawViaJson(pluginPath, serverPort) {
+  const cfgPath = join(OPENCLAW_DIR, "openclaw.json");
+  let cfg = {};
+  try { cfg = JSON.parse(await readFile(cfgPath, "utf8")); } catch { /* start fresh */ }
+  if (!cfg.plugins) cfg.plugins = {};
+  cfg.plugins.enabled = true;
+  cfg.plugins.allow = ["memory-openviking"];
+  if (!cfg.plugins.slots) cfg.plugins.slots = {};
+  cfg.plugins.slots.memory = "memory-openviking";
+  if (!cfg.plugins.load) cfg.plugins.load = {};
+  const paths = Array.isArray(cfg.plugins.load.paths) ? cfg.plugins.load.paths : [];
+  if (!paths.includes(pluginPath)) paths.push(pluginPath);
+  cfg.plugins.load.paths = paths;
+  if (!cfg.plugins.entries) cfg.plugins.entries = {};
+  const ovConfPath = join(OPENVIKING_DIR, "ov.conf");
+  cfg.plugins.entries["memory-openviking"] = {
+    config: {
+      mode: "local",
+      configPath: ovConfPath,
+      port: serverPort,
+      targetUri: "viking://user/memories",
+      autoRecall: true,
+      autoCapture: true,
+    },
+  };
+  if (!cfg.gateway) cfg.gateway = {};
+  cfg.gateway.mode = "local";
+  await mkdir(OPENCLAW_DIR, { recursive: true });
+  await writeFile(cfgPath, JSON.stringify(cfg, null, 2) + "\n");
+}
+
+async function configureOpenclawViaCli(pluginPath, serverPort, mode) {
+  const runNoShell = (cmd, args, opts = {}) => run(cmd, args, { ...opts, shell: false });
+  if (mode === "link") {
+    if (existsSync(PLUGIN_DEST)) {
+      log(`Removing old plugin dir ${PLUGIN_DEST}...`, "info");
+      await rm(PLUGIN_DEST, { recursive: true, force: true });
+    }
+    await run("openclaw", ["plugins", "install", "-l", pluginPath]);
+  } else {
+    await runNoShell("openclaw", ["config", "set", "plugins.load.paths", JSON.stringify([pluginPath])], { silent: true }).catch(() => {});
+  }
+  await runNoShell("openclaw", ["config", "set", "plugins.enabled", "true"]);
+  await runNoShell("openclaw", ["config", "set", "plugins.allow", JSON.stringify(["memory-openviking"]), "--json"]);
+  await runNoShell("openclaw", ["config", "set", "gateway.mode", "local"]);
+  await runNoShell("openclaw", ["config", "set", "plugins.slots.memory", "memory-openviking"]);
+  await runNoShell("openclaw", ["config", "set", "plugins.entries.memory-openviking.config.mode", "local"]);
+  const ovConfPath = join(OPENVIKING_DIR, "ov.conf");
+  await runNoShell("openclaw", ["config", "set", "plugins.entries.memory-openviking.config.configPath", ovConfPath]);
+  await runNoShell("openclaw", ["config", "set", "plugins.entries.memory-openviking.config.port", String(serverPort)]);
+  await runNoShell("openclaw", ["config", "set", "plugins.entries.memory-openviking.config.targetUri", "viking://user/memories"]);
+  await runNoShell("openclaw", ["config", "set", "plugins.entries.memory-openviking.config.autoRecall", "true", "--json"]);
+  await runNoShell("openclaw", ["config", "set", "plugins.entries.memory-openviking.config.autoCapture", "true", "--json"]);
+}
+
+async function configureOpenclaw(pluginPath, serverPort = DEFAULT_SERVER_PORT, mode = "link") {
+  await fixStalePluginPaths(pluginPath);
+  if (IS_WIN) {
+    await configureOpenclawViaJson(pluginPath, serverPort);
+  } else {
+    await configureOpenclawViaCli(pluginPath, serverPort, mode);
+  }
+  log("OpenClaw plugin config done", "ok");
+}
+
+async function resolveCommand(cmd) {
+  if (IS_WIN) {
+    const { code, out } = await runCapture("where", [cmd], { shell: true });
+    return code === 0 ? out.split(/\r?\n/)[0].trim() : "";
+  }
+  const { out } = await runCapture("sh", ["-c", `command -v ${cmd} 2>/dev/null || which ${cmd}`]);
+  return out || "";
+}
+
+async function writeOpenvikingEnv() {
+  const pyCmd = process.env.OPENVIKING_PYTHON || DEFAULT_PYTHON;
+  const pyPath = await resolveCommand(pyCmd);
+  const goOut = await resolveCommand("go");
+  const goPath = goOut ? dirname(goOut) : "";
+  await mkdir(OPENCLAW_DIR, { recursive: true });
+
+  if (IS_WIN) {
+    const lines = [];
+    if (pyPath) lines.push(`set OPENVIKING_PYTHON=${pyPath}`);
+    if (goPath) lines.push(`set OPENVIKING_GO_PATH=${goPath}`);
+    if (process.env.GOPATH) lines.push(`set OPENVIKING_GOPATH=${process.env.GOPATH}`);
+    if (process.env.GOPROXY) lines.push(`set OPENVIKING_GOPROXY=${process.env.GOPROXY}`);
+    await writeFile(join(OPENCLAW_DIR, "openviking.env.bat"), lines.join("\r\n") + "\r\n");
+    log(`Written ~/.openclaw/openviking.env.bat`, "ok");
+  } else {
+    const lines = [];
+    if (pyPath) lines.push(`export OPENVIKING_PYTHON='${pyPath}'`);
+    if (goPath) lines.push(`export OPENVIKING_GO_PATH='${goPath}'`);
+    if (process.env.GOPATH) lines.push(`export OPENVIKING_GOPATH='${process.env.GOPATH}'`);
+    if (process.env.GOPROXY) lines.push(`export OPENVIKING_GOPROXY='${process.env.GOPROXY}'`);
+    await writeFile(join(OPENCLAW_DIR, "openviking.env"), lines.join("\n") + "\n");
+    log(`Written ~/.openclaw/openviking.env`, "ok");
+  }
+}
+
+// ─── Main flow ───
+
+async function main() {
+  const args = process.argv.slice(2);
+  const help = args.includes("--help") || args.includes("-h");
+  const nonInteractive = args.includes("--yes") || args.includes("-y");
+
+  if (help) {
+    console.log(`
+OpenClaw + OpenViking setup helper
+
+Usage: npx openclaw-openviking-setup-helper [options]
+
+Options:
+  -y, --yes     Non-interactive, use defaults
+  -h, --help    Show help
+
+Steps:
+  1. Check OpenClaw
+  2. Check build environment (Python, Go, cmake, g++)
+  3. Install openviking module if needed
+  4. Configure ov.conf (API Key, VLM, Embedding, ports)
+  5. Deploy memory-openviking plugin
+  6. Write ~/.openclaw/openviking.env
+
+Env vars:
+  OPENVIKING_PYTHON       Python path
+  OPENVIKING_CONFIG_FILE  ov.conf path
+  OPENVIKING_REPO         Local OpenViking repo path (use local plugin if set)
+  OPENVIKING_ARK_API_KEY  Volcengine Ark API Key (used in -y mode, skip prompt)
+  OPENVIKING_GO_PATH      Go bin dir (when Go not in PATH, e.g. ~/local/go/bin)
+`);
+    process.exit(0);
+  }
+
+  console.log("\n\ud83e\udd9e OpenClaw + OpenViking setup helper\n");
+
+  const distro = await detectDistro();
+
+  // ════════════════════════════════════════════
+  // Phase 1: Check build tools & runtime environment
+  //   cmake/g++ must be present before OpenClaw install (node-llama-cpp needs them)
+  // ════════════════════════════════════════════
+  console.log("── Step 1/5: Checking build environment ──\n");
+
+  const missing = [];
+
+  // cmake check (needed by OpenClaw's node-llama-cpp AND OpenViking C++ extension)
+  const cmakeResult = await checkCmake();
+  if (cmakeResult.ok) {
+    log("cmake: installed", "ok");
+  } else {
+    log("cmake: not found", "err");
+    missing.push({ name: "cmake", detail: "Required by OpenClaw (llama.cpp) and OpenViking (C++ extension)" });
+  }
+
+  // g++ check (needed by OpenClaw's node-llama-cpp AND OpenViking C++ extension)
+  const gppResult = await checkGpp();
+  if (gppResult.ok) {
+    log("g++: installed", "ok");
+  } else {
+    log("g++: not found", "err");
+    missing.push({ name: "g++ (gcc-c++)", detail: "Required by OpenClaw (llama.cpp) and OpenViking (C++ extension)" });
+  }
+
+  // Python check
+  const pyResult = await checkPython();
+  if (pyResult.ok) {
+    log(`Python: ${pyResult.msg}`, "ok");
+  } else {
+    log(`Python: ${pyResult.msg}`, "err");
+    missing.push({ name: "Python >= 3.10", detail: pyResult.version ? `Current: ${pyResult.version}` : "Not found" });
+  }
+
+  // Go check (required on Linux for source install)
+  const goResult = await checkGo();
+  if (goResult.ok) {
+    log(`Go: ${goResult.msg}`, "ok");
+  } else if (IS_LINUX) {
+    log(`Go: ${goResult.msg}`, "err");
+    missing.push({ name: "Go >= 1.19", detail: goResult.msg });
+  } else {
+    log(`Go: not found (not required on ${process.platform})`, "warn");
+  }
+
+  if (missing.length > 0) {
+    console.log("\n\u2717 Missing dependencies:\n");
+    for (const m of missing) {
+      console.log(`  - ${m.name}: ${m.detail}`);
+    }
+
+    console.log("\n  Please install the missing dependencies:\n");
+
+    if (distro === "rhel") {
+      const needBuild = missing.some((m) => m.name === "cmake" || m.name === "g++ (gcc-c++)");
+      const needPython = missing.some((m) => m.name.startsWith("Python"));
+      const needGo = missing.some((m) => m.name.startsWith("Go"));
+
+      if (needBuild) console.log("    sudo dnf install -y gcc gcc-c++ cmake make");
+      if (needPython) {
+        console.log("    # Install Python 3.11 (try package manager first):");
+        console.log("    sudo dnf install -y python3.11 python3.11-devel python3.11-pip");
+        console.log("    # If unavailable, build from source:");
+        console.log("    #   See INSTALL-ZH.md 'Linux Environment Setup' section");
+      }
+      if (needGo) {
+        console.log("    # Install Go >= 1.19:");
+        console.log("    wget https://go.dev/dl/go1.25.6.linux-amd64.tar.gz");
+        console.log("    sudo rm -rf /usr/local/go");
+        console.log("    sudo tar -C /usr/local -xzf go1.25.6.linux-amd64.tar.gz");
+        console.log("    echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc");
+        console.log("    source ~/.bashrc");
+        console.log("    # Configure Go module proxy (recommended if downloads are slow):");
+        console.log("    go env -w GOPROXY=https://goproxy.cn,direct");
+      }
+    } else if (distro === "debian") {
+      const needBuild = missing.some((m) => m.name === "cmake" || m.name === "g++ (gcc-c++)");
+      const needPython = missing.some((m) => m.name.startsWith("Python"));
+      const needGo = missing.some((m) => m.name.startsWith("Go"));
+
+      if (needBuild) console.log("    sudo apt update && sudo apt install -y build-essential cmake");
+      if (needPython) {
+        console.log("    # Install Python 3.11:");
+        console.log("    sudo add-apt-repository ppa:deadsnakes/ppa");
+        console.log("    sudo apt install -y python3.11 python3.11-dev python3.11-venv");
+      }
+      if (needGo) {
+        console.log("    # Install Go >= 1.19:");
+        console.log("    wget https://go.dev/dl/go1.25.6.linux-amd64.tar.gz");
+        console.log("    sudo rm -rf /usr/local/go");
+        console.log("    sudo tar -C /usr/local -xzf go1.25.6.linux-amd64.tar.gz");
+        console.log("    echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc");
+        console.log("    source ~/.bashrc");
+        console.log("    # Configure Go module proxy (recommended if downloads are slow):");
+        console.log("    go env -w GOPROXY=https://goproxy.cn,direct");
+      }
+    } else {
+      console.log("    Please install: cmake, g++, Python >= 3.10, Go >= 1.19");
+      console.log("    See INSTALL-ZH.md for detailed instructions.");
+    }
+
+    console.log("\n  After installing, re-run this script:");
+    console.log("    npx ./examples/openclaw-memory-plugin/setup-helper\n");
+    process.exit(1);
+  }
+
+  // ════════════════════════════════════════════
+  // Phase 2: Check OpenClaw
+  // ════════════════════════════════════════════
+  console.log("\n── Step 2/5: Checking OpenClaw ──\n");
+
+  const hasOpenclaw = await checkOpenclaw();
+  if (!hasOpenclaw.ok) {
+    log("OpenClaw is not installed.", "err");
+    console.log("\n  Please install OpenClaw:\n");
+    console.log("    npm install -g openclaw\n");
+    console.log("  If downloads are slow, use npmmirror registry:");
+    console.log("    npm install -g openclaw --registry=https://registry.npmmirror.com\n");
+    console.log("  After installation, run onboarding to configure your LLM:");
+    console.log("    openclaw onboard\n");
+    console.log("  Then re-run this script:");
+    console.log("    npx ./examples/openclaw-memory-plugin/setup-helper\n");
+    process.exit(1);
+  }
+  log("OpenClaw: installed", "ok");
+
+  // ════════════════════════════════════════════
+  // Phase 3: Check & install openviking module
+  // ════════════════════════════════════════════
+  console.log("\n── Step 3/5: Checking openviking module ──\n");
+
+  const ovMod = await checkOpenvikingModule();
+  if (ovMod.ok) {
+    log("openviking module: installed", "ok");
+  } else {
+    log("openviking module: not found", "warn");
+    const inferredRepoRoot = join(__dirname, "..", "..", "..");
+    const hasLocalRepo = existsSync(join(inferredRepoRoot, "pyproject.toml"));
+    const repo = process.env.OPENVIKING_REPO || (hasLocalRepo ? inferredRepoRoot : "");
+
+    if (nonInteractive) {
+      await installOpenviking(repo);
+    } else {
+      const choice = await question(
+        repo
+          ? "Install openviking from local repo? (y=local repo / n=skip)"
+          : "Install openviking from PyPI? (y/n)",
+        "y"
+      );
+      if (choice.toLowerCase() === "y") {
+        await installOpenviking(repo);
+      } else {
+        log("Please install openviking manually and re-run this script.", "err");
+        if (repo) console.log(`    cd ${repo} && python3 -m pip install -e .`);
+        else console.log("    python3.11 -m pip install openviking --upgrade --force-reinstall");
+        process.exit(1);
+      }
+    }
+
+    const recheck = await checkOpenvikingModule();
+    if (!recheck.ok) {
+      log("openviking module installation failed. Check errors above.", "err");
+      process.exit(1);
+    }
+    log("openviking module: installed", "ok");
+  }
+
+  // ════════════════════════════════════════════
+  // Phase 4: Configure ov.conf (interactive)
+  // ════════════════════════════════════════════
+  console.log("\n── Step 4/5: Configuring OpenViking ──\n");
+
+  const ovConf = await checkOvvConf();
+  const ovConfPath = ovConf.path;
+  let ovOpts = {
+    apiKey: process.env.OPENVIKING_ARK_API_KEY || "",
+    serverPort: DEFAULT_SERVER_PORT,
+    agfsPort: DEFAULT_AGFS_PORT,
+    vlmModel: DEFAULT_VLM_MODEL,
+    embeddingModel: DEFAULT_EMBEDDING_MODEL,
+  };
+
+  if (!ovConf.ok) {
+    log(`ov.conf not found: ${ovConfPath}`, "info");
+    const create = nonInteractive || (await question("Create ov.conf now? (y/n)", "y")).toLowerCase() === "y";
+    if (create) {
+      ovOpts = await collectOvvConfInteractive(nonInteractive);
+      await ensureOvvConf(ovConfPath, ovOpts);
+    } else {
+      log("Please create ~/.openviking/ov.conf manually", "err");
+      process.exit(1);
+    }
+  } else {
+    log(`ov.conf found: ${ovConfPath}`, "ok");
+    const invalid = await isOvvConfInvalid(ovConfPath);
+    const existingKey = await getApiKeyFromOvvConf(ovConfPath);
+    const existingPorts = await getOvvConfPorts(ovConfPath);
+
+    if (invalid) {
+      log("ov.conf format is invalid, will recreate", "warn");
+      ovOpts = await collectOvvConfInteractive(nonInteractive);
+      await ensureOvvConf(ovConfPath, ovOpts);
+    } else if (!existingKey && !nonInteractive) {
+      log("API Key is not configured in ov.conf", "warn");
+      console.log("\nOpenViking needs a Volcengine Ark API Key for memory features.");
+      console.log("Get your API Key at: https://console.volcengine.com/ark\n");
+      const apiKey = (await questionApiKey("Volcengine Ark API Key (leave blank to skip): ")) || process.env.OPENVIKING_ARK_API_KEY || "";
+      if (apiKey) {
+        await updateOvvConf(ovConfPath, { apiKey });
+        log("Written API Key to ov.conf", "ok");
+      } else {
+        log("API Key not set; memory features may be unavailable. Edit ov.conf to add later.", "warn");
+      }
+      ovOpts = { ...existingPorts, apiKey };
+    } else if (!existingKey && process.env.OPENVIKING_ARK_API_KEY) {
+      await updateOvvConf(ovConfPath, { apiKey: process.env.OPENVIKING_ARK_API_KEY });
+      log("Written API Key from env to ov.conf", "ok");
+      ovOpts = { ...existingPorts, apiKey: process.env.OPENVIKING_ARK_API_KEY };
+    } else {
+      ovOpts = { ...existingPorts, apiKey: existingKey };
+    }
+  }
+
+  // ════════════════════════════════════════════
+  // Phase 5: Deploy plugin & finalize
+  // ════════════════════════════════════════════
+  console.log("\n── Step 5/5: Deploying plugin ──\n");
+
+  const inferredRepoRoot = join(__dirname, "..", "..", "..");
+  const repoRoot = process.env.OPENVIKING_REPO ||
+    (existsSync(join(inferredRepoRoot, "examples", "openclaw-memory-plugin", "index.ts")) ? inferredRepoRoot : "");
+  let pluginPath;
+  if (repoRoot && existsSync(join(repoRoot, "examples", "openclaw-memory-plugin", "index.ts"))) {
+    pluginPath = join(repoRoot, "examples", "openclaw-memory-plugin");
+    log(`Using local plugin: ${pluginPath}`, "ok");
+    if (!existsSync(join(pluginPath, "node_modules"))) {
+      await run("npm", ["install", "--no-audit", "--no-fund"], { cwd: pluginPath, silent: true });
+    }
+  } else {
+    await fetchPluginFromGitHub(PLUGIN_DEST);
+    pluginPath = PLUGIN_DEST;
+  }
+
+  await configureOpenclaw(pluginPath, ovOpts?.serverPort);
+  await writeOpenvikingEnv();
+
+  // Done
+  console.log("\n╔══════════════════════════════════════════════════════════╗");
+  console.log("║                   \u2705 Setup complete!                     ║");
+  console.log("╚══════════════════════════════════════════════════════════╝");
+  console.log("\nTo start OpenClaw with memory:");
+  if (IS_WIN) {
+    console.log('  call "%USERPROFILE%\\.openclaw\\openviking.env.bat" && openclaw gateway');
+  } else {
+    console.log("  source ~/.openclaw/openviking.env && openclaw gateway");
+  }
+  console.log("\nTo verify:");
+  console.log("  openclaw status");
+  console.log("");
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/install.js

@@ -0,0 +1,502 @@
+#!/usr/bin/env node
+/**
+ * OpenClaw + OpenViking cross-platform installer
+ * Usage: node install.js [ -y | --yes ] [ --zh ]
+ * Or: npx openclaw-openviking-install [ -y ] [ --zh ]
+ *
+ * Environment variables (see install.sh / install.ps1):
+ *   REPO, BRANCH, OPENVIKING_INSTALL_YES, SKIP_OPENCLAW, SKIP_OPENVIKING
+ *   OPENVIKING_VERSION       Pip install openviking==VERSION (omit for latest)
+ *   NPM_REGISTRY, PIP_INDEX_URL
+ *   OPENVIKING_VLM_API_KEY, OPENVIKING_EMBEDDING_API_KEY, OPENVIKING_ARK_API_KEY
+ *   OPENVIKING_ALLOW_BREAK_SYSTEM_PACKAGES (Linux), GET_PIP_URL
+ */
+
+import { spawn } from "node:child_process";
+import { mkdir, writeFile, readFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const REPO = process.env.REPO || "volcengine/OpenViking";
+const BRANCH = process.env.BRANCH || "main";
+const GH_RAW = `https://raw.githubusercontent.com/${REPO}/${BRANCH}`;
+const NPM_REGISTRY = process.env.NPM_REGISTRY || "https://registry.npmmirror.com";
+const PIP_INDEX_URL = process.env.PIP_INDEX_URL || "https://pypi.tuna.tsinghua.edu.cn/simple";
+
+const IS_WIN = process.platform === "win32";
+const HOME = process.env.HOME || process.env.USERPROFILE || "";
+const OPENCLAW_DIR = join(HOME, ".openclaw");
+const OPENVIKING_DIR = join(HOME, ".openviking");
+const PLUGIN_DEST = join(OPENCLAW_DIR, "extensions", "memory-openviking");
+
+const DEFAULT_SERVER_PORT = 1933;
+const DEFAULT_AGFS_PORT = 1833;
+const DEFAULT_VLM_MODEL = "doubao-seed-2-0-pro-260215";
+const DEFAULT_EMBED_MODEL = "doubao-embedding-vision-250615";
+
+const PLUGIN_FILES = [
+  "examples/openclaw-memory-plugin/index.ts",
+  "examples/openclaw-memory-plugin/config.ts",
+  "examples/openclaw-memory-plugin/openclaw.plugin.json",
+  "examples/openclaw-memory-plugin/package.json",
+  "examples/openclaw-memory-plugin/package-lock.json",
+  "examples/openclaw-memory-plugin/.gitignore",
+];
+
+let installYes = process.env.OPENVIKING_INSTALL_YES === "1";
+let langZh = false;
+let openvikingVersion = process.env.OPENVIKING_VERSION || "";
+for (const a of process.argv.slice(2)) {
+  if (a === "-y" || a === "--yes") installYes = true;
+  if (a === "--zh") langZh = true;
+  if (a === "-h" || a === "--help") {
+    console.log("Usage: node install.js [ -y | --yes ] [ --zh ] [ --openviking-version=VERSION ]");
+    console.log("");
+    console.log("  -y, --yes   Non-interactive (use defaults)");
+    console.log("  --zh       Chinese prompts");
+    console.log("  --openviking-version=VERSION   Pip install openviking==VERSION (default: latest)");
+    console.log("  -h, --help  This help");
+    console.log("");
+    console.log("Env: REPO, BRANCH, SKIP_OPENCLAW, SKIP_OPENVIKING, OPENVIKING_VERSION, NPM_REGISTRY, PIP_INDEX_URL");
+    process.exit(0);
+  }
+  if (a.startsWith("--openviking-version=")) {
+    openvikingVersion = a.slice("--openviking-version=".length).trim();
+  }
+}
+const OPENVIKING_PIP_SPEC = openvikingVersion ? `openviking==${openvikingVersion}` : "openviking";
+
+function tr(en, zh) {
+  return langZh ? zh : en;
+}
+
+function info(msg) {
+  console.log(`[INFO] ${msg}`);
+}
+function warn(msg) {
+  console.log(`[WARN] ${msg}`);
+}
+function err(msg) {
+  console.log(`[ERROR] ${msg}`);
+}
+function bold(msg) {
+  console.log(msg);
+}
+
+function run(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const p = spawn(cmd, args, {
+      stdio: opts.silent ? "pipe" : "inherit",
+      shell: opts.shell ?? true,
+      ...opts,
+    });
+    p.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`exit ${code}`))));
+  });
+}
+
+function runCapture(cmd, args, opts = {}) {
+  return new Promise((resolve) => {
+    const p = spawn(cmd, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: opts.shell ?? false,
+      ...opts,
+    });
+    let out = "";
+    let errOut = "";
+    p.stdout?.on("data", (d) => (out += d));
+    p.stderr?.on("data", (d) => (errOut += d));
+    p.on("error", (e) => resolve({ code: -1, out: "", err: String(e) }));
+    p.on("close", (code) => resolve({ code, out: out.trim(), err: errOut.trim() }));
+  });
+}
+
+function question(prompt, defaultValue = "") {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const def = defaultValue ? ` [${defaultValue}]` : "";
+  return new Promise((resolve) => {
+    rl.question(`${prompt}${def}: `, (answer) => {
+      rl.close();
+      resolve((answer ?? defaultValue).trim() || defaultValue);
+    });
+  });
+}
+
+async function checkPython() {
+  const py = process.env.OPENVIKING_PYTHON || (IS_WIN ? "python" : "python3");
+  const r = await runCapture(py, ["-c", "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')"]);
+  if (r.code !== 0 || !r.out) {
+    return { ok: false, detail: tr("Python not found or failed. Install Python >= 3.10.", "Python 未找到或执行失败，请安装 Python >= 3.10"), cmd: py };
+  }
+  const [major, minor] = r.out.split(".").map(Number);
+  if (major < 3 || (major === 3 && minor < 10)) {
+    return { ok: false, detail: tr(`Python ${r.out} is too old. Need >= 3.10.`, `Python ${r.out} 版本过低，需要 >= 3.10`), cmd: py };
+  }
+  return { ok: true, detail: r.out, cmd: py };
+}
+
+async function checkNode() {
+  const r = await runCapture("node", ["-v"]);
+  if (r.code !== 0 || !r.out) {
+    return { ok: false, detail: tr("Node.js not found. Install Node.js >= 22.", "Node.js 未找到，请安装 Node.js >= 22") };
+  }
+  const v = r.out.replace(/^v/, "").split(".")[0];
+  const major = parseInt(v, 10);
+  if (isNaN(major) || major < 22) {
+    return { ok: false, detail: tr(`Node.js ${r.out} is too old. Need >= 22.`, `Node.js ${r.out} 版本过低，需要 >= 22`) };
+  }
+  return { ok: true, detail: r.out };
+}
+
+async function validateEnvironment() {
+  info(tr("Checking OpenViking runtime environment...", "正在校验 OpenViking 运行环境..."));
+  console.log("");
+
+  const missing = [];
+  const py = await checkPython();
+  if (py.ok) {
+    info(`  Python: ${py.detail} ✓`);
+  } else {
+    missing.push(`Python 3.10+ | ${py.detail}`);
+  }
+
+  const node = await checkNode();
+  if (node.ok) {
+    info(`  Node.js: ${node.detail} ✓`);
+  } else {
+    missing.push(`Node.js 22+ | ${node.detail}`);
+  }
+
+  if (missing.length > 0) {
+    console.log("");
+    err(tr("Environment check failed. Install missing dependencies first.", "环境校验未通过，请先安装以下缺失组件。"));
+    console.log("");
+    if (missing.some((m) => m.startsWith("Python"))) {
+      console.log(tr("Python (example):", "Python（示例）："));
+      if (IS_WIN) console.log("  winget install --id Python.Python.3.11 -e");
+      else console.log("  pyenv install 3.11.12 && pyenv global 3.11.12");
+      console.log("");
+    }
+    if (missing.some((m) => m.startsWith("Node"))) {
+      console.log(tr("Node.js (example):", "Node.js（示例）："));
+      if (IS_WIN) console.log("  nvm install 22.22.0 && nvm use 22.22.0");
+      else console.log("  nvm install 22 && nvm use 22");
+      console.log("");
+    }
+    process.exit(1);
+  }
+  console.log("");
+  info(tr("Environment check passed ✓", "环境校验通过 ✓"));
+  console.log("");
+}
+
+async function checkOpenClaw() {
+  if (process.env.SKIP_OPENCLAW === "1") {
+    info(tr("Skipping OpenClaw check (SKIP_OPENCLAW=1)", "跳过 OpenClaw 校验 (SKIP_OPENCLAW=1)"));
+    return;
+  }
+  info(tr("Checking OpenClaw...", "正在校验 OpenClaw..."));
+  const r = await runCapture("openclaw", ["--version"]);
+  if (r.code === 0) {
+    info(tr("OpenClaw detected ✓", "OpenClaw 已安装 ✓"));
+    return;
+  }
+  err(tr("OpenClaw not found. Install it manually, then rerun this script.", "未检测到 OpenClaw，请先手动安装后再执行本脚本"));
+  console.log("");
+  console.log(tr("Recommended command:", "推荐命令："));
+  console.log(`  npm install -g openclaw --registry ${NPM_REGISTRY}`);
+  console.log("");
+  console.log("  openclaw --version");
+  console.log("  openclaw onboard");
+  console.log("");
+  process.exit(1);
+}
+
+let openvikingPythonPath = "";
+
+async function installOpenViking() {
+  if (process.env.SKIP_OPENVIKING === "1") {
+    info(tr("Skipping OpenViking install (SKIP_OPENVIKING=1)", "跳过 OpenViking 安装 (SKIP_OPENVIKING=1)"));
+    return;
+  }
+
+  const py = (await checkPython()).cmd;
+  if (!py) {
+    err(tr("Python check failed.", "Python 校验失败"));
+    process.exit(1);
+  }
+
+  info(tr("Installing OpenViking from PyPI...", "正在安装 OpenViking (PyPI)..."));
+  if (openvikingVersion) {
+    info(tr(`Requested version: openviking==${openvikingVersion}`, `指定版本: openviking==${openvikingVersion}`));
+  } else {
+    info(tr("Requested version: latest", "指定版本: 最新"));
+  }
+  info(tr(`Using pip index: ${PIP_INDEX_URL}`, `使用 pip 镜像源: ${PIP_INDEX_URL}`));
+
+  try {
+    await run(py, ["-m", "pip", "install", "--upgrade", "pip", "-q", "-i", PIP_INDEX_URL], { silent: true });
+    await run(py, ["-m", "pip", "install", OPENVIKING_PIP_SPEC, "-i", PIP_INDEX_URL]);
+    openvikingPythonPath = py;
+    info(tr("OpenViking installed ✓", "OpenViking 安装完成 ✓"));
+    return;
+  } catch (e) {
+    // On Linux: PEP 668 externally-managed-environment → try venv
+    if (!IS_WIN && (String(e).includes("externally") || String(e).includes("No module named pip"))) {
+      const venvDir = join(OPENVIKING_DIR, "venv");
+      const venvPy = IS_WIN ? join(venvDir, "Scripts", "python.exe") : join(venvDir, "bin", "python");
+      if (existsSync(venvPy)) {
+        try {
+          await run(venvPy, ["-c", "import openviking"]);
+          await run(venvPy, ["-m", "pip", "install", "-q", "-U", OPENVIKING_PIP_SPEC, "-i", PIP_INDEX_URL], { silent: true });
+          openvikingPythonPath = venvPy;
+          info(tr("OpenViking installed ✓ (venv)", "OpenViking 安装完成 ✓（虚拟环境）"));
+          return;
+        } catch (_) {}
+      }
+      await mkdir(OPENVIKING_DIR, { recursive: true });
+      try {
+        await run(py, ["-m", "venv", venvDir]);
+      } catch (_) {
+        err(tr("Could not create venv. Install python3-venv or use OPENVIKING_ALLOW_BREAK_SYSTEM_PACKAGES=1", "无法创建虚拟环境，请安装 python3-venv 或设置 OPENVIKING_ALLOW_BREAK_SYSTEM_PACKAGES=1"));
+        process.exit(1);
+      }
+      await run(venvPy, ["-m", "pip", "install", "--upgrade", "pip", "-q", "-i", PIP_INDEX_URL], { silent: true });
+      await run(venvPy, ["-m", "pip", "install", OPENVIKING_PIP_SPEC, "-i", PIP_INDEX_URL]);
+      openvikingPythonPath = venvPy;
+      info(tr("OpenViking installed ✓ (venv)", "OpenViking 安装完成 ✓（虚拟环境）"));
+      return;
+    }
+    if (process.env.OPENVIKING_ALLOW_BREAK_SYSTEM_PACKAGES === "1") {
+      try {
+        await run(py, ["-m", "pip", "install", "--break-system-packages", OPENVIKING_PIP_SPEC, "-i", PIP_INDEX_URL]);
+        openvikingPythonPath = py;
+        info(tr("OpenViking installed ✓ (system)", "OpenViking 安装完成 ✓（系统）"));
+        return;
+      } catch (_) {}
+    }
+    err(tr("OpenViking install failed. Check Python >= 3.10 and pip.", "OpenViking 安装失败，请检查 Python >= 3.10 及 pip"));
+    throw e;
+  }
+}
+
+let selectedServerPort = DEFAULT_SERVER_PORT;
+
+async function configureOvConf() {
+  await mkdir(OPENVIKING_DIR, { recursive: true });
+  let workspace = join(OPENVIKING_DIR, "data");
+  let serverPort = String(DEFAULT_SERVER_PORT);
+  let agfsPort = String(DEFAULT_AGFS_PORT);
+  let vlmModel = DEFAULT_VLM_MODEL;
+  let embeddingModel = DEFAULT_EMBED_MODEL;
+  let vlmApiKey = process.env.OPENVIKING_VLM_API_KEY || process.env.OPENVIKING_ARK_API_KEY || "";
+  let embeddingApiKey = process.env.OPENVIKING_EMBEDDING_API_KEY || process.env.OPENVIKING_ARK_API_KEY || "";
+
+  if (!installYes) {
+    console.log("");
+    workspace = await question(tr("OpenViking workspace path", "OpenViking 数据目录"), workspace);
+    serverPort = await question(tr("OpenViking HTTP port", "OpenViking HTTP 端口"), serverPort);
+    agfsPort = await question(tr("AGFS port", "AGFS 端口"), agfsPort);
+    vlmModel = await question(tr("VLM model", "VLM 模型"), vlmModel);
+    embeddingModel = await question(tr("Embedding model", "Embedding 模型"), embeddingModel);
+    console.log(tr("VLM and Embedding API keys can differ. Leave empty to edit ov.conf later.", "说明：VLM 与 Embedding 的 API Key 可分别填写，留空可稍后在 ov.conf 修改。"));
+    const vlmInput = await question(tr("VLM API key (optional)", "VLM API Key（可留空）"), "");
+    const embInput = await question(tr("Embedding API key (optional)", "Embedding API Key（可留空）"), "");
+    if (vlmInput) vlmApiKey = vlmInput;
+    if (embInput) embeddingApiKey = embInput;
+  }
+
+  selectedServerPort = parseInt(serverPort, 10) || DEFAULT_SERVER_PORT;
+  const agfsPortNum = parseInt(agfsPort, 10) || DEFAULT_AGFS_PORT;
+  await mkdir(workspace, { recursive: true });
+
+  const cfg = {
+    server: {
+      host: "127.0.0.1",
+      port: selectedServerPort,
+      root_api_key: null,
+      cors_origins: ["*"],
+    },
+    storage: {
+      workspace,
+      vectordb: { name: "context", backend: "local", project: "default" },
+      agfs: { port: agfsPortNum, log_level: "warn", backend: "local", timeout: 10, retry_times: 3 },
+    },
+    embedding: {
+      dense: {
+        backend: "volcengine",
+        api_key: embeddingApiKey || null,
+        model: embeddingModel,
+        api_base: "https://ark.cn-beijing.volces.com/api/v3",
+        dimension: 1024,
+        input: "multimodal",
+      },
+    },
+    vlm: {
+      backend: "volcengine",
+      api_key: vlmApiKey || null,
+      model: vlmModel,
+      api_base: "https://ark.cn-beijing.volces.com/api/v3",
+      temperature: 0.1,
+      max_retries: 3,
+    },
+  };
+
+  const confPath = join(OPENVIKING_DIR, "ov.conf");
+  await writeFile(confPath, JSON.stringify(cfg, null, 2), "utf8");
+  info(tr(`Config generated: ${confPath}`, `已生成配置: ${confPath}`));
+}
+
+async function downloadPlugin() {
+  await mkdir(PLUGIN_DEST, { recursive: true });
+  info(tr(`Downloading memory-openviking plugin from ${REPO}@${BRANCH}...`, `正在从 ${REPO}@${BRANCH} 下载 memory-openviking 插件...`));
+  const maxRetries = 3;
+  for (let i = 0; i < PLUGIN_FILES.length; i++) {
+    const rel = PLUGIN_FILES[i];
+    const name = rel.split("/").pop();
+    process.stdout.write(`  [${i + 1}/${PLUGIN_FILES.length}] ${name} `);
+    const url = `${GH_RAW}/${rel}`;
+    let ok = false;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        const res = await fetch(url);
+        if (res.ok) {
+          const buf = await res.arrayBuffer();
+          await writeFile(join(PLUGIN_DEST, name), Buffer.from(buf), "utf8");
+          ok = true;
+          break;
+        }
+      } catch (_) {}
+      if (attempt < maxRetries) await new Promise((r) => setTimeout(r, 2000));
+    }
+    if (ok) {
+      console.log("✓");
+    } else if (name === ".gitignore") {
+      console.log(tr("(retries failed, using minimal .gitignore)", "（重试失败，使用最小 .gitignore）"));
+      await writeFile(join(PLUGIN_DEST, name), "node_modules/\n", "utf8");
+    } else {
+      console.log("");
+      err(tr(`Download failed after ${maxRetries} retries: ${url}`, `下载失败（已重试 ${maxRetries} 次）: ${url}`));
+      process.exit(1);
+    }
+  }
+  info(tr("Installing plugin npm dependencies...", "正在安装插件 npm 依赖..."));
+  try {
+    await run("npm", ["install", "--no-audit", "--no-fund"], { cwd: PLUGIN_DEST, silent: false });
+  } catch (e) {
+    err(tr(`Plugin dependency install failed: ${PLUGIN_DEST}`, `插件依赖安装失败: ${PLUGIN_DEST}`));
+    throw e;
+  }
+  info(tr(`Plugin deployed: ${PLUGIN_DEST}`, `插件部署完成: ${PLUGIN_DEST}`));
+}
+
+async function configureOpenClawPlugin() {
+  info(tr("Configuring OpenClaw plugin...", "正在配置 OpenClaw 插件..."));
+  const cfgPath = join(OPENCLAW_DIR, "openclaw.json");
+  let cfg = {};
+  if (existsSync(cfgPath)) {
+    try {
+      const raw = await readFile(cfgPath, "utf8");
+      if (raw.trim()) cfg = JSON.parse(raw);
+    } catch (_) {
+      warn(tr("Existing openclaw.json invalid. Rebuilding required sections.", "已有 openclaw.json 非法，将重建相关配置节点。"));
+    }
+  }
+
+  if (!cfg.plugins) cfg.plugins = {};
+  if (!cfg.gateway) cfg.gateway = {};
+  if (!cfg.plugins.slots) cfg.plugins.slots = {};
+  if (!cfg.plugins.load) cfg.plugins.load = {};
+  if (!cfg.plugins.entries) cfg.plugins.entries = {};
+
+  const existingPaths = Array.isArray(cfg.plugins.load.paths) ? cfg.plugins.load.paths : [];
+  const mergedPaths = [...new Set([...existingPaths, PLUGIN_DEST])];
+  const ovConfPath = join(OPENVIKING_DIR, "ov.conf");
+
+  cfg.plugins.enabled = true;
+  cfg.plugins.allow = ["memory-openviking"];
+  cfg.plugins.slots.memory = "memory-openviking";
+  cfg.plugins.load.paths = mergedPaths;
+  cfg.plugins.entries["memory-openviking"] = {
+    config: {
+      mode: "local",
+      configPath: ovConfPath,
+      port: selectedServerPort,
+      targetUri: "viking://user/memories",
+      autoRecall: true,
+      autoCapture: true,
+    },
+  };
+  cfg.gateway.mode = "local";
+
+  await mkdir(OPENCLAW_DIR, { recursive: true });
+  await writeFile(cfgPath, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+  info(tr("OpenClaw plugin configured", "OpenClaw 插件配置完成"));
+}
+
+async function writeOpenvikingEnv() {
+  let pyPath = openvikingPythonPath;
+  if (!pyPath) {
+    const py = (await checkPython()).cmd;
+    if (IS_WIN) {
+      const r = await runCapture("where", [py], { shell: true });
+      pyPath = r.out.split(/\r?\n/)[0]?.trim() || py;
+    } else {
+      const r = await runCapture("which", [py]);
+      pyPath = r.out.trim() || py;
+    }
+  }
+  await mkdir(OPENCLAW_DIR, { recursive: true });
+  const envContent = IS_WIN
+    ? `@echo off\nset "OPENVIKING_PYTHON=${pyPath.replace(/"/g, '""')}"`
+    : `export OPENVIKING_PYTHON='${pyPath.replace(/'/g, "'\"'\"'")}'`;
+  const envFile = IS_WIN ? join(OPENCLAW_DIR, "openviking.env.bat") : join(OPENCLAW_DIR, "openviking.env");
+  await writeFile(envFile, envContent + "\n", "utf8");
+  if (IS_WIN) {
+    const ps1Path = join(OPENCLAW_DIR, "openviking.env.ps1");
+    await writeFile(ps1Path, `$env:OPENVIKING_PYTHON = "${String(pyPath).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"\n`, "utf8");
+    info(tr(`Environment file generated: ${ps1Path}`, `已生成环境文件: ${ps1Path}`));
+  } else {
+    info(tr(`Environment file generated: ${envFile}`, `已生成环境文件: ${envFile}`));
+  }
+}
+
+async function main() {
+  console.log("");
+  bold(tr("🦣 OpenClaw + OpenViking Installer", "🦣 OpenClaw + OpenViking 一键安装"));
+  console.log("");
+
+  await validateEnvironment();
+  await checkOpenClaw();
+  await installOpenViking();
+  await configureOvConf();
+  await downloadPlugin();
+  await configureOpenClawPlugin();
+  await writeOpenvikingEnv();
+
+  console.log("");
+  bold("═══════════════════════════════════════════════════════════");
+  bold("  " + tr("Installation complete!", "安装完成！"));
+  bold("═══════════════════════════════════════════════════════════");
+  console.log("");
+  info(tr("Run these commands to start OpenClaw + OpenViking:", "请按以下命令启动 OpenClaw + OpenViking："));
+  console.log("  1) openclaw --version");
+  console.log("  2) openclaw onboard");
+  if (IS_WIN) {
+    console.log('  3) call "%USERPROFILE%\\.openclaw\\openviking.env.bat" && openclaw gateway');
+  } else {
+    console.log("  3) source ~/.openclaw/openviking.env && openclaw gateway");
+  }
+  console.log("  4) openclaw status");
+  console.log("");
+  info(tr(`You can edit the config freely: ${OPENVIKING_DIR}/ov.conf`, `你可以按需自由修改配置文件: ${OPENVIKING_DIR}/ov.conf`));
+  console.log("");
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "openclaw-openviking-setup-helper",
+  "version": "0.1.0",
+  "description": "Setup helper for installing OpenViking memory plugin into OpenClaw",
+  "type": "module",
+  "bin": {
+    "openclaw-openviking-setup-helper": "cli.js",
+    "openclaw-openviking-install": "install.js"
+  },
+  "keywords": [
+    "openviking",
+    "openclaw",
+    "setup",
+    "memory",
+    "agent",
+    "installer"
+  ],
+  "author": "OpenViking",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OpenViking/OpenViking.git",
+    "directory": "examples/openclaw-memory-plugin/setup-helper"
+  },
+  "files": [
+    "cli.js",
+    "install.js"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}