Background Process Management Guide

Overview

OpenClaw Gateway needs to run as a persistent background service. Running it directly in a terminal means it will stop when the terminal closes. This article covers several approaches for background process management.

Using OpenClaw's Built-in Commands

OpenClaw provides simple commands for background operation:

# Start in the background
openclaw start --daemon

# Check status
openclaw status

# Stop the service
openclaw stop

# Restart the service
openclaw restart

Managing with PM2

PM2 is the most popular process manager in the Node.js ecosystem, offering rich features and ease of use.

Install PM2

npm install -g pm2

Start OpenClaw

pm2 start openclaw -- start

Starting with a configuration file (recommended):

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'openclaw',
    script: 'openclaw',
    args: 'start',
    instances: 1,
    autorestart: true,
    watch: false,
    max_memory_restart: '500M',
    env: {
      NODE_ENV: 'production'
    },
    error_file: '~/.openclaw/logs/pm2-error.log',
    out_file: '~/.openclaw/logs/pm2-out.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss'
  }]
};

pm2 start ecosystem.config.js

Common PM2 Commands

# List processes
pm2 list

# View logs
pm2 logs openclaw

# Monitor resource usage
pm2 monit

# Restart
pm2 restart openclaw

# Reload (zero downtime)
pm2 reload openclaw

# Stop
pm2 stop openclaw

# Delete process
pm2 delete openclaw

Enable Startup on Boot

pm2 startup
pm2 save

PM2 automatically generates the appropriate startup script for your system.

Managing with systemd

Suitable for Linux systems, offering system-level process management.

Create a Service File

sudo nano /etc/systemd/system/openclaw.service

[Unit]
Description=OpenClaw AI Assistant Gateway
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=openclaw
Group=openclaw
WorkingDirectory=/home/openclaw
ExecStart=/usr/local/bin/openclaw start
ExecStop=/usr/local/bin/openclaw stop
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=openclaw

# Security settings
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/openclaw/.openclaw

# Resource limits
MemoryMax=512M
CPUQuota=80%

[Install]
WantedBy=multi-user.target

Common systemd Commands

# Reload service files
sudo systemctl daemon-reload

# Start
sudo systemctl start openclaw

# Stop
sudo systemctl stop openclaw

# Restart
sudo systemctl restart openclaw

# Check status
sudo systemctl status openclaw

# Enable startup on boot
sudo systemctl enable openclaw

# View logs
journalctl -u openclaw -f
journalctl -u openclaw --since "1 hour ago"

Managing with Docker

Docker has built-in restart policies, so no extra process manager is needed:

docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest start

Docker Compose:

services:
  openclaw:
    image: openclaw/openclaw:latest
    restart: unless-stopped
    volumes:
      - openclaw-data:/root/.openclaw
    command: start

macOS with launchd

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.openclaw.gateway</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/openclaw</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/you/.openclaw/logs/launchd-out.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/you/.openclaw/logs/launchd-err.log</string>
</dict>
</plist>

cp com.openclaw.gateway.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist

Process Monitoring

Regardless of which process management approach you use, it is recommended to set up monitoring:

{
  "gateway": {
    "monitoring": {
      "enabled": true,
      "metrics": {
        "endpoint": "/metrics",
        "format": "prometheus"
      }
    }
  }
}

Log Rotation

Prevent log files from growing too large:

# /etc/logrotate.d/openclaw
/home/openclaw/.openclaw/logs/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}

Summary

Choosing the right process management solution depends on your environment: Docker deployments should use Docker's built-in restart policies; bare-metal Linux should use systemd; Node.js environments should use PM2; macOS should use launchd. The core goal is to ensure OpenClaw automatically recovers from crashes and starts on boot.