OpenClaw-自启动与手动启动配置说明

作者：路人丁1991
OpenClaw 自启动服务配置与手动启动说明-了解你的私人助理启动+启动日志

本文档说明 Gateway 自启动服务的安装、加载逻辑，以及 macOS 与 Linux 下配置变更后该如何操作；并梳理常见报错（如「Service unit not found」、重复插件警告）的原因与处理方式。
<hr>一、概念区分

1.1 自启动 vs 手动启动

方式	说明	典型命令
自启动（守护进程）	由系统在登录/开机时加载并监管，Gateway 常驻后台；日志由 launchd/systemd 重定向到文件。	openclaw gateway install 安装后，由系统自动拉起；日常用 start/stop/restart 控制。
手动启动（前台）	在当前终端运行，关掉终端或 Ctrl+C 即退出；不依赖 plist/systemd。	openclaw gateway 或 openclaw gateway --port 18789

1.2 两类「配置」不要混淆

配置	是什么	改完之后要做什么
应用配置	openclaw.json（插件、渠道、网关端口、认证等）	重启 Gateway 进程即可（openclaw gateway restart），不需要重新执行 gateway install。
服务配置	macOS：~/Library/LaunchAgents/ai.openclaw.gateway.plist Linux：~/.config/systemd/user/openclaw-gateway.service	改的是由谁、在什么环境下启动 Gateway。见下文「何时需要重新 install / daemon-reload」。

<hr>二、何时需要「重新安装」服务

2.1 不需要重新 install 的情况

只改了 openclaw.json（插件、渠道、端口、token 等）
→ 只需 重启 Gateway：openclaw gateway restart（或 Linux 下 systemctl --user restart openclaw-gateway.service）。只改了 ~/.openclaw.env（如 OPENCLAW_STATE_DIR）
→ 若希望已安装的守护进程用新环境，需要重新 install（因为 plist/unit 里写死了安装时的环境变量）。

2.2 需要重新 install（或 Linux 下 daemon-reload + restart）的情况

macOS：希望改 Node 路径、openclaw 入口路径、环境变量、日志路径 等写入 plist 的内容 → 执行 openclaw gateway install --force，会重写 plist 并再次 bootstrap 到 launchd。Linux：改动了 systemd 单元文件（ExecStart、Environment、日志路径等）→ 执行 systemctl --user daemon-reload，再 systemctl --user restart openclaw-gateway.service；若尚未安装服务，则执行 openclaw gateway install 会写 unit 并执行 daemon-reload + enable + restart。

2.3 macOS 特例：「Service unit not found」为何要再执行一次 install

现象：执行 openclaw gateway start 或 status 时报 「Service unit not found」、「Service not installed. Run: openclaw gateway install」，但 ~/Library/LaunchAgents/ai.openclaw.gateway.plist 文件还在。

• 原因：
  
  install 做两件事：① 写/更新 plist 文件 ② 用 launchctl bootstrap 把该 plist 注册进 launchd。若之后执行过 launchctl bootout、或系统/用户会话异常导致 job 被卸载，则 plist 仍在磁盘上，但 launchd 里已经没有这个 job。openclaw gateway start 不会自动替你 bootstrap，只会检测「job 是否在 launchd 里」；不在就报错并提示先 install。
  
  
  

原文地址：https://blog.csdn.net/qq_14834057/article/details/158542142