diff --git a/docs/gateway/index.md b/docs/gateway/index.md index 5a969bc70..95dd92573 100644 --- a/docs/gateway/index.md +++ b/docs/gateway/index.md @@ -172,7 +172,8 @@ clawdbot logs --follow Notes: - `daemon status` probes the Gateway RPC by default (same URL/token defaults as `gateway status`). - `daemon status --deep` adds system-level scans (LaunchDaemons/system units). -- `daemon status` now reports runtime state (PID/exit status) and port collisions when the gateway isn’t reachable. +- `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. - `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/troubleshooting.md b/docs/gateway/troubleshooting.md index f5956f97f..e3173ed25 100644 --- a/docs/gateway/troubleshooting.md +++ b/docs/gateway/troubleshooting.md @@ -5,7 +5,7 @@ read_when: --- # Troubleshooting 🔧 -When your CLAWDBOT misbehaves, here's how to fix it. +When 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. @@ -36,6 +36,11 @@ Doctor/daemon will show runtime state (PID/last exit) and log hints. If the service reports **running** but nothing is listening on the gateway port, the Gateway likely refused to bind. +**What "running" means here** +- `Runtime: running` means your supervisor (launchd/systemd/schtasks) thinks the process is alive. +- `RPC probe` means the CLI could actually connect to the gateway WebSocket and call `status`. +- Always trust `Probe target:` + `Config (daemon):` as the “what did we actually try?” lines. + **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`). @@ -81,13 +86,13 @@ The agent was interrupted mid-response. **Check 1:** Is the sender in `whatsapp.allowFrom`? ```bash -cat ~/.clawdbot/clawdbot.json | jq '.whatsapp.allowFrom' +cat "${CLAWDBOT_CONFIG_PATH:-$HOME/.clawdbot/clawdbot.json}" | jq '.whatsapp.allowFrom' ``` **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/clawdbot.json | jq '.routing.groupChat, .whatsapp.groups, .telegram.groups, .imessage.groups, .discord.guilds' +cat "${CLAWDBOT_CONFIG_PATH:-$HOME/.clawdbot/clawdbot.json}" | jq '.routing.groupChat, .whatsapp.groups, .telegram.groups, .imessage.groups, .discord.guilds' ``` **Check 3:** Check the logs @@ -159,7 +164,7 @@ If you’re logged out / unlinked: ```bash clawdbot providers logout -trash ~/.clawdbot/credentials # if logout can't cleanly remove everything +trash "${CLAWDBOT_STATE_DIR:-$HOME/.clawdbot}/credentials" # if logout can't cleanly remove everything clawdbot providers login --verbose # re-scan QR ``` @@ -211,22 +216,27 @@ If resetting doesn't work, change the `BUNDLE_ID` in [`scripts/package-mac-app.s The app connects to a local gateway on port `18789`. If it stays stuck: -**Fix 1: Kill Zombie Processes** -Another process might be holding the port. -```bash -lsof -nP -i :18789 -# Kill any matching PIDs -kill -9 -``` - -If the gateway is supervised by launchd, killing the PID will just respawn it. -Stop the supervisor instead: +**Fix 1: Stop the supervisor (preferred)** +If the gateway is supervised by launchd, killing the PID will just respawn it. Stop the supervisor first: ```bash +clawdbot daemon status clawdbot daemon stop # Or: launchctl bootout gui/$UID/com.clawdbot.gateway ``` -**Fix 2: Check embedded gateway** +**Fix 2: Port is busy (find the listener)** +```bash +lsof -nP -iTCP:18789 -sTCP:LISTEN +``` + +If it’s an unsupervised process, try a graceful stop first, then escalate: +```bash +kill -TERM +sleep 1 +kill -9 # last resort +``` + +**Fix 3: Check embedded gateway** Ensure the gateway relay was properly bundled. Run [`./scripts/package-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/package-mac-app.sh) and ensure `bun` is installed. ## Debug Mode @@ -235,7 +245,7 @@ Get verbose logging: ```bash # Turn on trace logging in config: -# ~/.clawdbot/clawdbot.json -> { logging: { level: "trace" } } +# ${CLAWDBOT_CONFIG_PATH:-$HOME/.clawdbot/clawdbot.json} -> { logging: { level: "trace" } } # # Then run verbose commands to mirror debug output to stdout: clawdbot gateway --verbose @@ -247,10 +257,10 @@ clawdbot providers login --verbose | Log | Location | |-----|----------| | 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/` | +| Gateway service logs (supervisor) | macOS: `$CLAWDBOT_STATE_DIR/logs/gateway.log` + `gateway.err.log` (default: `~/.clawdbot/logs/...`; 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_STATE_DIR/agents//sessions/` | +| Media cache | `$CLAWDBOT_STATE_DIR/media/` | +| Credentials | `$CLAWDBOT_STATE_DIR/credentials/` | ## Health Check @@ -270,7 +280,7 @@ tail -20 /tmp/clawdbot/clawdbot-*.log Nuclear option: ```bash -trash ~/.clawdbot +trash "${CLAWDBOT_STATE_DIR:-$HOME/.clawdbot}" clawdbot providers login # re-pair WhatsApp clawdbot gateway # start the Gateway again ``` diff --git a/docs/multi-agent-sandbox-tools.md b/docs/multi-agent-sandbox-tools.md index 4c06777a1..b9ee2bcdc 100644 --- a/docs/multi-agent-sandbox-tools.md +++ b/docs/multi-agent-sandbox-tools.md @@ -262,7 +262,7 @@ After configuring multi-agent sandbox and tools: 4. **Monitor logs:** ```bash - tail -f ~/.clawdbot/logs/gateway.log | grep -E "routing|sandbox|tools" + tail -f "${CLAWDBOT_STATE_DIR:-$HOME/.clawdbot}/logs/gateway.log" | grep -E "routing|sandbox|tools" ``` --- diff --git a/docs/platforms/mac/dev-setup.md b/docs/platforms/mac/dev-setup.md index a208e2195..c3caa6432 100644 --- a/docs/platforms/mac/dev-setup.md +++ b/docs/platforms/mac/dev-setup.md @@ -91,6 +91,10 @@ If the app crashes when you try to allow **Speech Recognition** or **Microphone* If the gateway status stays on "Starting...", check if a zombie process is holding the port: ```bash -lsof -nP -i :18789 +clawdbot daemon status +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. diff --git a/docs/start/faq.md b/docs/start/faq.md index 2171a0c92..850161706 100644 --- a/docs/start/faq.md +++ b/docs/start/faq.md @@ -13,30 +13,30 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, ``` Repairs/migrates config/state + runs health checks. See [Doctor](/gateway/doctor). -2) **Local probes** +2) **Daemon + port state** + ```bash + clawdbot daemon status + ``` + Shows supervisor runtime vs RPC reachability, the probe target URL, and which config the daemon likely used. + +3) **Local probes** ```bash clawdbot status --deep ``` Checks provider connectivity and local health. See [Health](/gateway/health). -3) **Gateway snapshot** +4) **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** +5) **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? ### What is Clawdbot, in one paragraph? @@ -92,18 +92,18 @@ Bun is supported for faster TypeScript execution, but **WhatsApp requires Node** ### Where does Clawdbot store its data? -Everything lives under `~/.clawdbot/` (or `$CLAWDBOT_STATE_DIR` if you override the state dir): +Everything lives under `$CLAWDBOT_STATE_DIR` (default: `~/.clawdbot`): | Path | Purpose | |------|---------| -| `~/.clawdbot/clawdbot.json` | Main config (JSON5) | -| `~/.clawdbot/credentials/oauth.json` | Legacy OAuth import (copied into auth profiles on first use) | -| `~/.clawdbot/agents//agent/auth-profiles.json` | Auth profiles (OAuth + API keys) | -| `~/.clawdbot/agents//agent/auth.json` | Runtime auth cache (managed automatically) | -| `~/.clawdbot/credentials/` | Provider state (e.g. `whatsapp//creds.json`) | -| `~/.clawdbot/agents/` | Per‑agent state (agentDir + sessions) | -| `~/.clawdbot/agents//sessions/` | Conversation history & state (per agent) | -| `~/.clawdbot/agents//sessions/sessions.json` | Session metadata (per agent) | +| `$CLAWDBOT_STATE_DIR/clawdbot.json` | Main config (JSON5) | +| `$CLAWDBOT_STATE_DIR/credentials/oauth.json` | Legacy OAuth import (copied into auth profiles on first use) | +| `$CLAWDBOT_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles (OAuth + API keys) | +| `$CLAWDBOT_STATE_DIR/agents//agent/auth.json` | Runtime auth cache (managed automatically) | +| `$CLAWDBOT_STATE_DIR/credentials/` | Provider state (e.g. `whatsapp//creds.json`) | +| `$CLAWDBOT_STATE_DIR/agents/` | Per‑agent state (agentDir + sessions) | +| `$CLAWDBOT_STATE_DIR/agents//sessions/` | Conversation history & state (per agent) | +| `$CLAWDBOT_STATE_DIR/agents//sessions/sessions.json` | Session metadata (per agent) | Legacy single‑agent path: `~/.clawdbot/agent/*` (migrated by `clawdbot doctor`). @@ -117,10 +117,10 @@ Session state is owned by the **gateway host**. If you’re in remote mode, the ### What format is the config? Where is it? -Clawdbot reads an optional **JSON5** config from: +Clawdbot reads an optional **JSON5** config from `$CLAWDBOT_CONFIG_PATH` (default: `~/.clawdbot/clawdbot.json`): ``` -~/.clawdbot/clawdbot.json +$CLAWDBOT_CONFIG_PATH ``` If the file is missing, it uses safe‑ish defaults (including a default workspace of `~/clawd`). @@ -436,7 +436,7 @@ 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/...`) +- macOS: `$CLAWDBOT_STATE_DIR/logs/gateway.log` and `gateway.err.log` (default: `~/.clawdbot/logs/...`; profiles use `~/.clawdbot-/logs/...`) - Linux: `journalctl --user -u clawdbot-gateway.service -n 200 --no-pager` - Windows: `schtasks /Query /TN "Clawdbot Gateway" /V /FO LIST`