How to Restart OpenClaw: Every Method for Every Setup [2026]

Docker Restart

Most OpenClaw deployments use Docker Compose. Here are the restart commands from most common to least common:

Graceful restart (recommended):

# Restart the OpenClaw container without removing it
docker compose restart openclaw

This sends a SIGTERM to the OpenClaw process, waits for it to finish processing current messages (up to 10 seconds by default), then starts a new process. Data, volumes, and network connections are preserved.

Full restart (for config changes):

# Stop, remove, and recreate the container
docker compose down && docker compose up -d

This fully destroys the container and creates a new one. Use this when you have changed environment variables in your .env file or modified your docker-compose.yml. Data on Docker volumes (conversation history, memory files) is preserved because volumes are not deleted by docker compose down.

Rebuild restart (for version updates):

# Pull the latest image and restart
docker compose pull && docker compose up -d

This downloads the latest OpenClaw Docker image and restarts with it. Use this when updating to a new version.

Hard restart (last resort):

# Force kill and restart
docker compose kill openclaw && docker compose up -d

This sends SIGKILL, which terminates the process immediately without waiting for clean shutdown. Only use this if the container is unresponsive and a graceful restart times out. There is a small risk of database corruption if a write was in progress.

Systemd Restart

If you installed OpenClaw directly on the server (without Docker), it likely runs as a systemd service:

# Graceful restart
sudo systemctl restart openclaw

# Check status after restart
sudo systemctl status openclaw

# If the service fails to start, check logs
journalctl -u openclaw --since "5 minutes ago"

Systemd automatically handles the stop-then-start sequence and waits for the process to exit cleanly before starting a new one.

If you need to reload configuration without a full restart (for supported config changes):

# Reload config (limited — only some settings support hot reload)
sudo systemctl reload openclaw

Mac App Restart

The OpenClaw Mac application runs as a menu bar app. To restart:

1. Click the OpenClaw icon in the menu bar
2. Select "Restart Agent" from the dropdown menu

Alternatively, you can quit and relaunch:

1. Click the OpenClaw icon in the menu bar
2. Select "Quit OpenClaw"
3. Reopen OpenClaw from your Applications folder or Spotlight

From the terminal:

# Quit the Mac app
osascript -e 'quit app "OpenClaw"'

# Wait a moment, then relaunch
open -a OpenClaw

The Mac app stores its data in ~/Library/Application Support/OpenClaw/. This directory contains the database, memory files, and configuration. It persists across restarts and app updates.

Safe Restart vs Hard Restart

Understanding the difference matters for production deployments:

Always try a safe restart first. If it hangs for more than 30 seconds (visible in docker compose logs -f), then fall back to a hard restart. After a hard restart, check the database integrity:

# Check SQLite database integrity
docker compose exec openclaw sqlite3 /data/openclaw.db "PRAGMA integrity_check;"

When to Restart

You need to restart when:

• You changed environment variables in .env
• You updated to a new OpenClaw version
• You installed or removed plugins
• You modified docker-compose.yml
• The agent is unresponsive (not processing messages)
• RAM usage is abnormally high (memory leak, rare but possible)

You do NOT need to restart when:

• You edited persona files — these are read dynamically on each conversation
• You edited memory files — these are read on access
• You edited workflow_auto.md — this is read on the next scheduled check
• You added or edited SKILL.md files — these are hot-reloaded in 3.22+
• You changed model routing rules (if using the web UI — changes apply immediately)

What Survives a Restart

OpenClaw is designed so that restarts are low-risk:

• Conversation history: Stored in SQLite on a Docker volume. Fully preserved.
• Memory files: Stored as .md files on a Docker volume. Fully preserved.
• Skills and plugins: Stored on a Docker volume. Fully preserved.
• Persona files: Stored on a Docker volume. Fully preserved.
• WhatsApp session: The session token is stored on a volume. In most cases, the WhatsApp connection reconnects automatically. Occasionally (roughly 1 in 20 restarts), the session needs to be re-authenticated by scanning the QR code again.
• Telegram and Discord connections: These reconnect automatically using the bot token. No action needed.

The only thing lost during a restart is the current in-memory context window — the conversation context the AI model was holding in RAM. On startup, OpenClaw rebuilds context from the database, so the agent can pick up conversations where it left off. There may be a brief period (the first 1-2 messages after restart) where the agent has slightly less conversational context than before the restart.

Troubleshooting Restart Issues

Container does not start after restart:

# Check logs for startup errors
docker compose logs --tail 50 openclaw

# Common causes:
# - Port already in use (another process grabbed the port)
# - Invalid .env variable (typo in a new variable)
# - Missing Docker volume (if volumes were manually deleted)
# - Insufficient disk space

WhatsApp does not reconnect:

# Check the WhatsApp session status
docker compose logs openclaw 2>&1 | grep -i whatsapp

# If you see "Session expired," you need to re-scan the QR code
# Access the web UI at http://your-server:3000/admin/whatsapp

Agent is slow after restart: This is normal for the first 30-60 seconds. OpenClaw is loading plugins, rebuilding indexes, and reconnecting to messaging platforms. If slowness persists beyond 2 minutes, check docker stats for resource issues.

Restart loop (container keeps restarting):

# Check the restart policy
docker inspect openclaw | grep -A 5 RestartPolicy

# Check recent crash logs
docker compose logs --tail 100 openclaw

# Common cause: a corrupted .env file or a plugin that crashes on load
# Try starting with minimal config:
# Comment out all plugins in .env, restart, add them back one by one