feat: add gateway service commands

docs/clawd.md

@@ -69,6 +69,11 @@ clawdbot login
 clawdbot gateway --port 18789
 ```
 
+Optional (supervised, always-on):
+```bash
+clawdbot gateway install
+```
+
 3) Put a minimal config in `~/.clawdbot/clawdbot.json`:
 
 ```json5

docs/faq.md

@@ -504,6 +504,11 @@ The gateway runs under a supervisor that auto-restarts it. You need to stop the
 - To inspect launchd state: `launchctl print gui/$UID | grep clawdbot`
 
 **macOS (CLI launchd service, if installed)**
+If you haven’t installed a supervisor yet, install one first:
+```bash
+clawdbot gateway install
+# Or: clawdbot service install
+```
 
 ```bash
 clawdbot gateway stop

docs/gateway.md

@@ -219,8 +219,13 @@ sudo systemctl enable --now clawdbot-gateway.service
 - `clawdbot gateway send --to <num> --message "hi" [--media-url ...]` — send via Gateway (idempotent).
 - `clawdbot gateway agent --message "hi" [--to ...]` — run an agent turn (waits for final by default).
 - `clawdbot gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
+- `clawdbot gateway install|uninstall` — install/remove the supervised gateway service (launchd/systemd/schtasks).
+- `clawdbot gateway service-status` — report supervised gateway service status.
 - `clawdbot gateway stop|restart` — stop/restart the supervised gateway service (launchd/systemd/schtasks).
 - Gateway helper subcommands assume a running gateway on `--url`; they no longer auto-spawn one.
+- Service aliases:
+  - `clawdbot service ...` — service controls (install/uninstall/status/stop/restart)
+  - `clawdbot daemon ...` — alias for `clawdbot service ...`
 
 ## Migration guidance
 - Retire uses of `clawdbot gateway` and the legacy TCP control port.

docs/setup.md

@@ -105,6 +105,20 @@ pnpm clawdbot health
   - Sessions: `~/.clawdbot/agents/<agentId>/sessions/`
   - Logs: `/tmp/clawdbot/`
 
+## Gateway service (optional)
+
+If you want the Gateway supervised outside the macOS app (CLI-only, headless, or remote setups). The macOS app already manages the Gateway via launchd.
+
+```bash
+clawdbot gateway install
+clawdbot gateway service-status
+clawdbot gateway uninstall
+```
+
+Aliases:
+- `clawdbot service ...`
+- `clawdbot daemon ...`
+
 ## Updating (without wrecking your setup)
 
 - Keep `~/clawd` and `~/.clawdbot/` as “your stuff”; don’t put personal prompts/config into the `clawdbot` repo.

docs/troubleshooting.md

@@ -167,6 +167,12 @@ clawdbot gateway stop
 # Or: launchctl bootout gui/$UID/com.clawdbot.gateway
 ```
 
+If no supervisor is installed yet:
+```bash
+clawdbot gateway install
+clawdbot gateway service-status
+```
+
 **Fix 2: Check embedded gateway**
 Ensure the gateway relay was properly bundled. Run [`./scripts/package-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/package-mac-app.sh) and ensure `bun` is installed.
 

docs/wizard.md

@@ -74,13 +74,14 @@ It does **not** install or change anything on the remote host.
    - DM security: default is pairing (unknown DMs get a pairing code). Approve via `clawdbot pairing approve --provider <provider> <code>`.
 
 6) **Daemon install**
-   - macOS: LaunchAgent
-     - Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
-   - Linux: systemd user unit
-     - Wizard attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
-     - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
-   - Windows: Scheduled Task
-     - Runs on user logon; headless/system services are not configured by default.
+  - macOS: LaunchAgent
+    - Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
+  - Linux: systemd user unit
+    - Wizard attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
+    - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
+  - Windows: Scheduled Task
+    - Runs on user logon; headless/system services are not configured by default.
+  - Manual alternative: `clawdbot gateway install` (or `clawdbot service install`).
 
 7) **Health check**
    - Starts the Gateway (if needed) and runs `clawdbot health`.