let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity

docs: expand gateway troubleshooting and faq

Browse Source
This commit is contained in:
Peter Steinberger
2026-01-08 08:40:05 +01:00
parent 1b2957d050
commit b341c9af6c
2 changed files with 68 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/gateway/troubleshooting.md
View File

@@ -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

40
docs/start/faq.md
View File

@@ -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: