openclaw daemon

Manage the Gateway service (launchd/systemd/schtasks)

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 and Start

# 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

Related Commands

• gateway - Run gateway directly (foreground)
• logs - View gateway logs
• status - Check overall system status
• doctor - Diagnose service issues