$cd ../troubleshooting/
Medium💻 Platform#macOS
Mac Mini: Gateway Not Auto-Starting After Reboot
// The gateway runs fine manually but doesn't survive a reboot. On macOS the gateway needs a launchd plist to run as a persistent background service. This is commonly missed during initial setup.
symptoms.log
🔍 Symptoms
✗Gateway works fine when started with 'openclaw gateway start'
✗After reboot or power cut, bot goes offline
✗No openclaw process found in Activity Monitor
✗'launchctl list | grep openclaw' returns nothing
install_service.sh
✅ Fix 1 — Install the launchd Service
Registers a launchd plist in ~/Library/LaunchAgents/
# The quickest fix — register as a launchd service openclaw service install # Enable and start it openclaw service enable openclaw service start # Check status openclaw service status
com.openclaw.gateway.plist
✅ Fix 2 — Manually Create the plist if install fails
Manual plist creation
# Create the plist manually
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/>
<key>StandardOutPath</key>
<string>/tmp/openclaw-gateway.log</string>
<key>StandardErrorPath</key>
<string>/tmp/openclaw-gateway-err.log</string>
</dict>
</plist>
EOF
# Load it
launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plistverify.sh
✅ Fix 3 — Verify Service Status
Verify it's running correctly
# Check if service is loaded launchctl list | grep openclaw # Should show PID number and label # View logs tail -f /tmp/openclaw-gateway.log
💡 Mac Mini M4 Tip
The Mac Mini M4 (16GB) is the most popular dedicated OpenClaw home server. Enable 'Prevent automatic sleeping' in System Settings → Energy for 24/7 uptime.
❓ FAQ
Q1. Why not use crontab @reboot instead?
crontab @reboot works but has several limitations on macOS: (1) It doesn't automatically restart if the process crashes — the bot just stays down until next reboot. (2) The environment variables (PATH, HOME, etc.) in a cron context may differ from your interactive shell, causing 'command not found' errors. (3) There's no built-in log aggregation. launchd is the native macOS way to manage persistent services and handles all of this correctly.
Q2. How do I check if the plist is loaded and running?
Run 'launchctl list | grep openclaw' — if it shows a row with a PID number, the service is running. If the first column (PID) is empty and the status column shows a non-zero number (e.g., 127, 78, 1), check your error log at /tmp/openclaw-gateway-err.log. Status 127 means the binary wasn't found (check the ProgramArguments path). Status 78 is a permission error on the plist file itself.
Q3. Does OpenClaw auto-create the launchd plist?
Yes, if you run 'openclaw gateway install' or 'openclaw onboard --install-daemon' during setup. The plist is placed in ~/Library/LaunchAgents/com.openclaw.gateway.plist. If you skipped this step during onboarding, you can run 'openclaw gateway install' any time afterward, or create the plist manually using the template in Fix 2.
Q4. The service loads but the gateway crashes immediately. How do I diagnose this?
Check the error log first: 'cat /tmp/openclaw-gateway-err.log'. Common causes: (1) Wrong binary path in ProgramArguments — verify with 'which openclaw'. (2) Missing environment variables — launchd doesn't inherit your shell's PATH. Add an EnvironmentVariables section to the plist for any variables OpenClaw needs. (3) Port conflict — if port 18789 is already in use, the gateway exits immediately. (4) Config file error — run 'openclaw config validate' to check for YAML syntax errors.
Q5. How do I prevent the Mac Mini from sleeping and killing OpenClaw?
Two settings in System Settings → Energy: (1) Enable 'Prevent automatic sleeping when the display is off' — this is the critical one. (2) Enable 'Wake for network access' so remote requests can wake the system. With KeepAlive: true in the plist, launchd restarts OpenClaw after a sleep-wake cycle, but there will be a gap during sleep. For true 24/7 operation, prevent sleep entirely. The Mac Mini M4 uses only ~7W idle — leaving it running is practical.
Q6. Can I run the gateway as a system-level launchd service instead of a user service?
Yes. Place the plist in /Library/LaunchDaemons/ instead of ~/Library/LaunchAgents/ and load it with 'sudo launchctl load /Library/LaunchDaemons/com.openclaw.gateway.plist'. System-level daemons start before any user logs in and run as root by default — add a 'UserName' key to run as a specific user. The advantage is the service starts even before you log into the Mac, which is useful for remote-only setups.