From 23e34dd598ae62770d32f94d8b34e51664bdfddf Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 8 Jan 2026 21:34:28 +0100 Subject: [PATCH] docs: clarify doctor + launchd service guidance --- docs/gateway/doctor.md | 5 +++++ docs/gateway/index.md | 2 ++ docs/gateway/troubleshooting.md | 4 ++++ docs/platforms/linux.md | 6 ------ docs/platforms/mac/bun.md | 2 ++ docs/platforms/windows.md | 6 ------ 6 files changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/gateway/doctor.md b/docs/gateway/doctor.md index 2bfc221ab..059ee480a 100644 --- a/docs/gateway/doctor.md +++ b/docs/gateway/doctor.md @@ -150,6 +150,11 @@ missing or outdated defaults (e.g., systemd network-online dependencies and restart delay). When it finds a mismatch, it recommends an update and can rewrite the service file/task to the current defaults. +Notes: +- `clawdbot doctor` prompts before rewriting supervisor config. +- `clawdbot doctor --yes` accepts the default repair prompts. +- You can always force a full rewrite via `clawdbot daemon install --force`. + ### 12) Gateway runtime + port diagnostics Doctor inspects the daemon runtime (PID, last exit status) and warns when the service is installed but not actually running. It also checks for port collisions diff --git a/docs/gateway/index.md b/docs/gateway/index.md index 9179b1c13..2b232303a 100644 --- a/docs/gateway/index.md +++ b/docs/gateway/index.md @@ -156,6 +156,8 @@ See also: [`docs/presence.md`](/concepts/presence) for how presence is produced/ - 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 doctor` audits the LaunchAgent config and can update it to current defaults. ## Daemon management (CLI) diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md index f7139ce33..f1295cb0c 100644 --- a/docs/gateway/troubleshooting.md +++ b/docs/gateway/troubleshooting.md @@ -55,6 +55,10 @@ the Gateway likely refused to bind. - 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 daemon 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). + **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. diff --git a/docs/platforms/linux.md b/docs/platforms/linux.md index 1c4913983..78cd062c6 100644 --- a/docs/platforms/linux.md +++ b/docs/platforms/linux.md @@ -35,12 +35,6 @@ clawdbot daemon install Or: -``` -clawdbot daemon install -``` - -Or: - ``` clawdbot configure ``` diff --git a/docs/platforms/mac/bun.md b/docs/platforms/mac/bun.md index 629d56a44..3b08a4ad7 100644 --- a/docs/platforms/mac/bun.md +++ b/docs/platforms/mac/bun.md @@ -63,6 +63,8 @@ Manager: Behavior: - “Clawdbot Active” enables/disables the LaunchAgent. - App quit does **not** stop the gateway (launchd keeps it alive). + - CLI install (`clawdbot daemon install`) writes the same LaunchAgent; `clawdbot daemon install --force` rewrites it. + - `clawdbot doctor` audits the LaunchAgent config and can update it to current defaults. Logging: - launchd stdout/err: `/tmp/clawdbot/clawdbot-gateway.log` diff --git a/docs/platforms/windows.md b/docs/platforms/windows.md index ce55d0076..ce06086a4 100644 --- a/docs/platforms/windows.md +++ b/docs/platforms/windows.md @@ -36,12 +36,6 @@ clawdbot daemon install Or: -``` -clawdbot daemon install -``` - -Or: - ``` clawdbot configure ```