$cd ../troubleshooting/
Medium💻 Platform#macOS
Mac Mini：重启后网关不自动启动
// 网关手动运行正常，但重启后失效。在 macOS 上，网关需要一个 launchd plist 才能作为持久后台服务运行。这在初始设置时经常被遗漏。
symptoms.log
🔍 症状
✗用 'openclaw gateway start' 手动启动时网关正常工作
✗重启或断电后，机器人离线
✗在活动监视器中找不到 openclaw 进程
✗'launchctl list | grep openclaw' 返回空
install_service.sh
✅ 修复方法 1 — 安装 launchd 服务
在 ~/Library/LaunchAgents/ 中注册 launchd plist
# 最快的修复方案 — 注册为 launchd 服务 openclaw service install # 启用并启动它 openclaw service enable openclaw service start # 检查状态 openclaw service status
com.openclaw.gateway.plist
✅ 修复方法 2 — 如果安装失败，手动创建 plist
手动 plist 创建
# 手动创建 plist
cat > ~/Library/LaunchAgents/com.openclaw.gateway.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.openclaw.gateway</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/openclaw</string>
<string>gateway</string>
<string>start</string>
<string>--foreground</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
</dict>
</plist>
EOF
# 加载它
launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plistverify.sh
✅ 修复方法 3 — 验证服务状态
验证它是否正确运行
# 检查服务是否已加载 launchctl list | grep openclaw # 应该显示 PID 号和标签 # 查看日志 tail -f /tmp/openclaw-gateway.log
💡 Mac Mini M4 提示
Mac Mini M4（16GB）是最受欢迎的 OpenClaw 家用服务器。在系统设置 → 节能中启用“阻止自动睡眠”以实现全天候运行。
❓ 常见问题
Q1. 为什么不用 crontab @reboot？
crontab @reboot 可以工作但有几个局限性：(1) 进程崩溃时不会自动重启——机器人只能等到下次重启才会恢复；(2) cron 环境中的环境变量（PATH、HOME 等）可能与交互式 shell 不同，导致'命令未找到'错误；(3) 没有内置日志聚合。launchd 是 macOS 管理持久服务的原生方式，可正确处理所有这些问题。
Q2. 如何检查 plist 是否已加载并正在运行？
运行 'launchctl list | grep openclaw'——如果显示有 PID 数字的行，表示服务正在运行。如果第一列（PID）为空且状态列显示非零数字（如 127、78、1），请检查 /tmp/openclaw-gateway-err.log 的错误日志。状态 127 表示找不到二进制文件（检查 ProgramArguments 路径）。状态 78 是 plist 文件本身的权限错误。
Q3. OpenClaw 会自动创建 launchd plist 吗？
会的，如果在设置时运行了 'openclaw gateway install' 或 'openclaw onboard --install-daemon'。plist 放置在 ~/Library/LaunchAgents/com.openclaw.gateway.plist。如果在引导时跳过了这步，可以之后随时运行 'openclaw gateway install'，或使用修复方法 2 中的模板手动创建 plist。
Q4. 服务加载了但网关立即崩溃，如何诊断？
首先检查错误日志：'cat /tmp/openclaw-gateway-err.log'。常见原因：(1) ProgramArguments 中的二进制路径错误——用 'which openclaw' 验证；(2) 缺少环境变量——launchd 不继承 shell 的 PATH，在 plist 中添加 EnvironmentVariables；(3) 端口冲突——若 18789 端口已被占用，网关会立即退出；(4) 配置文件错误——运行 'openclaw config validate' 检查 YAML 语法错误。
Q5. 如何防止 Mac Mini 进入睡眠并关闭 OpenClaw？
在系统设置 → 节能中做两个设置：(1) 启用'关闭显示器时阻止自动睡眠'——这是关键设置；(2) 启用'允许网络访问唤醒'，以便远程请求可以唤醒系统。plist 中 KeepAlive: true 时，launchd 会在睡眠唤醒周期后重启 OpenClaw，但睡眠期间会有间隔。要实现真正的全天候运行，需要完全阻止睡眠。Mac Mini M4 空闲功耗只有约 7W——让它持续运行是实际可行的。
Q6. 可以将网关作为系统级 launchd 服务而非用户服务运行吗？
可以。将 plist 放在 /Library/LaunchDaemons/ 而非 ~/Library/LaunchAgents/，并用 'sudo launchctl load /Library/LaunchDaemons/com.openclaw.gateway.plist' 加载。系统级守护进程在任何用户登录前启动，默认以 root 运行——添加 'UserName' 键以特定用户身份运行。优势是即使您没有登录 Mac，服务也会启动，非常适合纯远程访问的设置。