openclaw daemon
Manage the OpenClaw Gateway as a system background service.
Usage
openclaw daemon [command] [options]
Commands
install
Install the gateway as a system service.
openclaw daemon install [options]
- macOS: LaunchAgent (
~/Library/LaunchAgents/ai.openclaw.gateway.plist)
- Linux: systemd user service (
~/.config/systemd/user/openclaw-gateway.service)
- Windows: Task Scheduler task
Overwrite existing service configuration
start
Start the gateway service.
Starts the installed service using the platform’s service manager:
- macOS:
launchctl load
- Linux:
systemctl --user start
- Windows:
schtasks /run
stop
Stop the gateway service.
Stops the running service:
- macOS:
launchctl unload
- Linux:
systemctl --user stop
- Windows:
schtasks /end
restart
Restart the gateway service.
Equivalent to running stop followed by start.
status
Show service install status and probe the Gateway.
openclaw daemon status [options]
uninstall
Remove the gateway service.
openclaw daemon uninstall
- macOS: Removes LaunchAgent plist
- Linux: Removes systemd service unit
- Windows: Removes Task Scheduler task
Uninstalling stops the service and removes the service configuration, but does not delete the OpenClaw installation or configuration.
Examples
# Install the gateway service
openclaw daemon install
# Start the service
openclaw daemon start
# Check status
openclaw daemon status
# Restart service
openclaw daemon restart
# Stop service
openclaw daemon stop
# Check if running
openclaw daemon status
# Reinstall service (overwrites existing)
openclaw daemon install --force
# Or uninstall then install
openclaw daemon uninstall
openclaw daemon install
# Check status with details
openclaw daemon status
# JSON output for scripting
openclaw daemon status --json
macOS (LaunchAgent)
The service is installed as a LaunchAgent at:
~/Library/LaunchAgents/ai.openclaw.gateway.plist
Service Configuration
The plist includes:
- Automatic startup on login
- Standard output/error logging
- Restart on crash
- Environment variables
Manual Management
# Load service
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist
# Unload service
launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
# View logs
log show --predicate 'subsystem == "ai.openclaw"' --last 1h
Linux (systemd)
The service is installed as a user service at:
~/.config/systemd/user/openclaw-gateway.service
Service Configuration
The unit file includes:
- User service (no root required)
- Restart on failure
- Standard output to journal
- Environment variables
User Lingering
For the service to run when not logged in, enable lingering:
sudo loginctl enable-linger $USER
Without lingering enabled, systemd stops user services on logout. The doctor command will detect this and offer to enable lingering.
Manual Management
# Reload systemd after changes
systemctl --user daemon-reload
# Start service
systemctl --user start openclaw-gateway
# Stop service
systemctl --user stop openclaw-gateway
# Enable auto-start
systemctl --user enable openclaw-gateway
# View logs
journalctl --user -u openclaw-gateway -f
Windows (Task Scheduler)
The service is installed as a scheduled task.
Service Configuration
- Runs on user login
- Background execution
- Restart on failure
Manual Management
# Start task
schtasks /run /tn "OpenClaw Gateway"
# Stop task
schtasks /end /tn "OpenClaw Gateway"
# Query status
schtasks /query /tn "OpenClaw Gateway"
For Windows, WSL2 is recommended for better compatibility. Install OpenClaw in WSL2 and use systemd for service management.
Environment Variables
The daemon service inherits environment variables from:
- Service configuration (set during install)
- User environment (shell profile)
- Config file (
~/.openclaw/openclaw.json)
Common environment variables:
Gateway authentication token
OPENCLAW_GATEWAY_PASSWORD
Gateway authentication password
Node environment (production, development)
Configuration profile name
Logging
Service logs are managed by the platform’s logging system:
macOS Unified Logs
# View recent logs
log show --predicate 'subsystem == "ai.openclaw"' --last 1h
# Follow logs
log stream --predicate 'subsystem == "ai.openclaw"'
# Or use the clawlog helper
./scripts/clawlog.sh
Linux systemd Journal
# View logs
journalctl --user -u openclaw-gateway
# Follow logs
journalctl --user -u openclaw-gateway -f
# View last 100 lines
journalctl --user -u openclaw-gateway -n 100
Via OpenClaw CLI
Use the logs command to view gateway logs:
# Tail logs
openclaw logs
# Follow logs
openclaw logs --follow
# Last 500 lines
openclaw logs --limit 500
Troubleshooting
Service Won’t Start
-
Check installation:
-
Check gateway config:
openclaw config get gateway
-
Run diagnostics:
-
Try manual start:
openclaw gateway run --verbose
-
Check logs:
openclaw logs --limit 200
-
Check port availability:
-
Check authentication:
openclaw config get gateway.auth
Service Stops on Logout (Linux)
Enable user lingering:
sudo loginctl enable-linger $USER
loginctl show-user $USER | grep Linger
Linger=yes.
Permission Errors
Ensure the service runs as your user (not root):
# macOS
launchctl list | grep openclaw
# Linux
systemctl --user status openclaw-gateway
Automatic Startup
By default, the daemon starts automatically:
- macOS: On user login (LaunchAgent)
- Linux: When systemd user session starts (requires lingering)
- Windows: On user login (Task Scheduler)
To disable automatic startup:
macOS
launchctl unload -w ~/Library/LaunchAgents/ai.openclaw.gateway.plist
Linux
systemctl --user disable openclaw-gateway
Windows
schtasks /change /tn "OpenClaw Gateway" /disable
- gateway - Run gateway directly (foreground)
- logs - View gateway logs
- status - Check overall system status
- doctor - Diagnose service issues
