diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md index e812034e9..f5956f97f 100644 --- 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-/logs/...`)
Linux: `journalctl --user -u clawdbot-gateway.service -n 200 --no-pager`
Windows: `schtasks /Query /TN "Clawdbot Gateway" /V /FO LIST` | | Session files | `~/.clawdbot/agents//sessions/` | | Media cache | `~/.clawdbot/media/` | | Credentials | `~/.clawdbot/credentials/` | diff --git a/docs/start/faq.md b/docs/start/faq.md index e5c14e6d5..2171a0c92 100644 --- 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 ` 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-/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:` 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: