Manage the Gateway service

Native service lifecycle, recovery, wrappers, and the managed-service option reference. Part of the openclaw gateway reference.

Manage the Gateway service

openclaw gateway installopenclaw gateway startopenclaw gateway stopopenclaw gateway restartopenclaw gateway uninstall

gateway stop remains available when plugin configuration needs Doctor migration. It still validates core configuration and refuses configuration written by a newer OpenClaw binary. Start and restart continue to validate plugin configuration.

Recover an unreadable native service definition

If installation or a managed update reports SERVICE_DEFINITION_UNKNOWN, first restore access to the service files and native service manager. --force does not bypass unknown service facts. Inspect the selected service with openclaw gateway status --deep from the account and profile that own it.

For a malformed definition or unsupported environment syntax, privately back up the service files and any values stored only in its environment. Correct unresolved or unsupported values before reinstalling; OpenClaw cannot infer their intended values. Then, from an external shell using the same account and profile:

openclaw gateway uninstallopenclaw gateway installopenclaw gateway health

Uninstall removes the native registration and launcher, preserving configuration, plugin installations, session state, and workspaces. Reinstallation rebuilds the service environment from the current configuration and installation inputs; service-only values must be supplied again. If native service status is itself unavailable, uninstall also refuses: restore native manager access first instead of deleting state or bypassing inspection.

Lifecycle requests from Gateway chat

Gateway-hosted OpenClaw chat controls the exact Gateway serving that session. An approved start request reports Gateway already running without discovering or starting another service. Restart keeps the safe local restart behavior.

An approved stop reports Scheduled Gateway stop after the host has prepared the stop for its exact instance. This acknowledges scheduling, not completed termination. An exclusive foreground host drains work, finishes teardown, and exits successfully without discovering or changing an installed service. A host managed by launchd or systemd verifies native ownership and prepares an executor, then drains work and finishes teardown before asking the native manager to stop the service. The requesting operation can finish its audit, history, and response submission during that drain; this does not guarantee that the client receives the response before disconnecting.

After the normal grace period, stop cancels the remaining runs owned by that Gateway and waits for their commands and cleanup to settle. Ordinary stop does not schedule restart recovery. A required cleanup failure produces a nonzero exit and prevents an in-process replacement, including when startup failed before the Gateway became ready.

Ownership or preparation failures leave the Gateway serving and return an error. Linux uses an independent transient control scope, in the owning systemd manager, so the stop command survives service cgroup termination. On macOS, hosted stop requests ordinary launchctl bootout without changing persistent enablement. If the native manager sends SIGTERM during the final stop handoff, the host finishes its graceful exit after joining cleanup, including the owned stop client.

On Windows, a run loop that exclusively owns the Gateway process also uses graceful process exit under Task Scheduler. It does not select or stop a task by name. The generated task supervisor waits for the child process tree to exit and propagates the child exit result through the launcher. Its RestartOnFailure policy does not restart a successful task exit. Custom wrappers can have different exit or restart behavior; check their policy separately. This stop path does not change the task definition or its restart policy. Externally supervised Gateways direct stop requests to their supervisor.

If systemd definitively refuses a stop after teardown and the same native instance remains active with no pending job, the host logs the failed stop and starts a fresh Gateway generation in the same process. An uncertain native result is recorded as a failed shutdown, without claiming success or starting an in-process replacement. After an unexpected disconnect, check openclaw gateway status and the native service logs from an external shell before retrying. Standalone CLI lifecycle commands retain their service-management behavior.

Install with a wrapper

Use --wrapper when the managed service must start through another executable, for example a secrets manager shim or a run-as helper. The wrapper receives the normal Gateway args and is responsible for eventually exec'ing openclaw or Node with those args.

cat > ~/.local/bin/openclaw-doppler <<'EOF'#!/usr/bin/env bashset -euo pipefailexec doppler run --project my-project --config production -- openclaw "$@"EOFchmod +x ~/.local/bin/openclaw-doppler openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --forceopenclaw gateway restart

You can also set the wrapper through the environment. gateway install validates that the path is an executable file, writes the wrapper into the service ProgramArguments, and persists OPENCLAW_WRAPPER in the service environment for later forced reinstalls, updates, and doctor repairs.

OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --forceopenclaw doctor

To remove a persisted wrapper, clear OPENCLAW_WRAPPER while reinstalling:

OPENCLAW_WRAPPER= openclaw gateway install --forceopenclaw gateway restart