From b341c9af6c55a779fbf5888b35a41b251f1fb37e Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 8 Jan 2026 08:40:05 +0100 Subject: [PATCH] docs: expand gateway troubleshooting and faq --- docs/gateway/troubleshooting.md | 32 ++++++++++++++++++++++---- docs/start/faq.md | 40 +++++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+), 4 deletions(-) diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md index e3173ed25..087547732 100644 --- a/docs/gateway/troubleshooting.md +++ b/docs/gateway/troubleshooting.md @@ -27,7 +27,7 @@ Doctor/daemon will show runtime state (PID/last exit) and log hints. **Logs:** - Preferred: `clawdbot logs --follow` - File logs (always): `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (or your configured `logging.file`) -- macOS LaunchAgent (if installed): `~/.clawdbot/logs/gateway.log` and `gateway.err.log` +- macOS LaunchAgent (if installed): `$CLAWDBOT_STATE_DIR/logs/gateway.log` and `gateway.err.log` - Linux systemd (if installed): `journalctl --user -u clawdbot-gateway.service -n 200 --no-pager` - Windows: `schtasks /Query /TN "Clawdbot Gateway" /V /FO LIST` @@ -50,6 +50,23 @@ the Gateway likely refused to bind. - `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 `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. + +**If `clawdbot daemon 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`). + +**If `Probe note:` says the probe uses loopback** +- That’s expected for `bind=lan`: the gateway listens on `0.0.0.0` (all interfaces), and loopback should still connect locally. +- For remote clients, use a real LAN IP (not `0.0.0.0`) plus the port, and ensure auth is configured. + ### Address Already in Use (Port 18789) This means something is already listening on the gateway port. @@ -84,15 +101,17 @@ The agent was interrupted mid-response. ### Messages Not Triggering -**Check 1:** Is the sender in `whatsapp.allowFrom`? +**Check 1:** Is the sender allowlisted? ```bash -cat "${CLAWDBOT_CONFIG_PATH:-$HOME/.clawdbot/clawdbot.json}" | jq '.whatsapp.allowFrom' +clawdbot status ``` +Look for `AllowFrom: ...` in the output. **Check 2:** For group chats, is mention required? ```bash # The message must match mentionPatterns or explicit mentions; defaults live in provider groups/guilds. -cat "${CLAWDBOT_CONFIG_PATH:-$HOME/.clawdbot/clawdbot.json}" | jq '.routing.groupChat, .whatsapp.groups, .telegram.groups, .imessage.groups, .discord.guilds' +grep -n "routing\\|groupChat\\|mentionPatterns\\|whatsapp\\.groups\\|telegram\\.groups\\|imessage\\.groups\\|discord\\.guilds" \ + "${CLAWDBOT_CONFIG_PATH:-$HOME/.clawdbot/clawdbot.json}" ``` **Check 3:** Check the logs @@ -265,8 +284,13 @@ clawdbot providers login --verbose ## Health Check ```bash +# Supervisor + probe target + config paths +clawdbot daemon status + # Is the gateway reachable? clawdbot health --json +# If it fails, rerun with connection details: +clawdbot health --verbose # Is something listening on the default port? lsof -nP -iTCP:18789 -sTCP:LISTEN diff --git a/docs/start/faq.md b/docs/start/faq.md index 850161706..8088230f3 100644 --- a/docs/start/faq.md +++ b/docs/start/faq.md @@ -28,6 +28,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 4) **Gateway snapshot** ```bash clawdbot health --json + clawdbot health --verbose # shows the target URL + config path on errors ``` Asks the running gateway for a full snapshot (WS-only). See [Health](/gateway/health). @@ -379,6 +380,25 @@ Precedence: --port > CLAWDBOT_GATEWAY_PORT > gateway.port > default 18789 ``` +### Why does `clawdbot daemon 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: +- `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? + +You’re editing one config file while the daemon is running another (often a `--profile` / `CLAWDBOT_STATE_DIR` mismatch). + +Fix: +```bash +clawdbot daemon install --force +``` +Run that from the same `--profile` / environment you want the daemon to use. + ### What does “another gateway instance is already listening” mean? Clawdbot enforces a runtime lock by binding the WebSocket listener immediately on startup (default `ws://127.0.0.1:18789`). If the bind fails with `EADDRINUSE`, it throws `GatewayLockError` indicating another instance is already listening. @@ -406,6 +426,26 @@ Notes: - `clawdbot gateway` only starts when `gateway.mode` is `local` (or you pass the override flag). - The macOS app watches the config file and switches modes live when these values change. +### The Control UI says “unauthorized” (or keeps reconnecting). What now? + +Your gateway is running with auth enabled (`gateway.auth.*`), but the UI is not sending the matching token/password. + +Facts (from code): +- The Control UI stores the token in browser localStorage key `clawdbot.control.settings.v1`. +- The UI can import `?token=...` (and/or `?password=...`) once, then strips it from the URL. + +Fix: +- Set `gateway.auth.token` (or `CLAWDBOT_GATEWAY_TOKEN`) on the gateway host. +- In the Control UI settings, paste the same token (or refresh with a one-time `?token=...` link). + +### I set `gateway.bind: "tailnet"` but it can’t bind / nothing listens + +`tailnet` bind picks a Tailscale IP from your network interfaces (100.64.0.0/10). If the machine isn’t on Tailscale (or the interface is down), there’s nothing to bind to. + +Fix: +- Start Tailscale on that host (so it has a 100.x address), or +- Switch to `gateway.bind: "loopback"` / `"lan"`. + ### Can I run multiple Gateways on the same host? Yes, but you must isolate: