Why Use systemd
After installing OpenClaw on a Linux server, running openclaw start directly in the terminal works but has several drawbacks: the process terminates when the SSH connection closes, the service must be manually started after a server reboot, and it cannot automatically recover from crashes. systemd is the standard service manager on modern Linux systems and solves all these problems.
This article explains in detail how to configure OpenClaw as a reliable background service using systemd, enabling auto-start on boot, automatic crash recovery, and centralized log management.
Prerequisites
- OpenClaw is installed (via
npm install -g openclaw@latestor the official installation script) - Initial configuration is complete (
openclaw onboard) - Your Linux system uses systemd (Ubuntu 16.04+, Debian 9+, CentOS 7+, Fedora, etc.)
Automatic Installation
OpenClaw provides a command to automatically configure the daemon. On Linux systems, it automatically creates a systemd service:
openclaw onboard --install-daemon
If you already ran this command during the initial onboarding, the systemd service may already be configured. You can check with:
systemctl status openclaw
If the service already exists and is running properly, you can skip the manual configuration section and proceed to the management and optimization chapters below.
Manually Creating the systemd Service
If automatic installation didn't work or you want to customize the configuration, you can manually create the systemd service file.
Confirm the OpenClaw Path
First, confirm the location of the OpenClaw executable:
which openclaw
The typical result is /usr/bin/openclaw or /usr/local/bin/openclaw. Note this path for later use.
Also confirm the username and home directory you use to run OpenClaw:
echo $USER
echo $HOME
Create the Service File
Create the systemd service file with your preferred editor:
sudo nano /etc/systemd/system/openclaw.service
Enter the following content:
[Unit]
Description=OpenClaw AI Agent Gateway
Documentation=https://openclaw.ai/docs
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=your-username
Group=your-username
WorkingDirectory=/home/your-username
ExecStart=/usr/local/bin/openclaw start
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=5
StartLimitBurst=5
StartLimitIntervalSec=60
# Environment variables
Environment=NODE_ENV=production
Environment=HOME=/home/your-username
# Security hardening
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/your-username/.openclaw
# Resource limits
LimitNOFILE=65536
MemoryMax=1G
# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=openclaw
[Install]
WantedBy=multi-user.target
Replace "your-username" above with your actual Linux username. If the OpenClaw installation path differs, modify the path in ExecStart accordingly.
Configuration Explanation
Several key settings in this service file are worth explaining:
- Restart=always and RestartSec=5: Automatically restart every 5 seconds after a crash, ensuring high availability
- StartLimitBurst=5 and StartLimitIntervalSec=60: Maximum 5 restarts within 60 seconds, preventing infinite restart loops
- ProtectSystem=strict and ProtectHome=read-only: Security hardening options that restrict the service's filesystem write permissions
- ReadWritePaths: Explicitly allows writing to the OpenClaw configuration directory
~/.openclaw - LimitNOFILE=65536: Increases the file descriptor limit to accommodate high-concurrency connection scenarios
Enabling and Managing the Service
Load and Start the Service
sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw
The enable command sets the service to start on boot, and start immediately launches the service.
Common Management Commands
Check service status:
sudo systemctl status openclaw
Stop the service:
sudo systemctl stop openclaw
Restart the service:
sudo systemctl restart openclaw
Reload configuration (without interrupting service):
sudo systemctl reload openclaw
Disable auto-start on boot:
sudo systemctl disable openclaw
Log Management
systemd manages service logs centrally through journald. Here are common log viewing commands.
Follow logs in real time:
journalctl -u openclaw -f
View the last 100 lines of logs:
journalctl -u openclaw -n 100
View today's logs:
journalctl -u openclaw --since today
View logs for a specific time range:
journalctl -u openclaw --since "2026-03-14 08:00:00" --until "2026-03-14 18:00:00"
Filter by priority (errors only):
journalctl -u openclaw -p err
Running Diagnostics
After the service starts, it's recommended to run OpenClaw's built-in diagnostic tool:
openclaw doctor
This command checks whether the Node.js version meets the 22+ requirement, whether the configuration file ~/.openclaw/openclaw.json is complete, whether chat platform connections are working, network reachability, and other critical items.
Configuration File Updates
After modifying the ~/.openclaw/openclaw.json configuration file, you need to restart the service for changes to take effect:
sudo systemctl restart openclaw
Running Multiple Instances
If you need to run multiple OpenClaw instances on the same server (e.g., production and staging environments), you can use systemd's template instance feature:
sudo cp /etc/systemd/system/openclaw.service /etc/systemd/system/[email protected]
Modify the template file to replace fixed paths with parameterized instance paths, then start different instances separately:
sudo systemctl start openclaw@production
sudo systemctl start openclaw@staging
Troubleshooting
If the service fails to start, follow these steps:
- Check logs:
journalctl -u openclaw -n 50 --no-pager - Try running manually to confirm it works:
openclaw start - Check permissions: Ensure the service user has read/write access to the
~/.openclaw/directory - Check port conflicts:
ss -tlnp | grep 3000 - Check Node.js version:
node --version(must be 22+)
Summary
Managing the OpenClaw service with systemd gives you enterprise-grade reliability — auto-start on boot, automatic crash recovery, and centralized log management. Combined with security hardening options and resource limits, this configuration is suitable for long-term stable operation in production environments.