tencent-claw-shield 0.1.0-beta.4

package/scripts/claw-shieldctl.mjs

@@ -0,0 +1,1663 @@
+#!/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 = "claw-shield";
+const DEFAULT_PLUGIN_SPEC = "tencent-claw-shield";
+const DEFAULT_AUTH_FILE_NAME = "remote-guard-auth.json";
+const INSTALL_REPORT_PATH = "/api/guardrails/plugin/install_report";
+const API_KEY_ENV_NAME = "RUNTIME_GUARDRAIL_API_KEY";
+const DEFAULT_OPENCLAW_STATE_DIR = path.join(os.homedir(), ".openclaw");
+
+function printHelp() {
+  console.log(`claw-shieldctl
+
+Usage:
+  claw-shieldctl install [options]
+  claw-shieldctl update [options]
+  claw-shieldctl uninstall [options]
+  claw-shieldctl bypass [options]
+  claw-shieldctl resume [options]
+  claw-shieldctl set-api-key [options]
+  claw-shieldctl set-server [options]
+  claw-shieldctl set-websocket [options]
+  claw-shieldctl set-config [options]
+  claw-shieldctl reload [options]
+  claw-shieldctl 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 历史泄露）
+  --server-address <addr>     直接设置远端 Server 地址（格式：[http|https://]ip:port，如 203.0.113.1:80 或 https://203.0.113.1:443）
+  --ws-address <addr>         直接设置 WebSocket 地址（格式：[ws|wss://]ip:port，如 203.0.113.1:8081 或 wss://203.0.113.1:8081）
+  --openclaw-bin <bin>      OpenClaw 可执行文件名/路径，默认 openclaw
+  --global                  忽略 OPENCLAW_STATE_DIR / OPENCLAW_CONFIG_PATH，强制写入 ~/.openclaw
+  --state-dir <dir>         显式指定 OpenClaw state dir（优先级高于环境变量）
+  --no-restart              完成后不自动执行 gateway restart
+  --purge                   uninstall 时同时删除认证文件（API Key）
+  -h, --help                查看帮助
+`);
+}
+
+function fail(message, exitCode = 1) {
+  console.error(`[claw-shieldctl] ${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;
+  }
+
+  // 如果 openclawBin 是绝对路径（如通过 nvm 自动定位），将其所在目录加入 PATH 最前面，
+  // 确保 openclaw 执行时能找到对应版本的 node
+  const openclawBin = options.openclawBin;
+  if (openclawBin && path.isAbsolute(openclawBin)) {
+    const binDir = path.dirname(openclawBin);
+    const currentPath = nextEnv.PATH || "";
+    if (!currentPath.split(path.delimiter).includes(binDir)) {
+      nextEnv.PATH = `${binDir}${path.delimiter}${currentPath}`;
+    }
+  }
+
+  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 "--server-address":
+        options.serverAddress = args.shift() || fail("--server-address 需要值");
+        break;
+      case "--ws-address":
+        options.wsAddress = args.shift() || fail("--ws-address 需要值");
+        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 "--purge":
+        options.purge = true;
+        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(`[claw-shieldctl] 已移除插件目录 ${installPath}`);
+}
+
+/**
+ * 从 openclaw.json 中移除插件的所有配置记录
+ */
+function removePluginFromConfig(openclawConfigPath, pluginId) {
+  const config = readJsonFileIfExists(openclawConfigPath);
+  if (!config) {
+    return;
+  }
+
+  let changed = false;
+
+  // 移除 plugins.entries 中的记录
+  if (config.plugins?.entries?.[pluginId]) {
+    delete config.plugins.entries[pluginId];
+    changed = true;
+  }
+
+  // 移除 plugins.installs 中的记录
+  if (config.plugins?.installs?.[pluginId]) {
+    delete config.plugins.installs[pluginId];
+    changed = true;
+  }
+
+  // 移除 plugins.allowed 中的记录
+  if (Array.isArray(config.plugins?.allowed)) {
+    const idx = config.plugins.allowed.indexOf(pluginId);
+    if (idx >= 0) {
+      config.plugins.allowed.splice(idx, 1);
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    writeJsonFile(openclawConfigPath, config);
+    console.log(`[claw-shieldctl] 已从 ${openclawConfigPath} 中移除 ${pluginId} 相关配置`);
+  }
+}
+
+/**
+ * 移除认证文件（API Key）
+ */
+function removeAuthConfig(authConfigPath) {
+  if (!fs.existsSync(authConfigPath)) {
+    return;
+  }
+  fs.unlinkSync(authConfigPath);
+  console.log(`[claw-shieldctl] 已移除认证文件 ${authConfigPath}`);
+
+  // 尝试清理空目录
+  const dir = path.dirname(authConfigPath);
+  try {
+    const entries = fs.readdirSync(dir);
+    if (entries.length === 0) {
+      fs.rmdirSync(dir);
+      console.log(`[claw-shieldctl] 已移除空目录 ${dir}`);
+    }
+  } catch {
+    // 忽略目录清理失败
+  }
+}
+
+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(
+    `[claw-shieldctl] 卸载旧版本返回非 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(
+    `[claw-shieldctl] 检测到环境变量 ${API_KEY_ENV_NAME} (${maskApiKey(envApiKey)}) 与本地已保存的 API Key (${maskApiKey(storedApiKey)}) 不一致；本次 install/set-api-key 会优先取环境变量并写回本地文件，但插件运行时只会读取当前 OpenClaw state dir 下的 remote-guard-auth.json。若环境变量是旧值，请先清理该环境变量后再重新执行命令。`,
+  );
+}
+
+/**
+ * 解析地址字符串，支持以下格式：
+ *   ip:port            → { protocol: "http", ip, port }
+ *   http://ip:port     → { protocol: "http", ip, port }
+ *   https://ip:port    → { protocol: "https", ip, port }
+ *   ws://ip:port       → { protocol: "ws", ip, port }
+ *   wss://ip:port      → { protocol: "wss", ip, port }
+ * @returns {{ protocol: string, ip: string, port: number }} 或 null（格式无效）
+ */
+function parseAddress(address) {
+  const trimmed = (address || "").trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  let protocol = "http";
+  let rest = trimmed;
+
+  // 提取协议前缀
+  const protoMatch = rest.match(/^(https?|wss?):\/\//i);
+  if (protoMatch) {
+    protocol = protoMatch[1].toLowerCase();
+    rest = rest.slice(protoMatch[0].length);
+  }
+
+  const lastColon = rest.lastIndexOf(":");
+  if (lastColon < 1) {
+    return null;
+  }
+  const ip = rest.slice(0, lastColon);
+  const portStr = rest.slice(lastColon + 1);
+  const port = Number(portStr);
+  if (!ip || !Number.isInteger(port) || port < 1 || port > 65535) {
+    return null;
+  }
+  return { protocol, ip, port };
+}
+
+/**
+ * 将 http/https 协议映射为 ws/wss（用于 WebSocket 地址）
+ */
+function toWsProtocol(protocol) {
+  switch (protocol) {
+    case "https":
+    case "wss":
+      return "wss";
+    case "http":
+    case "ws":
+    default:
+      return "ws";
+  }
+}
+
+/**
+ * 交互式提示用户输入地址
+ */
+async function promptForAddress(prompt, defaultValue) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return undefined;
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+  });
+
+  try {
+    const answer = await new Promise((resolve) => {
+      rl.question(prompt, resolve);
+    });
+    const trimmed = typeof answer === "string" ? answer.trim() : "";
+    return trimmed || defaultValue;
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * 解析 server 地址（从命令行参数或交互式提示）
+ */
+async function resolveServerAddress(params) {
+  if (params.serverAddress) {
+    const parsed = parseAddress(params.serverAddress);
+    if (!parsed) {
+      fail(`--server-address 格式无效，应为 [http|https://]ip:port，如 203.0.113.1:80 或 https://203.0.113.1:443`);
+    }
+    return parsed;
+  }
+
+  // 读取已存在的配置值
+  const existing = readExistingRemoteGuardConfig(params.pluginInstallPath);
+  if (params.allowStoredValue !== false && existing?.server?.ip && existing?.server?.port) {
+    return { protocol: existing.server.protocol || "http", ip: existing.server.ip, port: existing.server.port };
+  }
+
+  // 交互式提示
+  const currentProtocol = existing?.server?.protocol || "http";
+  const hint = existing?.server?.ip
+    ? ` [当前: ${currentProtocol}://${existing.server.ip}:${existing.server.port}]`
+    : "";
+  const input = await promptForAddress(
+    `请输入远端 Server 地址 ([http|https://]ip:port，如 203.0.113.1:80 或 https://203.0.113.1:443)${hint}: `,
+  );
+  if (!input) {
+    if (existing?.server?.ip && existing?.server?.port) {
+      return { protocol: currentProtocol, ip: existing.server.ip, port: existing.server.port };
+    }
+    fail("Server 地址不能为空。请通过 --server-address 或交互式输入提供。");
+  }
+  const parsed = parseAddress(input);
+  if (!parsed) {
+    fail(`Server 地址格式无效，应为 [http|https://]ip:port，如 203.0.113.1:80 或 https://203.0.113.1:443`);
+  }
+  return parsed;
+}
+
+/**
+ * 解析 websocket 地址（从命令行参数或交互式提示）
+ */
+async function resolveWebSocketAddress(params) {
+  if (params.wsAddress) {
+    const parsed = parseAddress(params.wsAddress);
+    if (!parsed) {
+      fail(`--ws-address 格式无效，应为 [ws|wss|http|https://]ip:port，如 203.0.113.1:8081 或 wss://203.0.113.1:8081`);
+    }
+    return parsed;
+  }
+
+  // 读取已存在的配置值
+  const existing = readExistingRemoteGuardConfig(params.pluginInstallPath);
+  if (params.allowStoredValue !== false && existing?.websocket?.ip && existing?.websocket?.port) {
+    return { protocol: existing.websocket.protocol || "ws", ip: existing.websocket.ip, port: existing.websocket.port };
+  }
+
+  // 交互式提示
+  const currentProtocol = existing?.websocket?.protocol || "ws";
+  const hint = existing?.websocket?.ip
+    ? ` [当前: ${currentProtocol}://${existing.websocket.ip}:${existing.websocket.port}]`
+    : "";
+  const input = await promptForAddress(
+    `请输入 WebSocket 地址 ([ws|wss://]ip:port，如 203.0.113.1:8081 或 wss://203.0.113.1:8081)${hint}: `,
+  );
+  if (!input) {
+    if (existing?.websocket?.ip && existing?.websocket?.port) {
+      return { protocol: currentProtocol, ip: existing.websocket.ip, port: existing.websocket.port };
+    }
+    fail("WebSocket 地址不能为空。请通过 --ws-address 或交互式输入提供。");
+  }
+  const parsed = parseAddress(input);
+  if (!parsed) {
+    fail(`WebSocket 地址格式无效，应为 [ws|wss://]ip:port，如 203.0.113.1:8081 或 wss://203.0.113.1:8081`);
+  }
+  return parsed;
+}
+
+/**
+ * 读取已安装插件目录下的 remote-guard-config.json
+ */
+function readExistingRemoteGuardConfig(pluginInstallPath) {
+  if (!pluginInstallPath) {
+    return undefined;
+  }
+  const configPath = path.join(pluginInstallPath, "remote-guard-config.json");
+  return readJsonFileIfExists(configPath);
+}
+
+/**
+ * 将 server / websocket 地址写入已安装插件目录的 remote-guard-config.json
+ */
+function writeServerAndWebSocketConfig(pluginInstallPath, serverAddr, wsAddr) {
+  const configPath = path.join(pluginInstallPath, "remote-guard-config.json");
+  const existing = readJsonFileIfExists(configPath) || {};
+  const next = {
+    ...existing,
+    server: {
+      ...existing.server,
+      protocol: serverAddr.protocol,
+      ip: serverAddr.ip,
+      port: serverAddr.port,
+    },
+    websocket: {
+      ...existing.websocket,
+      ip: wsAddr.ip,
+      port: wsAddr.port,
+      protocol: toWsProtocol(wsAddr.protocol),
+    },
+  };
+  writeJsonFile(configPath, next);
+  console.log(
+    `[claw-shieldctl] Server 地址已写入: ${serverAddr.protocol}://${serverAddr.ip}:${serverAddr.port}`,
+  );
+  console.log(
+    `[claw-shieldctl] WebSocket 地址已写入: ${toWsProtocol(wsAddr.protocol)}://${wsAddr.ip}:${wsAddr.port}`,
+  );
+  console.log(`[claw-shieldctl] 配置文件: ${configPath}`);
+}
+
+/**
+ * 仅写入 server 地址
+ */
+function writeServerConfig(pluginInstallPath, serverAddr) {
+  const configPath = path.join(pluginInstallPath, "remote-guard-config.json");
+  const existing = readJsonFileIfExists(configPath) || {};
+  const next = {
+    ...existing,
+    server: {
+      ...existing.server,
+      protocol: serverAddr.protocol,
+      ip: serverAddr.ip,
+      port: serverAddr.port,
+    },
+  };
+  writeJsonFile(configPath, next);
+  console.log(
+    `[claw-shieldctl] Server 地址已写入: ${serverAddr.protocol}://${serverAddr.ip}:${serverAddr.port}`,
+  );
+  console.log(`[claw-shieldctl] 配置文件: ${configPath}`);
+}
+
+/**
+ * 仅写入 websocket 地址
+ */
+function writeWebSocketConfig(pluginInstallPath, wsAddr) {
+  const configPath = path.join(pluginInstallPath, "remote-guard-config.json");
+  const existing = readJsonFileIfExists(configPath) || {};
+  const next = {
+    ...existing,
+    websocket: {
+      ...existing.websocket,
+      ip: wsAddr.ip,
+      port: wsAddr.port,
+      protocol: toWsProtocol(wsAddr.protocol),
+    },
+  };
+  writeJsonFile(configPath, next);
+  console.log(
+    `[claw-shieldctl] WebSocket 地址已写入: ${toWsProtocol(wsAddr.protocol)}://${wsAddr.ip}:${wsAddr.port}`,
+  );
+  console.log(`[claw-shieldctl] 配置文件: ${configPath}`);
+}
+
+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;
+const OPENCLAW_SECURITY_SCAN_BLOCKED_RE =
+  /installation blocked:\s*dangerous code patterns detected/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, needsUnsafeRetry: false };
+  }
+
+  const combinedOutput = readCombinedOutput(result);
+  if (options.allowArchiveFallback && OPENCLAW_NPM_EXTRACT_FAILURE_RE.test(combinedOutput)) {
+    return { alreadyInstalled: false, needsArchiveFallback: true, needsUnsafeRetry: false };
+  }
+
+  if (options.allowUnsafeRetry && OPENCLAW_SECURITY_SCAN_BLOCKED_RE.test(combinedOutput)) {
+    return { alreadyInstalled: false, needsArchiveFallback: false, needsUnsafeRetry: true };
+  }
+
+  if (OPENCLAW_PLUGIN_ALREADY_EXISTS_RE.test(combinedOutput)) {
+    console.log(
+      `[claw-shieldctl] 检测到插件 ${params.pluginId} 已存在，将跳过重复安装并继续执行 API Key 配置。若需升级插件，请改用 update 命令。`,
+    );
+    return { alreadyInstalled: true, needsArchiveFallback: false, needsUnsafeRetry: 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 },
+  );
+  const normalizedResult = normalizePluginInstallResult(installResult, {
+    ...params,
+    installTarget: packageDir,
+  }, { allowUnsafeRetry: true });
+
+  if (normalizedResult.needsUnsafeRetry) {
+    console.log(
+      "[claw-shieldctl] OpenClaw 安全扫描拦截了安装（误报：本插件需要 child_process 和网络通信能力）。" +
+      "正在使用 --dangerously-force-unsafe-install 重试...",
+    );
+    const retryResult = runCommand(
+      params.openclawBin,
+      ["plugins", "install", packageDir, "--dangerously-force-unsafe-install"],
+      { captureOutput: true, echoOutput: false, env: params.openclawCommandEnv },
+    );
+    return normalizePluginInstallResult(retryResult, {
+      ...params,
+      installTarget: packageDir,
+    });
+  }
+
+  return normalizedResult;
+}
+
+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(), "claw-shieldctl-pack-"));
+  try {
+    let archivePath;
+    if (localSpecPath) {
+      const specStat = fs.statSync(localSpecPath);
+      if (!specStat.isFile()) {
+        fail(`安装失败：本地插件来源不是可用文件或目录（${localSpecPath}）。`);
+      }
+      archivePath = localSpecPath;
+      console.log("[claw-shieldctl] 检测到本地 tgz 包，将先解压后按目录方式安装到 OpenClaw。");
+    } else {
+      console.log("[claw-shieldctl] 将使用预打包目录安装方式（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-claw-shield-0.1.16.tgz），
+      // 但实际文件在 tempRoot 根目录下以展平命名存放（如 tencent-claw-shield-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(`[claw-shieldctl] 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, allowUnsafeRetry: true });
+  if (normalizedResult.needsArchiveFallback) {
+    return installPluginFromPreparedSource(params);
+  }
+  if (normalizedResult.needsUnsafeRetry) {
+    console.log(
+      "[claw-shieldctl] OpenClaw 安全扫描拦截了安装（误报：本插件需要 child_process 和网络通信能力）。" +
+      "正在使用 --dangerously-force-unsafe-install 重试...",
+    );
+    const retryResult = runCommand(
+      params.openclawBin,
+      ["plugins", "install", params.pluginSpec, "--dangerously-force-unsafe-install"],
+      { captureOutput: true, echoOutput: false, env: params.openclawCommandEnv },
+    );
+    return normalizePluginInstallResult(retryResult, {
+      ...params,
+      installTarget: params.pluginSpec,
+    });
+  }
+  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(`[claw-shieldctl] 已清理 OpenClaw 安装阶段残留目录 ${targetPath}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`[claw-shieldctl] 清理 OpenClaw 安装阶段残留目录失败：${message}`);
+  }
+}
+
+/**
+ * 上报插件安装/卸载结果到远端服务
+ * POST /api/guardrails/plugin/install_report
+ * Authorization: Bearer <api-key>
+ * Body: { action, status, reason }
+ *
+ * AppId、ServiceId、RequestId 由后端根据 API Key 自动注入，无需显式传入
+ */
+async function reportInstallResult(params) {
+  const { serverBaseUrl, apiKey, action, status, reason } = params;
+  if (!serverBaseUrl || !apiKey) {
+    console.log("[claw-shieldctl] 跳过安装结果上报：缺少 server 地址或 API Key。");
+    return;
+  }
+
+  const url = `${serverBaseUrl}${INSTALL_REPORT_PATH}`;
+  const body = {
+    action: action || "install",
+    status,
+    ...(reason ? { reason } : {}),
+  };
+
+  console.log(`[claw-shieldctl] 正在上报${action === "uninstall" ? "卸载" : "安装"}结果到 ${url}...`);
+
+  try {
+    // HTTPS 请求跳过证书校验
+    if (url.startsWith("https://")) {
+      process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 15000);
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    clearTimeout(timeoutId);
+
+    if (response.ok) {
+      const responseBody = await response.text();
+      console.log(`[claw-shieldctl] 上报成功：${response.status} ${responseBody.slice(0, 200)}`);
+    } else {
+      const errorText = await response.text();
+      console.warn(`[claw-shieldctl] 上报返回非 2xx：${response.status} ${errorText.slice(0, 200)}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`[claw-shieldctl] 上报失败（不影响安装/卸载流程）：${message}`);
+  }
+}
+
+/**
+ * 构建 server base URL（复用 remote-guard-config.json 中的 server 配置或从 pluginInstallPath 读取）
+ */
+function resolveServerBaseUrl(pluginInstallPath) {
+  const existing = readExistingRemoteGuardConfig(pluginInstallPath);
+  if (!existing?.server?.ip || !existing?.server?.port) {
+    return undefined;
+  }
+  const protocol = existing.server.protocol || "http";
+  return `${protocol}://${existing.server.ip}:${existing.server.port}`;
+}
+
+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("[claw-shieldctl] gateway call shield.config.refresh 未成功，将继续按 restart 策略处理。");
+    runOrFail(params.openclawBin, ["gateway", "restart"], { env: params.openclawCommandEnv });
+    return;
+  }
+  console.log("[claw-shieldctl] gateway call shield.config.refresh 未成功，且已按 --no-restart 跳过自动重启。");
+}
+
+/**
+ * 检测指定 bin 是否可执行
+ */
+function isBinAvailable(bin) {
+  try {
+    const result = spawnSync(bin, ["--version"], {
+      stdio: "pipe",
+      encoding: "utf-8",
+      timeout: 5000,
+    });
+    return !result.error && (result.status === 0 || result.status === null);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 通过 which/command -v 查找可执行文件的绝对路径
+ */
+function whichBin(bin) {
+  try {
+    const result = spawnSync("which", [bin], {
+      stdio: "pipe",
+      encoding: "utf-8",
+      timeout: 3000,
+    });
+    if (result.status === 0 && result.stdout?.trim()) {
+      return result.stdout.trim();
+    }
+  } catch {
+    // 忽略
+  }
+  return undefined;
+}
+
+/**
+ * 扫描 nvm 安装的所有 node 版本，查找包含 openclaw 的版本
+ * 返回 openclaw 的绝对路径，或 undefined
+ */
+function findOpenClawInNvm() {
+  const nvmDir = process.env.NVM_DIR?.trim() || path.join(os.homedir(), ".nvm");
+  const versionsDir = path.join(nvmDir, "versions", "node");
+
+  if (!fs.existsSync(versionsDir)) {
+    return undefined;
+  }
+
+  try {
+    const versions = fs.readdirSync(versionsDir).sort().reverse(); // 优先尝试最新版本
+    for (const version of versions) {
+      const binDir = path.join(versionsDir, version, "bin");
+      const openclawPath = path.join(binDir, "openclaw");
+      if (fs.existsSync(openclawPath)) {
+        // 验证可执行（用对应 node 版本的 PATH）
+        try {
+          const envWithCorrectNode = {
+            ...process.env,
+            PATH: `${binDir}${path.delimiter}${process.env.PATH || ""}`,
+          };
+          const result = spawnSync(openclawPath, ["--version"], {
+            stdio: "pipe",
+            encoding: "utf-8",
+            timeout: 5000,
+            env: envWithCorrectNode,
+          });
+          if (!result.error && (result.status === 0 || result.status === null)) {
+            return openclawPath;
+          }
+        } catch {
+          continue;
+        }
+      }
+    }
+  } catch {
+    // 扫描失败，忽略
+  }
+
+  return undefined;
+}
+
+/**
+ * 扫描常见全局安装路径查找 openclaw
+ */
+function findOpenClawInGlobalPaths() {
+  const candidates = [
+    "/usr/local/bin/openclaw",
+    "/usr/bin/openclaw",
+    path.join(os.homedir(), ".npm-global", "bin", "openclaw"),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * 确认 openclaw 可用，不可用时尝试自动定位，最终仍不可用则给出详细错误提示
+ * @returns 可用的 openclaw 二进制路径
+ */
+function resolveOpenClawBinOrFail(requestedBin) {
+  // 1. 检查请求的 bin 是否直接可用
+  if (isBinAvailable(requestedBin)) {
+    return requestedBin;
+  }
+
+  // 2. 用 which 查找
+  const whichResult = whichBin(requestedBin);
+  if (whichResult && isBinAvailable(whichResult)) {
+    return whichResult;
+  }
+
+  console.warn(`[claw-shieldctl] 当前 PATH 中未找到 "${requestedBin}"，正在尝试自动定位...`);
+
+  // 3. 扫描 nvm 环境
+  const nvmResult = findOpenClawInNvm();
+  if (nvmResult) {
+    console.log(`[claw-shieldctl] 在 nvm 环境中找到 OpenClaw: ${nvmResult}`);
+    return nvmResult;
+  }
+
+  // 4. 扫描全局路径
+  const globalResult = findOpenClawInGlobalPaths();
+  if (globalResult) {
+    console.log(`[claw-shieldctl] 在全局路径中找到 OpenClaw: ${globalResult}`);
+    return globalResult;
+  }
+
+  // 5. 全部失败，给出详细错误提示
+  const nvmDir = process.env.NVM_DIR?.trim() || path.join(os.homedir(), ".nvm");
+  const hasNvm = fs.existsSync(nvmDir);
+
+  let message = `[claw-shieldctl] 错误：未找到 OpenClaw CLI（"${requestedBin}"）。\n\n`;
+  message += "Claw Shield 是 OpenClaw Agent 的安全插件，需要先安装 OpenClaw 才能使用。\n\n";
+  message += "请按以下步骤操作：\n\n";
+  message += "  1. 安装 OpenClaw:\n";
+  message += "     npm install -g openclaw\n\n";
+  message += "  2. 验证安装:\n";
+  message += "     openclaw --version\n\n";
+  message += "  3. 重新运行本命令:\n";
+  message += "     npx -y tencent-claw-shield install --global\n\n";
+
+  if (hasNvm) {
+    message += "检测到本机已安装 nvm，但在所有 node 版本中均未找到 openclaw。\n";
+    message += "请确认在正确的 node 版本下安装了 openclaw：\n\n";
+    message += "  nvm ls                        # 查看已安装的 node 版本\n";
+    message += "  nvm use <version>             # 切换到目标版本\n";
+    message += "  npm install -g openclaw       # 在该版本下安装\n";
+    message += "  openclaw --version            # 验证\n\n";
+  }
+
+  message += "如果 openclaw 已安装但不在默认 PATH 中，可通过 --openclaw-bin 指定路径：\n\n";
+  message += "  npx -y tencent-claw-shield install --global --openclaw-bin /path/to/openclaw\n";
+
+  fail(message);
+}
+
+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", "uninstall", "bypass", "resume", "set-api-key", "set-server", "set-websocket", "set-config", "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),
+    pluginInstallPath: resolveManagedPluginInstallPath(options.pluginId, resolvedStateDir),
+  };
+
+  console.log(`[claw-shieldctl] OpenClaw state dir: ${mergedOptions.resolvedStateDir}`);
+  console.log(`[claw-shieldctl] OpenClaw config path: ${mergedOptions.openclawConfigPath}`);
+  console.log(
+    `[claw-shieldctl] OpenClaw extensions dir: ${path.join(mergedOptions.resolvedStateDir, "extensions")}`,
+  );
+
+  // ── 前置检查：确认 openclaw 可用 ──────────────────────────────
+  const resolvedOpenClawBin = resolveOpenClawBinOrFail(mergedOptions.openclawBin);
+  if (resolvedOpenClawBin !== mergedOptions.openclawBin) {
+    mergedOptions.openclawBin = resolvedOpenClawBin;
+    // 重建 env，确保新 bin 路径的 node 环境在 PATH 中
+    mergedOptions.openclawCommandEnv = buildOpenClawCommandEnv(
+      { ...options, openclawBin: resolvedOpenClawBin },
+      resolvedStateDir,
+      openclawConfigPath,
+    );
+    console.log(`[claw-shieldctl] 已自动定位 OpenClaw: ${resolvedOpenClawBin}`);
+  }
+
+  if (normalizedCommand === "install") {
+    let installApiKey;
+
+    try {
+      installApiKey = await resolveApiKey({
+        apiKey: mergedOptions.apiKey,
+        authConfigPath: mergedOptions.authConfigPath,
+        allowStoredValue: true,
+      });
+      writeApiKey(mergedOptions.authConfigPath, installApiKey);
+      console.log(
+        `[claw-shieldctl] API Key 已写入 ${mergedOptions.authConfigPath} (${maskApiKey(installApiKey)})`,
+      );
+      warnIfEnvApiKeyDiffers(installApiKey);
+
+      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(`[claw-shieldctl] OpenClaw 配置已写入 ${openclawConfigPath}`);
+
+      // 配置 server 和 websocket 地址
+      const serverAddr = await resolveServerAddress({
+        serverAddress: mergedOptions.serverAddress,
+        pluginInstallPath: mergedOptions.pluginInstallPath,
+        allowStoredValue: true,
+      });
+      const wsAddr = await resolveWebSocketAddress({
+        wsAddress: mergedOptions.wsAddress,
+        pluginInstallPath: mergedOptions.pluginInstallPath,
+        allowStoredValue: true,
+      });
+      writeServerAndWebSocketConfig(mergedOptions.pluginInstallPath, serverAddr, wsAddr);
+
+      if (mergedOptions.restart) {
+        runOrFail(mergedOptions.openclawBin, ["gateway", "restart"], { env: mergedOptions.openclawCommandEnv });
+      }
+
+      // 安装成功上报
+      const serverBaseUrl = resolveServerBaseUrl(mergedOptions.pluginInstallPath);
+      await reportInstallResult({
+        serverBaseUrl,
+        apiKey: installApiKey,
+        action: "install",
+        status: "success",
+      });
+    } catch (installError) {
+      // 安装失败上报
+      const serverBaseUrl = resolveServerBaseUrl(mergedOptions.pluginInstallPath);
+      const reason = installError instanceof Error ? installError.message : String(installError);
+      await reportInstallResult({
+        serverBaseUrl,
+        apiKey: installApiKey || readStoredApiKey(mergedOptions.authConfigPath),
+        action: "install",
+        status: "failed",
+        reason,
+      });
+      throw installError;
+    }
+  } else if (normalizedCommand === "update") {
+    console.log(
+      `[claw-shieldctl] 将按“卸载旧版本 + 重装 ${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(
+      `[claw-shieldctl] 已为 ${mergedOptions.pluginId} 写入可追踪的安装记录（${mergedOptions.pluginSpec}）。`,
+    );
+    console.log(`[claw-shieldctl] OpenClaw 配置已写入 ${openclawConfigPath}`);
+
+    const installedVersion = readInstalledPluginVersion(mergedOptions.pluginId, mergedOptions.resolvedStateDir);
+    if (installedVersion) {
+      console.log(`[claw-shieldctl] 当前已安装版本：${installedVersion}`);
+    }
+
+    const existingApiKey = readStoredApiKey(mergedOptions.authConfigPath);
+    if (!existingApiKey) {
+      console.log(
+        `[claw-shieldctl] 尚未检测到 API Key，请执行 claw-shieldctl set-api-key 完成本地配置。`,
+      );
+    } else {
+      warnIfEnvApiKeyDiffers(existingApiKey);
+    }
+    if (mergedOptions.restart) {
+      runOrFail(mergedOptions.openclawBin, ["gateway", "restart"], { env: mergedOptions.openclawCommandEnv });
+    }
+  } else if (normalizedCommand === "uninstall") {
+    console.log(`[claw-shieldctl] 开始卸载插件 ${mergedOptions.pluginId}...`);
+
+    // 在卸载前先读取 server 地址和 API Key，因为卸载后可能读不到了
+    const serverBaseUrl = resolveServerBaseUrl(mergedOptions.pluginInstallPath);
+    const uninstallApiKey = readStoredApiKey(mergedOptions.authConfigPath);
+
+    try {
+      // 1. 通过 OpenClaw CLI 卸载插件
+      const uninstallResult = runCommand(
+        mergedOptions.openclawBin,
+        ["plugins", "uninstall", mergedOptions.pluginId, "--force"],
+        { captureOutput: true, echoOutput: false, env: mergedOptions.openclawCommandEnv },
+      );
+      if (uninstallResult.error) {
+        console.warn(
+          `[claw-shieldctl] openclaw plugins uninstall 执行出错：${uninstallResult.error.message}，将继续清理本地文件。`,
+        );
+      } else {
+        echoCapturedOutput(uninstallResult);
+      }
+
+      // 2. 移除插件安装目录
+      removeManagedPluginInstallDir(mergedOptions.pluginId, mergedOptions.resolvedStateDir);
+
+      // 3. 从 openclaw.json 中移除插件配置
+      removePluginFromConfig(mergedOptions.openclawConfigPath, mergedOptions.pluginId);
+
+      // 4. 可选：清理认证文件
+      if (mergedOptions.purge) {
+        removeAuthConfig(mergedOptions.authConfigPath);
+        console.log(`[claw-shieldctl] --purge 已启用，认证文件已清理。`);
+      } else {
+        console.log(
+          `[claw-shieldctl] 认证文件已保留（${mergedOptions.authConfigPath}）。如需同时删除，请使用 --purge 参数。`,
+        );
+      }
+
+      // 5. 重启 gateway 使卸载生效
+      if (mergedOptions.restart) {
+        console.log(`[claw-shieldctl] 正在重启 OpenClaw gateway...`);
+        runOrFail(mergedOptions.openclawBin, ["gateway", "restart"], { env: mergedOptions.openclawCommandEnv });
+      }
+
+      console.log(`[claw-shieldctl] 插件 ${mergedOptions.pluginId} 已成功卸载。`);
+
+      // 卸载成功上报
+      await reportInstallResult({
+        serverBaseUrl,
+        apiKey: uninstallApiKey,
+        action: "uninstall",
+        status: "success",
+      });
+    } catch (uninstallError) {
+      // 卸载失败上报
+      const reason = uninstallError instanceof Error ? uninstallError.message : String(uninstallError);
+      await reportInstallResult({
+        serverBaseUrl,
+        apiKey: uninstallApiKey,
+        action: "uninstall",
+        status: "failed",
+        reason,
+      });
+      throw uninstallError;
+    }
+  } else if (normalizedCommand === "bypass") {
+    console.log(`[claw-shieldctl] 正在激活 bypass 模式...`);
+    const callResult = runCommand(
+      mergedOptions.openclawBin,
+      ["gateway", "call", "shield.bypass", "--json"],
+      { captureOutput: true, echoOutput: false, env: mergedOptions.openclawCommandEnv },
+    );
+    if (callResult.error) {
+      fail(`执行 shield.bypass 失败：${callResult.error.message}`);
+    }
+    echoCapturedOutput(callResult);
+    if ((callResult.status ?? 1) !== 0) {
+      fail("shield.bypass 调用返回非 0，请检查 Gateway 是否正在运行。");
+    }
+    console.log(`[claw-shieldctl] Bypass 模式已激活：所有安全检测、遥测上报、Skills 上报均已暂停。`);
+    console.log(`[claw-shieldctl] 如需恢复防护，请执行：npx -y tencent-claw-shield resume`);
+  } else if (normalizedCommand === "resume") {
+    console.log(`[claw-shieldctl] 正在恢复防护模式...`);
+    const callResult = runCommand(
+      mergedOptions.openclawBin,
+      ["gateway", "call", "shield.resume", "--json"],
+      { captureOutput: true, echoOutput: false, env: mergedOptions.openclawCommandEnv },
+    );
+    if (callResult.error) {
+      fail(`执行 shield.resume 失败：${callResult.error.message}`);
+    }
+    echoCapturedOutput(callResult);
+    if ((callResult.status ?? 1) !== 0) {
+      fail("shield.resume 调用返回非 0，请检查 Gateway 是否正在运行。");
+    }
+    console.log(`[claw-shieldctl] 防护模式已恢复：所有安全检测、遥测上报已重新启用。`);
+  } else if (normalizedCommand === "set-api-key") {
+    const apiKey = await resolveApiKey({
+      apiKey: mergedOptions.apiKey,
+      authConfigPath: mergedOptions.authConfigPath,
+      allowStoredValue: false,
+    });
+    writeApiKey(mergedOptions.authConfigPath, apiKey);
+    console.log(
+      `[claw-shieldctl] API Key 已写入 ${mergedOptions.authConfigPath} (${maskApiKey(apiKey)})`,
+    );
+    warnIfEnvApiKeyDiffers(apiKey);
+    refreshOrRestart(mergedOptions);
+  } else if (normalizedCommand === "set-server") {
+    const serverAddr = await resolveServerAddress({
+      serverAddress: mergedOptions.serverAddress,
+      pluginInstallPath: mergedOptions.pluginInstallPath,
+      allowStoredValue: false,
+    });
+    writeServerConfig(mergedOptions.pluginInstallPath, serverAddr);
+    refreshOrRestart(mergedOptions);
+  } else if (normalizedCommand === "set-websocket") {
+    const wsAddr = await resolveWebSocketAddress({
+      wsAddress: mergedOptions.wsAddress,
+      pluginInstallPath: mergedOptions.pluginInstallPath,
+      allowStoredValue: false,
+    });
+    writeWebSocketConfig(mergedOptions.pluginInstallPath, wsAddr);
+    refreshOrRestart(mergedOptions);
+  } else if (normalizedCommand === "set-config") {
+    // 聚合命令：依次设置 API Key、Server 地址、WebSocket 地址，最后一次性热刷新
+    console.log("[claw-shieldctl] 开始配置 API Key、Server 地址和 WebSocket 地址...\n");
+
+    // 1. API Key
+    const apiKey = await resolveApiKey({
+      apiKey: mergedOptions.apiKey,
+      authConfigPath: mergedOptions.authConfigPath,
+      allowStoredValue: false,
+    });
+    writeApiKey(mergedOptions.authConfigPath, apiKey);
+    console.log(
+      `[claw-shieldctl] API Key 已写入 ${mergedOptions.authConfigPath} (${maskApiKey(apiKey)})`,
+    );
+    warnIfEnvApiKeyDiffers(apiKey);
+
+    // 2. Server 地址
+    const serverAddr = await resolveServerAddress({
+      serverAddress: mergedOptions.serverAddress,
+      pluginInstallPath: mergedOptions.pluginInstallPath,
+      allowStoredValue: false,
+    });
+    writeServerConfig(mergedOptions.pluginInstallPath, serverAddr);
+
+    // 3. WebSocket 地址
+    const wsAddr = await resolveWebSocketAddress({
+      wsAddress: mergedOptions.wsAddress,
+      pluginInstallPath: mergedOptions.pluginInstallPath,
+      allowStoredValue: false,
+    });
+    writeWebSocketConfig(mergedOptions.pluginInstallPath, wsAddr);
+
+    // 一次性热刷新
+    refreshOrRestart(mergedOptions);
+  } else if (normalizedCommand === "reload") {
+    refreshOrRestart(mergedOptions);
+  }
+
+  console.log(`[claw-shieldctl] ${normalizedCommand} 完成。`);
+  if (mergedOptions.configPath) {
+    console.log(`[claw-shieldctl] 自定义配置路径：${mergedOptions.configPath}`);
+  } else {
+    console.log("[claw-shieldctl] 当前使用插件随包发布的静态基础配置。");
+  }
+  console.log(`[claw-shieldctl] API Key 配置路径：${mergedOptions.authConfigPath}`);
+}
+
+await main();