docs: align gateway service naming

2026-01-21 17:45:12 +00:00
parent 9e22f019db
commit c129f0bbaa
29 changed files with 211 additions and 197 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,7 @@ Docs: https://docs.clawd.bot
 - Exec approvals: support wildcard agent allowlists (`*`) across all agents.
 - Nodes: expose node PATH in status/describe and bootstrap PATH for node-host execution.
 - CLI: flatten node service commands under `clawdbot node` and remove `service node` docs.
+- CLI: move gateway service commands under `clawdbot gateway` and add `gateway probe` for reachability.

 ### Fixes
 - Nodes tool: include agent/node/gateway context in tool failure logs to speed approval debugging.
--- a/docs/cli/daemon.md
+++ b/docs/cli/daemon.md
@@ -1,23 +0,0 @@
---
-summary: "CLI reference for `clawdbot daemon` (install/uninstall/status for the Gateway service)"
-read_when:
-  - You want to run the Gateway as a background service
-  - You’re debugging daemon install, status, or logs
---
-
-# `clawdbot daemon`
-
-Manage the Gateway daemon (background service).
-
-Note: `clawdbot daemon …` is the preferred surface for Gateway service management; `daemon` remains
-as a legacy alias for compatibility.
-
-Related:
- Gateway CLI: [Gateway](/cli/gateway)
- macOS platform notes: [macOS](/platforms/macos)
-
-Tip: run `clawdbot daemon --help` for platform-specific flags.
-
-Notes:
- `daemon status` supports `--json` for scripting.
- `daemon install|uninstall|start|stop|restart` support `--json` for scripting (default output stays human-friendly).
--- a/docs/cli/gateway.md
+++ b/docs/cli/gateway.md
@@ -25,6 +25,12 @@ Run a local Gateway process:
 clawdbot gateway
 ```

+Foreground alias:
+
+```bash
+clawdbot gateway run
+```
+
 Notes:
 - By default, the Gateway refuses to start unless `gateway.mode=local` is set in `~/.clawdbot/clawdbot.json`. Use `--allow-unconfigured` for ad-hoc/dev runs.
 - Binding beyond loopback without auth is blocked (safety guardrail).
@@ -75,15 +81,32 @@ clawdbot gateway health --url ws://127.0.0.1:18789

 ### `gateway status`

-`gateway status` is the “debug everything” command. It always probes:
+`gateway status` shows the Gateway service (launchd/systemd/schtasks) plus an optional RPC probe.
+
+```bash
+clawdbot gateway status
+clawdbot gateway status --json
+```
+
+Options:
+- `--url <url>`: override the probe URL.
+- `--token <token>`: token auth for the probe.
+- `--password <password>`: password auth for the probe.
+- `--timeout <ms>`: probe timeout (default `10000`).
+- `--no-probe`: skip the RPC probe (service-only view).
+- `--deep`: scan system-level services too.
+
+### `gateway probe`
+
+`gateway probe` is the “debug everything” command. It always probes:
 - your configured remote gateway (if set), and
 - localhost (loopback) **even if remote is configured**.

 If multiple gateways are reachable, it prints all of them. Multiple gateways are supported when you use isolated profiles/ports (e.g., a rescue bot), but most installs still run a single gateway.

 ```bash
-clawdbot gateway status
-clawdbot gateway status --json
+clawdbot gateway probe
+clawdbot gateway probe --json
 ```

 #### Remote over SSH (Mac app parity)
@@ -93,7 +116,7 @@ The macOS app “Remote over SSH” mode uses a local port-forward so the remote
 CLI equivalent:

 ```bash
-clawdbot gateway status --ssh user@gateway-host
+clawdbot gateway probe --ssh user@gateway-host
 ```

 Options:
@@ -114,6 +137,20 @@ clawdbot gateway call status
 clawdbot gateway call logs.tail --params '{"sinceMs": 60000}'
 ```

+## Manage the Gateway service
+
+```bash
+clawdbot gateway install
+clawdbot gateway start
+clawdbot gateway stop
+clawdbot gateway restart
+clawdbot gateway uninstall
+```
+
+Notes:
+- `gateway install` supports `--port`, `--runtime`, `--token`, `--force`, `--json`.
+- Lifecycle commands accept `--json` for scripting.
+
 ## Discover gateways (Bonjour)

 `gateway discover` scans for Gateway beacons (`_clawdbot-gw._tcp`).
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -28,7 +28,6 @@ This page describes the current CLI behavior. If commands change, update this do
 - [`health`](/cli/health)
 - [`sessions`](/cli/sessions)
 - [`gateway`](/cli/gateway)
- [`daemon`](/cli/daemon)
 - [`logs`](/cli/logs)
 - [`models`](/cli/models)
 - [`memory`](/cli/memory)
@@ -137,14 +136,14 @@ clawdbot [--dev] [--profile <name>] <command>
    call
    health
    status
+    probe
    discover
-  daemon
-    status
    install
    uninstall
    start
    stop
    restart
+    run
  logs
  models
    list
@@ -175,14 +174,13 @@ clawdbot [--dev] [--profile <name>] <command>
  nodes
  devices
  node
+    run
+    status
+    install
+    uninstall
    start
-    daemon
-      status
-      install
-      uninstall
-      start
-      stop
-      restart
+    stop
+    restart
  approvals
    get
    set
@@ -615,25 +613,25 @@ Options:
 - `--raw-stream`
 - `--raw-stream-path <path>`

-### `daemon`
+### `gateway service`
 Manage the Gateway service (launchd/systemd/schtasks).

 Subcommands:
- `daemon status` (probes the Gateway RPC by default)
- `daemon install` (service install)
- `daemon uninstall`
- `daemon start`
- `daemon stop`
- `daemon restart`
+- `gateway status` (probes the Gateway RPC by default)
+- `gateway install` (service install)
+- `gateway uninstall`
+- `gateway start`
+- `gateway stop`
+- `gateway restart`

 Notes:
- `daemon status` probes the Gateway RPC by default using the daemon’s resolved port/config (override with `--url/--token/--password`).
- `daemon status` supports `--no-probe`, `--deep`, and `--json` for scripting.
- `daemon status` also surfaces legacy or extra gateway services when it can detect them (`--deep` adds system-level scans). Profile-named Clawdbot services are treated as first-class and aren't flagged as "extra".
- `daemon status` prints which config path the CLI uses vs which config the daemon likely uses (service env), plus the resolved probe target URL.
- `daemon install|uninstall|start|stop|restart` support `--json` for scripting (default output stays human-friendly).
- `daemon install` defaults to Node runtime; bun is **not recommended** (WhatsApp/Telegram bugs).
- `daemon install` options: `--port`, `--runtime`, `--token`, `--force`, `--json`.
+- `gateway status` probes the Gateway RPC by default using the service’s resolved port/config (override with `--url/--token/--password`).
+- `gateway status` supports `--no-probe`, `--deep`, and `--json` for scripting.
+- `gateway status` also surfaces legacy or extra gateway services when it can detect them (`--deep` adds system-level scans). Profile-named Clawdbot services are treated as first-class and aren't flagged as "extra".
+- `gateway status` prints which config path the CLI uses vs which config the service likely uses (service env), plus the resolved probe target URL.
+- `gateway install|uninstall|start|stop|restart` support `--json` for scripting (default output stays human-friendly).
+- `gateway install` defaults to Node runtime; bun is **not recommended** (WhatsApp/Telegram bugs).
+- `gateway install` options: `--port`, `--runtime`, `--token`, `--force`, `--json`.

 ### `logs`
 Tail Gateway file logs via RPC.
@@ -652,13 +650,16 @@ clawdbot logs --no-color
 ```

 ### `gateway <subcommand>`
-Gateway RPC helpers (use `--url`, `--token`, `--password`, `--timeout`, `--expect-final` for each).
+Gateway CLI helpers (use `--url`, `--token`, `--password`, `--timeout`, `--expect-final` for RPC subcommands).

 Subcommands:
 - `gateway call <method> [--params <json>]`
 - `gateway health`
 - `gateway status`
+- `gateway probe`
 - `gateway discover`
+- `gateway install|uninstall|start|stop|restart`
+- `gateway run`

 Common RPCs:
 - `config.apply` (validate + write config + restart + wake)
--- a/docs/cli/update.md
+++ b/docs/cli/update.md
@@ -1,5 +1,5 @@
 ---
-summary: "CLI reference for `clawdbot update` (safe-ish source update + optional daemon restart)"
+summary: "CLI reference for `clawdbot update` (safe-ish source update + optional gateway restart)"
 read_when:
  - You want to update a source checkout safely
  - You need to understand `--update` shorthand behavior
@@ -26,7 +26,7 @@ clawdbot --update

 ## Options

- `--restart`: restart the Gateway daemon after a successful update.
+- `--restart`: restart the Gateway service after a successful update.
 - `--channel <stable|beta|dev>`: set the update channel (git + npm; persisted in config).
 - `--tag <dist-tag|version>`: override the npm dist-tag or version for this update only.
 - `--json`: print machine-readable `UpdateRunResult` JSON.
--- a/docs/debugging.md
+++ b/docs/debugging.md
@@ -100,7 +100,7 @@ CLAWDBOT_PROFILE=dev clawdbot gateway --dev --reset
 Tip: if a non‑dev gateway is already running (launchd/systemd), stop it first:

 ```bash
-clawdbot daemon stop
+clawdbot gateway stop
 ```

 ## Raw stream logging (Clawdbot)
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -829,8 +829,6 @@
          "cli/nodes",
          "cli/approvals",
          "cli/gateway",
-          "cli/daemon",
-          "cli/service",
          "cli/tui",
          "cli/voicecall",
          "cli/wake",
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -24,7 +24,7 @@ Unknown keys, malformed types, or invalid values cause the Gateway to **refuse t

 When validation fails:
 - The Gateway does not boot.
- Only diagnostic commands are allowed (for example: `clawdbot doctor`, `clawdbot logs`, `clawdbot health`, `clawdbot status`, `clawdbot daemon`, `clawdbot help`).
+- Only diagnostic commands are allowed (for example: `clawdbot doctor`, `clawdbot logs`, `clawdbot health`, `clawdbot status`, `clawdbot gateway status`, `clawdbot gateway probe`, `clawdbot help`).
 - Run `clawdbot doctor` to see the exact issues.
 - Run `clawdbot doctor --fix` (or `--yes`) to apply migrations/repairs.

--- a/docs/gateway/doctor.md
+++ b/docs/gateway/doctor.md
@@ -225,10 +225,10 @@ Notes:
 - `clawdbot doctor --yes` accepts the default repair prompts.
 - `clawdbot doctor --repair` applies recommended fixes without prompts.
 - `clawdbot doctor --repair --force` overwrites custom supervisor configs.
- You can always force a full rewrite via `clawdbot daemon install --force`.
+- You can always force a full rewrite via `clawdbot gateway install --force`.

 ### 16) Gateway runtime + port diagnostics
-Doctor inspects the daemon runtime (PID, last exit status) and warns when the
+Doctor inspects the service runtime (PID, last exit status) and warns when the
 service is installed but not actually running. It also checks for port collisions
 on the gateway port (default `18789`) and reports likely causes (gateway already
 running, SSH tunnel).
@@ -236,7 +236,7 @@ running, SSH tunnel).
 ### 17) Gateway runtime best practices
 Doctor warns when the gateway service runs on Bun or a version-managed Node path
 (`nvm`, `fnm`, `volta`, `asdf`, etc.). WhatsApp + Telegram channels require Node,
-and version-manager paths can break after upgrades because the daemon does not
+and version-manager paths can break after upgrades because the service does not
 load your shell init. Doctor offers to migrate to a system Node install when
 available (Homebrew/apt/choco).

--- a/docs/gateway/index.md
+++ b/docs/gateway/index.md
@@ -1,9 +1,9 @@
 ---
-summary: "Runbook for the Gateway daemon, lifecycle, and operations"
+summary: "Runbook for the Gateway service, lifecycle, and operations"
 read_when:
  - Running or debugging the gateway process
 ---
-# Gateway (daemon) runbook
+# Gateway service runbook

 Last updated: 2025-12-09

@@ -101,10 +101,10 @@ Checklist per instance:
 - unique `agents.defaults.workspace`
 - separate WhatsApp numbers (if using WA)

-Daemon install per profile:
+Service install per profile:
 ```bash
-clawdbot --profile main daemon install
-clawdbot --profile rescue daemon install
+clawdbot --profile main gateway install
+clawdbot --profile rescue gateway install
 ```

 Example:
@@ -175,49 +175,49 @@ See also: [Presence](/concepts/presence) for how presence is produced/deduped an
 - Events are not replayed. Clients detect seq gaps and should refresh (`health` + `system-presence`) before continuing. WebChat and macOS clients now auto-refresh on gap.

 ## Supervision (macOS example)
- Use launchd to keep the daemon alive:
+- Use launchd to keep the service alive:
  - Program: path to `clawdbot`
  - Arguments: `gateway`
  - KeepAlive: true
  - StandardOut/Err: file paths or `syslog`
 - On failure, launchd restarts; fatal misconfig should keep exiting so the operator notices.
 - LaunchAgents are per-user and require a logged-in session; for headless setups use a custom LaunchDaemon (not shipped).
-  - `clawdbot daemon install` writes `~/Library/LaunchAgents/com.clawdbot.gateway.plist`
+  - `clawdbot gateway install` writes `~/Library/LaunchAgents/com.clawdbot.gateway.plist`
    (or `com.clawdbot.<profile>.plist`).
  - `clawdbot doctor` audits the LaunchAgent config and can update it to current defaults.

-## Daemon management (CLI)
+## Gateway service management (CLI)

-Use the CLI daemon manager for install/start/stop/restart/status:
+Use the Gateway CLI for install/start/stop/restart/status:

 ```bash
-clawdbot daemon status
-clawdbot daemon install
-clawdbot daemon stop
-clawdbot daemon restart
+clawdbot gateway status
+clawdbot gateway install
+clawdbot gateway stop
+clawdbot gateway restart
 clawdbot logs --follow
 ```

 Notes:
- `daemon status` probes the Gateway RPC by default using the daemon’s resolved port/config (override with `--url`).
- `daemon status --deep` adds system-level scans (LaunchDaemons/system units).
- `daemon status --no-probe` skips the RPC probe (useful when networking is down).
- `daemon status --json` is stable for scripts.
- `daemon status` reports **supervisor runtime** (launchd/systemd running) separately from **RPC reachability** (WS connect + status RPC).
- `daemon status` prints config path + probe target to avoid “localhost vs LAN bind” confusion and profile mismatches.
- `daemon status` includes the last gateway error line when the service looks running but the port is closed.
+- `gateway status` probes the Gateway RPC by default using the service’s resolved port/config (override with `--url`).
+- `gateway status --deep` adds system-level scans (LaunchDaemons/system units).
+- `gateway status --no-probe` skips the RPC probe (useful when networking is down).
+- `gateway status --json` is stable for scripts.
+- `gateway status` reports **supervisor runtime** (launchd/systemd running) separately from **RPC reachability** (WS connect + status RPC).
+- `gateway status` prints config path + probe target to avoid “localhost vs LAN bind” confusion and profile mismatches.
+- `gateway status` includes the last gateway error line when the service looks running but the port is closed.
 - `logs` tails the Gateway file log via RPC (no manual `tail`/`grep` needed).
 - If other gateway-like services are detected, the CLI warns unless they are Clawdbot profile services.
  We still recommend **one gateway per machine** for most setups; use isolated profiles/ports for redundancy or a rescue bot. See [Multiple gateways](/gateway/multiple-gateways).
-  - Cleanup: `clawdbot daemon uninstall` (current service) and `clawdbot doctor` (legacy migrations).
- `daemon install` is a no-op when already installed; use `clawdbot daemon install --force` to reinstall (profile/env/path changes).
+  - Cleanup: `clawdbot gateway uninstall` (current service) and `clawdbot doctor` (legacy migrations).
+- `gateway install` is a no-op when already installed; use `clawdbot gateway install --force` to reinstall (profile/env/path changes).

 Bundled mac app:
 - Clawdbot.app can bundle a Node-based gateway relay and install a per-user LaunchAgent labeled
  `com.clawdbot.gateway` (or `com.clawdbot.<profile>`).
- To stop it cleanly, use `clawdbot daemon stop` (or `launchctl bootout gui/$UID/com.clawdbot.gateway`).
- To restart, use `clawdbot daemon restart` (or `launchctl kickstart -k gui/$UID/com.clawdbot.gateway`).
-  - `launchctl` only works if the LaunchAgent is installed; otherwise use `clawdbot daemon install` first.
+- To stop it cleanly, use `clawdbot gateway stop` (or `launchctl bootout gui/$UID/com.clawdbot.gateway`).
+- To restart, use `clawdbot gateway restart` (or `launchctl kickstart -k gui/$UID/com.clawdbot.gateway`).
+  - `launchctl` only works if the LaunchAgent is installed; otherwise use `clawdbot gateway install` first.
  - Replace the label with `com.clawdbot.<profile>` when running a named profile.

 ## Supervision (systemd user unit)
@@ -226,7 +226,7 @@ recommend user services for single-user machines (simpler env, per-user config).
 Use a **system service** for multi-user or always-on servers (no lingering
 required, shared supervision).

-`clawdbot daemon install` writes the user unit. `clawdbot doctor` audits the
+`clawdbot gateway install` writes the user unit. `clawdbot doctor` audits the
 unit and can update it to match the current recommended defaults.

 Create `~/.config/systemd/user/clawdbot-gateway[-<profile>].service`:
@@ -285,7 +285,7 @@ Windows installs should use **WSL2** and follow the Linux systemd section above.
 - `clawdbot message send --target <num> --message "hi" [--media ...]` — send via Gateway (idempotent for WhatsApp).
 - `clawdbot agent --message "hi" --to <num>` — run an agent turn (waits for final by default).
 - `clawdbot gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
- `clawdbot daemon stop|restart` — stop/restart the supervised gateway service (launchd/systemd).
+- `clawdbot gateway stop|restart` — stop/restart the supervised gateway service (launchd/systemd).
 - Gateway helper subcommands assume a running gateway on `--url`; they no longer auto-spawn one.

 ## Migration guidance
--- a/docs/gateway/multiple-gateways.md
+++ b/docs/gateway/multiple-gateways.md
@@ -31,10 +31,10 @@ clawdbot --profile rescue setup
 clawdbot --profile rescue gateway --port 19001
 ```

-Per-profile daemons:
+Per-profile services:
 ```bash
-clawdbot --profile main daemon install
-clawdbot --profile rescue daemon install
+clawdbot --profile main gateway install
+clawdbot --profile rescue gateway install
 ```

 ## Rescue-bot guide
@@ -55,7 +55,7 @@ Port spacing: leave at least 20 ports between base ports so the derived bridge/b
 # Main bot (existing or fresh, without --profile param)
 # Runs on port 18789 + Chrome CDC/Canvas/... Ports 
 clawdbot onboard
-clawdbot daemon install
+clawdbot gateway install

 # Rescue bot (isolated profile + ports)
 clawdbot --profile rescue onboard
@@ -65,8 +65,8 @@ clawdbot --profile rescue onboard
 #   better choose completely different base port, like 19789,
 # - rest of the onboarding is the same as normal

-# To install the daemon (if not happened automatically during onboarding)
-clawdbot --profile rescue daemon install
+# To install the service (if not happened automatically during onboarding)
+clawdbot --profile rescue gateway install
 ```

 ## Port mapping (derived)
--- a/docs/gateway/remote.md
+++ b/docs/gateway/remote.md
@@ -50,7 +50,7 @@ Guide: [Tailscale](/gateway/tailscale) and [Web overview](/web).

 ## Command flow (what runs where)

-One gateway daemon owns state + channels. Nodes are peripherals.
+One gateway service owns state + channels. Nodes are peripherals.

 Flow example (Telegram → node):
 - Telegram message arrives at the **Gateway**.
@@ -59,7 +59,7 @@ Flow example (Telegram → node):
 - Node returns the result; Gateway replies back out to Telegram.

 Notes:
- **Nodes do not run the gateway daemon.** Only one gateway should run per host unless you intentionally run isolated profiles (see [Multiple gateways](/gateway/multiple-gateways)).
+- **Nodes do not run the gateway service.** Only one gateway should run per host unless you intentionally run isolated profiles (see [Multiple gateways](/gateway/multiple-gateways)).
 - macOS app “node mode” is just a node client over the Bridge.

 ## SSH tunnel (CLI + tools)
--- a/docs/gateway/troubleshooting.md
+++ b/docs/gateway/troubleshooting.md
@@ -17,12 +17,12 @@ Quick triage commands (in order):

 | Command | What it tells you | When to use it |
 |---|---|---|
-| `clawdbot status` | Local summary: OS + update, gateway reachability/mode, daemon, agents/sessions, provider config state | First check, quick overview |
+| `clawdbot status` | Local summary: OS + update, gateway reachability/mode, service, agents/sessions, provider config state | First check, quick overview |
 | `clawdbot status --all` | Full local diagnosis (read-only, pasteable, safe-ish) incl. log tail | When you need to share a debug report |
 | `clawdbot status --deep` | Runs gateway health checks (incl. provider probes; requires reachable gateway) | When “configured” doesn’t mean “working” |
-| `clawdbot gateway status` | Gateway discovery + reachability (local + remote targets) | When you suspect you’re probing the wrong gateway |
+| `clawdbot gateway probe` | Gateway discovery + reachability (local + remote targets) | When you suspect you’re probing the wrong gateway |
 | `clawdbot channels status --probe` | Asks the running gateway for channel status (and optionally probes) | When gateway is reachable but channels misbehave |
-| `clawdbot daemon status` | Supervisor state (launchd/systemd/schtasks), runtime PID/exit, last gateway error | When the daemon “looks loaded” but nothing runs |
+| `clawdbot gateway status` | Supervisor state (launchd/systemd/schtasks), runtime PID/exit, last gateway error | When the service “looks loaded” but nothing runs |
 | `clawdbot logs --follow` | Live logs (best signal for runtime issues) | When you need the actual failure reason |

 **Sharing output:** prefer `clawdbot status --all` (it redacts tokens). If you paste `clawdbot status`, consider setting `CLAWDBOT_SHOW_SECRETS=0` first (token previews).
@@ -38,16 +38,16 @@ Follow [Secret scanning](/gateway/security#secret-scanning-detect-secrets).

 ### Service Installed but Nothing is Running

-If the gateway service is installed but the process exits immediately, the daemon
+If the gateway service is installed but the process exits immediately, the service
 can appear “loaded” while nothing is running.

 **Check:**
 ```bash
-clawdbot daemon status
+clawdbot gateway status
 clawdbot doctor
 ```

-Doctor/daemon will show runtime state (PID/last exit) and log hints.
+Doctor/service will show runtime state (PID/last exit) and log hints.

 **Logs:**
 - Preferred: `clawdbot logs --follow`
@@ -71,12 +71,12 @@ See [/logging](/logging) for a full overview of formats, config, and access.

 ### Service Environment (PATH + runtime)

-The gateway daemon runs with a **minimal PATH** to avoid shell/manager cruft:
+The gateway service runs with a **minimal PATH** to avoid shell/manager cruft:
 - macOS: `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin`
 - Linux: `/usr/local/bin`, `/usr/bin`, `/bin`

 This intentionally excludes version managers (nvm/fnm/volta/asdf) and package
-managers (pnpm/npm) because the daemon does not load your shell init. Runtime
+managers (pnpm/npm) because the service does not load your shell init. Runtime
 variables like `DISPLAY` should live in `~/.clawdbot/.env` (loaded early by the
 gateway).
 Exec runs on `host=gateway` merge your login-shell `PATH` into the exec environment,
@@ -106,31 +106,31 @@ the Gateway likely refused to bind.
 **What "running" means here**
 - `Runtime: running` means your supervisor (launchd/systemd/schtasks) thinks the process is alive.
 - `RPC probe` means the CLI could actually connect to the gateway WebSocket and call `status`.
- Always trust `Probe target:` + `Config (daemon):` as the “what did we actually try?” lines.
+- Always trust `Probe target:` + `Config (service):` as the “what did we actually try?” lines.

 **Check:**
- `gateway.mode` must be `local` for `clawdbot gateway` and the daemon.
- If you set `gateway.mode=remote`, the **CLI defaults** to a remote URL. The daemon can still be running locally, but your CLI may be probing the wrong place. Use `clawdbot daemon status` to see the daemon’s resolved port + probe target (or pass `--url`).
- `clawdbot daemon status` and `clawdbot doctor` surface the **last gateway error** from logs when the service looks running but the port is closed.
+- `gateway.mode` must be `local` for `clawdbot gateway` and the service.
+- If you set `gateway.mode=remote`, the **CLI defaults** to a remote URL. The service can still be running locally, but your CLI may be probing the wrong place. Use `clawdbot gateway status` to see the service’s resolved port + probe target (or pass `--url`).
+- `clawdbot gateway status` and `clawdbot doctor` surface the **last gateway error** from logs when the service looks running but the port is closed.
 - Non-loopback binds (`lan`/`tailnet`/`auto`) require auth:
  `gateway.auth.token` (or `CLAWDBOT_GATEWAY_TOKEN`).
 - `gateway.remote.token` is for remote CLI calls only; it does **not** enable local auth.
 - `gateway.token` is ignored; use `gateway.auth.token`.

-**If `clawdbot daemon status` shows a config mismatch**
- `Config (cli): ...` and `Config (daemon): ...` should normally match.
- If they don’t, you’re almost certainly editing one config while the daemon is running another.
- Fix: rerun `clawdbot daemon install --force` from the same `--profile` / `CLAWDBOT_STATE_DIR` you want the daemon to use.
+**If `clawdbot gateway status` shows a config mismatch**
+- `Config (cli): ...` and `Config (service): ...` should normally match.
+- If they don’t, you’re almost certainly editing one config while the service is running another.
+- Fix: rerun `clawdbot gateway install --force` from the same `--profile` / `CLAWDBOT_STATE_DIR` you want the service to use.

-**If `clawdbot daemon status` reports service config issues**
+**If `clawdbot gateway status` reports service config issues**
 - The supervisor config (launchd/systemd/schtasks) is missing current defaults.
- Fix: run `clawdbot doctor` to update it (or `clawdbot daemon install --force` for a full rewrite).
+- Fix: run `clawdbot doctor` to update it (or `clawdbot gateway install --force` for a full rewrite).

 **If `Last gateway error:` mentions “refusing to bind … without auth”**
 - You set `gateway.bind` to a non-loopback mode (`lan`/`tailnet`/`auto`) but left auth off.
- Fix: set `gateway.auth.mode` + `gateway.auth.token` (or export `CLAWDBOT_GATEWAY_TOKEN`) and restart the daemon.
+- Fix: set `gateway.auth.mode` + `gateway.auth.token` (or export `CLAWDBOT_GATEWAY_TOKEN`) and restart the service.

-**If `clawdbot daemon status` says `bind=tailnet` but no tailnet interface was found**
+**If `clawdbot gateway status` says `bind=tailnet` but no tailnet interface was found**
 - The gateway tried to bind to a Tailscale IP (100.64.0.0/10) but none were detected on the host.
 - Fix: bring up Tailscale on that machine (or change `gateway.bind` to `loopback`/`lan`).

@@ -144,7 +144,7 @@ This means something is already listening on the gateway port.

 **Check:**
 ```bash
-clawdbot daemon status
+clawdbot gateway status
 ```

 It will show the listener(s) and likely causes (gateway already running, SSH tunnel).
@@ -354,7 +354,7 @@ clawdbot doctor --fix
 Notes:
 - `clawdbot doctor` reports every invalid entry.
 - `clawdbot doctor --fix` applies migrations/repairs and rewrites the config.
- Diagnostic commands like `clawdbot logs`, `clawdbot health`, `clawdbot status`, and `clawdbot daemon` still run even if the config is invalid.
+- Diagnostic commands like `clawdbot logs`, `clawdbot health`, `clawdbot status`, `clawdbot gateway status`, and `clawdbot gateway probe` still run even if the config is invalid.

 ### “All models failed” — what should I check first?

@@ -407,7 +407,7 @@ git status   # ensure you’re in the repo root
 pnpm install
 pnpm build
 clawdbot doctor
-clawdbot daemon restart
+clawdbot gateway restart
 ```

 Why: pnpm is the configured package manager for this repo.
@@ -432,7 +432,7 @@ Notes:
 - After switching, run:
  ```bash
  clawdbot doctor
-  clawdbot daemon restart
+  clawdbot gateway restart
  ```

 ### Telegram block streaming isn’t splitting text between tool calls. Why?
@@ -507,8 +507,8 @@ The app connects to a local gateway on port `18789`. If it stays stuck:
 **Fix 1: Stop the supervisor (preferred)**
 If the gateway is supervised by launchd, killing the PID will just respawn it. Stop the supervisor first:
 ```bash
-clawdbot daemon status
-clawdbot daemon stop
+clawdbot gateway status
+clawdbot gateway stop
 # Or: launchctl bootout gui/$UID/com.clawdbot.gateway (replace with com.clawdbot.<profile> if needed)
 ```

@@ -558,9 +558,9 @@ clawdbot channels login --verbose

 ```bash
 # Supervisor + probe target + config paths
-clawdbot daemon status
+clawdbot gateway status
 # Include system-level scans (legacy/extra services, port listeners)
-clawdbot daemon status --deep
+clawdbot gateway status --deep

 # Is the gateway reachable?
 clawdbot health --json
@@ -581,13 +581,13 @@ tail -20 /tmp/clawdbot/clawdbot-*.log
 Nuclear option:

 ```bash
-clawdbot daemon stop
+clawdbot gateway stop
 # If you installed a service and want a clean install:
-# clawdbot daemon uninstall
+# clawdbot gateway uninstall

 trash "${CLAWDBOT_STATE_DIR:-$HOME/.clawdbot}"
 clawdbot channels login         # re-pair WhatsApp
-clawdbot daemon restart           # or: clawdbot gateway
+clawdbot gateway restart           # or: clawdbot gateway
 ```

 ⚠️ This loses all sessions and requires re-pairing WhatsApp.
--- a/docs/help/troubleshooting.md
+++ b/docs/help/troubleshooting.md
@@ -14,7 +14,7 @@ Run these in order:
 ```bash
 clawdbot status
 clawdbot status --all
-clawdbot daemon status
+clawdbot gateway probe
 clawdbot logs --follow
 clawdbot doctor
 ```
@@ -38,10 +38,10 @@ Almost always a Node/npm PATH issue. Start here:
 - [Gateway troubleshooting](/gateway/troubleshooting)
 - [Gateway authentication](/gateway/authentication)

-### Daemon says running, but RPC probe fails
+### Service says running, but RPC probe fails

 - [Gateway troubleshooting](/gateway/troubleshooting)
- [Background process / daemon](/gateway/background-process)
+- [Background process / service](/gateway/background-process)

 ### Model/auth failures (rate limit, billing, “all models failed”)

--- a/docs/index.md
+++ b/docs/index.md
@@ -103,13 +103,13 @@ Runtime requirement: **Node ≥ 22**.
 npm install -g clawdbot@latest
 # or: pnpm add -g clawdbot@latest

-# Onboard + install the daemon (launchd/systemd user service)
+# Onboard + install the service (launchd/systemd user service)
 clawdbot onboard --install-daemon

 # Pair WhatsApp Web (shows QR)
 clawdbot channels login

-# Gateway runs via daemon after onboarding; manual run is still possible:
+# Gateway runs via the service after onboarding; manual run is still possible:
 clawdbot gateway --port 18789
 ```

--- a/docs/install/uninstall.md
+++ b/docs/install/uninstall.md
@@ -31,13 +31,13 @@ Manual steps (same result):
 1) Stop the gateway service:

 ```bash
-clawdbot daemon stop
+clawdbot gateway stop
 ```

 2) Uninstall the gateway service (launchd/systemd/schtasks):

 ```bash
-clawdbot daemon uninstall
+clawdbot gateway uninstall
 ```

 3) Delete state + config:
--- a/docs/install/updating.md
+++ b/docs/install/updating.md
@@ -68,12 +68,12 @@ Then:

 ```bash
 clawdbot doctor
-clawdbot daemon restart
+clawdbot gateway restart
 clawdbot health
 ```

 Notes:
- If your Gateway runs as a service, `clawdbot daemon restart` is preferred over killing PIDs.
+- If your Gateway runs as a service, `clawdbot gateway restart` is preferred over killing PIDs.
 - If you’re pinned to a specific version, see “Rollback / pinning” below.

 ## Update (`clawdbot update`)
@@ -148,9 +148,9 @@ Details: [Doctor](/gateway/doctor)
 CLI (works regardless of OS):

 ```bash
-clawdbot daemon status
-clawdbot daemon stop
-clawdbot daemon restart
+clawdbot gateway status
+clawdbot gateway stop
+clawdbot gateway restart
 clawdbot gateway --port 18789
 clawdbot logs --follow
 ```
@@ -159,7 +159,7 @@ If you’re supervised:
 - macOS launchd (app-bundled LaunchAgent): `launchctl kickstart -k gui/$UID/com.clawdbot.gateway` (use `com.clawdbot.<profile>` if set)
 - Linux systemd user service: `systemctl --user restart clawdbot-gateway[-<profile>].service`
 - Windows (WSL2): `systemctl --user restart clawdbot-gateway[-<profile>].service`
-  - `launchctl`/`systemctl` only work if the service is installed; otherwise run `clawdbot daemon install`.
+  - `launchctl`/`systemctl` only work if the service is installed; otherwise run `clawdbot gateway install`.

 Runbook + exact service labels: [Gateway runbook](/gateway)

@@ -183,7 +183,7 @@ Then restart + re-run doctor:

 ```bash
 clawdbot doctor
-clawdbot daemon restart
+clawdbot gateway restart
 ```

 ### Pin (source) by date
@@ -200,7 +200,7 @@ Then reinstall deps + restart:
 ```bash
 pnpm install
 pnpm build
-clawdbot daemon restart
+clawdbot gateway restart
 ```

 If you want to go back to latest later:
--- a/docs/nodes/index.md
+++ b/docs/nodes/index.md
@@ -13,7 +13,7 @@ A **node** is a companion device (iOS/Android today) that connects to the Gatewa
 macOS can also run in **node mode**: the menubar app connects to the Gateway’s bridge and exposes its local canvas/camera commands as a node (so `clawdbot nodes …` works against this Mac).

 Notes:
- Nodes are **peripherals**, not gateways. They don’t run the gateway daemon.
+- Nodes are **peripherals**, not gateways. They don’t run the gateway service.
 - Telegram/WhatsApp/etc. messages land on the **gateway**, not on nodes.

 ## Pairing + status
--- a/docs/platforms/exe-dev.md
+++ b/docs/platforms/exe-dev.md
@@ -97,7 +97,7 @@ It can set up:
 - `~/.clawdbot/clawdbot.json` config
 - model auth profiles
 - model provider config/login
- Linux systemd **user** service (daemon)
+- Linux systemd **user** service (service)

 If you’re doing OAuth on a headless VM: do OAuth on a normal machine first, then copy the auth profile to the VM (see [Help](/help)).

@@ -125,7 +125,7 @@ export CLAWDBOT_GATEWAY_TOKEN="$(openssl rand -hex 32)"
 clawdbot gateway --bind lan --port 8080 --token "$CLAWDBOT_GATEWAY_TOKEN"
 ```

-For daemon runs, persist it in `~/.clawdbot/clawdbot.json`:
+For service runs, persist it in `~/.clawdbot/clawdbot.json`:

 ```json5
 {
@@ -159,7 +159,7 @@ Notes:

 Control UI details: [Control UI](/web/control-ui)

-## 6) Keep it running (daemon)
+## 6) Keep it running (service)

 On Linux, Clawdbot uses a systemd **user** service. After `--install-daemon`, verify:

@@ -180,7 +180,7 @@ More: [Linux](/platforms/linux)
 ```bash
 npm i -g clawdbot@latest
 clawdbot doctor
-clawdbot daemon restart
+clawdbot gateway restart
 clawdbot health
 ```

--- a/docs/platforms/index.md
+++ b/docs/platforms/index.md
@@ -31,15 +31,15 @@ Native companion apps for Windows are also planned; the Gateway is recommended v
 - Install guide: [Getting Started](/start/getting-started)
 - Gateway runbook: [Gateway](/gateway)
 - Gateway configuration: [Configuration](/gateway/configuration)
- Service status: `clawdbot daemon status`
+- Service status: `clawdbot gateway status`

 ## Gateway service install (CLI)

 Use one of these (all supported):

 - Wizard (recommended): `clawdbot onboard --install-daemon`
- Direct: `clawdbot daemon install`
- Configure flow: `clawdbot configure` → select **Gateway daemon**
+- Direct: `clawdbot gateway install`
+- Configure flow: `clawdbot configure` → select **Gateway service**
 - Repair/migrate: `clawdbot doctor` (offers to install or fix the service)

 The service target depends on OS:
--- a/docs/platforms/linux.md
+++ b/docs/platforms/linux.md
@@ -41,7 +41,7 @@ clawdbot onboard --install-daemon
 Or:

 ```
-clawdbot daemon install
+clawdbot gateway install
 ```

 Or:
@@ -50,7 +50,7 @@ Or:
 clawdbot configure
 ```

-Select **Gateway daemon** when prompted.
+Select **Gateway service** when prompted.

 Repair/migrate:

--- a/docs/platforms/mac/bundled-gateway.md
+++ b/docs/platforms/mac/bundled-gateway.md
@@ -34,7 +34,7 @@ Plist location (per‑user):

 Manager:
 - The macOS app owns LaunchAgent install/update in Local mode.
- The CLI can also install it: `clawdbot daemon install`.
+- The CLI can also install it: `clawdbot gateway install`.

 Behavior:
 - “Clawdbot Active” enables/disables the LaunchAgent.
--- a/docs/platforms/mac/dev-setup.md
+++ b/docs/platforms/mac/dev-setup.md
@@ -82,8 +82,8 @@ If the app crashes when you try to allow **Speech Recognition** or **Microphone*
 If the gateway status stays on "Starting...", check if a zombie process is holding the port:

 ```bash
-clawdbot daemon status
-clawdbot daemon stop
+clawdbot gateway status
+clawdbot gateway stop

 # If you’re not using a LaunchAgent (dev mode / manual runs), find the listener:
 lsof -nP -iTCP:18789 -sTCP:LISTEN
--- a/docs/platforms/macos.md
+++ b/docs/platforms/macos.md
@@ -24,7 +24,7 @@ capabilities to the agent as a node.
 ## Local vs remote mode

 - **Local** (default): the app attaches to a running local Gateway if present;
-  otherwise it enables the launchd service via `clawdbot daemon`.
+  otherwise it enables the launchd service via `clawdbot gateway install`.
 - **Remote**: the app connects to a Gateway over SSH/Tailscale and never starts
  a local process.
  The app starts the local **node host service** so the remote Gateway can reach this Mac.
@@ -43,7 +43,7 @@ launchctl bootout gui/$UID/com.clawdbot.gateway
 Replace the label with `com.clawdbot.<profile>` when running a named profile.

 If the LaunchAgent isn’t installed, enable it from the app or run
-`clawdbot daemon install`.
+`clawdbot gateway install`.

 ## Node capabilities (mac)

--- a/docs/platforms/windows.md
+++ b/docs/platforms/windows.md
@@ -32,7 +32,7 @@ clawdbot onboard --install-daemon
 Or:

 ```
-clawdbot daemon install
+clawdbot gateway install
 ```

 Or:
@@ -41,7 +41,7 @@ Or:
 clawdbot configure
 ```

-Select **Gateway daemon** when prompted.
+Select **Gateway service** when prompted.

 Repair/migrate:

@@ -108,7 +108,7 @@ wsl --install -d Ubuntu-24.04

 Reboot if Windows asks.

-### 2) Enable systemd (required for daemon install)
+### 2) Enable systemd (required for gateway install)

 In your WSL terminal:

--- a/docs/refactor/strict-config.md
+++ b/docs/refactor/strict-config.md
@@ -54,7 +54,7 @@ Allowed (diagnostic-only):
 - `clawdbot health`
 - `clawdbot help`
 - `clawdbot status`
- `clawdbot daemon`
+- `clawdbot gateway status`

 Everything else must hard-fail with: “Config invalid. Run `clawdbot doctor --fix`.”

--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -59,14 +59,14 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
  - [How do I use Brave for browser control?](#how-do-i-use-brave-for-browser-control)
 - [Remote gateways + nodes](#remote-gateways-nodes)
  - [How do commands propagate between Telegram, the gateway, and nodes?](#how-do-commands-propagate-between-telegram-the-gateway-and-nodes)
-  - [Do nodes run a gateway daemon?](#do-nodes-run-a-gateway-daemon)
+  - [Do nodes run a gateway service?](#do-nodes-run-a-gateway-service)
  - [Is there an API / RPC way to apply config?](#is-there-an-api-rpc-way-to-apply-config)
  - [What’s a minimal “sane” config for a first install?](#whats-a-minimal-sane-config-for-a-first-install)
  - [How do I set up Tailscale on a VPS and connect from my Mac?](#how-do-i-set-up-tailscale-on-a-vps-and-connect-from-my-mac)
  - [How do I connect a Mac node to a remote Gateway (Tailscale Serve)?](#how-do-i-connect-a-mac-node-to-a-remote-gateway-tailscale-serve)
 - [Env vars and .env loading](#env-vars-and-env-loading)
  - [How does Clawdbot load environment variables?](#how-does-clawdbot-load-environment-variables)
-  - [“I started the Gateway via a daemon and my env vars disappeared.” What now?](#i-started-the-gateway-via-a-daemon-and-my-env-vars-disappeared-what-now)
+  - [“I started the Gateway via the service and my env vars disappeared.” What now?](#i-started-the-gateway-via-the-service-and-my-env-vars-disappeared-what-now)
  - [I set `COPILOT_GITHUB_TOKEN`, but models status shows “Shell env: off.” Why?](#i-set-copilot_github_token-but-models-status-shows-shell-env-off-why)
 - [Sessions & multiple chats](#sessions-multiple-chats)
  - [How do I start a fresh conversation?](#how-do-i-start-a-fresh-conversation)
@@ -100,8 +100,8 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
  - [OAuth vs API key: what’s the difference?](#oauth-vs-api-key-whats-the-difference)
 - [Gateway: ports, “already running”, and remote mode](#gateway-ports-already-running-and-remote-mode)
  - [What port does the Gateway use?](#what-port-does-the-gateway-use)
-  - [Why does `clawdbot daemon status` say `Runtime: running` but `RPC probe: failed`?](#why-does-clawdbot-daemon-status-say-runtime-running-but-rpc-probe-failed)
-  - [Why does `clawdbot daemon status` show `Config (cli)` and `Config (daemon)` different?](#why-does-clawdbot-daemon-status-show-config-cli-and-config-daemon-different)
+  - [Why does `clawdbot gateway status` say `Runtime: running` but `RPC probe: failed`?](#why-does-clawdbot-gateway-status-say-runtime-running-but-rpc-probe-failed)
+  - [Why does `clawdbot gateway status` show `Config (cli)` and `Config (service)` different?](#why-does-clawdbot-gateway-status-show-config-cli-and-config-service-different)
  - [What does “another gateway instance is already listening” mean?](#what-does-another-gateway-instance-is-already-listening-mean)
  - [How do I run Clawdbot in remote mode (client connects to a Gateway elsewhere)?](#how-do-i-run-clawdbot-in-remote-mode-client-connects-to-a-gateway-elsewhere)
  - [The Control UI says “unauthorized” (or keeps reconnecting). What now?](#the-control-ui-says-unauthorized-or-keeps-reconnecting-what-now)
@@ -110,8 +110,8 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
  - [What does “invalid handshake” / code 1008 mean?](#what-does-invalid-handshake--code-1008-mean)
 - [Logging and debugging](#logging-and-debugging)
  - [Where are logs?](#where-are-logs)
-  - [How do I start/stop/restart the Gateway daemon?](#how-do-i-startstoprestart-the-gateway-daemon)
-  - [ELI5: `clawdbot daemon restart` vs `clawdbot gateway`](#eli5-clawdbot-daemon-restart-vs-clawdbot-gateway)
+  - [How do I start/stop/restart the Gateway service?](#how-do-i-startstoprestart-the-gateway-service)
+  - [ELI5: `clawdbot gateway restart` vs `clawdbot gateway`](#eli5-clawdbot-gateway-restart-vs-clawdbot-gateway)
  - [What’s the fastest way to get more details when something fails?](#whats-the-fastest-way-to-get-more-details-when-something-fails)
 - [Media & attachments](#media-attachments)
  - [My skill generated an image/PDF, but nothing was sent](#my-skill-generated-an-imagepdf-but-nothing-was-sent)
@@ -129,7 +129,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   ```bash
   clawdbot status
   ```
-   Fast local summary: OS + update, gateway/daemon reachability, agents/sessions, provider config + runtime issues (when gateway is reachable).
+   Fast local summary: OS + update, gateway/service reachability, agents/sessions, provider config + runtime issues (when gateway is reachable).

 2) **Pasteable report (safe to share)**
   ```bash
@@ -139,9 +139,9 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,

 3) **Daemon + port state**
   ```bash
-   clawdbot daemon status
+   clawdbot gateway status
   ```
-   Shows supervisor runtime vs RPC reachability, the probe target URL, and which config the daemon likely used.
+   Shows supervisor runtime vs RPC reachability, the probe target URL, and which config the service likely used.

 4) **Deep probes**
   ```bash
@@ -335,7 +335,7 @@ cd clawdbot
 pnpm install
 pnpm build
 clawdbot doctor
-clawdbot daemon restart
+clawdbot gateway restart
 ```

 From git → npm:
@@ -343,7 +343,7 @@ From git → npm:
 ```bash
 npm install -g clawdbot@latest
 clawdbot doctor
-clawdbot daemon restart
+clawdbot gateway restart
 ```

 Doctor detects a gateway service entrypoint mismatch and offers to rewrite the service config to match the current install (use `--repair` in automation).
@@ -748,7 +748,7 @@ pair devices you trust, and review [Security](/gateway/security).

 Docs: [Nodes](/nodes), [Bridge protocol](/gateway/bridge-protocol), [macOS remote mode](/platforms/mac/remote), [Security](/gateway/security).

-### Do nodes run a gateway daemon?
+### Do nodes run a gateway service?

 No. Only **one gateway** should run per host unless you intentionally run isolated profiles (see [Multiple gateways](/gateway/multiple-gateways)). Nodes are peripherals that connect
 to the gateway (iOS/Android nodes, or macOS “node mode” in the menubar app).
@@ -840,11 +840,11 @@ You can also define inline env vars in config (applied only if missing from the

 See [/environment](/environment) for full precedence and sources.

-### “I started the Gateway via a daemon and my env vars disappeared.” What now?
+### “I started the Gateway via a service and my env vars disappeared.” What now?

 Two common fixes:

-1) Put the missing keys in `~/.clawdbot/.env` so they’re picked up even when the daemon doesn’t inherit your shell env.
+1) Put the missing keys in `~/.clawdbot/.env` so they’re picked up even when the service doesn’t inherit your shell env.
 2) Enable shell import (opt‑in convenience):

 ```json5
@@ -867,7 +867,7 @@ This runs your login shell and imports only missing expected keys (never overrid
 does **not** mean your env vars are missing — it just means Clawdbot won’t load
 your login shell automatically.

-If the Gateway runs as a daemon (launchd/systemd), it won’t inherit your shell
+If the Gateway runs as a service (launchd/systemd), it won’t inherit your shell
 environment. Fix by doing one of these:

 1) Put the token in `~/.clawdbot/.env`:
@@ -1345,24 +1345,24 @@ Precedence:
 --port > CLAWDBOT_GATEWAY_PORT > gateway.port > default 18789
 ```

-### Why does `clawdbot daemon status` say `Runtime: running` but `RPC probe: failed`?
+### Why does `clawdbot gateway status` say `Runtime: running` but `RPC probe: failed`?

 Because “running” is the **supervisor’s** view (launchd/systemd/schtasks). The RPC probe is the CLI actually connecting to the gateway WebSocket and calling `status`.

-Use `clawdbot daemon status` and trust these lines:
+Use `clawdbot gateway status` and trust these lines:
 - `Probe target:` (the URL the probe actually used)
 - `Listening:` (what’s actually bound on the port)
 - `Last gateway error:` (common root cause when the process is alive but the port isn’t listening)

-### Why does `clawdbot daemon status` show `Config (cli)` and `Config (daemon)` different?
+### Why does `clawdbot gateway status` show `Config (cli)` and `Config (service)` different?

-You’re editing one config file while the daemon is running another (often a `--profile` / `CLAWDBOT_STATE_DIR` mismatch).
+You’re editing one config file while the service is running another (often a `--profile` / `CLAWDBOT_STATE_DIR` mismatch).

 Fix:
 ```bash
-clawdbot daemon install --force
+clawdbot gateway install --force
 ```
-Run that from the same `--profile` / environment you want the daemon to use.
+Run that from the same `--profile` / environment you want the service to use.

 ### What does “another gateway instance is already listening” mean?

@@ -1431,7 +1431,7 @@ Yes, but you must isolate:
 Quick setup (recommended):
 - Use `clawdbot --profile <name> …` per instance (auto-creates `~/.clawdbot-<name>`).
 - Set a unique `gateway.port` in each profile config (or pass `--port` for manual runs).
- Install a per-profile daemon: `clawdbot --profile <name> daemon install`.
+- Install a per-profile service: `clawdbot --profile <name> gateway install`.

 Profiles also suffix service names (`com.clawdbot.<profile>`, `clawdbot-gateway-<profile>.service`, `Clawdbot Gateway (<profile>)`).
 Full guide: [Multiple gateways](/gateway/multiple-gateways).
@@ -1484,23 +1484,23 @@ Service/supervisor logs (when the gateway runs via launchd/systemd):

 See [Troubleshooting](/gateway/troubleshooting#log-locations) for more.

-### How do I start/stop/restart the Gateway daemon?
+### How do I start/stop/restart the Gateway service?

-Use the daemon helpers:
+Use the gateway helpers:

 ```bash
-clawdbot daemon status
-clawdbot daemon restart
+clawdbot gateway status
+clawdbot gateway restart
 ```

 If you run the gateway manually, `clawdbot gateway --force` can reclaim the port. See [Gateway](/gateway).

-### ELI5: `clawdbot daemon restart` vs `clawdbot gateway`
+### ELI5: `clawdbot gateway restart` vs `clawdbot gateway`

- `clawdbot daemon restart`: restarts the **background service** (launchd/systemd).
+- `clawdbot gateway restart`: restarts the **background service** (launchd/systemd).
 - `clawdbot gateway`: runs the gateway **in the foreground** for this terminal session.

-If you installed the daemon, use the daemon commands. Use `clawdbot gateway` when
+If you installed the service, use the gateway commands. Use `clawdbot gateway` when
 you want a one-off, foreground run.

 ### What’s the fastest way to get more details when something fails?
--- a/docs/start/getting-started.md
+++ b/docs/start/getting-started.md
@@ -15,7 +15,7 @@ Recommended path: use the **CLI onboarding wizard** (`clawdbot onboard`). It set
 - channels (WhatsApp/Telegram/Discord/…)
 - pairing defaults (secure DMs)
 - workspace bootstrap + skills
- optional background daemon
+- optional background service

 If you want the deeper reference pages, jump to: [Wizard](/start/wizard), [Setup](/start/setup), [Pairing](/start/pairing), [Security](/gateway/security).

@@ -71,7 +71,7 @@ npm install -g clawdbot@latest
 pnpm add -g clawdbot@latest
 ```

-## 2) Run the onboarding wizard (and install the daemon)
+## 2) Run the onboarding wizard (and install the service)

 ```bash
 clawdbot onboard --install-daemon
@@ -89,7 +89,7 @@ Wizard doc: [Wizard](/start/wizard)

 ### Auth: where it lives (important)

- **Recommended Anthropic path:** set an API key (wizard can store it for daemon use). `claude setup-token` is also supported if you want to reuse Claude Code credentials.
+- **Recommended Anthropic path:** set an API key (wizard can store it for service use). `claude setup-token` is also supported if you want to reuse Claude Code credentials.

 - OAuth credentials (legacy import): `~/.clawdbot/credentials/oauth.json`
 - Auth profiles (OAuth + API keys): `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`
@@ -98,10 +98,10 @@ Headless/server tip: do OAuth on a normal machine first, then copy `oauth.json`

 ## 3) Start the Gateway

-If you installed the daemon during onboarding, the Gateway should already be running:
+If you installed the service during onboarding, the Gateway should already be running:

 ```bash
-clawdbot daemon status
+clawdbot gateway status
 ```

 Manual run (foreground):
--- a/docs/tools/web.md
+++ b/docs/tools/web.md
@@ -83,7 +83,7 @@ current limits and pricing.
 `~/.clawdbot/clawdbot.json` under `tools.web.search.apiKey`.

 **Environment alternative:** set `BRAVE_API_KEY` in the Gateway process
-environment. For a daemon install, put it in `~/.clawdbot/.env` (or your
+environment. For a gateway install, put it in `~/.clawdbot/.env` (or your
 service environment). See [Env vars](/start/faq#how-does-clawdbot-load-environment-variables).

 ## Using Perplexity (direct or via OpenRouter)
@@ -122,7 +122,7 @@ crypto/prepaid).
 ```

 **Environment alternative:** set `OPENROUTER_API_KEY` or `PERPLEXITY_API_KEY` in the Gateway
-environment. For a daemon install, put it in `~/.clawdbot/.env`.
+environment. For a gateway install, put it in `~/.clawdbot/.env`.

 If no base URL is set, Clawdbot chooses a default based on the API key source: