OpenClaw 三种运行模式如何避免冲突：判断、切换与排障

OpenClaw 常见有三种运行方式：系统服务模式、独立进程模式、PM2 模式。三者都能启动 Gateway，但如果混用，最容易出现端口冲突、进程残留和配置错位。

这篇文档给你一套可直接执行的规范：

1. 先理解冲突根因。
2. 学会快速判断当前模式。
3. 用统一 SOP 安全切换。
4. 出问题时按排障表处理。

1. 三种模式的本质区别

模式	管理主体	适用场景	典型特征
系统服务模式	launchctl（macOS）	本机长期常驻、开机自启	进程父级通常是 launchd
独立进程模式	终端会话（bash/zsh）	前台调试、临时测试	终端关闭后通常进程结束
PM2 模式	PM2 进程管理器	跨平台常驻、日志与监控	pm2 status 可见在线进程

2.冲突原因

三种模式都在做同一件事：启动 OpenClaw Gateway。冲突集中在三类。

冲突类型	表现	常见触发方式
端口占用	port is already in use	两种模式同时监听同一端口
进程管理混乱	关掉一个还有一个在跑	同时存在系统服务进程和 PM2/独立进程
配置加载不一致	同样命令行为不同	不同模式读取了不同配置来源

核心结论：同一时间只保留一个管理入口。

3. 运行原则

1. 同一时间只运行一种模式。
2. 切换前必须清场（停服务、停 PM2、杀独立进程、验端口）。
3. 切换后必须验证（状态 + 端口 + 日志）。

4. 切换前通用清场

# 1) 关闭系统服务模式
openclaw gateway stop 2>/dev/null
openclaw gateway bootout 2>/dev/null

# 2) 关闭 PM2 模式
pm2 stop openclaw-gateway 2>/dev/null
pm2 delete openclaw-gateway 2>/dev/null

# 3) 关闭独立进程模式
pkill -f "openclaw gateway" 2>/dev/null
lsof -ti :8765 | xargs kill -9 2>/dev/null

# 4) 验证无残留
ps aux | grep -v grep | grep "openclaw gateway"
lsof -i :8765

判定标准：最后两条命令都没有有效输出，才算清场完成。

5. 如何判断当前是哪种模式

5.1 快速三步

# 系统服务模式检查
openclaw gateway status

# PM2 模式检查
pm2 status openclaw-gateway

# 独立进程检查
ps aux | grep -v grep | grep "openclaw gateway"

5.2 判断规则

结果特征	结论
openclaw gateway status 显示 Loaded/Running 为 true	系统服务模式
pm2 status openclaw-gateway 显示 online	PM2 模式
仅在 ps 中看到进程，且父进程是终端	独立进程模式
三者都查不到	当前无运行实例

5.3 模糊场景用父进程确认

PID=$(ps aux | grep -v grep | grep "openclaw gateway" | awk '{print $2}')
ps -o ppid= -p $PID | xargs ps -o comm= -p {}

输出解释：

• launchd -> 系统服务模式
• pm2 或 pm2-runtime -> PM2 模式
• bash/zsh/iTerm2 -> 独立进程模式

6. 三种常见切换场景

6.1 独立进程 -> 系统服务

# 先清场
# ...执行第 4 节通用清场...

openclaw gateway install
openclaw gateway bootstrap
openclaw gateway start
openclaw gateway status

6.2 系统服务 -> PM2

# 先清场
# ...执行第 4 节通用清场...

pm2 start openclaw --name "openclaw-gateway" -- gateway --port 18790
pm2 status openclaw-gateway
lsof -i :18790

如需 PM2 开机自启：

pm2 startup
pm2 save

6.3 PM2 -> 独立进程（前台调试）

# 先清场
# ...执行第 4 节通用清场...

openclaw gateway --port 18790

新终端验证：

ps aux | grep -v grep | grep "openclaw gateway"
lsof -i :18790

7. 可选方案：多实例测试时分端口

只在测试场景建议同时跑多实例，并且必须分端口。

模式	建议端口
系统服务模式	8765
独立进程模式	18790
PM2 模式	18791

示例：

openclaw gateway --port 18790
pm2 start openclaw --name "openclaw-pm2" -- gateway --port 18791

8. 故障排查速查

8.1 报错 port is already in use

lsof -i :8765
kill -9 <PID>

8.2 系统服务启动失败

openclaw gateway bootout
openclaw gateway bootstrap
openclaw gateway start

8.3 PM2 状态 errored

pm2 logs openclaw-gateway

先看日志中的路径、端口和参数是否正确，再修正启动命令。