OpenClaw（系统服务模式与独立进程模式）

OpenClaw 系统服务模式 vs 独立进程模式

核心区别

对比维度	系统服务模式（LaunchAgent）	独立进程模式（直接启动）
运行本质	注册为 macOS 系统级后台服务，由 `launchctl` 管理	普通 Node.js 进程，由终端或用户直接管控
启动方式	先 `install` 安装服务 + `bootstrap` 加载，再 `start` 启动	直接执行 `openclaw gateway --port 端口`
运行位置	后台静默运行，不占前台终端	默认前台运行（终端需保持打开），也可 `nohup` 后台运行
生命周期	可开机自启，关闭终端不影响	前台模式下关终端即停止；后台模式下重启后需手动拉起
管控命令	`openclaw gateway start/stop/restart` 或 `launchctl`	前台用 `Ctrl+C`，后台用 `kill -9 PID`
状态检测	`openclaw gateway status` 可识别 loaded/running	`openclaw gateway status` 常显示 not loaded，需用 `lsof -i :端口` 验证
依赖条件	依赖 `launchctl` 与兼容的 Node 路径（`nvm` 场景易踩坑）	只要 Node 可运行即可
容错复杂度	较复杂，服务加载/卸载链路较长	较简单，直接作用于进程

通俗类比

可以把两种模式理解为手机 App 的两种使用方式：

系统服务模式：像"开机自启 + 后台常驻"。
优点是省心、常驻；缺点是配置和权限链路更复杂。
独立进程模式：像"手动打开 App"。
优点是直观好排障；缺点是不会自动常驻。

实操差异与避坑

1. 停止行为不同

系统服务模式：openclaw gateway stop 往往不只是停进程，还会触发服务卸载；之后直接 start 可能失效，需要重新加载服务。
独立进程模式：Ctrl+C 或 kill -9 PID 仅停止当前进程，重新运行命令即可恢复。

2. 日志查看方式不同

系统服务模式：日志通常在 /tmp/openclaw/openclaw-日期.log，需要手动查看文件。
独立进程模式：日志直接实时输出在终端，调试更直观。

3. 端口冲突处理不同

系统服务模式：默认端口冲突时，通常要改服务配置。
独立进程模式：启动时直接指定端口，如 --port 18790，处理更快。

penClaw 系统服务模式 vs 独立进程模式详解

一、系统服务模式（LaunchAgent）

这种模式是将 OpenClaw 注册为 macOS 系统后台服务，核心依赖 launchctl 管理，操作链路稍长但能实现常驻/开机自启。

1. 完整启动流程

bash 复制代码

# 步骤1：安装服务（生成 LaunchAgent 配置文件到 ~/Library/LaunchAgents/）
openclaw gateway install

# 步骤2：加载服务（将配置文件注册到 launchctl 中）
openclaw gateway bootstrap

# 步骤3：启动服务（真正运行 OpenClaw 网关）
openclaw gateway start

# 验证启动状态（关键：确认服务已加载且运行）
openclaw gateway status
# 正常输出示例：Loaded: true, Running: true, PID: 12345

2. 关闭服务（停止+卸载，彻底关停）

bash 复制代码

# 步骤1：停止服务进程
openclaw gateway stop

# 步骤2：卸载服务（从 launchctl 中移除配置，可选但建议做，避免残留）
openclaw gateway bootout

# 验证关闭状态
openclaw gateway status
# 正常输出示例：Loaded: false, Running: false

3. 关闭后重启

bash 复制代码

# 方式1：先关停再重新加载启动（推荐，避免缓存问题）
openclaw gateway stop && openclaw gateway bootout
openclaw gateway bootstrap && openclaw gateway start

# 方式2：快速重启（部分版本支持，简化操作）
openclaw gateway restart
# 注意：restart 本质是 stop + start，但如果服务未加载，可能失效，建议优先用方式1

关键注意事项

bootstrap/bootout 是 macOS LaunchAgent 的核心操作：bootstrap 是"加载服务配置"，bootout 是"卸载服务配置"，缺少这两步，start/stop 可能无效；
若 openclaw gateway status 显示 Loaded: true 但 Running: false，说明服务配置加载了但进程没启动，只需执行 openclaw gateway start；
开机自启：安装服务后，默认会开启开机自启，若要关闭，执行 openclaw gateway install --no-auto-start。

二、独立进程模式

这种模式是把 OpenClaw 当作普通 Node.js 进程运行，操作更直观，适合调试或临时使用。

1. 启动（分前台/后台两种方式）

方式1：前台启动（调试首选，日志实时输出）

bash 复制代码

# 基础启动（用默认端口，通常是 8765）
openclaw gateway

# 指定端口启动（避免端口冲突，推荐）
openclaw gateway --port 18790

# 验证启动：查看端口是否被占用
lsof -i :18790
# 输出中能看到 openclaw 进程即表示启动成功

方式2：后台启动（常驻运行，关闭终端不停止）

bash 复制代码

# 用 nohup 后台启动，日志输出到指定文件
nohup openclaw gateway --port 18790 > ~/.openclaw/gateway.log 2>&1 &

# 记录进程 PID（方便后续关停）
echo $! > ~/.openclaw/gateway.pid

2. 关闭（对应前台/后台模式）

方式1：关闭前台进程（最简单）

直接在启动进程的终端中按下 Ctrl + C，进程会立即停止。

方式2：关闭后台进程（两种方法）

bash 复制代码

# 方法1：用保存的 PID 文件关停（推荐）
kill -9 $(cat ~/.openclaw/gateway.pid)
rm -f ~/.openclaw/gateway.pid  # 删除 PID 文件

# 方法2：通过端口查找 PID 并关停（忘记保存 PID 时用）
PID=$(lsof -ti :18790)
if [ -n "$PID" ]; then
  kill -9 $PID
  echo "OpenClaw 进程 $PID 已停止"
else
  echo "未找到运行中的 OpenClaw 进程"
fi

3. 关闭后重启（对应前台/后台模式）

方式1：前台进程重启

先按 Ctrl + C 停止当前前台进程；
重新执行启动命令：openclaw gateway --port 18790。

方式2：后台进程重启

bash 复制代码

# 1. 先关停现有后台进程
PID=$(lsof -ti :18790)
[ -n "$PID" ] && kill -9 $PID

# 2. 重新后台启动
nohup openclaw gateway --port 18790 > ~/.openclaw/gateway.log 2>&1 &
echo $! > ~/.openclaw/gateway.pid

# 验证重启结果
lsof -i :18790

关键注意事项

前台模式：关闭终端会直接终止进程，仅适合调试；
后台模式：nohup 启动后，日志不会输出到终端，需查看指定的日志文件（如 ~/.openclaw/gateway.log）；
端口冲突：启动前若提示端口被占用，先关停对应进程，或换一个端口（如 --port 18791）。

总结

系统服务模式核心命令

启动：openclaw gateway install → bootstrap → start；
关闭：openclaw gateway stop → bootout；
重启：stop + bootout → bootstrap + start（或直接 restart）。

独立进程模式核心命令

前台启动：openclaw gateway --port 端口，关闭：Ctrl+C，重启：停掉后重新执行启动命令；
后台启动：nohup openclaw gateway --port 端口 > 日志文件 2>&1 &，关闭：kill -9 PID，重启：先关停再重新后台启动。