@carfiedli/runtime-guardrail 0.1.19

package/scripts/runtime-guardrailctl.mjs

@@ -0,0 +1,864 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { spawnSync } from "node:child_process";
+import JSON5 from "json5";
+
+const DEFAULT_PLUGIN_ID = "runtime-guardrail";
+const DEFAULT_PLUGIN_SPEC = "@tencent/runtime-guardrail";
+const DEFAULT_AUTH_FILE_NAME = "remote-guard-auth.json";
+const API_KEY_ENV_NAME = "RUNTIME_GUARDRAIL_API_KEY";
+const DEFAULT_OPENCLAW_STATE_DIR = path.join(os.homedir(), ".openclaw");
+
+function printHelp() {
+  console.log(`runtime-guardrailctl
+
+Usage:
+  runtime-guardrailctl install [options]
+  runtime-guardrailctl update [options]
+  runtime-guardrailctl set-api-key [options]
+  runtime-guardrailctl reload [options]
+  runtime-guardrailctl sync [options]      # reload 的兼容别名
+
+Options:
+  --plugin-spec <spec>      插件 npm spec，默认 ${DEFAULT_PLUGIN_SPEC}
+  --plugin-id <id>          插件 id，默认 ${DEFAULT_PLUGIN_ID}
+  --config-path <path>      自定义 remote-guard-config.json 路径（高级覆盖项）
+  --api-key <key>           直接设置 AI Guardrails 平台 API Key（注意避免 shell 历史泄露）
+  --openclaw-bin <bin>      OpenClaw 可执行文件名/路径，默认 openclaw
+  --global                  忽略 OPENCLAW_STATE_DIR / OPENCLAW_CONFIG_PATH，强制写入 ~/.openclaw
+  --state-dir <dir>         显式指定 OpenClaw state dir（优先级高于环境变量）
+  --no-restart              完成后不自动执行 gateway restart
+  -h, --help                查看帮助
+`);
+}
+
+function fail(message, exitCode = 1) {
+  console.error(`[runtime-guardrailctl] ${message}`);
+  process.exit(exitCode);
+}
+
+function resolveUserPath(input) {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return trimmed;
+  }
+  if (trimmed === "~") {
+    return os.homedir();
+  }
+  if (trimmed.startsWith("~/")) {
+    return path.join(os.homedir(), trimmed.slice(2));
+  }
+  return path.resolve(trimmed);
+}
+
+function resolveOpenClawStateDir(options = {}) {
+  if (options.global === true) {
+    return DEFAULT_OPENCLAW_STATE_DIR;
+  }
+
+  if (options.stateDir?.trim()) {
+    return resolveUserPath(options.stateDir);
+  }
+
+  const override = process.env.OPENCLAW_STATE_DIR?.trim();
+  return resolveUserPath(override || DEFAULT_OPENCLAW_STATE_DIR);
+}
+
+function resolveOpenClawConfigPath(options = {}, resolvedStateDir = resolveOpenClawStateDir(options)) {
+  if (options.global === true || options.stateDir?.trim()) {
+    return path.join(resolvedStateDir, "openclaw.json");
+  }
+
+  const override = process.env.OPENCLAW_CONFIG_PATH?.trim();
+  if (override) {
+    return resolveUserPath(override);
+  }
+  return path.join(resolvedStateDir, "openclaw.json");
+}
+
+function resolveManagedConfigPath(explicitPath) {
+  if (!explicitPath?.trim()) {
+    return undefined;
+  }
+  return resolveUserPath(explicitPath);
+}
+
+function resolveAuthConfigPath(pluginId, resolvedStateDir) {
+  return path.join(resolvedStateDir, pluginId, DEFAULT_AUTH_FILE_NAME);
+}
+
+function buildOpenClawCommandEnv(options, resolvedStateDir, openclawConfigPath) {
+  const nextEnv = { ...process.env };
+
+  if (options.global === true || options.stateDir?.trim()) {
+    nextEnv.OPENCLAW_STATE_DIR = resolvedStateDir;
+    nextEnv.OPENCLAW_CONFIG_PATH = openclawConfigPath;
+  }
+
+  return nextEnv;
+}
+
+function readConfigFile(configPath) {
+  if (!fs.existsSync(configPath)) {
+    return {};
+  }
+  const raw = fs.readFileSync(configPath, "utf-8");
+  if (!raw.trim()) {
+    return {};
+  }
+  return JSON5.parse(raw);
+}
+
+function writeJsonFile(targetPath, payload, options = {}) {
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(targetPath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+  if (typeof options.mode === "number") {
+    try {
+      fs.chmodSync(targetPath, options.mode);
+    } catch {
+      // best effort on cross-platform environments
+    }
+  }
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  const command = args.shift();
+  if (!command || command === "-h" || command === "--help" || command === "help") {
+    return { command: "help", options: {} };
+  }
+
+  const options = {
+    pluginSpec: DEFAULT_PLUGIN_SPEC,
+    pluginSpecExplicit: false,
+    pluginId: DEFAULT_PLUGIN_ID,
+    openclawBin: "openclaw",
+    restart: true,
+    global: false,
+  };
+
+  while (args.length > 0) {
+    const token = args.shift();
+    switch (token) {
+      case "--plugin-spec":
+        options.pluginSpec = args.shift() || fail("--plugin-spec 需要值");
+        options.pluginSpecExplicit = true;
+        break;
+      case "--plugin-id":
+        options.pluginId = args.shift() || fail("--plugin-id 需要值");
+        break;
+      case "--config-path":
+        options.configPath = args.shift() || fail("--config-path 需要值");
+        break;
+      case "--api-key":
+        options.apiKey = args.shift() || fail("--api-key 需要值");
+        break;
+      case "--openclaw-bin":
+        options.openclawBin = args.shift() || fail("--openclaw-bin 需要值");
+        break;
+      case "--global":
+        options.global = true;
+        break;
+      case "--state-dir":
+        options.stateDir = args.shift() || fail("--state-dir 需要值");
+        break;
+      case "--no-restart":
+        options.restart = false;
+        break;
+      case "-h":
+      case "--help":
+        return { command: "help", options };
+      default:
+        fail(`未知参数: ${token}`);
+    }
+  }
+
+  if (options.global && options.stateDir?.trim()) {
+    fail("--global 和 --state-dir 不能同时使用");
+  }
+
+  return { command, options };
+}
+
+function ensurePluginAllowed(config, pluginId) {
+  const next = typeof config === "object" && config !== null ? { ...config } : {};
+  next.plugins = typeof next.plugins === "object" && next.plugins !== null ? { ...next.plugins } : {};
+  next.plugins.allow = Array.isArray(next.plugins.allow) ? [...next.plugins.allow] : [];
+  if (!next.plugins.allow.includes(pluginId)) {
+    next.plugins.allow.push(pluginId);
+  }
+  return next;
+}
+
+function ensurePluginEntry(config, params) {
+  const next = ensurePluginAllowed(config, params.pluginId);
+  next.plugins.entries =
+    typeof next.plugins.entries === "object" && next.plugins.entries !== null
+      ? { ...next.plugins.entries }
+      : {};
+
+  const entry =
+    typeof next.plugins.entries[params.pluginId] === "object" && next.plugins.entries[params.pluginId] !== null
+      ? { ...next.plugins.entries[params.pluginId] }
+      : {};
+
+  entry.enabled = true;
+  const currentConfig = typeof entry.config === "object" && entry.config !== null ? { ...entry.config } : {};
+  if (params.configPath) {
+    currentConfig.remoteGuard = {
+      ...(typeof currentConfig.remoteGuard === "object" && currentConfig.remoteGuard !== null
+        ? currentConfig.remoteGuard
+        : {}),
+      configPath: params.configPath,
+    };
+  } else {
+    delete currentConfig.remoteGuard;
+  }
+  delete currentConfig.configSync;
+  entry.config = currentConfig;
+
+  if (typeof entry.options === "object" && entry.options !== null) {
+    const nextOptions = { ...entry.options };
+    delete nextOptions.remoteGuard;
+    delete nextOptions.configSync;
+    entry.options = nextOptions;
+  }
+
+  next.plugins.entries[params.pluginId] = entry;
+  return next;
+}
+
+function resolveManagedPluginInstallPath(pluginId, resolvedStateDir) {
+  return path.join(resolvedStateDir, "extensions", pluginId);
+}
+
+function readJsonFileIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return undefined;
+  }
+
+  try {
+    const raw = fs.readFileSync(filePath, "utf-8");
+    if (!raw.trim()) {
+      return undefined;
+    }
+    return JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+function readInstalledPluginVersion(pluginId, resolvedStateDir) {
+  const installPath = resolveManagedPluginInstallPath(pluginId, resolvedStateDir);
+  const packageJson = readJsonFileIfExists(path.join(installPath, "package.json"));
+  if (typeof packageJson?.version === "string" && packageJson.version.trim()) {
+    return packageJson.version.trim();
+  }
+
+  const manifest = readJsonFileIfExists(path.join(installPath, "openclaw.plugin.json"));
+  if (typeof manifest?.version === "string" && manifest.version.trim()) {
+    return manifest.version.trim();
+  }
+
+  return undefined;
+}
+
+function ensurePluginTrackedInstallRecord(config, params) {
+  const next = ensurePluginEntry(config, params);
+  next.plugins.installs =
+    typeof next.plugins.installs === "object" && next.plugins.installs !== null
+      ? { ...next.plugins.installs }
+      : {};
+
+  const installedVersion = readInstalledPluginVersion(params.pluginId, params.resolvedStateDir);
+
+  next.plugins.installs[params.pluginId] = {
+    ...(typeof installedVersion === "string" && installedVersion ? { version: installedVersion } : {}),
+    installedAt: new Date().toISOString(),
+    source: "npm",
+    spec: params.pluginSpec,
+    installPath: resolveManagedPluginInstallPath(params.pluginId, params.resolvedStateDir),
+  };
+
+  return next;
+}
+
+function removeManagedPluginInstallDir(pluginId, resolvedStateDir) {
+  const installPath = resolveManagedPluginInstallPath(pluginId, resolvedStateDir);
+  if (!fs.existsSync(installPath)) {
+    return;
+  }
+
+  fs.rmSync(installPath, { recursive: true, force: true });
+  console.log(`[runtime-guardrailctl] 已移除插件目录 ${installPath}`);
+}
+
+function uninstallPluginForReinstall(params) {
+  const uninstallResult = runCommand(
+    params.openclawBin,
+    ["plugins", "uninstall", params.pluginId, "--force"],
+    { captureOutput: true, echoOutput: false, env: params.openclawCommandEnv },
+  );
+  if (uninstallResult.error) {
+    fail(`执行 ${params.openclawBin} plugins uninstall ${params.pluginId} 失败：${uninstallResult.error.message}`);
+  }
+
+  if ((uninstallResult.status ?? 1) === 0) {
+    echoCapturedOutput(uninstallResult);
+    return;
+  }
+
+  console.warn(
+    `[runtime-guardrailctl] 卸载旧版本返回非 0，将继续按目录重装方式更新 ${params.pluginId}。`,
+  );
+  echoCapturedOutput(uninstallResult);
+}
+
+function readPluginEntry(config, pluginId) {
+  return config?.plugins?.entries?.[pluginId] ?? {};
+}
+
+function readStoredApiKey(authConfigPath) {
+  if (!fs.existsSync(authConfigPath)) {
+    return undefined;
+  }
+  try {
+    const raw = fs.readFileSync(authConfigPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed?.auth?.key === "string" && parsed.auth.key.trim()) {
+      return parsed.auth.key.trim();
+    }
+    if (typeof parsed?.key === "string" && parsed.key.trim()) {
+      return parsed.key.trim();
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+function maskApiKey(apiKey) {
+  if (!apiKey) {
+    return "<empty>";
+  }
+  if (apiKey.length <= 8) {
+    return `${apiKey.slice(0, 2)}***${apiKey.slice(-1)}`;
+  }
+  return `${apiKey.slice(0, 4)}***${apiKey.slice(-4)}`;
+}
+
+async function promptForSecret(prompt) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    fail(`当前终端不可交互，请通过 --api-key 或环境变量 ${API_KEY_ENV_NAME} 提供 API Key。`);
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+  });
+
+  try {
+    const answer = await new Promise((resolve) => {
+      rl.question(prompt, resolve);
+    });
+    return typeof answer === "string" ? answer.trim() : "";
+  } finally {
+    rl.close();
+  }
+}
+
+async function resolveApiKey(params) {
+  const fromArg = params.apiKey?.trim();
+  if (fromArg) {
+    return fromArg;
+  }
+
+  const fromEnv = process.env[API_KEY_ENV_NAME]?.trim();
+  if (fromEnv) {
+    return fromEnv;
+  }
+
+  if (params.allowStoredValue !== false) {
+    const stored = readStoredApiKey(params.authConfigPath);
+    if (stored) {
+      return stored;
+    }
+  }
+
+  const prompted = await promptForSecret("请输入 AI Guardrails 平台 API Key: ");
+  if (!prompted) {
+    fail("API Key 不能为空。");
+  }
+  return prompted;
+}
+
+function writeApiKey(authConfigPath, apiKey) {
+  writeJsonFile(
+    authConfigPath,
+    {
+      auth: {
+        key: apiKey,
+      },
+    },
+    { mode: 0o600 },
+  );
+}
+
+function warnIfEnvApiKeyDiffers(storedApiKey) {
+  const envApiKey = process.env[API_KEY_ENV_NAME]?.trim();
+  if (!envApiKey || !storedApiKey || envApiKey === storedApiKey) {
+    return;
+  }
+
+  console.warn(
+    `[runtime-guardrailctl] 检测到环境变量 ${API_KEY_ENV_NAME} (${maskApiKey(envApiKey)}) 与本地已保存的 API Key (${maskApiKey(storedApiKey)}) 不一致；本次 install/set-api-key 会优先取环境变量并写回本地文件，但插件运行时只会读取当前 OpenClaw state dir 下的 remote-guard-auth.json。若环境变量是旧值，请先清理该环境变量后再重新执行命令。`,
+  );
+}
+
+const OPENCLAW_NPM_EXTRACT_FAILURE_RE =
+  /failed to extract archive:\s*SafeOpenError:\s*path is not a regular file under root/i;
+const OPENCLAW_PLUGIN_ALREADY_EXISTS_RE = /plugin already exists\b/i;
+
+function echoCapturedOutput(result) {
+  if (typeof result.stdout === "string" && result.stdout.length > 0) {
+    process.stdout.write(result.stdout);
+  }
+  if (typeof result.stderr === "string" && result.stderr.length > 0) {
+    process.stderr.write(result.stderr);
+  }
+}
+
+function readCombinedOutput(result) {
+  return `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+}
+
+function normalizePluginInstallResult(result, params, options = {}) {
+  if (result.error) {
+    fail(`执行 ${params.openclawBin} plugins install ${params.installTarget} 失败：${result.error.message}`);
+  }
+  if ((result.status ?? 1) === 0) {
+    echoCapturedOutput(result);
+    return { alreadyInstalled: false, needsArchiveFallback: false };
+  }
+
+  const combinedOutput = readCombinedOutput(result);
+  if (options.allowArchiveFallback && OPENCLAW_NPM_EXTRACT_FAILURE_RE.test(combinedOutput)) {
+    return { alreadyInstalled: false, needsArchiveFallback: true };
+  }
+
+  if (OPENCLAW_PLUGIN_ALREADY_EXISTS_RE.test(combinedOutput)) {
+    console.log(
+      `[runtime-guardrailctl] 检测到插件 ${params.pluginId} 已存在，将跳过重复安装并继续执行 API Key 配置。若需升级插件，请改用 update 命令。`,
+    );
+    return { alreadyInstalled: true, needsArchiveFallback: false };
+  }
+
+  echoCapturedOutput(result);
+  process.exit(result.status ?? 1);
+}
+
+function runCommand(bin, args, options = {}) {
+  const captureOutput = options.captureOutput === true;
+  const echoOutput = captureOutput && options.echoOutput !== false;
+  const baseOptions = {
+    ...(options.cwd ? { cwd: options.cwd } : {}),
+    ...(options.env ? { env: options.env } : {}),
+  };
+  const result = spawnSync(bin, args, captureOutput
+    ? { ...baseOptions, stdio: "pipe", encoding: "utf-8" }
+    : { ...baseOptions, stdio: "inherit" });
+  if (echoOutput) {
+    echoCapturedOutput(result);
+  }
+  return result;
+}
+
+function runOrFail(bin, args, options = {}) {
+  const result = runCommand(bin, args, options);
+  if (result.error) {
+    fail(`执行 ${bin} ${args.join(" ")} 失败：${result.error.message}`);
+  }
+  if ((result.status ?? 1) !== 0) {
+    process.exit(result.status ?? 1);
+  }
+  return result;
+}
+
+function tryRun(bin, args, options = {}) {
+  const result = runCommand(bin, args, options);
+  if (result.error) {
+    return false;
+  }
+  return (result.status ?? 1) === 0;
+}
+
+function parsePackedArchiveFilename(raw) {
+  const trimmed = typeof raw === "string" ? raw.trim() : "";
+  if (!trimmed) {
+    return undefined;
+  }
+  const candidates = [trimmed];
+  const arrayStart = trimmed.indexOf("[");
+  if (arrayStart > 0) {
+    candidates.push(trimmed.slice(arrayStart));
+  }
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(candidate);
+      const entries = Array.isArray(parsed) ? parsed : [parsed];
+      for (let i = entries.length - 1; i >= 0; i -= 1) {
+        const entry = entries[i];
+        const filename = entry && typeof entry === "object" ? entry.filename : undefined;
+        if (typeof filename === "string" && filename.trim()) {
+          return filename.trim();
+        }
+      }
+    } catch {
+      // ignore parse failure and fallback to directory scan
+    }
+  }
+  return undefined;
+}
+
+function findPackedArchiveInDir(dirPath) {
+  try {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    const tgz = entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".tgz"))
+      .map((entry) => entry.name)
+      .sort();
+    return tgz[0];
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveLocalPluginSpecPath(pluginSpec) {
+  const trimmed = typeof pluginSpec === "string" ? pluginSpec.trim() : "";
+  if (!trimmed) {
+    return undefined;
+  }
+
+  const normalized = trimmed.startsWith("file:") ? trimmed.slice("file:".length) : trimmed;
+  const looksLikePath =
+    normalized === "." ||
+    normalized === ".." ||
+    normalized.startsWith("./") ||
+    normalized.startsWith("../") ||
+    normalized.startsWith("~/") ||
+    normalized.startsWith("/") ||
+    normalized.endsWith(".tgz") ||
+    normalized.endsWith(".tar.gz");
+  if (!looksLikePath) {
+    return undefined;
+  }
+
+  const resolved = resolveUserPath(normalized);
+  if (!fs.existsSync(resolved)) {
+    return undefined;
+  }
+  return resolved;
+}
+
+function extractArchiveToPackageDir(archivePath, extractDir) {
+  fs.mkdirSync(extractDir, { recursive: true });
+  runOrFail("tar", ["-xzf", archivePath, "-C", extractDir], { captureOutput: true });
+
+  const packageDir = path.join(extractDir, "package");
+  if (!fs.existsSync(path.join(packageDir, "package.json"))) {
+    fail(`安装失败：解压后未找到 package/package.json（${packageDir}）。`);
+  }
+  return packageDir;
+}
+
+function installPluginFromDirectory(params, packageDir) {
+  const installResult = runCommand(
+    params.openclawBin,
+    ["plugins", "install", packageDir],
+    { captureOutput: true, echoOutput: false, env: params.openclawCommandEnv },
+  );
+  return normalizePluginInstallResult(installResult, {
+    ...params,
+    installTarget: packageDir,
+  });
+}
+
+function installPluginFromPreparedSource(params) {
+  if (process.platform === "win32") {
+    fail(
+      "当前 OpenClaw 的 tgz 安装兼容模式未在 Windows 下启用。请先手动执行 npm pack 解压，再使用 openclaw plugins install <packageDir> 安装。",
+    );
+  }
+
+  const localSpecPath = resolveLocalPluginSpecPath(params.pluginSpec);
+  if (localSpecPath) {
+    const specStat = fs.statSync(localSpecPath);
+    if (specStat.isDirectory()) {
+      return installPluginFromDirectory(params, localSpecPath);
+    }
+  }
+
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "runtime-guardrailctl-pack-"));
+  try {
+    let archivePath;
+    if (localSpecPath) {
+      const specStat = fs.statSync(localSpecPath);
+      if (!specStat.isFile()) {
+        fail(`安装失败：本地插件来源不是可用文件或目录（${localSpecPath}）。`);
+      }
+      archivePath = localSpecPath;
+      console.log("[runtime-guardrailctl] 检测到本地 tgz 包，将先解压后按目录方式安装到 OpenClaw。");
+    } else {
+      console.log("[runtime-guardrailctl] 将使用预打包目录安装方式（npm pack + 本地目录）安装插件。");
+      const packResult = runOrFail(
+        "npm",
+        ["pack", params.pluginSpec, "--ignore-scripts", "--json"],
+        { captureOutput: true, echoOutput: false, cwd: tempRoot },
+      );
+      const packedName =
+        parsePackedArchiveFilename(packResult.stdout) ?? findPackedArchiveInDir(tempRoot);
+      if (!packedName) {
+        fail("安装失败：npm pack 成功但未找到生成的 .tgz 文件。");
+      }
+
+      // npm pack --json 报告的 filename 可能带 scope 子目录（如 @tencent/runtime-guardrail-0.1.16.tgz），
+      // 但实际文件在 tempRoot 根目录下以展平命名存放（如 tencent-runtime-guardrail-0.1.16.tgz）。
+      // 因此先尝试 JSON 报告的路径，若不存在则回退到目录扫描。
+      const sourceArchivePath = path.resolve(
+        path.isAbsolute(packedName)
+          ? packedName
+          : path.join(tempRoot, packedName),
+      );
+
+      if (fs.existsSync(sourceArchivePath)) {
+        archivePath = sourceArchivePath;
+        if (path.dirname(sourceArchivePath) !== tempRoot) {
+          archivePath = path.join(tempRoot, path.basename(sourceArchivePath));
+          fs.copyFileSync(sourceArchivePath, archivePath);
+        }
+      } else {
+        // JSON 报告的路径不存在，回退到扫描 tempRoot 下的实际 .tgz 文件
+        const fallbackName = findPackedArchiveInDir(tempRoot);
+        if (!fallbackName) {
+          fail(
+            `安装失败：npm pack 输出的文件路径不存在（${sourceArchivePath}），且在临时目录中未找到 .tgz 文件。`,
+          );
+        }
+        archivePath = path.join(tempRoot, fallbackName);
+        console.log(`[runtime-guardrailctl] npm pack 报告的路径与实际文件不一致，已回退到 ${fallbackName}`);
+      }
+    }
+
+    const extractDir = path.join(tempRoot, "extract");
+    const packageDir = extractArchiveToPackageDir(archivePath, extractDir);
+    return installPluginFromDirectory(params, packageDir);
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+function installPluginWithFallback(params) {
+  const localSpecPath = resolveLocalPluginSpecPath(params.pluginSpec);
+  if (process.platform !== "win32") {
+    return installPluginFromPreparedSource(params);
+  }
+
+  if (localSpecPath && fs.statSync(localSpecPath).isDirectory()) {
+    return installPluginFromDirectory(params, localSpecPath);
+  }
+
+  const result = runCommand(
+    params.openclawBin,
+    ["plugins", "install", params.pluginSpec],
+    { captureOutput: true, echoOutput: false, env: params.openclawCommandEnv },
+  );
+  const normalizedResult = normalizePluginInstallResult(result, {
+    ...params,
+    installTarget: params.pluginSpec,
+  }, { allowArchiveFallback: true });
+  if (normalizedResult.needsArchiveFallback) {
+    return installPluginFromPreparedSource(params);
+  }
+  return normalizedResult;
+}
+
+const OPENCLAW_INSTALL_STAGE_DIR_PREFIX = ".openclaw-install-stage-";
+
+function cleanupOpenClawInstallStageDirs(resolvedStateDir) {
+  const extensionsDir = path.join(resolvedStateDir, "extensions");
+  if (!fs.existsSync(extensionsDir)) {
+    return;
+  }
+
+  try {
+    const entries = fs.readdirSync(extensionsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !entry.name.startsWith(OPENCLAW_INSTALL_STAGE_DIR_PREFIX)) {
+        continue;
+      }
+
+      const targetPath = path.join(extensionsDir, entry.name);
+      fs.rmSync(targetPath, { recursive: true, force: true });
+      console.log(`[runtime-guardrailctl] 已清理 OpenClaw 安装阶段残留目录 ${targetPath}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`[runtime-guardrailctl] 清理 OpenClaw 安装阶段残留目录失败：${message}`);
+  }
+}
+
+function refreshOrRestart(params) {
+  const refreshed = tryRun(params.openclawBin, [
+    "gateway",
+    "call",
+    "shield.config.refresh",
+    "--json",
+  ], { env: params.openclawCommandEnv });
+  if (refreshed) {
+    return;
+  }
+  if (params.restart) {
+    console.log("[runtime-guardrailctl] gateway call shield.config.refresh 未成功，将继续按 restart 策略处理。");
+    runOrFail(params.openclawBin, ["gateway", "restart"], { env: params.openclawCommandEnv });
+    return;
+  }
+  console.log("[runtime-guardrailctl] gateway call shield.config.refresh 未成功，且已按 --no-restart 跳过自动重启。");
+}
+
+async function main() {
+  const { command, options } = parseArgs(process.argv.slice(2));
+  if (command === "help") {
+    printHelp();
+    return;
+  }
+
+  const normalizedCommand = command === "sync" ? "reload" : command;
+  if (!["install", "update", "set-api-key", "reload"].includes(normalizedCommand)) {
+    fail(`不支持的命令：${command}`);
+  }
+
+  const resolvedStateDir = resolveOpenClawStateDir(options);
+  const openclawConfigPath = resolveOpenClawConfigPath(options, resolvedStateDir);
+  const existingConfig = readConfigFile(openclawConfigPath);
+  const existingEntry = readPluginEntry(existingConfig, options.pluginId);
+  const mergedOptions = {
+    ...options,
+    resolvedStateDir,
+    openclawConfigPath,
+    openclawCommandEnv: buildOpenClawCommandEnv(options, resolvedStateDir, openclawConfigPath),
+    configPath: resolveManagedConfigPath(
+      options.configPath || existingEntry?.config?.remoteGuard?.configPath,
+    ),
+    authConfigPath: resolveAuthConfigPath(options.pluginId, resolvedStateDir),
+  };
+
+  console.log(`[runtime-guardrailctl] OpenClaw state dir: ${mergedOptions.resolvedStateDir}`);
+  console.log(`[runtime-guardrailctl] OpenClaw config path: ${mergedOptions.openclawConfigPath}`);
+  console.log(
+    `[runtime-guardrailctl] OpenClaw extensions dir: ${path.join(mergedOptions.resolvedStateDir, "extensions")}`,
+  );
+
+  if (normalizedCommand === "install") {
+    const apiKey = await resolveApiKey({
+      apiKey: mergedOptions.apiKey,
+      authConfigPath: mergedOptions.authConfigPath,
+      allowStoredValue: true,
+    });
+    writeApiKey(mergedOptions.authConfigPath, apiKey);
+    console.log(
+      `[runtime-guardrailctl] API Key 已写入 ${mergedOptions.authConfigPath} (${maskApiKey(apiKey)})`,
+    );
+    warnIfEnvApiKeyDiffers(apiKey);
+
+    try {
+      installPluginWithFallback({
+        openclawBin: mergedOptions.openclawBin,
+        pluginId: mergedOptions.pluginId,
+        pluginSpec: mergedOptions.pluginSpec,
+        openclawCommandEnv: mergedOptions.openclawCommandEnv,
+      });
+    } finally {
+      cleanupOpenClawInstallStageDirs(mergedOptions.resolvedStateDir);
+    }
+
+    const installedConfig = readConfigFile(openclawConfigPath);
+    const nextConfig = ensurePluginTrackedInstallRecord(installedConfig, mergedOptions);
+    writeJsonFile(openclawConfigPath, nextConfig);
+    console.log(`[runtime-guardrailctl] OpenClaw 配置已写入 ${openclawConfigPath}`);
+
+    if (mergedOptions.restart) {
+      runOrFail(mergedOptions.openclawBin, ["gateway", "restart"], { env: mergedOptions.openclawCommandEnv });
+    }
+  } else if (normalizedCommand === "update") {
+    console.log(
+      `[runtime-guardrailctl] 将按“卸载旧版本 + 重装 ${mergedOptions.pluginSpec}”方式更新 ${mergedOptions.pluginId}。`,
+    );
+    uninstallPluginForReinstall(mergedOptions);
+    removeManagedPluginInstallDir(mergedOptions.pluginId, mergedOptions.resolvedStateDir);
+
+    try {
+      installPluginWithFallback({
+        openclawBin: mergedOptions.openclawBin,
+        pluginId: mergedOptions.pluginId,
+        pluginSpec: mergedOptions.pluginSpec,
+        openclawCommandEnv: mergedOptions.openclawCommandEnv,
+      });
+    } finally {
+      cleanupOpenClawInstallStageDirs(mergedOptions.resolvedStateDir);
+    }
+
+    const currentConfig = readConfigFile(openclawConfigPath);
+    const nextConfig = ensurePluginTrackedInstallRecord(currentConfig, mergedOptions);
+    writeJsonFile(openclawConfigPath, nextConfig);
+    console.log(
+      `[runtime-guardrailctl] 已为 ${mergedOptions.pluginId} 写入可追踪的安装记录（${mergedOptions.pluginSpec}）。`,
+    );
+    console.log(`[runtime-guardrailctl] OpenClaw 配置已写入 ${openclawConfigPath}`);
+
+    const installedVersion = readInstalledPluginVersion(mergedOptions.pluginId, mergedOptions.resolvedStateDir);
+    if (installedVersion) {
+      console.log(`[runtime-guardrailctl] 当前已安装版本：${installedVersion}`);
+    }
+
+    const existingApiKey = readStoredApiKey(mergedOptions.authConfigPath);
+    if (!existingApiKey) {
+      console.log(
+        `[runtime-guardrailctl] 尚未检测到 API Key，请执行 runtime-guardrailctl set-api-key 完成本地配置。`,
+      );
+    } else {
+      warnIfEnvApiKeyDiffers(existingApiKey);
+    }
+    if (mergedOptions.restart) {
+      runOrFail(mergedOptions.openclawBin, ["gateway", "restart"], { env: mergedOptions.openclawCommandEnv });
+    }
+  } else if (normalizedCommand === "set-api-key") {
+    const apiKey = await resolveApiKey({
+      apiKey: mergedOptions.apiKey,
+      authConfigPath: mergedOptions.authConfigPath,
+      allowStoredValue: false,
+    });
+    writeApiKey(mergedOptions.authConfigPath, apiKey);
+    console.log(
+      `[runtime-guardrailctl] API Key 已写入 ${mergedOptions.authConfigPath} (${maskApiKey(apiKey)})`,
+    );
+    warnIfEnvApiKeyDiffers(apiKey);
+    refreshOrRestart(mergedOptions);
+  } else if (normalizedCommand === "reload") {
+    refreshOrRestart(mergedOptions);
+  }
+
+  console.log(`[runtime-guardrailctl] ${normalizedCommand} 完成。`);
+  if (mergedOptions.configPath) {
+    console.log(`[runtime-guardrailctl] 自定义配置路径：${mergedOptions.configPath}`);
+  } else {
+    console.log("[runtime-guardrailctl] 当前使用插件随包发布的静态基础配置。");
+  }
+  console.log(`[runtime-guardrailctl] API Key 配置路径：${mergedOptions.authConfigPath}`);
+}
+
+await main();