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: 123452. 关闭服务（停止+卸载，彻底关停）
bash
# 步骤1：停止服务进程
openclaw gateway stop
# 步骤2：卸载服务（从 launchctl 中移除配置，可选但建议做，避免残留）
openclaw gateway bootout
# 验证关闭状态
openclaw gateway status
# 正常输出示例：Loaded: false, Running: false3. 关闭后重启
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.pid2. 关闭（对应前台/后台模式）
方式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 进程"
fi3. 关闭后重启（对应前台/后台模式）
方式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，重启：先关停再重新后台启动。