OpenClaw LaunchOpenClaw Launch
← Home

Operations Guide

How to Stop the OpenClaw Gateway

Whether you need to apply a config change, free up a port, or update OpenClaw to a new version, stopping the gateway is a routine task — but doing it the wrong way can cut off active conversations mid-sentence. This guide covers every method: Ctrl+C for local installs, docker stop for containerized deployments, and PM2 commands for process-managed setups.

When to Stop the OpenClaw Gateway

Most of the time the OpenClaw gateway runs quietly in the background and you never need to touch it. But several situations require a stop or restart:

  • Config changes that need a restart — Changes toplugins.* or gateway.auth.* are not hot-reloaded. OpenClaw must be restarted before these take effect. Changes to channels.*, agents.*, and models.* do hot-reload automatically without a restart.
  • Updating to a newer OpenClaw version — You need to pull the new Docker image and recreate the container, which requires stopping the running one first.
  • Port conflicts — If another process has taken port 18789 (the default gateway port), stopping OpenClaw and restarting it — or changing the port in config — resolves the conflict.
  • Maintenance and troubleshooting — Sometimes a clean restart is the fastest way to clear a stuck state, flush in-memory session data, or force a fresh reconnect from all clients.
  • Resource constraints — On a low-memory server, stopping OpenClaw temporarily frees RAM for other work.

Stop the Gateway (Local Install)

If you started OpenClaw directly in a terminal — by running npx openclaw or the equivalent binary — the simplest way to stop it is to press Ctrl+C in that terminal window. This sends a SIGINT signal to the process, which triggers a graceful shutdown.

# In the terminal where OpenClaw is running: Ctrl+C

If the terminal is no longer accessible (you closed it, or the process is running in a different session), you can find and kill the process by port or by name:

# Find the process using port 18789 lsof -ti :18789 # Kill it gracefully (SIGTERM) kill $(lsof -ti :18789) # Or find by process name pkill -f openclaw

The kill command sends SIGTERM by default, which is a graceful shutdown signal — the same as Ctrl+C. OpenClaw will finish handling in-flight requests before exiting. To restart after stopping, simply run the same start command again.

Stop the Gateway (Docker)

For Docker-based deployments, use docker stop to gracefully stop the container. First, find the container name or ID:

# List running containers (look for your openclaw container) docker ps # Gracefully stop the container (sends SIGTERM, waits up to 10s, then SIGKILL) docker stop openclaw # Restart the container (stop + start in one command) docker restart openclaw

If your container has a different name, substitute it. You can also use the container ID shown in docker ps instead of the name.

To start the container again after stopping it:

docker start openclaw

If you need to remove the container entirely (for example, to recreate it with new settings or a new image version), stop it first and then remove it:

docker stop openclaw docker rm openclaw # Then recreate with your usual docker run command docker run -d \ --name openclaw \ -p 18789:18789 \ -v ~/.openclaw:/home/node/.openclaw \ ghcr.io/openclaw/openclaw:1.2.3
Note on volumes: docker rm removes the container but leaves bind-mounted directories (like ~/.openclaw) untouched on the host. Your config file, credentials, and conversation history are safe even after removing and recreating the container.

Stop the Gateway (PM2)

If you manage OpenClaw with PM2 (a Node.js process manager commonly used for always-on deployments), use these commands:

# Stop the openclaw process (keeps it in PM2's list, but not running) pm2 stop openclaw # Restart the openclaw process (stop + start) pm2 restart openclaw # Reload without downtime (zero-downtime restart, if PM2 supports it for your setup) pm2 reload openclaw # Remove openclaw from PM2 entirely (stops it and deletes from process list) pm2 delete openclaw

After making changes, save the PM2 process list so it survives a server reboot:

pm2 save

To check the current status of all PM2-managed processes:

pm2 list pm2 logs openclaw --lines 50

Graceful vs Force Stop

There are two ways to stop any running process: gracefully or forcefully. The difference matters when users have active conversations in progress.

A graceful stop (SIGTERM) signals the process to finish what it's doing and then exit cleanly. OpenClaw will:

  • Stop accepting new connections
  • Allow in-flight message processing to complete
  • Flush any pending writes to disk
  • Close open file handles and network connections cleanly

A force stop (SIGKILL / docker kill) terminates the process immediately with no cleanup. Any messages being processed at that exact moment are dropped. Sessions may be left in an inconsistent state, and the next startup may be slightly slower while OpenClaw reconciles state.

# Graceful (recommended) — waits for clean shutdown docker stop openclaw          # Docker: SIGTERM, 10s grace period, then SIGKILL kill $(lsof -ti :18789)       # Local: SIGTERM pm2 stop openclaw             # PM2: SIGTERM # Force stop (only if graceful is stuck) docker kill openclaw          # Docker: immediate SIGKILL kill -9 $(lsof -ti :18789)    # Local: SIGKILL (cannot be caught or ignored)

Always prefer the graceful stop. Only use force stop if the process is completely unresponsive and the graceful command has been waiting more than 30 seconds.

Restart After Config Changes

Not every config change requires a restart. OpenClaw hot-reloads certain sections automatically while the gateway keeps running:

  • Hot-reload (no restart needed): channels.*, agents.*, models.* — changes take effect within seconds of saving the config file.
  • Restart required: plugins.*, gateway.auth.*, gateway.port, gateway.trustedProxies — these are read only at startup and require a full restart to apply.

When in doubt, a restart is always safe. The downtime is typically under 5 seconds for a local or Docker install, and PM2's reload command can achieve near-zero downtime for supported configurations.

After editing openclaw.json, verify the config loaded correctly by checking the gateway logs immediately after restart:

# Check Docker logs after restart docker logs openclaw --tail 30 # Check PM2 logs after restart pm2 logs openclaw --lines 30

Look for any ERROR or WARN lines that indicate a config parsing failure. If the config has a JSON syntax error, OpenClaw will log it and may fall back to defaults or refuse to start.

Never Worry About Gateway Management Again

Stopping, starting, and restarting the OpenClaw gateway is manageable — but it's also something you should never have to think about. Every restart is a moment of potential downtime, and every config change that requires one is a decision point where things can go wrong.

OpenClaw Launch handles all of this automatically. The managed platform restarts your gateway when needed (and only when needed), applies config changes that support hot-reload without any downtime, and handles updates to new OpenClaw versions with zero manual steps from you.

  • Auto-restart on crash — If the gateway process ever exits unexpectedly, it's brought back up within seconds — no manual intervention.
  • Zero-downtime updates — When a new OpenClaw version is released, the platform updates your instance without dropping your active conversations.
  • Visual config editor — Change channels, models, and agent settings through a UI. No JSON editing, no manual restart commands.
  • Always-on monitoring — The platform watches your instance health continuously, so you're notified of problems before your users notice them.

If you're tired of managing gateway lifecycle yourself, try OpenClaw Launch — deploy your OpenClaw instance in under 10 seconds and never run another docker stop command again.

Related Guides

Skip Gateway Management Entirely

Auto-restart, zero-downtime updates, visual config editor. Deploy in 10 seconds.

Deploy with OpenClaw Launch