From 840c64084e8ae7ddba64836271018a77a735a019 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 8 Jan 2026 10:42:23 +0100 Subject: [PATCH] docs: refresh daemon troubleshooting guidance --- docs/gateway/index.md | 3 +++ docs/gateway/remote-gateway-readme.md | 2 +- docs/gateway/troubleshooting.md | 12 ++++++++++-- docs/install/updating.md | 1 + docs/platforms/mac/dev-setup.md | 2 +- 5 files changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/gateway/index.md b/docs/gateway/index.md index b060df1c2..f30ce3db6 100644 --- a/docs/gateway/index.md +++ b/docs/gateway/index.md @@ -172,8 +172,11 @@ 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. - `logs` tails the Gateway file log via RPC (no manual `tail`/`grep` needed). - If other gateway-like services are detected, the CLI warns. We recommend **one gateway per machine**; one gateway can host multiple agents. - Cleanup: `clawdbot daemon uninstall` (current service) and `clawdbot doctor` (legacy migrations). diff --git a/docs/gateway/remote-gateway-readme.md b/docs/gateway/remote-gateway-readme.md index f0b3f8ba4..8aee92842 100644 --- a/docs/gateway/remote-gateway-readme.md +++ b/docs/gateway/remote-gateway-readme.md @@ -68,7 +68,7 @@ ssh -N remote-gateway & ### Step 5: Restart Clawdbot.app ```bash -killall Clawdbot +# Quit Clawdbot.app (⌘Q), then reopen: open /path/to/Clawdbot.app ``` diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md index 087547732..f7139ce33 100644 --- a/docs/gateway/troubleshooting.md +++ b/docs/gateway/troubleshooting.md @@ -286,6 +286,8 @@ clawdbot providers login --verbose ```bash # Supervisor + probe target + config paths clawdbot daemon status +# Include system-level scans (legacy/extra services, port listeners) +clawdbot daemon status --deep # Is the gateway reachable? clawdbot health --json @@ -295,7 +297,9 @@ clawdbot health --verbose # Is something listening on the default port? lsof -nP -iTCP:18789 -sTCP:LISTEN -# Recent activity +# Recent activity (RPC log tail) +clawdbot logs --follow +# Fallback if RPC is down tail -20 /tmp/clawdbot/clawdbot-*.log ``` @@ -304,9 +308,13 @@ tail -20 /tmp/clawdbot/clawdbot-*.log Nuclear option: ```bash +clawdbot daemon stop +# If you installed a service and want a clean install: +# clawdbot daemon uninstall + trash "${CLAWDBOT_STATE_DIR:-$HOME/.clawdbot}" clawdbot providers login # re-pair WhatsApp -clawdbot gateway # start the Gateway again +clawdbot daemon restart # or: clawdbot gateway ``` ⚠️ This loses all sessions and requires re-pairing WhatsApp. diff --git a/docs/install/updating.md b/docs/install/updating.md index 8320021f0..913227a11 100644 --- a/docs/install/updating.md +++ b/docs/install/updating.md @@ -87,6 +87,7 @@ Details: [Doctor](/gateway/doctor) CLI (works regardless of OS): ```bash +clawdbot daemon status clawdbot daemon stop clawdbot daemon restart clawdbot gateway --port 18789 diff --git a/docs/platforms/mac/dev-setup.md b/docs/platforms/mac/dev-setup.md index c3caa6432..68b318974 100644 --- a/docs/platforms/mac/dev-setup.md +++ b/docs/platforms/mac/dev-setup.md @@ -97,4 +97,4 @@ clawdbot daemon stop # If you’re not using a LaunchAgent (dev mode / manual runs), find the listener: lsof -nP -iTCP:18789 -sTCP:LISTEN ``` -Kill any existing `node` or `clawdbot` processes listening on that port and restart the app. +If a manual run is holding the port, stop that process (Ctrl+C). As a last resort, kill the PID you found above.