What does openclaw onboard --install-daemon do?

It registers OpenClaw with your OS service manager (systemd on Linux, launchd on macOS, Windows Service on Windows) so the agent starts at boot, stays running after you close the terminal, and restarts automatically if it crashes.

Do I need --install-daemon if I use OpenClaw Launch?

No. OpenClaw Launch runs your agent as a managed Docker container with automatic restarts and health monitoring — the daemon setup is only for self-hosted installations on your own machine.

How do I uninstall the OpenClaw daemon?

Run "openclaw onboard --uninstall-daemon" to remove it cleanly on all platforms. On Linux you can also disable with "systemctl --user disable --now openclaw"; on macOS use "launchctl unload"; on Windows use "sc.exe delete OpenClaw" from an admin PowerShell.

Can I run the daemon alongside PM2 or tmux?

No. Two supervisors trying to manage the same OpenClaw process will fight and cause crash loops. Pick one — daemon (systemd/launchd/Windows Service), PM2, or a manual tmux session.

← Home

Command Reference

openclaw onboard --install-daemon

The --install-daemon flag on openclaw onboard installs the OpenClaw background service so your agent keeps running after you close the terminal. This page explains what the flag does, when to use it, and how to verify or undo the install on Linux, macOS, and Windows.

What It Does

openclaw onboard --install-daemon registers OpenClaw with your operating system's service manager so the agent:

Starts automatically at boot, no terminal required
Keeps running after you close the shell that launched it
Gets restarted by the OS if it crashes
Logs through the system log facility (journalctl, launchd, Event Viewer)

On each platform it uses the native supervisor:

Linux — installs a systemd user or system unit
macOS — installs a launchd plist under ~/Library/LaunchAgents
Windows — registers a Windows Service via the Service Control Manager

When You Need It (and When You Don't)

You want the daemon when:

You run OpenClaw on a always-on home server, NAS, or VPS
You want the agent to survive reboots without manually restarting
You connect chat channels (Telegram / Discord / Slack) that expect the agent to stay online
You're running on Windows and want OpenClaw to start with the machine

You do NOT need it when:

You just want to try OpenClaw interactively — run openclaw in the foreground
You are using OpenClaw Launch — the managed service already runs your agent as a supervised container, no daemon setup required
You use tmux, screen, or PM2 for supervision — these conflict with the daemon; pick one

Usage

Run the command after installing OpenClaw:

# Install OpenClaw daemon for the current user
openclaw onboard --install-daemon

# With a specific port
openclaw onboard --install-daemon --port 7777

# System-wide install (requires sudo on Linux)
sudo openclaw onboard --install-daemon --system

After a successful install, the daemon is started immediately and enabled on boot. You can close the terminal; your agent keeps running.

Verifying the Daemon Is Running

Linux (systemd)

# User-level install (default)
systemctl --user status openclaw

# System-level install
sudo systemctl status openclaw

# Follow logs
journalctl --user -u openclaw -f

macOS (launchd)

# Check status
launchctl list | grep openclaw

# Follow logs (location printed at install time)
tail -f ~/Library/Logs/openclaw.log

Windows

# PowerShell (as admin)
Get-Service OpenClaw

# Or via services.msc — find "OpenClaw" in the list

Uninstalling the Daemon

If you want to go back to running OpenClaw manually or switch to a different supervisor:

# Remove the daemon (all platforms)
openclaw onboard --uninstall-daemon

# Or manually:
# Linux
systemctl --user disable --now openclaw
rm ~/.config/systemd/user/openclaw.service

# macOS
launchctl unload ~/Library/LaunchAgents/org.openclaw.plist
rm ~/Library/LaunchAgents/org.openclaw.plist

# Windows (admin PowerShell)
Stop-Service OpenClaw
sc.exe delete OpenClaw

Common Issues

"Permission denied" on Linux

If you see permission errors, you probably need to choose between user-level and system-level installation. User-level (--user, the default) places the unit in ~/.config/systemd/user/ and requires no sudo. System-level (--system) places it in /etc/systemd/system/ and needs sudo. Don't mix — pick one.

Daemon installed but the agent won't start

Check the logs (journalctl --user -u openclaw on Linux). The most common causes:

Port already in use (another OpenClaw or PM2 instance)
Missing ~/.openclaw/openclaw.json config file
Gateway pairing not completed — see Gateway Pairing Fix
Model API key invalid or out of credits

Service Manager Conflict

Don't run the daemon at the same time as PM2, tmux, or openclaw start in the foreground. Two supervisors trying to own the same process causes crash loops. Uninstall the daemon before switching to a different supervision approach.

Easier Alternative: OpenClaw Launch

Setting up systemd / launchd / Windows Services is fine for hobby deployments, but it's a lot of moving parts to maintain on a single machine. If you want the "always-on" property without the daemon plumbing, OpenClaw Launch runs your agent as a managed Docker container with automatic restarts, log retention, and health monitoring — Lite plan at $3 first month ($6/mo after).