How to Restart OpenClaw: Step-by-Step CLI Guide

OpenClaw runs as a background Gateway service (WebSocket server) that powers your AI agent. Restarting it reloads configs, recovers from crashes, and applies updates without losing your skills or memory.

Step 1: Verify Installation and OpenClaw Version

Open your terminal and run:

openclaw --version

Expected output (example):

openclaw/1.2.3 (cli)

If the command is not found, reinstall with npm install -g openclaw@latest and restart your terminal. This confirms the CLI is ready.

Step 2: Check Current Gateway Status

Always start here to diagnose issues:

openclaw gateway status

For deeper system-level details (recommended on servers):

openclaw gateway status --deep

Expected healthy output:

• Runtime: running
• RPC probe: ok
• Service state shows active (systemd, launchd, etc.).

If it shows stopped or errors, proceed to restart. Pair this with logs for full visibility:

openclaw logs --follow

Leave this running in one terminal window to monitor live output.

Step 3: Restart the Gateway Service (Recommended Method)

This is the primary way for most users (daemon/service mode):

openclaw gateway restart

What happens:

• Stops the current Gateway.
• Starts it fresh as a background service.
• Applies any pending config changes.

Expected output:

✅ Gateway restarted successfully
Runtime: running

Switch back to your logs terminal to confirm startup (look for "Gateway ready" or channel connections).

Step 4: Restart in Foreground Mode (For Development or Testing)

If you run OpenClaw manually (no daemon):

1. Stop it with Ctrl + C in the running terminal.
2. Restart with:

openclaw gateway run

Or force-kill any lingering process first:

openclaw gateway --force

Use this for quick testing after code changes or plugin installs.

Step 5: Restart on Linux Servers (Systemd)

On Ubuntu, Debian, or VPS setups where OpenClaw was installed as a systemd service:

sudo systemctl restart openclaw

Check status:

sudo systemctl status openclaw
sudo journalctl -u openclaw -f

The CLI method (openclaw gateway restart) works here too and is preferred as it handles platform details automatically.

Step 6: Restart After Config or Plugin Changes

Many changes (e.g., editing ~/.openclaw/openclaw.json) hot-reload automatically. For others (new skills, model updates):

1. Edit your config if needed:

openclaw config edit

2. Restart immediately:

openclaw gateway restart

Run openclaw doctor afterward to verify everything is healthy.

Common Issues & Troubleshooting

• "Gateway already running" or port conflict: Add --force to start/restart commands or kill processes with pkill -f openclaw.
• Service won't start (stopped runtime): Run openclaw gateway install --force then restart. Check logs for auth/token errors.
• Config mismatch after upgrade: openclaw gateway status --deep will flag it. Fix with openclaw config set gateway.mode local (if needed) and restart.
• No response from agent: Confirm channels (WhatsApp, Telegram) are connected via openclaw channels status --probe.
• Crash loops on server: Edit restart policy in systemd unit or use openclaw gateway restart in a cron job.
• Permission issues: Run CLI commands as the same user who installed OpenClaw (avoid sudo unless on Linux servers).

If issues persist, run openclaw doctor and share the output in the official Discord community.

Next Steps

• Explore skills: openclaw skills list and add community plugins.
• Monitor performance: Set up Tailscale or remote access for easier management.
• Backup your setup: openclaw backup create before major changes.
• Update OpenClaw: npm update -g openclaw then restart.

Your OpenClaw agent is now fresh and ready to handle tasks. Restarting takes under 30 seconds once you're comfortable with the CLI.