Principle:Openclaw Openclaw Gateway Restart

Gateway Restart

Gateway Restart is the principle of gracefully stopping the running gateway process via the OS service manager and relaunching it to pick up new configuration, updated binaries, or repaired state.

Motivation

The OpenClaw gateway runs as a persistent background service managed by the operating system's service infrastructure (launchd on macOS, systemd on Linux). When operators update the codebase, change configuration, or fix issues via the doctor command, those changes only take effect after the gateway process is restarted. A reliable restart mechanism is essential for operational continuity.

Unlike a simple process kill-and-relaunch, a proper restart must:

Verify the service is currently loaded before attempting to restart.
Use the OS service manager's native restart mechanism for clean shutdown (allowing in-flight messages to complete).
Verify the service is still loaded after the restart (detecting crash-on-start scenarios).
Provide clear feedback when the service is not loaded, including actionable hints for how to start it.

Core Concepts

Service Abstraction

OpenClaw abstracts the OS service manager behind a GatewayService interface resolved by resolveGatewayService(). This abstraction provides:

isLoaded() -- Checks whether the service is registered and running with the OS service manager.
restart() -- Stops and restarts the service via the native mechanism.
stop() -- Stops the service.
install() / uninstall() -- Registers or removes the service definition.

On macOS, this maps to launchd operations (e.g., launchctl bootout / launchctl bootstrap). On Linux, it maps to systemd user service operations (e.g., systemctl --user restart).

Restart vs. Start

The restart function distinguishes between two states:

Service loaded -- The service is registered with the OS service manager. A restart is issued, which performs a stop-then-start cycle.
Service not loaded -- The service is not registered. The restart function does not attempt to start it; instead, it returns false and provides hints for how to install and start the service (e.g., openclaw daemon install).

This distinction is important because attempting to restart a non-existent service would fail silently, leaving the operator confused about why the gateway is not running.

macOS App Restart

On macOS, the gateway often runs as part of the OpenClaw menu bar app rather than a standalone service. The restart-mac.sh script provides a comprehensive restart workflow for development:

Kill all instances -- Terminates any running OpenClaw processes (app bundle, debug builds, release builds).
Stop the LaunchAgent -- Unloads the launchd job.
Rebuild -- Runs a clean Swift build of the macOS app.
Package -- Creates the app bundle with embedded resources.
Code signing -- Auto-detects signing keys or uses ad-hoc signing for development.
Launch -- Opens the app bundle via LaunchServices with a sanitized environment.
Verify -- Checks that the app process is running after launch.

This script handles the additional complexity of macOS development where the gateway is embedded in a native app rather than running as a standalone Node.js process.

JSON Output Mode

All daemon lifecycle operations (start, stop, restart, uninstall) support a --json flag that emits structured JSON payloads instead of human-readable output. This enables programmatic consumption by scripts, CI systems, and the web control UI. The JSON output includes the action performed, success/failure status, error details, hints, and the current service snapshot.

Design Principles

Verify before and after -- Always check whether the service is loaded before attempting a restart, and verify it is still loaded afterward to detect crash-on-start.
Never force-start -- If the service is not loaded, return false with hints rather than silently installing and starting. Service installation is a separate, intentional operation.
Platform-native -- Use the OS service manager's native restart mechanism rather than kill/spawn. This ensures proper signal handling, resource cleanup, and service dependency resolution.
Environment isolation -- When launching the macOS app (via the restart script), use env -i to prevent the shell's environment variables from leaking into the GUI app, which can cause launchd spawn failures.

Relationship to Other Concepts

Gateway Restart is the final step in the Version Update flow and may be triggered by Diagnostic Repair when the doctor detects that the gateway is not healthy. The post-restart state can be verified via Health Monitoring.

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment