夜雨聆风🏷️ 文章标签#OpenClaw#launchd#开机自启#踩坑指南#macOS
一、问题现象
我的Mac mini跑着OpenClaw Gateway，作为飞书BOT的后端服务。最近一次系统自动重启后，我发现Gateway没有自动启动——我登录后还得手动敲命令启动服务。
这不对啊。我明明配置了launchd服务，RunAtLoad和KeepAlive都设置了true，应该能自动启动才对。
是配置写错了？还是macOS的问题？我开始排查。
二、第一步：检查现有配置
先看看launchd配置文件有没有问题。我打开终端，检查plist文件：
# 检查文件是否存在 ls -la ~/Library/LaunchAgents/ai.openclaw.gateway.plist # 输出：文件存在，权限正常 # 检查plist语法是否正确 plutil -lint ~/Library/LaunchAgents/ai.openclaw.gateway.plist # 输出：OK文件存在，语法正确。打开plist文件，找到两个关键配置：
<key>RunAtLoad</key> <true/> // 加载时立即运行 <key>KeepAlive</key> <true/> // 进程退出后自动重启配置看起来是对的。但问题来了：配置是对的，为什么开机后没有自动启动？
三、第二步：分析日志时间线
光看配置不够，我要看看Gateway实际运行情况。打开Gateway日志文件：
tail -100 ~/.openclaw/logs/gateway.log然后查看系统重启历史：
last reboot | head -3输出显示：2026-04-10 21:29 系统重启。
时间线是这样的：
44分钟空白。系统重启后到22:13这段时间，Gateway完全没有运行。这说明launchd并没有在重启后自动加载并启动服务。
四、第三步：设计验证实验
我怀疑KeepAlive可能没有生效。想验证一下：如果我手动杀掉进程，launchd会不会自动重启？
实验步骤：
记录当前Gateway进程的PID 用kill -9强制杀掉进程 等待几秒 检查进程是否自动重启
开始实验：
# Step 1: 找到当前PID ps aux | grep openclaw-gateway | grep -v grep # 输出：amosliu 2727 ... openclaw-gateway # Step 2: 强制杀掉进程 kill -9 2727 # Step 3: 等3秒后检查 launchctl list | grep openclaw # 输出：20321 0 ai.openclaw.gateway（新PID）实验结果：原进程PID 2727被杀掉后，3秒内新进程PID 20321自动启动。KeepAlive配置正常工作！
这就有趣了。实验证明KeepAlive是生效的。那问题出在哪里？
五、根因分析：LaunchAgent的设计限制
答案在这里：
LaunchAgent vs LaunchDaemonLaunchAgent是用户级服务，需要用户登录后才加载LaunchDaemon是系统级服务，开机就启动，无需登录
我的plist文件放在~/Library/LaunchAgents/目录下，这是用户级服务的位置。macOS的设计是这样的：
系统启动，加载内核 加载系统级服务（LaunchDaemons） - 等待用户登录
用户登录后，才加载用户级服务（LaunchAgents） LaunchAgent被加载后，才启动对应的服务
关键点：LaunchAgent需要用户登录后才加载。
如果你的Mac没有设置自动登录，系统重启后会停在登录界面。此时LaunchAgent根本没有被加载，launchd根本不知道有这个服务存在，自然不会启动Gateway。
六、解决方案
知道根因后，解决方案就清晰了。有两种方案：
方案一：设置macOS自动登录（推荐）
这是最简单的方法：
系统设置 → 用户与群组 → 登录选项 → 自动登录 → 选择你的账户设置后输入账户密码确认。以后重启流程变成：
系统启动 自动登录（无需人工干预） LaunchAgent自动加载 Gateway自动启动
适合场景：Mac mini作为服务器放在家里或办公室，不需要每次手动登录。配合FileVault加密，既方便又安全。
方案二：改用LaunchDaemon（复杂）
如果你的Mac有安全顾虑，不想设置自动登录，可以改用系统级服务：
plist文件放到/Library/LaunchDaemons/目录 需要root权限 所有路径配置改用绝对路径
这个方案改动较大，不建议轻易尝试。
七、验证服务状态的常用命令
排查过程中用到的命令：
# 检查服务是否被launchd管理 launchctl list | grep openclaw # 查看服务详情 launchctl print gui/$(id -u)/ai.openclaw.gateway # 检查plist语法 plutil -lint ~/Library/LaunchAgents/ai.openclaw.gateway.plist # 查看Gateway运行日志 tail -f ~/.openclaw/logs/gateway.log # 查看系统重启历史 last reboot | head -5八、总结
一句话结论：配置是正确的，问题在macOS设计：LaunchAgent需要用户登录后才加载。解决方案：设置自动登录。
这次排查给我几个教训：
先验证配置是否正确，不要一上来就怀疑配置写错了 设计实验验证假设 缩小问题范围 理解系统设计
排查问题的思路比结果更有价值。下次遇到类似问题，你可以用同样的方法：验证配置→设计实验→缩小范围→理解系统。
相关文章：
OpenClaw配置第二个飞书BOT踩坑指南 OpenClaw向量记忆系统部署完整指南 OpenClaw技能系统使用指南
—— 爱默如深 · OpenClaw技术系列 ——
