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

docs: refine troubleshooting and faq guidance

Browse Source
This commit is contained in:
Peter Steinberger
2026-01-08 08:24:16 +01:00
parent 97cb469faf
commit 15dd6b65b6
5 changed files with 60 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/gateway/index.md
View File

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

52
docs/gateway/troubleshooting.md
View File

@@ -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 <PID>
```
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 <PID>
sleep 1
kill -9 <PID> # 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-<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/` |
| Gateway service logs (supervisor) | macOS: `$CLAWDBOT_STATE_DIR/logs/gateway.log` + `gateway.err.log` (default: `~/.clawdbot/logs/...`; 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_STATE_DIR/agents/<agentId>/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
```

2
docs/multi-agent-sandbox-tools.md
View File

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

6
docs/platforms/mac/dev-setup.md
View File

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

42
docs/start/faq.md
View File

@@ -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/<agentId>/agent/auth-profiles.json` | Auth profiles (OAuth + API keys) |
| `~/.clawdbot/agents/<agentId>/agent/auth.json` | Runtime auth cache (managed automatically) |
| `~/.clawdbot/credentials/` | Provider state (e.g. `whatsapp/<accountId>/creds.json`) |
| `~/.clawdbot/agents/` | Per‑agent state (agentDir + sessions) |
| `~/.clawdbot/agents/<agentId>/sessions/` | Conversation history & state (per agent) |
| `~/.clawdbot/agents/<agentId>/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/<agentId>/agent/auth-profiles.json` | Auth profiles (OAuth + API keys) |
| `$CLAWDBOT_STATE_DIR/agents/<agentId>/agent/auth.json` | Runtime auth cache (managed automatically) |
| `$CLAWDBOT_STATE_DIR/credentials/` | Provider state (e.g. `whatsapp/<accountId>/creds.json`) |
| `$CLAWDBOT_STATE_DIR/agents/` | Per‑agent state (agentDir + sessions) |
| `$CLAWDBOT_STATE_DIR/agents/<agentId>/sessions/` | Conversation history & state (per agent) |
| `$CLAWDBOT_STATE_DIR/agents/<agentId>/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-<profile>/logs/...`)
- macOS: `$CLAWDBOT_STATE_DIR/logs/gateway.log` and `gateway.err.log` (default: `~/.clawdbot/logs/...`; 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`