Skip to main content

​
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]
Installs the appropriate service for your platform:
  • macOS: LaunchAgent (~/Library/LaunchAgents/ai.openclaw.gateway.plist)
  • Linux: systemd user service (~/.config/systemd/user/openclaw-gateway.service)
  • Windows: Task Scheduler task
​
--force
boolean
Overwrite existing service configuration

​
start

Start the gateway service. 
openclaw daemon start
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. 
openclaw daemon stop
Stops the running service:
  • macOS: launchctl unload
  • Linux: systemctl --user stop
  • Windows: schtasks /end

​
restart

Restart the gateway service. 
openclaw daemon restart
Equivalent to running stop followed by start.

​
status

Show service install status and probe the Gateway. 
openclaw daemon status [options]
​
--json
boolean
Output JSON format

​
uninstall

Remove the gateway service. 
openclaw daemon uninstall
Removes the service configuration:
  • 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

​
Platform Details

​
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:
  1. Service configuration (set during install)
  2. User environment (shell profile)
  3. Config file (~/.openclaw/openclaw.json)
Common environment variables:
​
OPENCLAW_GATEWAY_TOKEN
string
Gateway authentication token
​
OPENCLAW_GATEWAY_PASSWORD
string
Gateway authentication password
​
NODE_ENV
string
Node environment (production, development)
​
OPENCLAW_PROFILE
string
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

  1. Check installation: 
    openclaw daemon status
  2. Check gateway config: 
    openclaw config get gateway
  3. Run diagnostics: 
    openclaw doctor
  4. Try manual start: 
    openclaw gateway run --verbose

​
Service Crashes Immediately

  1. Check logs: 
    openclaw logs --limit 200
  2. Check port availability: 
    lsof -i :18789
  3. Check authentication: 
    openclaw config get gateway.auth

​
Service Stops on Logout (Linux)

Enable user lingering: 
sudo loginctl enable-linger $USER
Verify: 
loginctl show-user $USER | grep Linger
Should show 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