docs: improve faq triage

2026-01-08 07:58:14 +01:00
parent b367ed75bf
commit 16682531d1
2 changed files with 122 additions and 3 deletions
--- a/docs/gateway/troubleshooting.md
+++ b/docs/gateway/troubleshooting.md
@@ -7,6 +7,8 @@ read_when:

 When your CLAWDBOT misbehaves, here's how to fix it.

+Start with the FAQ’s [First 60 seconds](/start/faq#first-60-seconds-if-somethings-broken) if you just want a quick triage recipe. This page goes deeper on runtime failures and diagnostics.
+
 ## Common Issues

 ### Service Installed but Nothing is Running
@@ -36,6 +38,8 @@ the Gateway likely refused to bind.

 **Check:**
 - `gateway.mode` must be `local` for `clawdbot gateway` and the daemon.
+- If you set `gateway.mode=remote`, the **CLI defaults** to a remote URL. The daemon can still be running locally, but your CLI may be probing the wrong place. Use `clawdbot daemon status` to see the daemon’s resolved port + probe target (or pass `--url`).
+- `clawdbot daemon status` and `clawdbot doctor` surface the **last gateway error** from logs when the service looks running but the port is closed.
 - Non-loopback binds (`lan`/`tailnet`/`auto`) require auth:
  `gateway.auth.token` (or `CLAWDBOT_GATEWAY_TOKEN`).
 - `gateway.remote.token` is for remote CLI calls only; it does **not** enable local auth.
@@ -242,7 +246,8 @@ clawdbot providers login --verbose

 | Log | Location |
 |-----|----------|
-| Main logs (default) | `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` |
+| Gateway file logs (structured) | `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (or `logging.file`) |
+| Gateway service logs (supervisor) | macOS: `~/.clawdbot/logs/gateway.log` + `gateway.err.log` (profiles use `~/.clawdbot-<profile>/logs/...`)<br>Linux: `journalctl --user -u clawdbot-gateway.service -n 200 --no-pager`<br>Windows: `schtasks /Query /TN "Clawdbot Gateway" /V /FO LIST` |
 | Session files | `~/.clawdbot/agents/<agentId>/sessions/` |
 | Media cache | `~/.clawdbot/media/` |
 | Credentials | `~/.clawdbot/credentials/` |
--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -3,7 +3,39 @@ summary: "Frequently asked questions about Clawdbot setup, configuration, and us
 ---
 # FAQ

-Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, multi-agent, OAuth/API keys, model failover). For the full config reference, see [Configuration](/gateway/configuration).
+Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, multi-agent, OAuth/API keys, model failover). For runtime diagnostics, see [Troubleshooting](/gateway/troubleshooting). For the full config reference, see [Configuration](/gateway/configuration).
+
+## First 60 seconds if something's broken
+
+1) **Run the doctor**
+   ```bash
+   clawdbot doctor
+   ```
+   Repairs/migrates config/state + runs health checks. See [Doctor](/gateway/doctor).
+
+2) **Local probes**
+   ```bash
+   clawdbot status --deep
+   ```
+   Checks provider connectivity and local health. See [Health](/gateway/health).
+
+3) **Gateway snapshot**
+   ```bash
+   clawdbot health --json
+   ```
+   Asks the running gateway for a full snapshot (WS-only). See [Health](/gateway/health).
+
+4) **Tail the latest log**
+   ```bash
+   tail -f "$(ls -t /tmp/clawdbot/clawdbot-*.log | head -1)"
+   ```
+   File logs are separate from service logs; see [Logging](/gateway/logging) and [Troubleshooting](/gateway/troubleshooting).
+
+5) **Daemon + port state**
+   ```bash
+   clawdbot daemon status
+   ```
+   Shows service runtime, port listeners, and last gateway error if it refused to bind.

 ## What is Clawdbot?

@@ -77,6 +109,10 @@ Legacy single‑agent path: `~/.clawdbot/agent/*` (migrated by `clawdbot doctor`

 Your **workspace** (AGENTS.md, memory files, skills, etc.) is separate and configured via `agent.workspace` (default: `~/clawd`).

+### I’m in remote mode — where is the session store?
+
+Session state is owned by the **gateway host**. If you’re in remote mode, the session store you care about is on the remote machine, not your local laptop. See [Session management](/concepts/session).
+
 ## Config basics

 ### What format is the config? Where is it?
@@ -89,6 +125,26 @@ Clawdbot reads an optional **JSON5** config from:

 If the file is missing, it uses safe‑ish defaults (including a default workspace of `~/clawd`).

+### I set `gateway.bind: "lan"` (or `"tailnet"`) and now nothing listens / the UI says unauthorized
+
+Non-loopback binds **require auth**. Configure `gateway.auth.mode` + `gateway.auth.token` (or use `CLAWDBOT_GATEWAY_TOKEN`).
+
+```json5
+{
+  gateway: {
+    bind: "lan",
+    auth: {
+      mode: "token",
+      token: "replace-me"
+    }
+  }
+}
+```
+
+Notes:
+- `gateway.remote.token` is for **remote CLI calls** only; it does not enable local gateway auth.
+- The Control UI authenticates via `connect.params.auth.token` (stored in app/UI settings). Avoid putting tokens in URLs.
+
 ### Do I have to restart after changing config?

 The Gateway watches the config and supports hot‑reload:
@@ -145,6 +201,16 @@ Two common fixes:
 This runs your login shell and imports only missing expected keys (never overrides). Env var equivalents:
 `CLAWDBOT_LOAD_SHELL_ENV=1`, `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000`.

+## Sessions & multiple chats
+
+### How do I start a fresh conversation?
+
+Send `/new` or `/reset` as a standalone message. See [Session management](/concepts/session).
+
+### Do groups/threads share context with DMs?
+
+Direct chats collapse to the main session by default. Groups/channels have their own session keys, and Telegram topics / Discord threads are separate sessions. See [Groups](/concepts/groups) and [Group messages](/concepts/group-messages).
+
 ## Models: defaults, selection, aliases, switching

 ### What is the “default model”?
@@ -355,7 +421,7 @@ There are convenience CLI flags like `--dev` and `--profile <name>` that shift s

 ### Where are logs?

-Default log file:
+File logs (structured):

 ```
 /tmp/clawdbot/clawdbot-YYYY-MM-DD.log
@@ -369,10 +435,42 @@ Fastest log tail:
 clawdbot logs --follow
 ```

+Service/supervisor logs (when the gateway runs via launchd/systemd):
+- macOS: `~/.clawdbot/logs/gateway.log` and `gateway.err.log` (profiles use `~/.clawdbot-<profile>/logs/...`)
+- Linux: `journalctl --user -u clawdbot-gateway.service -n 200 --no-pager`
+- Windows: `schtasks /Query /TN "Clawdbot Gateway" /V /FO LIST`
+
+See [Troubleshooting](/gateway/troubleshooting#log-locations) for more.
+
+### How do I start/stop/restart the Gateway daemon?
+
+Use the daemon helpers:
+
+```bash
+clawdbot daemon status
+clawdbot daemon restart
+```
+
+If you run the gateway manually, `clawdbot gateway --force` can reclaim the port. See [Gateway](/gateway).
+
 ### What’s the fastest way to get more details when something fails?

 Start the Gateway with `--verbose` to get more console detail. Then inspect the log file for provider auth, model routing, and RPC errors.

+## Media & attachments
+
+### My skill generated an image/PDF, but nothing was sent
+
+Outbound attachments from the agent must include a `MEDIA:<path-or-url>` line (on its own line). See [Clawd setup](/start/clawd) and [Agent send](/tools/agent-send).
+
+CLI sending:
+
+```bash
+clawdbot send --to +15555550123 --message "Here you go" --media /path/to/file.png
+```
+
+Note: images are resized/recompressed (max side 2048px) to hit size limits. See [Images](/nodes/images).
+
 ## Security and access control

 ### Is it safe to expose Clawdbot to inbound DMs?
@@ -431,6 +529,22 @@ You can add options like `debounce:2s cap:25 drop:summarize` for followup modes.
 - **Gateway logs** in `/tmp/clawdbot/…` for the exact provider error.
 - **`/model status`** to see current configured models + shorthands.

+### I’m running on my personal WhatsApp number — why is self-chat weird?
+
+Enable self-chat mode and allowlist your own number:
+
+```json5
+{
+  whatsapp: {
+    selfChatMode: true,
+    dmPolicy: "allowlist",
+    allowFrom: ["+15555550123"]
+  }
+}
+```
+
+See [WhatsApp setup](/providers/whatsapp).
+
 ### WhatsApp logged me out. How do I re‑auth?

 Run the login command again and scan the QR code: