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 uninstall --service" to remove the gateway service while keeping your config and workspace. Add --dry-run first to preview what will be removed. On Linux you can also disable it manually with "systemctl --user disable --now openclaw-gateway"; 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.

← All Guides

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.

Short answer: run openclaw onboard --install-daemon. It registers OpenClaw with your OS service manager — systemd on Linux, launchd on macOS, the Service Control Manager on Windows — so the agent starts at boot, survives closing the terminal, and is restarted automatically if it crashes. Verify with systemctl --user status openclaw-gateway. Undo it with openclaw uninstall --service.

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 the OpenClaw gateway service for the current user
openclaw onboard --install-daemon

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

# Unattended install (CI, cloud-init, Ansible)
openclaw onboard --install-daemon --non-interactive --accept-risk

The related daemon flags on openclaw onboard are:

Flag	What it does
`--install-daemon`	Install the gateway service
`--no-install-daemon`	Skip the gateway service install
`--skip-daemon`	Also skips the service install
`--daemon-runtime <runtime>`	Daemon runtime (currently `node`)

Flags verified against OpenClaw 2026.7.1. There is no --uninstall-daemon flag — removal goes through openclaw uninstall --service, covered below.

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

The systemd unit is named openclaw-gateway, not openclaw. This trips people up constantly: systemctl --user status openclaw fails with “Unit openclaw.service could not be found” even though the service is installed and running perfectly. If you run named profiles, each gets its own unit suffixed with the profile name (openclaw-gateway-work.service).

Linux (systemd)

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

# System-level install
sudo systemctl status openclaw-gateway

# Follow logs
journalctl --user -u openclaw-gateway -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 gateway service, keep your config and workspace (all platforms)
openclaw uninstall --service

# Preview exactly what would be removed first
openclaw uninstall --service --dry-run

# Or manually:
# Linux
systemctl --user disable --now openclaw-gateway
rm ~/.config/systemd/user/openclaw-gateway.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-gateway 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).