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 install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

gateway stop, gateway uninstall, and gateway restart remain available when configuration is invalid or needs Doctor migration, including configuration written by a newer OpenClaw version. They control the recorded service and report config problems as warnings with openclaw doctor --fix guidance. Stop and uninstall do not rewrite configuration. Restart preserves the installed service definition when config needs repair; its health check still reports whether the Gateway came back. gateway start continues to validate configuration before starting the Gateway.

gateway status reports service process state separately from Gateway readiness. When its connection check fails, inspect the service logs even if the process is running. Recent log errors are matching evidence from the bounded log tail, may belong to an earlier run, and do not establish the current process's startup phase. Routine startup and shutdown messages are not reported as errors. Doctor and onboarding use the same error selection.

On Windows, Scheduled Task stop and restart first ask the verified Gateway to drain and exit. Older or unresponsive Gateways fall back to termination of the captured process tree; a replacement instance is preserved. Transient SQLite sharing errors after confirmed process exit are retried; if inspection remains unavailable, the command warns and checks that the Gateway port is free before continuing with restart.

If task settlement inspection remains unavailable within the stop budget, restart still attempts the captured task after confirming the Gateway exited, then reports that restart is unverified. An observed replacement is preserved and the restart is refused.

gateway start checks readiness even when the service process is already running. It reports already-running only after the selected Gateway passes the health and readiness checks; it does not restart a process that is still warming up.

If gateway start reaches its readiness deadline while the managed Gateway is still starting, it reports still-starting and exits with code 2. The service keeps running; check openclaw gateway status --deep again before restarting it. A crashed service or a foreign listener still produces a failure. Port ownership alone does not prove readiness or rule out warm-up.

Linux maintenance holds

On Linux, openclaw gateway stop asks systemd to stop the unit. An explicit stop suppresses its Restart=always policy until the unit is started again; it does not disable startup at the next login or boot. gateway stop --disable is macOS-only. For non-interactive maintenance, use openclaw gateway stop --force.

A systemd mask also refuses explicit starts. Keep masks under operator control: OpenClaw does not remove them automatically. If you masked the default user service for maintenance, remove the hold before updating:

systemctl --user unmask openclaw-gateway.service
openclaw update

Use the unit and scope shown by openclaw gateway status --deep for a custom profile or system service. Unmask before running openclaw update: preflight refuses a masked managed unit before replacing files or running migrations. Doctor and status report the mask with the unmask command; Doctor does not remove the hold or offer to reinstall the masked unit.

If a unit becomes masked during an update, the updater keeps the activated candidate and reports a service-definition warning. Remove the mask, run openclaw gateway start, and check openclaw gateway status --deep; the refused start does not prove the candidate unhealthy or the Gateway ready.

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 uninstall
openclaw gateway install
openclaw 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.

Pin the service runtime

When no runtime option is supplied, forced reinstall retains a supported Node or Bun executable recorded in an unpinned service without a wrapper. Update refresh does the same without creating a pin. Doctor also defaults to the recorded runtime when no runtime migration is needed, including an existing but unloaded service. A missing, non-executable, or unsupported recorded Bun falls back to automatic Node selection. An explicit --runtime node or --runtime bun requests automatic selection of that runtime.

Configure and advanced onboarding suggest the supported recorded runtime first. Without one, their runtime picker suggests the running supported Bun when no supported Node is available, otherwise Node. A picker choice is explicit: choosing Node on a Bun-only host reports that Node is unavailable before replacing the service. Quickstart keeps automatic selection without creating a runtime pin.

Use --runtime-path to keep the service on an operator-selected Node or Bun executable instead of automatic runtime selection:

openclaw gateway install --runtime-path "/absolute/path/to/node" --force

The path must be absolute, executable, and match --runtime when that option is also supplied. The runtime must pass the current Node/Bun and SQLite capability checks. Paths containing spaces are supported; quote them in your shell.

The pin is saved in machine-state metadata for this managed service. Forced reinstall, update, and definition repair preserve it. A missing or unsupported pin fails with a diagnostic rather than silently switching runtimes. To replace it, supply another --runtime-path; to return to automatic selection, run openclaw gateway install --runtime node --force without --runtime-path. An explicit wrapper still controls the executable and takes precedence over a pin. Installation starts the service and may restart an existing Gateway.

Repair a LaunchAgent environment wrapper

On macOS, the generated LaunchAgent starts a shell wrapper with the generated environment file followed by the Gateway command. If gateway status reports a missing environment-file argument, or the service log reports Invalid LaunchAgent environment file, run openclaw gateway install --force from the owning account and profile, then check openclaw gateway status and openclaw health.

Back up the plist and private service environment file before repairing a malformed definition. If its runtime argument was also changed, select the intended executable explicitly with --runtime-path as shown above. A recorded runtime pin whose service definition has changed must be explicitly selected again. Keep service-only environment values available to the reinstall; malformed wrapper arguments can prevent OpenClaw from reading the previous environment file.

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 bash
set -euo pipefail
exec doppler run --project my-project --config production -- openclaw "$@"
EOF
chmod +x ~/.local/bin/openclaw-doppler

openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw 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 --force
openclaw doctor

To remove a persisted wrapper, clear OPENCLAW_WRAPPER while reinstalling:

OPENCLAW_WRAPPER= openclaw gateway install --force
openclaw gateway restart