OpenClaw Gateway systemd Service: Run Your Agent 24/7 on Linux

Running OpenClaw in a terminal session is fine for testing. It is not a deployment strategy. Every server reboot, every closed SSH session, every OOM kill takes your agent offline until someone manually restarts it. Three lines in a systemd unit file eliminate that entire category of problem. Here's the setup that actually holds up in production.

Why systemd Is the Right Choice

Linux systems using systemd — which is every major distribution since 2015 — have a process supervisor built in. It handles startup ordering, crash recovery, log aggregation, and resource limits. The alternative approaches all have problems:

• Screen/tmux sessions — die on server reboot, require manual restart, logs are lost when session closes
• nohup & background processes — no crash recovery, no log management, hard to track down the PID later
• Docker without a restart policy — same crash recovery issues unless you configure it correctly, and adds container overhead you may not need
• Custom shell scripts with while loops — fragile, hard to debug, reinvents what systemd already does better

systemd gives you crash recovery, boot integration, log management, and process isolation with about 20 lines of configuration. Use it.

Create a Dedicated Service User

Never run the OpenClaw gateway as root. Create a system user with no login shell, no home directory, and minimal permissions.

sudo useradd --system --no-create-home --shell /usr/sbin/nologin openclaw

This creates a system account (--system) that can't log in interactively (--shell /usr/sbin/nologin) and has no home directory (--no-create-home). The gateway process runs under this account, so any compromise of the process is limited to what this account can access.

Next, set up the directories the gateway needs and assign ownership:

sudo mkdir -p /etc/openclaw /var/lib/openclaw /var/log/openclaw
sudo chown openclaw:openclaw /var/lib/openclaw /var/log/openclaw
sudo chmod 750 /etc/openclaw

Your gateway.yaml lives in /etc/openclaw/. The gateway process reads it but doesn't need to write to it — keep it owned by root with read permission for the openclaw group.

The Complete Unit File

Create the unit file at /etc/systemd/system/openclaw-gateway.service:

[Unit]
Description=OpenClaw Gateway Service
Documentation=https://aiagentsguides.com/category/configuration-cli/
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=openclaw
Group=openclaw
WorkingDirectory=/var/lib/openclaw
ExecStart=/usr/local/bin/openclaw gateway --config /etc/openclaw/gateway.yaml
ExecReload=/bin/kill -HUP $MAINPID

# Restart policy
Restart=on-failure
RestartSec=5s
StartLimitIntervalSec=60
StartLimitBurst=3

# Environment
EnvironmentFile=-/etc/openclaw/gateway.env

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/var/lib/openclaw /var/log/openclaw

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=openclaw-gateway

[Install]
WantedBy=multi-user.target

Let's unpack the key settings before moving on — because a few of these will save you significant debugging time.

After=network-online.target — waits for the network to be fully up before starting. Without this, the gateway may start before network interfaces are ready and fail to bind or connect to upstream services.

Restart=on-failure — restarts only on unexpected exits (non-zero exit codes). If you manually run systemctl stop openclaw-gateway, it stays stopped. If the process crashes, it restarts automatically.

StartLimitBurst=3 — if the gateway crashes 3 times within 60 seconds, systemd stops trying to restart it. This prevents an endless restart loop if there's a configuration error causing immediate crashes.

Storing Secrets with EnvironmentFile

The unit file references /etc/openclaw/gateway.env for environment variables. The dash before the path (-/etc/openclaw/gateway.env) means systemd won't fail if the file doesn't exist — useful when you don't need environment overrides.

When you do need to pass secrets — like your gateway token or API keys — create the env file:

sudo tee /etc/openclaw/gateway.env > /dev/null << 'EOF'
OPENCLAW_GATEWAY_TOKEN=your-secret-token-here
ANTHROPIC_API_KEY=your-anthropic-key
OPENAI_API_KEY=your-openai-key
EOF

sudo chown root:openclaw /etc/openclaw/gateway.env
sudo chmod 640 /etc/openclaw/gateway.env

The file is owned by root, readable by the openclaw group. The gateway process running as the openclaw user can read the secrets, but no other non-root user can.

Enable and Start the Service

After writing the unit file, tell systemd to load it and enable it for boot:

# Reload systemd to pick up the new unit file
sudo systemctl daemon-reload

# Enable the service to start on boot
sudo systemctl enable openclaw-gateway

# Start it immediately without rebooting
sudo systemctl start openclaw-gateway

# Verify it started cleanly
sudo systemctl status openclaw-gateway

The status output shows whether the service is active, the last few log lines, and the process ID. A healthy output looks like:

● openclaw-gateway.service - OpenClaw Gateway Service
     Loaded: loaded (/etc/systemd/system/openclaw-gateway.service; enabled)
     Active: active (running) since Sat 2025-02-23 14:22:11 UTC; 5s ago
   Main PID: 12847 (openclaw)
      Tasks: 8 (limit: 4915)
     Memory: 42.3M
        CPU: 312ms
     CGroup: /system.slice/openclaw-gateway.service
             └─12847 /usr/local/bin/openclaw gateway --config /etc/openclaw/gateway.yaml

Viewing and Filtering Logs

All gateway output goes to journald automatically. Access it with journalctl:

# Follow live logs (like tail -f)
sudo journalctl -u openclaw-gateway -f

# Last 100 lines
sudo journalctl -u openclaw-gateway -n 100

# Logs since last boot
sudo journalctl -u openclaw-gateway -b

# Logs from the last hour
sudo journalctl -u openclaw-gateway --since "1 hour ago"

# Only errors
sudo journalctl -u openclaw-gateway -p err

journald handles log rotation automatically. No separate logrotate configuration needed unless you're also writing to files in /var/log/openclaw/.

Common Mistakes

• Forgetting daemon-reload after changing the unit file — systemd caches the unit file in memory. Any change requires systemctl daemon-reload before the change takes effect, even if you then restart the service.
• Binary path wrong in ExecStart — find where openclaw is installed with which openclaw and use that exact path. Relative paths don't work in unit files.
• Missing network dependency — without After=network-online.target, the gateway starts before the network is ready and fails immediately. Systemd retries based on your restart policy, usually succeeding on the second try — but the first failure shows up as an error in logs and can confuse monitoring systems.
• Wrong file permissions on gateway.yaml — if the openclaw user can't read the config file, the service fails to start with a cryptic permission error. Run sudo -u openclaw cat /etc/openclaw/gateway.yaml to verify read access.
• Not checking journal after start failures — systemctl status shows the last few lines but not the full error. Always check journalctl -u openclaw-gateway -n 50 after a failed start to see the actual error message from the gateway process.

Frequently Asked Questions

How do I run OpenClaw Gateway as a systemd service?

Create a unit file at /etc/systemd/system/openclaw-gateway.service with ExecStart pointing to your openclaw binary and config. Run systemctl daemon-reload, systemctl enable openclaw-gateway, and systemctl start openclaw-gateway. The gateway starts automatically on boot and restarts on crash.

How do I view OpenClaw Gateway logs with systemd?

Use journalctl -u openclaw-gateway to view all logs. Add -f to follow live output, -n 100 to see the last 100 lines, or --since '1 hour ago' to filter by time. Logs are managed by journald automatically — no separate log file configuration is required.

What user should run the OpenClaw Gateway systemd service?

Create a dedicated system user — for example, openclaw — with no login shell and no home directory. Set User=openclaw and Group=openclaw in the unit file. Never run the gateway as root. The service user needs read access to the config file and write access to any data directories.

How do I pass environment variables to the OpenClaw systemd service?

Use an EnvironmentFile directive pointing to a file like /etc/openclaw/gateway.env. Store secrets like your gateway token in that file as KEY=VALUE pairs. Never hardcode secrets in the unit file itself — unit files are readable by all users on the system by default.

How do I restart the OpenClaw Gateway service after a config change?

Run systemctl restart openclaw-gateway to restart the gateway and pick up config changes. If you changed the unit file, run systemctl daemon-reload first, then restart. Use systemctl status openclaw-gateway to verify the service started cleanly after the restart.

What RestartSec and Restart values should I use for OpenClaw Gateway?

Set Restart=on-failure and RestartSec=5s as a baseline. This restarts 5 seconds after an unexpected exit, preventing rapid crash loops. Add StartLimitIntervalSec=60 and StartLimitBurst=3 to stop systemd from restarting endlessly on configuration errors causing repeated failures.