openclaw daemon: Legacy Gateway Service Control Reference

openclaw daemon

The older name for handling Gateway service operations. openclaw daemon ... points to the same set of service-control commands as openclaw gateway .... For up-to-date guidance and samples, turn to openclaw gateway.

Usage

openclaw daemon status
openclaw daemon install
openclaw daemon start
openclaw daemon stop
openclaw daemon restart
openclaw daemon uninstall

Subcommands and options

--json works either before or after any subcommand, for instance daemon --json status and daemon status --json.

• status: reports whether the service is installed (launchd/systemd/schtasks) and checks Gateway health.
• status --port <port>: picks a local Gateway, relying on the invoking CLI config for auth and TLS. It cannot be used together with --url; native service details are for diagnostics only.
• install: sets up the service, while --force reinstalls or overwrites an existing setup.
• Node serves as the primary, default, and recommended runtime for the service. Bun 1.4+ with WAL-reset-safe node:sqlite is an explicit opt-in through install --runtime bun.
• restart --safe: instructs the running Gateway to preflight active work and arrange a single combined restart once work finishes draining, capped at 5 minutes. If that limit is reached, the restart is forced regardless. A plain restart goes straight through the service manager, and --force is the immediate override.
• restart --safe --skip-deferral: skips only the active-work deferral gate. Shutdown can still wait for pending replies to finish before the Gateway process exits. --safe is a prerequisite.

Notes

• When a probe's auth SecretRefs can be resolved, status handles them automatically. Should a required SecretRef remain unresolved, status --json flags it with rpc.authWarning; either supply --token/--password directly or ensure the secret source is resolved beforehand. Once the probe passes on its own, warnings about unresolved auth are no longer shown.
• status --deep performs a best-effort scan across the system for other gateway-like services, offering cleanup suggestions while still recommending one Gateway per machine, and it runs config validation with plugin awareness, exposing plugin manifest warnings that the quicker default route omits.
• On Linux systemd setups, token-drift checks look at both Environment= and EnvironmentFile= unit sources.
• For token-drift checks, gateway.auth.token SecretRefs are resolved using merged runtime environment variables, with service command env taking priority over process env. If token auth isn't truly active, which happens when gateway.auth.mode of password/none/trusted-proxy is present, or when it's unset and a password could take precedence, config token resolution gets skipped.
• install confirms that a gateway.auth.token managed by SecretRef is resolvable but never writes the resolved value into service environment metadata; if resolution fails, the install stops with an error.
• When both gateway.auth.token and gateway.auth.password are set and gateway.auth.mode is missing, install waits until you explicitly choose the mode.
• On macOS, install restricts LaunchAgent plists and the generated env file/wrapper to the owner only, using mode 0600/0700, rather than placing secrets inside EnvironmentVariables.
• For multiple Gateways on a single host, keep ports, config/state, and workspaces separate. Refer to Multiple gateways.

Related

• CLI reference
• Gateway runbook