@matelink/cli 2026.4.10 → 2026.4.12

package/README.md

@@ -78,7 +78,7 @@ of `openclaw.json`.
 Start OpenClaw first, then pair from the app:
 
 ```bash
-openclaw gateway run --bind loopback --port 18789 --force
+openclaw gateway run --bind loopback --port <gateway.port in openclaw.json> --force
 ```
 
 Use the mobile app to generate a pairing code, then run:

package/bin/matecli.mjs

@@ -19,13 +19,17 @@ import { fileURLToPath } from "node:url";
 const NUMERIC_CODE_LENGTH = 4;
 const GROUP_SIZE = 4;
 const DEFAULT_RELAY_WORKER_WAIT_SECONDS = 600;
+const DEFAULT_NETWORK_TIMEOUT_MS = 600000;
 const DEFAULT_RELAY_URL = "http://43.134.64.199:8090";
 const DEFAULT_GATEWAY_HOST = "127.0.0.1";
 const DEFAULT_WEBHOOK_PATH = "/testnextim/webhook";
 const DEFAULT_BIND_PATH = "/testnextim/bind";
-const GATEWAY_RPC_CLI_TIMEOUT_MS = 20000;
+const GATEWAY_RPC_CLI_TIMEOUT_MS = DEFAULT_NETWORK_TIMEOUT_MS;
 const CLI_PACKAGE_NAME = "@matelink/cli";
 const CLI_COMMAND_NAME = "matecli";
+const SERVICE_LABEL = "com.matelink.matecli.bridge";
+const SERVICE_UNIT_NAME = "matelink-matecli-bridge.service";
+const SERVICE_TASK_NAME = "Matelink MateCLI Bridge";
 // Relay worker defaults to full operator scope so gateway HTTP routes and RPC-adjacent
 // compatibility endpoints remain available without per-method scope juggling.
 const DEFAULT_GATEWAY_SCOPES = "operator.admin";
@@ -38,8 +42,9 @@ const CLI_I18N = {
     help_environment: "环境变量:",
     help_package: `包名: ${CLI_PACKAGE_NAME}`,
     help_tip: "提示:",
-    help_tip_pair: "  pair 命令会自动以后台模式启动 relay bridge worker。",
+    help_tip_pair: "  pair 命令会自动安装并启动系统后台服务，保持 relay bridge 在线。",
     help_tip_no_serve: "  如果不希望自动启动 bridge worker，可使用 --no-serve-relay。",
+    help_tip_service: `  可使用 \`${CLI_COMMAND_NAME} service status|install|uninstall|restart\` 管理后台服务。`,
     help_env_home: "  OPENCLAW_HOME   覆盖 OpenClaw 主目录（默认: ~/.openclaw）",
     help_env_openim: "  OPENIM_RELAY_URL / OPENIM_RELAY_TOKEN",
     help_env_relay_url: `  TESTNEXTIM_RELAY_URL   覆盖 relay 地址（默认: ${DEFAULT_RELAY_URL})`,
@@ -74,6 +79,14 @@ const CLI_I18N = {
     gateway_ready_hint: "请确认 OpenClaw daemon 正在运行，并且 responses endpoint 已启用。",
     pair_success: "配对已就绪，请回到 App 完成确认。",
     pair_worker_failed: "配对初始化失败，relay bridge worker 启动失败。",
+    service_install_failed: "后台服务安装失败，将回退到临时后台进程。",
+    service_installed: "后台服务已安装并启动。",
+    service_uninstalled: "后台服务已卸载。",
+    service_status_manager: "服务管理器: {value}",
+    service_status_installed: "服务已安装: {value}",
+    service_status_running: "服务运行中: {value}",
+    service_status_target: "服务目标: {value}",
+    service_status_logs: "日志目录: {value}",
     setup_updated: "配置已更新: {path}",
     setup_ready: "配置已准备好: {path}",
     setup_state_file: "状态文件: {path}",
@@ -115,8 +128,9 @@ const CLI_I18N = {
     help_environment: "Environment:",
     help_package: `Package: ${CLI_PACKAGE_NAME}`,
     help_tip: "Tip:",
-    help_tip_pair: "  The pair command auto-starts the relay bridge worker in detached mode.",
+    help_tip_pair: "  The pair command auto-installs and starts a background service to keep the relay bridge online.",
     help_tip_no_serve: "  Use --no-serve-relay if you do not want the bridge worker to start automatically.",
+    help_tip_service: `  Use \`${CLI_COMMAND_NAME} service status|install|uninstall|restart\` to manage the background service.`,
     help_env_home: "  OPENCLAW_HOME   Override OpenClaw home directory (default: ~/.openclaw)",
     help_env_openim: "  OPENIM_RELAY_URL / OPENIM_RELAY_TOKEN",
     help_env_relay_url: `  TESTNEXTIM_RELAY_URL   Override relay base URL (default: ${DEFAULT_RELAY_URL})`,
@@ -152,6 +166,14 @@ const CLI_I18N = {
       "Make sure OpenClaw daemon is running and the responses endpoint is enabled.",
     pair_success: "Pairing is ready. Return to the app to finish confirmation.",
     pair_worker_failed: "Pairing initialization failed because the relay bridge worker could not start.",
+    service_install_failed: "Background service install failed. Falling back to a temporary detached process.",
+    service_installed: "Background service installed and started.",
+    service_uninstalled: "Background service uninstalled.",
+    service_status_manager: "Service Manager: {value}",
+    service_status_installed: "Service Installed: {value}",
+    service_status_running: "Service Running: {value}",
+    service_status_target: "Service Target: {value}",
+    service_status_logs: "Log Directory: {value}",
     setup_updated: "Updated config: {path}",
     setup_ready: "Config already prepared: {path}",
     setup_state_file: "State file: {path}",
@@ -233,6 +255,7 @@ function printHelp() {
       `  ${CLI_COMMAND_NAME} pair <1234|123456|XXXX-XXXX> [--mode <relay>]`,
       `  ${CLI_COMMAND_NAME} reset [--relay <url>] [--gateway <url>] [--json]`,
       `  ${CLI_COMMAND_NAME} bridge [--relay <url>] [--gateway <url>] [--json] (Deprecated)`,
+      `  ${CLI_COMMAND_NAME} service <status|install|uninstall|restart> [--relay <url>] [--gateway <url>] [--json]`,
       `  ${CLI_COMMAND_NAME} pair-url [<1234|123456|XXXX-XXXX>] [--account <id>] [--code <1234|123456|XXXX-XXXX>] [--json]`,
       `  ${CLI_COMMAND_NAME} status [--json]`,
       "",
@@ -249,6 +272,7 @@ function printHelp() {
       t("help_tip"),
       t("help_tip_pair"),
       t("help_tip_no_serve"),
+      t("help_tip_service"),
     ].join("\n"),
   );
 }
@@ -273,6 +297,7 @@ function parseArgs(argv) {
     waitBind: false,
     waitSeconds: DEFAULT_RELAY_WORKER_WAIT_SECONDS,
     serveRelay: true,
+    serviceAction: "status",
     mode: undefined,
   };
 
@@ -369,6 +394,14 @@ function parseArgs(argv) {
       fail(`unknown option: ${token}`);
     }
 
+    if (command === "service") {
+      if (!options.serviceAction || options.serviceAction === "status") {
+        options.serviceAction = token.trim().toLowerCase();
+        continue;
+      }
+      fail(`unexpected argument: ${token}`);
+    }
+
     if (command === "pair" || command === "pair-url") {
       if (!options.code) {
         options.code = token.trim();
@@ -399,6 +432,26 @@ function resolveTestNextIMStatePath() {
   return path.join(resolveOpenClawHome(), "testnextim.state.json");
 }
 
+function resolveMatecliRuntimeDir() {
+  return path.join(resolveOpenClawHome(), "matecli");
+}
+
+function resolveBridgeLogsDir() {
+  return path.join(resolveMatecliRuntimeDir(), "logs");
+}
+
+function resolveBridgeLaunchScriptPath() {
+  return path.join(resolveMatecliRuntimeDir(), "bridge-launch.sh");
+}
+
+function resolveMacLaunchAgentPath() {
+  return path.join(os.homedir(), "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`);
+}
+
+function resolveLinuxUserUnitPath() {
+  return path.join(os.homedir(), ".config", "systemd", "user", SERVICE_UNIT_NAME);
+}
+
 function resolveBridgeLockPath({ relayUrl, gatewayId, gatewayBaseUrl }) {
   const digest = createHash("sha256")
     .update(
@@ -440,6 +493,39 @@ function readOptionalJsonFile(filePath) {
   }
 }
 
+function readJsonFileIfExists(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function commandToString(command, args) {
+  return [command, ...args]
+    .map((part) => {
+      const value = String(part);
+      return /[\s"]/u.test(value) ? `"${value.replaceAll("\"", "\\\"")}"` : value;
+    })
+    .join(" ");
+}
+
+function quoteWindowsCommandArg(value) {
+  const text = String(value ?? "");
+  if (!/[\s"]/u.test(text)) {
+    return text;
+  }
+  return `"${text.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"")}"`;
+}
+
+function runCommand(command, args, options = {}) {
+  return spawnSync(command, args, {
+    encoding: "utf8",
+    windowsHide: process.platform === "win32",
+    ...options,
+  });
+}
+
 function isPidAlive(pid) {
   const normalized = Number(pid);
   if (!Number.isFinite(normalized) || normalized <= 0) {
@@ -774,6 +860,34 @@ function formatHostForUrl(host) {
   return value;
 }
 
+function resolveGatewayHost(config) {
+  const fromEnv = String(process.env.OPENCLAW_GATEWAY_HOST ?? "").trim();
+  if (fromEnv) {
+    return fromEnv;
+  }
+
+  const gateway = ensureObject(config?.gateway);
+  const http = ensureObject(gateway.http);
+  const bindMode = String(gateway.bind ?? "").trim().toLowerCase();
+
+  const configuredHostCandidates = [
+    gateway.host,
+    gateway.hostname,
+    http.host,
+    http.hostname,
+    bindMode === "custom" ? gateway.customBindHost : "",
+  ];
+
+  for (const candidate of configuredHostCandidates) {
+    const value = String(candidate ?? "").trim();
+    if (value) {
+      return value;
+    }
+  }
+
+  return DEFAULT_GATEWAY_HOST;
+}
+
 function resolveGatewayPort(config) {
   const fromEnv = parseGatewayPortEnvValue(process.env.OPENCLAW_GATEWAY_PORT);
   if (fromEnv != null) {
@@ -809,11 +923,7 @@ function resolveGatewayBaseUrl(options, config) {
       ].join("\n"),
     );
   }
-  const bindMode = String(config?.gateway?.bind ?? "").trim().toLowerCase();
-  const customBindHost = String(config?.gateway?.customBindHost ?? "").trim();
-  const host =
-    String(process.env.OPENCLAW_GATEWAY_HOST ?? "").trim() ||
-    (bindMode === "custom" && customBindHost ? customBindHost : DEFAULT_GATEWAY_HOST);
+  const host = resolveGatewayHost(config);
   return `http://${formatHostForUrl(host)}:${gatewayPort}`;
 }
 
@@ -868,7 +978,7 @@ function extractErrorMessage(decoded, fallback) {
   return fallback;
 }
 
-async function fetchWithTimeout(url, options = {}, timeoutMs = 30000) {
+async function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_NETWORK_TIMEOUT_MS) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(new Error(`fetch timeout after ${timeoutMs}ms`)), timeoutMs);
   try {
@@ -1137,6 +1247,462 @@ function restartOpenClaw() {
   };
 }
 
+function bridgeInvocationArgs({ relayUrl, gatewayBaseUrl }) {
+  return [CLI_ENTRY, "bridge", "--relay", relayUrl, "--gateway", gatewayBaseUrl];
+}
+
+function escapePosixShellSingleQuoted(value) {
+  return String(value ?? "").replaceAll("'", "'\"'\"'");
+}
+
+function buildPosixShellExec(command, args) {
+  return [command, ...args]
+    .map((part) => `'${escapePosixShellSingleQuoted(part)}'`)
+    .join(" ");
+}
+
+function resolveNodeCandidates() {
+  const homeDir = os.homedir();
+  const candidates = new Set();
+  const addCandidate = (candidate) => {
+    const normalized = String(candidate ?? "").trim();
+    if (!normalized) {
+      return;
+    }
+    try {
+      if (fs.existsSync(normalized)) {
+        candidates.add(fs.realpathSync(normalized));
+      }
+    } catch {
+      if (fs.existsSync(normalized)) {
+        candidates.add(normalized);
+      }
+    }
+  };
+
+  addCandidate(process.execPath);
+  addCandidate(path.join(homeDir, ".nvm", "current", "bin", "node"));
+  addCandidate(path.join(homeDir, ".volta", "bin", "node"));
+  addCandidate("/opt/homebrew/bin/node");
+  addCandidate("/usr/local/bin/node");
+  addCandidate("/usr/bin/node");
+
+  const nvmVersionsDir = path.join(homeDir, ".nvm", "versions", "node");
+  try {
+    const nvmEntries = fs
+      .readdirSync(nvmVersionsDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort((a, b) => b.localeCompare(a, undefined, { numeric: true, sensitivity: "base" }));
+    for (const version of nvmEntries) {
+      addCandidate(path.join(nvmVersionsDir, version, "bin", "node"));
+    }
+  } catch {}
+
+  const localNodeRoots = [
+    path.join(homeDir, ".local"),
+    path.join(homeDir, ".local", "node"),
+  ];
+  for (const root of localNodeRoots) {
+    try {
+      const entries = fs
+        .readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && entry.name.startsWith("node-"))
+        .map((entry) => entry.name)
+        .sort((a, b) => b.localeCompare(a, undefined, { numeric: true, sensitivity: "base" }));
+      for (const name of entries) {
+        addCandidate(path.join(root, name, "bin", "node"));
+      }
+    } catch {}
+  }
+
+  return [...candidates];
+}
+
+function resolveBridgeServiceNodePath() {
+  for (const candidate of resolveNodeCandidates()) {
+    if (candidate && fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  const whichNode = runCommand("which", ["node"]);
+  if (whichNode.status === 0) {
+    const resolved = String(whichNode.stdout ?? "").trim();
+    if (resolved && fs.existsSync(resolved)) {
+      return resolved;
+    }
+  }
+  fail("node runtime is required for bridge service install");
+}
+
+function writeBridgeLaunchScript(installConfig) {
+  const scriptPath = resolveBridgeLaunchScriptPath();
+  fs.mkdirSync(path.dirname(scriptPath), { recursive: true });
+  const defaultPath = [
+    "/opt/homebrew/bin",
+    "/usr/local/bin",
+    "/usr/bin",
+    "/bin",
+    "/usr/sbin",
+    "/sbin",
+    path.join(os.homedir(), ".volta", "bin"),
+    path.join(os.homedir(), ".nvm", "current", "bin"),
+  ].join(":");
+  const knownNodeCandidates = resolveNodeCandidates();
+  const candidateChecks = knownNodeCandidates
+    .map((candidate) => `if [ -x '${escapePosixShellSingleQuoted(candidate)}' ]; then NODE_BIN='${escapePosixShellSingleQuoted(candidate)}'; fi`)
+    .join("\n");
+  const fallbackLine = buildPosixShellExec("node", installConfig.args);
+  const script = [
+    "#!/bin/sh",
+    "set -eu",
+    "export PATH='" + escapePosixShellSingleQuoted(defaultPath) + ":'\"${PATH:-}\"",
+    "NODE_BIN=''",
+    candidateChecks,
+    "if [ -z \"$NODE_BIN\" ] && command -v node >/dev/null 2>&1; then",
+    "  NODE_BIN=\"$(command -v node)\"",
+    "fi",
+    "if [ -n \"$NODE_BIN\" ]; then",
+    `  exec "$NODE_BIN" ${installConfig.args.map((arg) => `'${escapePosixShellSingleQuoted(arg)}'`).join(" ")}`,
+    "fi",
+    `exec ${fallbackLine}`,
+    "",
+  ].join("\n");
+  fs.writeFileSync(scriptPath, script, { encoding: "utf8", mode: 0o755 });
+  return scriptPath;
+}
+
+function ensureBridgeServiceInstallConfig({ relayUrl, gatewayBaseUrl }) {
+  if (!relayUrl) {
+    fail("relay URL is required for bridge service");
+  }
+  if (!gatewayBaseUrl) {
+    fail("gateway base URL is required for bridge service");
+  }
+  const logDir = resolveBridgeLogsDir();
+  fs.mkdirSync(logDir, { recursive: true });
+  return {
+    relayUrl,
+    gatewayBaseUrl,
+    logDir,
+    stdoutLog: path.join(logDir, "bridge.stdout.log"),
+    stderrLog: path.join(logDir, "bridge.stderr.log"),
+    nodePath: resolveBridgeServiceNodePath(),
+    scriptPath: CLI_ENTRY,
+    args: bridgeInvocationArgs({ relayUrl, gatewayBaseUrl }),
+  };
+}
+
+function escapeXmlText(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
+function readMacLaunchdServiceStatus(uid, plistPath) {
+  const refs = uid == null ? [] : [`gui/${uid}/${SERVICE_LABEL}`, `user/${uid}/${SERVICE_LABEL}`];
+  for (const ref of refs) {
+    const result = runCommand("launchctl", ["print", ref]);
+    if (result.status !== 0) {
+      continue;
+    }
+    const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+    const stateMatch = output.match(/state = ([^\n]+)/u);
+    const activeCountMatch = output.match(/active count = (\d+)/u);
+    const pidMatch = output.match(/\bpid = (\d+)/u);
+    const exitCodeMatch = output.match(/last exit code = (\d+)/u);
+    const state = stateMatch?.[1]?.trim() ?? "";
+    const activeCount = Number.parseInt(activeCountMatch?.[1] ?? "0", 10) || 0;
+    const pid = Number.parseInt(pidMatch?.[1] ?? "0", 10) || 0;
+    const lastExitCode = Number.parseInt(exitCodeMatch?.[1] ?? "0", 10) || 0;
+    const running =
+      state.toLowerCase() === "running" ||
+      activeCount > 0 ||
+      (pid > 0 && isPidAlive(pid));
+    return {
+      manager: "launchd",
+      installed: true,
+      running,
+      target: plistPath,
+      logDir: resolveBridgeLogsDir(),
+      ref,
+      state,
+      activeCount,
+      pid: pid || null,
+      lastExitCode,
+    };
+  }
+  return {
+    manager: "launchd",
+    installed: fs.existsSync(plistPath),
+    running: false,
+    target: plistPath,
+    logDir: resolveBridgeLogsDir(),
+    ref: SERVICE_LABEL,
+    state: "not-loaded",
+    activeCount: 0,
+    pid: null,
+    lastExitCode: 0,
+  };
+}
+
+function installBridgeServiceMac(installConfig) {
+  const plistPath = resolveMacLaunchAgentPath();
+  const launchScriptPath = writeBridgeLaunchScript(installConfig);
+  fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+  const argsXml = [launchScriptPath]
+    .map((arg) => `    <string>${escapeXmlText(arg)}</string>`)
+    .join("\n");
+  const plist = [
+    "<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
+    "<!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">",
+    "<plist version=\"1.0\">",
+    "<dict>",
+    `  <key>Label</key><string>${SERVICE_LABEL}</string>`,
+    "  <key>ProgramArguments</key>",
+    "  <array>",
+    argsXml,
+    "  </array>",
+    "  <key>RunAtLoad</key><true/>",
+    "  <key>KeepAlive</key><true/>",
+    `  <key>WorkingDirectory</key><string>${resolveOpenClawHome()}</string>`,
+    `  <key>StandardOutPath</key><string>${installConfig.stdoutLog}</string>`,
+    `  <key>StandardErrorPath</key><string>${installConfig.stderrLog}</string>`,
+    "</dict>",
+    "</plist>",
+    "",
+  ].join("\n");
+  fs.writeFileSync(plistPath, plist, "utf8");
+
+  const uid = typeof process.getuid === "function" ? process.getuid() : null;
+  const domains = uid == null ? [] : [`gui/${uid}`, `user/${uid}`];
+  let selectedDomain = null;
+  for (const domain of domains) {
+    runCommand("launchctl", ["bootout", domain, plistPath]);
+    const bootstrap = runCommand("launchctl", ["bootstrap", domain, plistPath]);
+    if (bootstrap.status === 0) {
+      selectedDomain = domain;
+      runCommand("launchctl", ["enable", `${domain}/${SERVICE_LABEL}`]);
+      runCommand("launchctl", ["kickstart", "-k", `${domain}/${SERVICE_LABEL}`]);
+      break;
+    }
+  }
+  if (!selectedDomain) {
+    const fallback = runCommand("launchctl", ["load", "-w", plistPath]);
+    if (fallback.status !== 0) {
+      throw new Error((fallback.stderr || fallback.stdout || "launchctl bootstrap failed").trim());
+    }
+    selectedDomain = "launchd";
+  }
+  const status = readMacLaunchdServiceStatus(uid, plistPath);
+  if (!status.running) {
+    const details = status.lastExitCode
+      ? `launchd last exit code: ${status.lastExitCode}`
+      : "launchd service failed to stay running";
+    throw new Error(details);
+  }
+  return {
+    manager: "launchd",
+    installed: true,
+    running: true,
+    target: plistPath,
+    logDir: installConfig.logDir,
+    ref: `${selectedDomain}/${SERVICE_LABEL}`,
+  };
+}
+
+function installBridgeServiceLinux(installConfig) {
+  const unitPath = resolveLinuxUserUnitPath();
+  fs.mkdirSync(path.dirname(unitPath), { recursive: true });
+  const execStart = commandToString(installConfig.nodePath, installConfig.args);
+  const unit = [
+    "[Unit]",
+    "Description=Matelink relay bridge",
+    "After=network-online.target",
+    "Wants=network-online.target",
+    "",
+    "[Service]",
+    "Type=simple",
+    `WorkingDirectory=${resolveOpenClawHome()}`,
+    `ExecStart=${execStart}`,
+    "Restart=always",
+    "RestartSec=5",
+    `StandardOutput=append:${installConfig.stdoutLog}`,
+    `StandardError=append:${installConfig.stderrLog}`,
+    "",
+    "[Install]",
+    "WantedBy=default.target",
+    "",
+  ].join("\n");
+  fs.writeFileSync(unitPath, unit, "utf8");
+  const commands = [
+    ["systemctl", ["--user", "daemon-reload"]],
+    ["systemctl", ["--user", "enable", "--now", SERVICE_UNIT_NAME]],
+  ];
+  for (const [command, args] of commands) {
+    const result = runCommand(command, args);
+    if (result.status !== 0) {
+      throw new Error((result.stderr || result.stdout || `${command} failed`).trim());
+    }
+  }
+  return {
+    manager: "systemd-user",
+    installed: true,
+    running: true,
+    target: unitPath,
+    logDir: installConfig.logDir,
+    ref: SERVICE_UNIT_NAME,
+  };
+}
+
+function installBridgeServiceWindows(installConfig) {
+  const commandLine = installConfig.args.map(quoteWindowsCommandArg).join(" ");
+  const script = [
+    `$Action = New-ScheduledTaskAction -Execute '${installConfig.nodePath.replaceAll("'", "''")}' -Argument '${commandLine.replaceAll("'", "''")}'`,
+    "$Trigger = New-ScheduledTaskTrigger -AtLogOn",
+    "$Settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1)",
+    `Register-ScheduledTask -TaskName '${SERVICE_TASK_NAME}' -Action $Action -Trigger $Trigger -Settings $Settings -Description 'Matelink relay bridge' -Force | Out-Null`,
+    `Start-ScheduledTask -TaskName '${SERVICE_TASK_NAME}'`,
+  ].join("; ");
+  const result = runCommand("powershell.exe", ["-NoProfile", "-Command", script]);
+  if (result.status !== 0) {
+    throw new Error((result.stderr || result.stdout || "scheduled task install failed").trim());
+  }
+  return {
+    manager: "task-scheduler",
+    installed: true,
+    running: true,
+    target: SERVICE_TASK_NAME,
+    logDir: installConfig.logDir,
+    ref: SERVICE_TASK_NAME,
+  };
+}
+
+function installBridgeService({ relayUrl, gatewayBaseUrl }) {
+  const installConfig = ensureBridgeServiceInstallConfig({ relayUrl, gatewayBaseUrl });
+  if (process.platform === "darwin") {
+    return installBridgeServiceMac(installConfig);
+  }
+  if (process.platform === "linux") {
+    return installBridgeServiceLinux(installConfig);
+  }
+  if (process.platform === "win32") {
+    return installBridgeServiceWindows(installConfig);
+  }
+  throw new Error(`unsupported platform for service install: ${process.platform}`);
+}
+
+function uninstallBridgeService() {
+  if (process.platform === "darwin") {
+    const plistPath = resolveMacLaunchAgentPath();
+    const launchScriptPath = resolveBridgeLaunchScriptPath();
+    const uid = typeof process.getuid === "function" ? process.getuid() : null;
+    if (uid != null) {
+      runCommand("launchctl", ["bootout", `gui/${uid}`, plistPath]);
+      runCommand("launchctl", ["bootout", `user/${uid}`, plistPath]);
+    }
+    try {
+      fs.unlinkSync(plistPath);
+    } catch {}
+    try {
+      fs.unlinkSync(launchScriptPath);
+    } catch {}
+    return { manager: "launchd", installed: false, running: false, target: plistPath, logDir: resolveBridgeLogsDir() };
+  }
+  if (process.platform === "linux") {
+    const unitPath = resolveLinuxUserUnitPath();
+    runCommand("systemctl", ["--user", "disable", "--now", SERVICE_UNIT_NAME]);
+    try {
+      fs.unlinkSync(unitPath);
+    } catch {}
+    runCommand("systemctl", ["--user", "daemon-reload"]);
+    return { manager: "systemd-user", installed: false, running: false, target: unitPath, logDir: resolveBridgeLogsDir() };
+  }
+  if (process.platform === "win32") {
+    runCommand("powershell.exe", ["-NoProfile", "-Command", `Unregister-ScheduledTask -TaskName '${SERVICE_TASK_NAME}' -Confirm:$false -ErrorAction SilentlyContinue`]);
+    return { manager: "task-scheduler", installed: false, running: false, target: SERVICE_TASK_NAME, logDir: resolveBridgeLogsDir() };
+  }
+  throw new Error(`unsupported platform for service uninstall: ${process.platform}`);
+}
+
+function stopBridgeService() {
+  if (process.platform === "darwin") {
+    const plistPath = resolveMacLaunchAgentPath();
+    const uid = typeof process.getuid === "function" ? process.getuid() : null;
+    if (uid != null) {
+      runCommand("launchctl", ["bootout", `gui/${uid}`, plistPath]);
+      runCommand("launchctl", ["bootout", `user/${uid}`, plistPath]);
+    }
+    return {
+      manager: "launchd",
+      installed: fs.existsSync(plistPath),
+      running: false,
+      target: plistPath,
+      logDir: resolveBridgeLogsDir(),
+    };
+  }
+  if (process.platform === "linux") {
+    const unitPath = resolveLinuxUserUnitPath();
+    runCommand("systemctl", ["--user", "stop", SERVICE_UNIT_NAME]);
+    return {
+      manager: "systemd-user",
+      installed: fs.existsSync(unitPath),
+      running: false,
+      target: unitPath,
+      logDir: resolveBridgeLogsDir(),
+    };
+  }
+  if (process.platform === "win32") {
+    runCommand("powershell.exe", ["-NoProfile", "-Command", `Stop-ScheduledTask -TaskName '${SERVICE_TASK_NAME}' -ErrorAction SilentlyContinue`]);
+    return {
+      manager: "task-scheduler",
+      installed: true,
+      running: false,
+      target: SERVICE_TASK_NAME,
+      logDir: resolveBridgeLogsDir(),
+    };
+  }
+  return { manager: process.platform, installed: false, running: false, target: null, logDir: resolveBridgeLogsDir() };
+}
+
+function restartBridgeService({ relayUrl, gatewayBaseUrl }) {
+  stopBridgeService();
+  return installBridgeService({ relayUrl, gatewayBaseUrl });
+}
+
+function getBridgeServiceStatus() {
+  if (process.platform === "darwin") {
+    const plistPath = resolveMacLaunchAgentPath();
+    const uid = typeof process.getuid === "function" ? process.getuid() : null;
+    return readMacLaunchdServiceStatus(uid, plistPath);
+  }
+  if (process.platform === "linux") {
+    const enabled = runCommand("systemctl", ["--user", "is-enabled", SERVICE_UNIT_NAME]);
+    const active = runCommand("systemctl", ["--user", "is-active", SERVICE_UNIT_NAME]);
+    return {
+      manager: "systemd-user",
+      installed: enabled.status === 0 || fs.existsSync(resolveLinuxUserUnitPath()),
+      running: active.status === 0,
+      target: resolveLinuxUserUnitPath(),
+      logDir: resolveBridgeLogsDir(),
+      ref: SERVICE_UNIT_NAME,
+    };
+  }
+  if (process.platform === "win32") {
+    const result = runCommand("powershell.exe", ["-NoProfile", "-Command", `Get-ScheduledTask -TaskName '${SERVICE_TASK_NAME}' | Select-Object -ExpandProperty State`]);
+    return {
+      manager: "task-scheduler",
+      installed: result.status === 0,
+      running: result.status === 0 && String(result.stdout ?? "").trim().toLowerCase() === "ready",
+      target: SERVICE_TASK_NAME,
+      logDir: resolveBridgeLogsDir(),
+      ref: SERVICE_TASK_NAME,
+    };
+  }
+  return { manager: process.platform, installed: false, running: false, target: null, logDir: resolveBridgeLogsDir(), ref: null };
+}
+
 function listBridgeProcesses({ relayUrl, gatewayBaseUrl }) {
   let result;
   if (process.platform === "win32") {
@@ -1173,7 +1739,11 @@ function listBridgeProcesses({ relayUrl, gatewayBaseUrl }) {
       (entry) =>
         Number.isFinite(entry.pid) &&
         entry.pid !== process.pid &&
-        entry.command.includes("testnextim") &&
+        (
+          entry.command.includes(CLI_COMMAND_NAME) ||
+          entry.command.includes(CLI_PACKAGE_NAME) ||
+          entry.command.includes(path.basename(CLI_ENTRY))
+        ) &&
         entry.command.includes("bridge") &&
         entry.command.includes(relayUrl) &&
         entry.command.includes(gatewayBaseUrl),
@@ -1195,6 +1765,29 @@ function stopBridgeProcesses({ relayUrl, gatewayBaseUrl }) {
   };
 }
 
+function clearExistingBridgeRuntime({ relayUrl, gatewayBaseUrl }) {
+  const serviceStatus = getBridgeServiceStatus();
+  let serviceStopped = null;
+  if (serviceStatus.installed) {
+    try {
+      serviceStopped = stopBridgeService();
+    } catch (error) {
+      serviceStopped = {
+        error: String(error instanceof Error ? error.message : error),
+      };
+    }
+  }
+  const stoppedProcesses =
+    relayUrl && gatewayBaseUrl
+      ? stopBridgeProcesses({ relayUrl, gatewayBaseUrl })
+      : { count: 0, pids: [] };
+  return {
+    serviceStatus,
+    serviceStopped,
+    stoppedProcesses,
+  };
+}
+
 function resolvePublishedGatewayBaseUrl({
   relayUrl,
   bindPublicBaseUrl,
@@ -1644,7 +2237,7 @@ async function publishRelayGatewayEvent({
       ...relayGatewayHeaders(gatewayToken),
     },
     body: JSON.stringify(payload),
-  }, 20000);
+  }, DEFAULT_NETWORK_TIMEOUT_MS);
 
   const text = await response.text();
   if (!response.ok) {
@@ -1671,7 +2264,7 @@ async function publishRelayGatewayChatEvent({
       ...relayGatewayHeaders(gatewayToken),
     },
     body: JSON.stringify(payload ?? {}),
-  }, 20000);
+  }, DEFAULT_NETWORK_TIMEOUT_MS);
 
   const text = await response.text();
   if (!response.ok) {
@@ -2071,7 +2664,7 @@ function createGatewayWsClient({ gatewayBaseUrl, gatewayAuthToken }) {
       const timer = setTimeout(() => {
         pending.delete(id);
         reject(new Error(`gateway rpc timeout: ${method}`));
-      }, 30000);
+      }, DEFAULT_NETWORK_TIMEOUT_MS);
       pending.set(id, {
         resolve: (v) => { clearTimeout(timer); resolve(v); },
         reject: (e) => { clearTimeout(timer); reject(e); },
@@ -2488,7 +3081,7 @@ async function runRelayBridge({
       relayUrl,
       gatewayId,
       gatewayToken,
-      waitSeconds: 30,
+      waitSeconds: DEFAULT_RELAY_WORKER_WAIT_SECONDS,
     });
     if (!request) {
       continue;
@@ -2571,6 +3164,18 @@ function startRelayBridgeDetached({
   return { started: true, alreadyRunning: false, mode: "detached" };
 }
 
+function formatServiceStatusOutput(result) {
+  return [
+    t("service_status_manager", { value: result.manager }),
+    t("service_status_installed", { value: result.installed ? t("yes") : t("no") }),
+    t("service_status_running", { value: result.running ? t("yes") : t("no") }),
+    result.target ? t("service_status_target", { value: result.target }) : null,
+    result.logDir ? t("service_status_logs", { value: result.logDir }) : null,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
 async function runPair({
   json,
   account,
@@ -2804,22 +3409,55 @@ async function runPair({
     publishedGatewayBaseUrl,
     gatewayRestarted: Boolean(restartResult?.ok),
     relayGatewayId: relayCredentials?.gatewayId ?? null,
+    bridgeCleanup: null,
   };
 
   if (serveRelay && !json) {
+    const bridgeCleanup = clearExistingBridgeRuntime({
+      relayUrl,
+      gatewayBaseUrl: localGatewayBaseUrl,
+    });
+    output.bridgeCleanup = {
+      serviceInstalled: bridgeCleanup.serviceStatus?.installed === true,
+      serviceRunning: bridgeCleanup.serviceStatus?.running === true,
+      serviceStopError: bridgeCleanup.serviceStopped?.error ?? null,
+      stoppedProcessCount: bridgeCleanup.stoppedProcesses?.count ?? 0,
+      stoppedPids: bridgeCleanup.stoppedProcesses?.pids ?? [],
+    };
     try {
-      const bridgeResult = startRelayBridgeDetached({
+      const serviceStatus = getBridgeServiceStatus();
+      const serviceResult = (serviceStatus.installed ? restartBridgeService : installBridgeService)({
         relayUrl,
         gatewayBaseUrl: localGatewayBaseUrl,
       });
-      output.relayWorkerResult = bridgeResult;
-    } catch (error) {
       output.relayWorkerResult = {
-        mode: "detached",
-        started: false,
-        error: String(error instanceof Error ? error.message : error),
+        ...serviceResult,
+        started: true,
+        alreadyRunning: serviceResult.running,
+        mode: "service",
       };
-      console.warn(`Failed to start relay bridge worker: ${output.relayWorkerResult.error}`);
+      console.log(t("service_installed"));
+    } catch (error) {
+      const serviceError = String(error instanceof Error ? error.message : error);
+      console.warn(t("service_install_failed"));
+      console.warn(serviceError);
+      try {
+        const bridgeResult = startRelayBridgeDetached({
+          relayUrl,
+          gatewayBaseUrl: localGatewayBaseUrl,
+        });
+        output.relayWorkerResult = {
+          ...bridgeResult,
+          error: serviceError,
+        };
+      } catch (fallbackError) {
+        output.relayWorkerResult = {
+          mode: "detached",
+          started: false,
+          error: String(fallbackError instanceof Error ? fallbackError.message : fallbackError),
+        };
+        console.warn(`Failed to start relay bridge worker: ${output.relayWorkerResult.error}`);
+      }
     }
   }
 
@@ -2862,6 +3500,14 @@ async function runReset({ json, relay, noRelay, gateway }) {
     });
   }
 
+  let serviceReset = null;
+  if (relayUrl && gatewayBaseUrl) {
+    try {
+      serviceReset = uninstallBridgeService();
+    } catch (error) {
+      serviceReset = { error: String(error instanceof Error ? error.message : error) };
+    }
+  }
   const stoppedBridges =
     relayUrl && gatewayBaseUrl
       ? stopBridgeProcesses({ relayUrl, gatewayBaseUrl })
@@ -2883,6 +3529,7 @@ async function runReset({ json, relay, noRelay, gateway }) {
             clearedCodes: relayResetResult.clearedCodes,
           },
     stoppedBridgeCount: stoppedBridges.count,
+    serviceReset,
     nextGatewayId: nextState.state.relayGatewayId ?? null,
     statePath: nextState.statePath,
   };
@@ -2917,6 +3564,61 @@ async function runReset({ json, relay, noRelay, gateway }) {
   console.log(t("reset_ready"));
 }
 
+async function runService({ json, relay, noRelay, gateway, serviceAction }) {
+  const configPath = resolveOpenClawConfigPath();
+  const action = String(serviceAction ?? "status").trim().toLowerCase() || "status";
+  const config = readJsonFileIfExists(configPath);
+  const section = config ? readChannelSection(config) : {};
+  const relayUrl =
+    action === "install" || action === "restart"
+      ? resolveRelayUrl({ relay, noRelay }, section)
+      : normalizeBaseUrl(relay) || (config ? resolveRelayUrl({ relay: null, noRelay }, section) : null);
+  const gatewayBaseUrl =
+    action === "install" || action === "restart"
+      ? resolveGatewayBaseUrl({ gateway }, config)
+      : normalizeBaseUrl(gateway) || (config ? resolveGatewayBaseUrl({ gateway: null }, config) : null);
+
+  let result;
+  switch (action) {
+    case "status":
+      result = getBridgeServiceStatus();
+      break;
+    case "install":
+      clearExistingBridgeRuntime({ relayUrl, gatewayBaseUrl });
+      result = installBridgeService({ relayUrl, gatewayBaseUrl });
+      break;
+    case "restart":
+      clearExistingBridgeRuntime({ relayUrl, gatewayBaseUrl });
+      result = restartBridgeService({ relayUrl, gatewayBaseUrl });
+      break;
+    case "uninstall":
+      result = uninstallBridgeService();
+      break;
+    default:
+      fail(`unknown service action: ${action}`);
+  }
+
+  const output = {
+    command: "service",
+    action,
+    relayUrl: relayUrl ?? null,
+    gatewayBaseUrl: gatewayBaseUrl ?? null,
+    ...result,
+  };
+
+  if (json) {
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
+  if (action === "uninstall") {
+    console.log(t("service_uninstalled"));
+  } else if (action === "install" || action === "restart") {
+    console.log(t("service_installed"));
+  }
+  console.log(formatServiceStatusOutput(output));
+}
+
 function runSetup({
   json,
   account,
@@ -3192,6 +3894,7 @@ function runStatus({ json }) {
   const config = readJsonFile(configPath);
   const section = readChannelSection(config);
   const creds = resolveRelayCredentialsFromSection(section);
+  const service = getBridgeServiceStatus();
 
   const status = {
     configPath,
@@ -3213,6 +3916,10 @@ function runStatus({ json }) {
     relayGatewayId: creds.gatewayId || null,
     hasRelayClientToken: Boolean(creds.clientToken),
     hasRelayGatewayToken: Boolean(creds.gatewayToken),
+    serviceManager: service.manager,
+    serviceInstalled: service.installed,
+    serviceRunning: service.running,
+    serviceTarget: service.target,
     linkedUserId:
       typeof section?.linkedUserId === "string" && section.linkedUserId.trim()
         ? section.linkedUserId.trim()
@@ -3254,6 +3961,20 @@ function runStatus({ json }) {
       value: status.hasAccessToken ? t("set") : t("missing"),
     }),
   );
+  console.log(t("service_status_manager", { value: status.serviceManager }));
+  console.log(
+    t("service_status_installed", {
+      value: status.serviceInstalled ? t("yes") : t("no"),
+    }),
+  );
+  console.log(
+    t("service_status_running", {
+      value: status.serviceRunning ? t("yes") : t("no"),
+    }),
+  );
+  if (status.serviceTarget) {
+    console.log(t("service_status_target", { value: status.serviceTarget }));
+  }
   console.log(t("status_linked_user", { value: status.linkedUserId ?? t("not_linked") }));
 }
 
@@ -3273,6 +3994,9 @@ async function main() {
     case "bridge":
       await runBridge(options);
       return;
+    case "service":
+      await runService(options);
+      return;
     case "pair-url":
       runPairUrl(options);
       return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matelink/cli",
-  "version": "2026.4.10",
+  "version": "2026.4.12",
   "private": false,
   "description": "Relay-first CLI for pairing and bridging OpenClaw gateway traffic",
   "type": "module",