这是为您整理的 OpenClaw macOS 启动故障排查与修复完整记录。您可以将其保存为笔记，以便未来遇到类似问题时参考。
📝 OpenClaw macOS 启动故障修复指南
1. 问题现象
在 macOS 上尝试启动 OpenClaw 网关服务时，服务无法正常运行，端口 18789 未被监听。
- 症状：lsof -i :18789 无输出。
- 状态：launchctl print 显示服务处于 spawn scheduled 状态，但 last exit code = 1（表示进程启动后立即崩溃）。
- 日志：系统日志 (log show) 无明显报错，但应用错误日志中有重复的崩溃记录。
2. 根本原因分析
通过查看错误日志文件 (~/.openclaw/logs/gateway.err.log)，发现核心错误为：
Error: Cannot find module ‘…/openclaw@2026.2.23_…/dist/index.js’
code: ‘MODULE_NOT_FOUND’
原因详解：
macOS 的 launchd 配置文件 (plist) 中硬编码了 旧版本 (2026.2.23) 的绝对路径。由于用户升级了 OpenClaw 或 pnpm 的全局包结构发生了变化，该路径已失效。launchd 试图用旧路径启动 Node.js，导致找不到模块而立即退出，并陷入无限重启循环。
3. 解决方案步骤
第一步：确认错误并清理旧配置
首先确认报错信息，然后停止服务并删除错误的配置文件，强制系统重新生成。
# 1. 查看具体报错（确认为 MODULE_NOT_FOUND）
cat /Users/mrex/.openclaw/logs/gateway.err.log
# 2. 停止当前的 LaunchAgent 服务
launchctl bootout gui/$(id -u)/ai.openclaw.gateway 2>/dev/null || true
# 3. 删除旧的、包含错误路径的 plist 配置文件
rm -f ~/Library/LaunchAgents/ai.openclaw.gateway.plist
第二步：重新安装/注册服务
运行 OpenClaw 的安装命令。该命令会自动检测当前正确的安装路径（包括 pnpm 的最新链接结构），并生成新的 plist 文件。
# 重新生成 LaunchAgent 配置
openclaw gateway install
注：此时终端可能会提示关于 iMessage 配置的警告（如 groupPolicy 设置），这不影响网关启动，可稍后处理。
第三步：加载新配置并启动
让 launchd 加载新生成的配置文件并启动服务。
# 1. 加载新的 LaunchAgent
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist
# 2. 等待几秒让进程完全启动
sleep 3
第四步：验证服务状态
检查端口 18789 是否处于监听状态。
lsof -i :18789
成功标志：
输出中包含 LISTEN 状态和 node 进程，例如：
COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
node 2523 mrex 14u IPv4 … 0t0 TCP *:18789 (LISTEN)
第五步：启动终端界面
确认网关正常后，即可启动主程序。
openclaw tui
4. 附加建议：处理配置警告
如果在 install 步骤中看到如下警告：
channels.imessage.groupPolicy is “allowlist” but groupAllowFrom is empty
这意味着 iMessage 群聊消息将被丢弃。如需接收群消息，请编辑配置文件：
- 打开配置：nano ~/.openclaw/config.yaml
- 找到 channels.imessage 部分。
- 将 groupPolicy 修改为 “open”，或在 groupAllowFrom 中添加允许的联系人 ID。
- 保存并重启服务（通常 openclaw 会自动热重载，或手动执行 launchctl kickstart）。
5. 常用命令速查表
操作 命令
查看网关状态 launchctl print gui/$(id -u)/ai.openclaw.gateway
查看错误日志 tail -n 20 ~/.openclaw/logs/gateway.err.log
检查端口监听 lsof -i :18789
停止服务 launchctl bootout gui/$(id -u)/ai.openclaw.gateway
重启服务 launchctl kickstart gui/$(id -u)/ai.openclaw.gateway
重置配置 rm ~/Library/LaunchAgents/ai.openclaw.gateway.plist && openclaw gateway install
总结：此类问题通常由 pnpm 全局包路径变更 导致 launchd 配置过期引起。核心解决思路是删除旧 plist 并运行 openclaw gateway install 让程序自动修复路径。
