Hot Reload & Lifecycle Management

+15 Mana ✨
OpenClaw Hot Reload Configuration(DOCUMENTATION)OpenClaw Lifecycle Management(DOCUMENTATION)

Introduction

The OpenClaw Gateway supports hot reload to apply configuration changes without dropping active connections, and integrates with platform-specific service managers for lifecycle management. This lesson covers the four hot reload modes, how to manage the Gateway as a system service, and the client connection handshake protocol.

Key Concepts

  • Hot Reload Modes: Four modes controlling how the Gateway applies configuration changes: off, hot, restart, and hybrid (default).
  • Lifecycle Management: Integration with launchd (macOS) and systemd (Linux) for automatic startup, restart, and supervision.
  • Connect/Hello-OK Protocol: The handshake sequence where clients send a connect frame and the Gateway responds with a hello-ok frame containing presence, health, and uptime information.

Real World Context

Hot reload is a pattern borrowed from web development servers (like Vite or Webpack Dev Server) and production load balancers (like Nginx or HAProxy). The idea is to apply safe changes without downtime. The distinction between hot and restart modes mirrors how Nginx handles reload (re-reads config without dropping connections) versus restart (full process restart). The connect/hello-ok handshake is similar to protocol negotiations in WebSocket, SMTP (HELO/EHLO), and gRPC health checking.

Deep Dive

Hot Reload Modes

The Gateway supports four hot reload modes that control how it responds to configuration changes:

Off mode disables all automatic reloading. Changes to the config file require a manual restart.

bash
# Start with hot reload disabled
openclaw gateway --hot-reload off

After running this, any changes to ~/.openclaw/openclaw.json are ignored until you manually stop and restart the Gateway process. This is useful in production environments where you want full control over when changes take effect.

Hot mode applies only safe changes without any process restart. Safe changes include modifications to routing rules, channel weights, and logging levels. Changes that require a restart (like port or binding changes) are ignored with a warning.

bash
# Start with hot-only reload
openclaw gateway --hot-reload hot

With this mode active, editing the config file to add a new channel route takes effect immediately. But changing the port number would log a warning indicating a restart is needed.

Restart mode performs a full process restart whenever any configuration change is detected. This is the most thorough but causes brief downtime.

bash
# Start with restart-on-change mode
openclaw gateway --hot-reload restart

Every config file change triggers a graceful shutdown followed by a fresh start. Active connections are drained before the restart occurs.

Hybrid mode (default) combines both strategies. Safe changes are applied hot, and unsafe changes trigger a full restart.

bash
# Hybrid is the default, but you can be explicit
openclaw gateway --hot-reload hybrid

This is the default because it offers the best balance: most day-to-day config tweaks apply instantly, but structural changes like port or binding modifications still take effect automatically via restart.

Lifecycle Management

The Gateway integrates with platform service managers to run as a supervised background process.

On macOS, the Gateway uses launchd:

bash
# The gateway command manages the launchd service automatically
openclaw gateway

When you run openclaw gateway on macOS, it registers itself with launchd so the Gateway starts automatically on login and restarts if the process crashes. You do not need to write a plist file manually.

On Linux, the Gateway uses systemd:

bash
# Same command, detects Linux and uses systemd
openclaw gateway

The Gateway creates and manages its own systemd unit file. It handles ExecStart, Restart=on-failure, and proper socket activation.

To check the status of the running Gateway regardless of platform:

bash
# Check gateway status (works on both macOS and Linux)
openclaw gateway status

This command reports whether the Gateway is running, its PID, uptime, bound port, active channels, and connected clients.

Connect / Hello-OK Protocol

When a client connects to the Gateway, a handshake protocol establishes the session. The client sends a connect frame, and the Gateway responds with a hello-ok frame.

The connect frame is sent by the client over WebSocket to initiate the session. The Gateway validates the authentication credentials included in the frame and, if valid, responds with hello-ok.

The hello-ok response contains three key pieces of information:

  • Presence: Which channels and models are currently available.
  • Health: The health status of each connected channel.
  • Uptime: How long the Gateway has been running since its last start.

This handshake ensures that clients immediately know what capabilities are available without needing to make additional discovery requests. If authentication fails during the connect phase, the Gateway closes the WebSocket connection with an appropriate error code.

Remote Access

For accessing the Gateway from other machines, two approaches are supported:

Tailscale/VPN (preferred): Use the tailnet binding mode so the Gateway is only accessible within your Tailscale network. This provides encrypted, authenticated access without exposing any ports to the public internet.

SSH tunneling (fallback): Forward the Gateway port over SSH when a VPN is not available.

bash
# SSH tunnel to access remote gateway on localhost:18789
ssh -L 18789:localhost:18789 user@remote-machine

After running this command, you can access the remote Gateway at localhost:18789 on your local machine as if it were running locally. The traffic is encrypted through the SSH connection.

Common Pitfalls

  • Expecting port changes to apply in hot mode: Changing the port in the config file while running in hot reload mode produces a warning but does not take effect. Use hybrid or restart mode, or manually restart the Gateway.
  • Forgetting that hybrid is the default: If you are debugging unexpected restarts, remember that the Gateway in its default hybrid mode will automatically restart when it detects unsafe configuration changes.
  • Skipping the connect handshake: Clients that send API requests without first establishing a WebSocket connect/hello-ok handshake miss out on presence and health data, which can lead to requests being sent to unavailable channels.

Best Practices

  • Use the default hybrid hot reload mode for most deployments – it minimizes downtime for routine changes while still applying structural changes.
  • Always check openclaw gateway status after configuration changes to confirm they took effect.
  • Prefer Tailscale over SSH tunneling for remote access, as it provides persistent connectivity without manual tunnel management.

Summary

  • Hot reload has four modes: off (manual only), hot (safe changes only), restart (full restart on any change), and hybrid (default, combines both).
  • The Gateway integrates with launchd on macOS and systemd on Linux for automatic lifecycle management.
  • The connect/hello-ok handshake provides clients with presence, health, and uptime data at connection time.
  • Remote access is best achieved via Tailscale/VPN, with SSH tunneling as a fallback.
  • Use openclaw gateway to start and openclaw gateway status to monitor the running instance.
✓ Completed