vrr/openclaw
2
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-10-04 02:00:10 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 33
openclaw/docs/cli/daemon.md
Alex Naidis b810a28a4a
docs(gateway): warn that installation starts the service (#139562) 
## What Problem This Solves

Gateway and daemon install help omitted that installation starts the service and that forced reinstallation may restart a running Gateway. Operators could activate the service before finishing offline configuration or runtime repairs.

## Why This Change Was Made

State those effects in the shared install help, Gateway CLI index, and daemon reference. Tell operators to finish offline configuration and runtime repairs before installation. Service behavior, public options, and the private updater handoff stay unchanged.

This retains @TheCrazyLex's activation-help contribution and commit ancestry. The separate Doctor, user-bus, and systemd drop-in diagnosis changes remain outside this repair; [PR #137647](https://github.com/openclaw/openclaw/pull/137647) owns that work.

## User Impact

Operators reading install help or the updated reference pages can see the activation risk before running the command. The linked Gateway service guide remains unchanged, so direct visitors to that page can still miss the index notice.

## Evidence

- Actual `pnpm openclaw gateway install --help` and `pnpm openclaw daemon install --help` on pinned main omit startup and restart effects. Both commands on `4d802b78fb94344d2dac839663d94053cad348d5` display the corrected descriptions and preserve the existing public options.
- The official Mintlify preview renders the Gateway index, daemon reference, and linked service guide on baseline and candidate. Inspected before/after screenshots, full article text and HTML, and browser results confirm the new visible warnings on the two updated pages. No browser errors were recorded.
- The 36 focused registration tests remain valid for unchanged test and implementation inputs. Fresh formatting, syntax lint, both changed pages' MDX checks, and the 13,190-link audit pass. Independent source and behavior reviews agree within the stated scope.
- Native launchd, systemd, and Scheduled Task owners were source-audited. Proof executed help and documentation preview only; no Gateway service installation or lifecycle action was run.

The preview retains its existing missing ClawHub-mirror and inactive-search warnings. Mobile layout, search, expanded service-guide panels, and published-site deployment are outside this proof.

The screenshot links require authenticated GitHub access in the verified retrieval path; anonymous requests returned 404. All four authenticated downloads matched the original inspected PNG bytes. Complete local images are retained for independent review.

<details>
<summary>Gateway documentation preview</summary>

| Before | After |
| --- | --- |
| ![Gateway index before the activation warning](https://github.com/user-attachments/assets/4f7c2b09-1b9d-49ea-8c2e-e708932812ab) | ![Gateway index with the activation and offline-preparation warning](https://github.com/user-attachments/assets/b3518e85-bf38-4111-8a29-08408415eaee) |

</details>

<details>
<summary>Daemon documentation preview</summary>

| Before | After |
| --- | --- |
| ![Daemon reference before the activation warning](https://github.com/user-attachments/assets/6e22d0f9-85fb-4f1f-8880-a520feca08aa) | ![Daemon reference with the activation and offline-preparation warning](https://github.com/user-attachments/assets/6c1d5e45-77de-449d-b477-03eeb4a0b32c) |

</details>

Co-authored-by: Ayaan Zaidi <hi@obviy.us>
2026-09-10 17:23:20 +05:30

4.8 KiB
Raw Blame History

summary read_when title
CLI reference for `openclaw daemon` (legacy alias for gateway service management)
You still use `openclaw daemon ...` in scripts
You need service lifecycle commands (install/start/stop/restart/status)
Daemon

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

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

Subcommands and options

Subcommand Options
status --url, --port, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
install --port, --runtime <node|bun>, --token, --wrapper <path>, --force, --json
uninstall --json
start --json
stop --force, --json, --disable (launchd only: suppress KeepAlive/RunAtLoad until next start)
restart --force, --safe, --skip-deferral, --wait <duration>, --json

--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.

Related