Complete reference for openclaw daemon, installing, starting, stopping, and monitoring the Gateway as a background system service across macOS, Linux, and Windows.
What does Openclaw Daemon do?
It manages the OpenClaw Gateway as a persistent background service registered with your operating system’s process supervisor, launchd on macOS, systemd on Linux, and schtasks on Windows. Once installed, the Gateway starts automatically on login or boot, survives terminal sessions closing, and can be managed without knowing OS-specific service commands. Think of it as pm2 or a systemd unit file, but built into the CLI and cross-platform.
Pro Tip: This is the standard method for Installing OpenClaw on a VPS or a dedicated server where you need the gateway to remain active 24/7 without an open SSH session.
Legacy Alias — Migrate to Openclaw Gateway
The daemon namespace is a legacy alias for openclaw gateway. Both namespaces expose identical subcommands and accept the same flags, nothing breaks if you keep using daemon, but new scripts should use openclaw gateway instead. The one-line sed migration covers bulk script updates. Check Command Options before running daemon install, the –port and –runtime flags are only available at install time and require an uninstall + reinstall cycle to change.
Legacy Namespace
openclaw daemon is a legacy alias. It is generally recommended to migrate your scripts to use openclaw gateway instead, for example, replace openclaw daemon restart with openclaw gateway restart.
Subcommand Reference
Six subcommands covering the full Gateway service lifecycle. All are available identically under both openclaw daemon and openclaw gateway.
| openclaw daemon status Shows the service installation state and probes the Gateway’s health. The first diagnostic step, confirms whether the service is installed, whether it’s currently running, and whether the Gateway is responding to requests. |
| openclaw daemon install Installs the Gateway as a background service using your system’s supervisor. Platform detection is automatic, the CLI picks the right supervisor for your OS. macOS launchdLinux systemdWindows schtasks |
| openclaw daemon start Starts the installed Gateway service. Requires the service to be registered first via daemon install. Use after a manual stop or if the service didn’t auto-start after a reboot. |
| openclaw daemon stop Stops the running Gateway service without uninstalling it. The service definition remains in place and can be restarted at any time with daemon start. |
| openclaw daemon restart Restarts the Gateway service. The most common operation after a configuration change, equivalent to stop then start in one command. |
| openclaw daemon uninstall Removes the Gateway service registration from your OS supervisor entirely. Does not delete your configuration files, only the service entry is removed. Re-run daemon install to re-register. |
common usage examples
openclaw daemon status openclaw daemon install openclaw daemon start openclaw daemon stop openclaw daemon restart openclaw daemon uninstall
Command Options
Flags are scoped to specific subcommands. Not all flags apply to all commands, the groupings below reflect exactly what each subcommand accepts.
status flags
| Flag | Description |
|---|---|
| –url | Gateway WebSocket URL to probe. Defaults to your configured Gateway URL. |
| –token | Auth token used when probing the Gateway endpoint. |
| –password | Password-based auth alternative to –token for the health probe request. |
| –timeout | Request timeout in milliseconds for the Gateway health probe. |
| –no-probe | Skips the live health probe and only checks service installation state. Faster, but won’t tell you if the Gateway process is stuck. |
| –deep | Runs a deeper diagnostic probe with additional health checks beyond basic reachability. |
| –json | Outputs status as machine-readable JSON. Useful in CI or scripted health checks. |
install flags
| Flag | Description |
|---|---|
| –port | Sets the port the Gateway listens on. Install-time only, requires uninstall + reinstall to change afterward. |
--runtime <node|bun> | Selects the JavaScript runtime for the Gateway process. Defaults to the runtime detected in your environment. |
| –token | Embeds an auth token into the service definition at install time. |
| –force | Forces reinstallation even if a service is already registered. Use to recover from a broken install state. |
| –json | Outputs the install result as machine-readable JSON. |
lifecycle flags
| Flag | Description |
|---|---|
| –json | Outputs the result as machine-readable JSON. Accepted by all four lifecycle subcommands. |
–port and –runtime are install-time only. To change the port after installation, run openclaw daemon uninstall then openclaw daemon install --port <new-port>.
Migration to Openclaw Gateway
A straight find-and-replace. No flag changes, no behavioral changes, just the namespace prefix.
before and after
# Before — legacy namespaceopenclaw daemon statusopenclaw daemon installopenclaw daemon restart# After — modern namespace (identical behavior) openclaw gateway status openclaw gateway install openclaw gateway restart
sed one-liner for bulk migration
# Replace in all .sh files recursively sed -i 's/openclaw daemon/openclaw gateway/g' **/*.sh
