@ww-ai-lab/openclaw-office 2026.4.8 → 2026.4.10

package/README.en.md

@@ -125,6 +125,38 @@ OPENCLAW_GATEWAY_TOKEN=<token> openclaw-office
 
 ---
 
+## Install as a System Service (Background Mode)
+
+Register OpenClaw Office as a system service so it starts automatically on boot/login — no manual command needed. Supported on macOS (launchd) and Linux (systemd --user).
+
+### Install the Service
+
+```bash
+# Install as system service (token auto-detected, or specify manually)
+openclaw-office service install
+
+# Specify token and port
+openclaw-office service install --token <your-token> --port 3000
+```
+
+Once installed, the service **starts immediately** and runs in the background. It will be automatically launched on every subsequent boot/login.
+
+### Service Management Commands
+
+```bash
+openclaw-office service status              # Check service status
+openclaw-office service stop                # Stop the service
+openclaw-office service start               # Start the service
+openclaw-office service restart             # Restart the service
+openclaw-office service log                 # Show service logs
+openclaw-office service log --follow        # Follow log output in real time
+openclaw-office service uninstall           # Remove the system service
+```
+
+> **Tip:** After installing as a service, you can also view Gateway status and perform operations like restart from the Settings page "Service Management" panel.
+
+---
+
 ## Quick Start (from source)
 
 ### 1. Install Dependencies

package/README.md

@@ -125,6 +125,38 @@ OPENCLAW_GATEWAY_TOKEN=<token> openclaw-office
 
 ---
 
+## 安装为系统服务（后台运行）
+
+将 OpenClaw Office 注册为系统服务后，它会在开机 / 登录时自动启动，无需手动运行命令。支持 macOS（launchd）和 Linux（systemd --user）。
+
+### 安装服务
+
+```bash
+# 安装为系统服务（token 自动检测，也可手动指定）
+openclaw-office service install
+
+# 指定 token 和端口
+openclaw-office service install --token <your-token> --port 3000
+```
+
+安装完成后，服务会**立即启动**并在后台运行。后续每次开机/登录，服务将自动拉起。
+
+### 服务管理命令
+
+```bash
+openclaw-office service status              # 查看服务状态
+openclaw-office service stop                # 停止服务
+openclaw-office service start               # 启动服务
+openclaw-office service restart             # 重启服务
+openclaw-office service log                 # 查看服务日志
+openclaw-office service log --follow        # 实时跟踪日志
+openclaw-office service uninstall           # 卸载系统服务
+```
+
+> **提示：** 安装为服务后，也可通过 Settings 页面的「服务管理」面板查看 Gateway 状态和执行重启等操作。
+
+---
+
 ## 快速开始（从源码）
 
 ### 1. 安装依赖

package/bin/openclaw-office.js

@@ -11,6 +11,14 @@ import { networkInterfaces, homedir } from "node:os";
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
 const distDir = resolve(__dirname, "..", "dist");
 
+// --- Service subcommand routing ---
+// If argv[2] is "service", delegate to the service manager module.
+if (process.argv[2] === "service") {
+  const { runService } = await import("./service.js");
+  await runService();
+  process.exit(0);
+}
+
 const MIME_TYPES = {
   ".html": "text/html; charset=utf-8",
   ".js": "application/javascript; charset=utf-8",
@@ -79,6 +87,13 @@ function printHelp() {
     openclaw-office --token my-secret-token
     openclaw-office --gateway ws://192.168.1.100:18789
     PORT=3000 openclaw-office
+
+  \x1b[1mService management:\x1b[0m
+    openclaw-office service install --token <token>    # Auto-start on login/boot
+    openclaw-office service status                     # Check service status
+    openclaw-office service stop                       # Stop the service
+    openclaw-office service uninstall                  # Remove the service
+    openclaw-office service help                       # Show service help
 `);
 }
 

package/bin/platform.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+
+// Platform Service — lightweight local HTTP server for managing OpenClaw Gateway lifecycle.
+// Zero external dependencies; uses only Node.js built-in modules.
+// Binds exclusively to 127.0.0.1:18790 for security.
+
+import { createServer } from "node:http";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const HOST = "127.0.0.1";
+const PORT = parseInt(process.env.PLATFORM_PORT || "18790", 10);
+const COMMAND_TIMEOUT_MS = 30_000;
+
+function findOpenclawBin() {
+  const explicit = process.env.OPENCLAW_BIN;
+  if (explicit) return explicit;
+  return "openclaw";
+}
+
+const OPENCLAW_BIN = findOpenclawBin();
+
+function corsHeaders() {
+  return {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type",
+    "Content-Type": "application/json; charset=utf-8",
+  };
+}
+
+function sendJson(res, statusCode, data) {
+  const body = JSON.stringify(data);
+  res.writeHead(statusCode, corsHeaders());
+  res.end(body);
+}
+
+function isLocalRequest(req) {
+  const remote = req.socket.remoteAddress;
+  return remote === "127.0.0.1" || remote === "::1" || remote === "::ffff:127.0.0.1";
+}
+
+async function runCommand(args, timeoutMs = COMMAND_TIMEOUT_MS) {
+  try {
+    const { stdout, stderr } = await execFileAsync(OPENCLAW_BIN, args, {
+      timeout: timeoutMs,
+      env: { ...process.env },
+    });
+    return { ok: true, stdout: stdout.trim(), stderr: stderr.trim() };
+  } catch (err) {
+    return {
+      ok: false,
+      stdout: err.stdout?.trim() ?? "",
+      stderr: err.stderr?.trim() ?? "",
+      message: err.message,
+      code: err.code,
+    };
+  }
+}
+
+async function handleServiceStatus() {
+  const result = await runCommand(["gateway", "status", "--json"]);
+  if (result.ok) {
+    try {
+      const data = JSON.parse(result.stdout);
+      return { ok: true, data };
+    } catch {
+      return { ok: true, data: { raw: result.stdout } };
+    }
+  }
+  // gateway status may return non-zero when not running — still valid info
+  try {
+    const data = JSON.parse(result.stdout || result.stderr);
+    return { ok: true, data };
+  } catch {
+    return {
+      ok: false,
+      error: result.stderr || result.message || "Failed to get status",
+      raw: result.stdout,
+    };
+  }
+}
+
+async function handleServiceAction(action) {
+  const result = await runCommand(["gateway", action]);
+  return {
+    ok: result.ok,
+    action,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    ...(result.ok ? {} : { error: result.message }),
+  };
+}
+
+async function handleConfigSetup() {
+  const results = [];
+  for (const [key, value] of [
+    ["gateway.controlUi.dangerouslyDisableDeviceAuth", "true"],
+    ["gateway.controlUi.allowInsecureAuth", "true"],
+  ]) {
+    const r = await runCommand(["config", "set", key, value]);
+    results.push({ key, ok: r.ok, stderr: r.stderr });
+  }
+  const allOk = results.every((r) => r.ok);
+  return { ok: allOk, results };
+}
+
+const routes = new Map([
+  ["GET /api/service/status", handleServiceStatus],
+  ["POST /api/service/start", () => handleServiceAction("start")],
+  ["POST /api/service/stop", () => handleServiceAction("stop")],
+  ["POST /api/service/restart", () => handleServiceAction("restart")],
+  ["POST /api/service/install", () => handleServiceAction("install")],
+  ["POST /api/service/uninstall", () => handleServiceAction("uninstall")],
+  ["POST /api/config/setup", handleConfigSetup],
+]);
+
+const server = createServer(async (req, res) => {
+  // CORS preflight
+  if (req.method === "OPTIONS") {
+    res.writeHead(204, corsHeaders());
+    res.end();
+    return;
+  }
+
+  // Security: only accept local requests
+  if (!isLocalRequest(req)) {
+    sendJson(res, 403, { error: "Forbidden: only local connections allowed" });
+    return;
+  }
+
+  const url = new URL(req.url || "/", `http://${HOST}:${PORT}`);
+  const routeKey = `${req.method} ${url.pathname}`;
+
+  // Health check
+  if (req.method === "GET" && url.pathname === "/api/health") {
+    sendJson(res, 200, { ok: true, service: "platform", pid: process.pid });
+    return;
+  }
+
+  const handler = routes.get(routeKey);
+  if (!handler) {
+    sendJson(res, 404, { error: "Not found" });
+    return;
+  }
+
+  try {
+    const result = await handler();
+    sendJson(res, result.ok ? 200 : 500, result);
+  } catch (err) {
+    sendJson(res, 500, { error: String(err) });
+  }
+});
+
+server.listen(PORT, HOST, () => {
+  console.log(`[platform] listening on http://${HOST}:${PORT}`);
+  console.log(`[platform] openclaw bin: ${OPENCLAW_BIN}`);
+});

package/bin/service-linux.js

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+
+/**
+ * Linux systemd service manager for openclaw-office.
+ *
+ * Manages the OpenClaw Office service via systemd --user.
+ * Commands: install, uninstall, start, stop, restart, status, log
+ */
+
+import { existsSync, mkdirSync, writeFileSync, unlinkSync, readFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+
+const SYSTEMD_DIR = join(homedir(), ".config", "systemd", "user");
+const SERVICE_NAME = "openclaw-office.service";
+const SERVICE_PATH = join(SYSTEMD_DIR, SERVICE_NAME);
+const NODE_BIN = process.execPath;
+const SERVER_SCRIPT = join(__dirname, "openclaw-office.js");
+const LOG_DIR = join(homedir(), ".local", "state", "openclaw-office");
+const STDOUT_LOG = join(LOG_DIR, "openclaw-office.log");
+const STDERR_LOG = join(LOG_DIR, "openclaw-office-error.log");
+
+// --- Colors ---
+
+const C = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+  gray: "\x1b[90m",
+};
+
+function printLog(msg, color = "") { console.log(`${color}${msg}${C.reset}`); }
+function ok(msg) { printLog(`  \u2713 ${msg}`, C.green); }
+function err(msg) { printLog(`  \u2717 ${msg}`, C.red); }
+function info(msg) { printLog(`  \u2022 ${msg}`, C.cyan); }
+function warn(msg) { printLog(`  \u2022 ${msg}`, C.yellow); }
+function dim(msg) { printLog(`    ${msg}`, C.gray); }
+
+// --- Helpers ---
+
+function systemctl(args) {
+  try {
+    execSync(`systemctl --user ${args}`, { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isEnabled() {
+  return systemctl(`is-enabled ${SERVICE_NAME}`);
+}
+
+function isActive() {
+  return systemctl(`is-active ${SERVICE_NAME}`);
+}
+
+function generateService(config) {
+  const args = [];
+  args.push(SERVER_SCRIPT);
+  if (config.gatewayUrl) args.push(`--gateway ${config.gatewayUrl}`);
+  if (config.port) args.push(`--port ${config.port}`);
+  if (config.host) args.push(`--host ${config.host}`);
+  if (config.token) args.push(`--token ${config.token}`);
+
+  return `[Unit]
+Description=OpenClaw Office — Multi-Agent Monitoring Console
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=${NODE_BIN} ${args.join(" ")}
+Restart=on-failure
+RestartSec=5
+StandardOutput=append:${STDOUT_LOG}
+StandardError=append:${STDERR_LOG}
+Environment=HOME=${homedir()}
+Environment=PATH=/usr/local/bin:/usr/bin:/bin
+WorkingDirectory=${__dirname}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+function generateTimer(config) {
+  return `[Unit]
+Description=Restart OpenClaw Office if not running
+[Timer]
+OnBootSec=1min
+OnUnitActiveSec=5min
+[Install]
+WantedBy=timers.target
+`;
+}
+
+// --- Commands ---
+
+/**
+ * @param {{ token: string, gatewayUrl?: string, port?: number, host?: string }} config
+ */
+export async function install(config) {
+  if (!config.token) {
+    err("Token is required for service installation.");
+    info("Provide via --token flag or it will be auto-detected from ~/.openclaw/openclaw.json");
+    process.exit(1);
+  }
+
+  // Ensure directories
+  if (!existsSync(SYSTEMD_DIR)) {
+    mkdirSync(SYSTEMD_DIR, { recursive: true });
+  }
+  if (!existsSync(LOG_DIR)) {
+    mkdirSync(LOG_DIR, { recursive: true });
+  }
+
+  // Reload systemd user daemon
+  systemctl("daemon-reload");
+
+  // Stop existing service if active
+  if (isActive()) {
+    warn("Existing service found, stopping...");
+    systemctl(`stop ${SERVICE_NAME}`);
+  }
+
+  // Write service file
+  const service = generateService(config);
+  writeFileSync(SERVICE_PATH, service, "utf-8");
+  ok(`Service file written: ${SERVICE_PATH}`);
+
+  // Reload and enable
+  systemctl("daemon-reload");
+  systemctl(`enable ${SERVICE_NAME}`);
+  ok("Service enabled");
+
+  // Start the service
+  systemctl(`start ${SERVICE_NAME}`);
+  ok("Service started");
+
+  printLog("");
+  ok("OpenClaw Office service installed successfully!");
+  printLog("");
+  info(`Service file: ${SERVICE_PATH}`);
+  info(`Stdout log: ${STDOUT_LOG}`);
+  info(`Stderr log: ${STDERR_LOG}`);
+  printLog("");
+  info("The service will auto-start on boot and restart on failure.");
+  dim("To manage: systemctl --user start|stop|restart|status openclaw-office.service");
+  dim("To uninstall: openclaw-office service uninstall");
+}
+
+export function uninstall() {
+  if (!existsSync(SERVICE_PATH)) {
+    warn("Service not installed. Nothing to do.");
+    return;
+  }
+
+  if (isActive()) {
+    info("Stopping running service...");
+    systemctl(`stop ${SERVICE_NAME}`);
+    ok("Service stopped");
+  }
+
+  systemctl(`disable ${SERVICE_NAME}`);
+  systemctl("daemon-reload");
+
+  try {
+    unlinkSync(SERVICE_PATH);
+    ok(`Service file removed: ${SERVICE_PATH}`);
+  } catch {
+    err("Failed to remove service file");
+    process.exitCode = 1;
+  }
+
+  systemctl("daemon-reload");
+  printLog("");
+  ok("OpenClaw Office service uninstalled.");
+}
+
+export function start() {
+  if (!existsSync(SERVICE_PATH)) {
+    err("Service not installed. Run: openclaw-office service install --token <token>");
+    process.exit(1);
+  }
+  if (isActive()) {
+    warn("Service is already running.");
+    return;
+  }
+  systemctl(`start ${SERVICE_NAME}`);
+  if (isActive()) {
+    ok("Service started");
+  } else {
+    err("Failed to start service. Check logs:");
+    dim(`journalctl --user -u ${SERVICE_NAME} --no-pager -n 20`);
+    process.exitCode = 1;
+  }
+}
+
+export function stop() {
+  if (!isActive()) {
+    warn("Service is not running.");
+    return;
+  }
+  systemctl(`stop ${SERVICE_NAME}`);
+  ok("Service stopped");
+}
+
+export function restart() {
+  if (!existsSync(SERVICE_PATH)) {
+    err("Service not installed. Run: openclaw-office service install --token <token>");
+    process.exit(1);
+  }
+  systemctl(`restart ${SERVICE_NAME}`);
+  ok("Service restarted");
+}
+
+export function status() {
+  if (!existsSync(SERVICE_PATH)) {
+    warn("Service not installed");
+    printLog("");
+    dim("Install with: openclaw-office service install --token <token>");
+    return;
+  }
+
+  info(`Service file: ${SERVICE_PATH}`);
+
+  if (isActive()) {
+    ok("Status: active (running)");
+  } else {
+    err("Status: inactive (dead)");
+  }
+
+  if (isEnabled()) {
+    ok("Enabled: yes (auto-start on boot)");
+  } else {
+    warn("Enabled: no");
+  }
+
+  // Show recent journal entries
+  try {
+    const journal = execSync(
+      `journalctl --user -u ${SERVICE_NAME} --no-pager -n 10 2>/dev/null || echo "(journalctl not available)"`,
+      { stdio: "pipe" }
+    ).toString();
+    if (journal.trim()) {
+      printLog("");
+      info("Recent journal entries:");
+      dim(journal.trim());
+    }
+  } catch { /* ok */ }
+}
+
+export function showLogs(follow = false) {
+  // Try journalctl first, fall back to file
+  try {
+    if (follow) {
+      execSync(`journalctl --user -u ${SERVICE_NAME} -f 2>/dev/null`, { stdio: "inherit" });
+      return;
+    } else {
+      const output = execSync(
+        `journalctl --user -u ${SERVICE_NAME} --no-pager -n 100 2>/dev/null`,
+        { stdio: "pipe" }
+      ).toString();
+      if (output.trim()) {
+        console.log(output.trim());
+        return;
+      }
+    }
+  } catch { /* fall back to file */ }
+
+  // Fall back to file-based log
+  if (!existsSync(STDOUT_LOG)) {
+    warn("No log file found.");
+    return;
+  }
+  try {
+    if (follow) {
+      execSync(`tail -f "${STDOUT_LOG}"`, { stdio: "inherit" });
+    } else {
+      const content = readFileSync(STDOUT_LOG, "utf-8");
+      console.log(content);
+    }
+  } catch (e) {
+    err("Failed to read log file");
+  }
+}
+
+export function printHelp() {
+  console.log(`
+  ${C.cyan}OpenClaw Office — Service Management (Linux)${C.reset}
+
+  ${C.bold}Usage:${C.reset}
+    openclaw-office service <command> [options]
+
+  ${C.bold}Commands:${C.reset}
+    install     Install as a systemd --user service (auto-start on boot)
+    uninstall   Remove the systemd service
+    start       Start the service
+    stop        Stop the service
+    restart     Restart the service
+    status      Show service status
+    log         Show service logs (add --follow to tail)
+
+  ${C.bold}Install options:${C.reset}
+    --token <token>      Gateway auth token (required)
+    --gateway <url>      Gateway WebSocket URL
+    --port <port>        Server port (default: 5180)
+    --host <host>        Bind address (default: 0.0.0.0)
+
+  ${C.bold}Examples:${C.reset}
+    openclaw-office service install --token my-token
+    openclaw-office service install --token my-token --port 3000
+    openclaw-office service status
+    openclaw-office service log --follow
+`);
+}