Skip to main content

​
openclaw daemon

Legacy alias for Gateway service management. openclaw daemon ... maps to the same service-control commands as openclaw gateway .... Prefer openclaw gateway for current docs and examples.

​
Usage

​
Subcommands and options

--json is accepted before or after every subcommand (for example, daemon --json status and daemon status --json).
  • status: shows service install state (launchd/systemd/schtasks) and probes Gateway health.
  • status --port <port>: selects a local Gateway using the invoking CLI config for auth and TLS. Cannot combine with --url. Native service details remain diagnostic-only.
  • install: installs and starts the service. --force reinstalls an existing install and may restart a running Gateway. Finish offline configuration and runtime repairs before installation.
  • Node is the primary, default, and recommended service runtime. Bun 1.4+ with WAL-reset-safe node:sqlite is available as an explicit opt-in with install --runtime bun.
  • restart --safe: asks the running Gateway to preflight active work and schedule one coalesced restart after work drains, bounded to 5 minutes. When that budget expires, the restart is forced anyway. Plain restart normally uses the service manager directly. On Windows, commands launched from a Gateway service automatically use the safe restart path. Explicit lifecycle controls retain their behavior. --force is the immediate override.
  • restart --safe --skip-deferral: bypasses only the active-work deferral gate. Shutdown may still wait for pending replies to drain before the Gateway process exits. Requires --safe.

​
Notes

  • status resolves configured auth SecretRefs for probe auth when possible. If a required SecretRef is unresolved, status --json reports rpc.authWarning. Pass --token/--password explicitly, or resolve the secret source first. Unresolved-auth warnings are suppressed once the probe otherwise succeeds.
  • status --deep adds a best-effort system-level scan for other gateway-like services. The scan prints cleanup hints. One Gateway per machine is still the recommendation. status --deep also runs config validation in plugin-aware mode. That mode surfaces plugin manifest warnings that the fast default path skips.
  • On Linux systemd installs, token-drift checks inspect both Environment= and EnvironmentFile= unit sources.
  • Token-drift checks resolve gateway.auth.token SecretRefs using merged runtime env (service command env first, then process env). If token auth is not effectively active (gateway.auth.mode of password/none/trusted-proxy, or unset with password able to win), config token resolution is skipped.
  • install validates that a SecretRef-managed gateway.auth.token is resolvable. It never persists the resolved value into service environment metadata. If it cannot resolve the token, install fails closed.
  • If both gateway.auth.token and gateway.auth.password are configured and gateway.auth.mode is unset, install blocks until you set the mode explicitly.
  • On macOS, install writes LaunchAgent plists with mode 0644. Secrets stay in the generated owner-only environment file (0600), loaded through an owner-only wrapper (0700).
  • Running multiple Gateways on one host: isolate ports, config/state, and workspaces. See Multiple gateways.