diff --git a/docs/automation/cron-jobs.md b/docs/automation/cron-jobs.md index 54d6a96470..25661ae7f4 100644 --- a/docs/automation/cron-jobs.md +++ b/docs/automation/cron-jobs.md @@ -17,6 +17,8 @@ the right time, and can optionally deliver output back to a chat. If you want _“run this every morning”_ or _“poke the agent in 20 minutes”_, cron is the mechanism. +Troubleshooting: [/automation/troubleshooting](/automation/troubleshooting) + ## TL;DR - Cron runs **inside the Gateway** (not inside the model). diff --git a/docs/automation/troubleshooting.md b/docs/automation/troubleshooting.md new file mode 100644 index 0000000000..51f2aa209c --- /dev/null +++ b/docs/automation/troubleshooting.md @@ -0,0 +1,122 @@ +--- +summary: "Troubleshoot cron and heartbeat scheduling and delivery" +read_when: + - Cron did not run + - Cron ran but no message was delivered + - Heartbeat seems silent or skipped +title: "Automation Troubleshooting" +--- + +# Automation troubleshooting + +Use this page for scheduler and delivery issues (`cron` + `heartbeat`). + +## Command ladder + +```bash +openclaw status +openclaw gateway status +openclaw logs --follow +openclaw doctor +openclaw channels status --probe +``` + +Then run automation checks: + +```bash +openclaw cron status +openclaw cron list +openclaw system heartbeat last +``` + +## Cron not firing + +```bash +openclaw cron status +openclaw cron list +openclaw cron runs --id --limit 20 +openclaw logs --follow +``` + +Good output looks like: + +- `cron status` reports enabled and a future `nextWakeAtMs`. +- Job is enabled and has a valid schedule/timezone. +- `cron runs` shows `ok` or explicit skip reason. + +Common signatures: + +- `cron: scheduler disabled; jobs will not run automatically` → cron disabled in config/env. +- `cron: timer tick failed` → scheduler tick crashed; inspect surrounding stack/log context. +- `reason: not-due` in run output → manual run called without `--force` and job not due yet. + +## Cron fired but no delivery + +```bash +openclaw cron runs --id --limit 20 +openclaw cron list +openclaw channels status --probe +openclaw logs --follow +``` + +Good output looks like: + +- Run status is `ok`. +- Delivery mode/target are set for isolated jobs. +- Channel probe reports target channel connected. + +Common signatures: + +- Run succeeded but delivery mode is `none` → no external message is expected. +- Delivery target missing/invalid (`channel`/`to`) → run may succeed internally but skip outbound. +- Channel auth errors (`unauthorized`, `missing_scope`, `Forbidden`) → delivery blocked by channel credentials/permissions. + +## Heartbeat suppressed or skipped + +```bash +openclaw system heartbeat last +openclaw logs --follow +openclaw config get agents.defaults.heartbeat +openclaw channels status --probe +``` + +Good output looks like: + +- Heartbeat enabled with non-zero interval. +- Last heartbeat result is `ran` (or skip reason is understood). + +Common signatures: + +- `heartbeat skipped` with `reason=quiet-hours` → outside `activeHours`. +- `requests-in-flight` → main lane busy; heartbeat deferred. +- `empty-heartbeat-file` → `HEARTBEAT.md` exists but has no actionable content. +- `alerts-disabled` → visibility settings suppress outbound heartbeat messages. + +## Timezone and activeHours gotchas + +```bash +openclaw config get agents.defaults.heartbeat.activeHours +openclaw config get agents.defaults.heartbeat.activeHours.timezone +openclaw config get agents.defaults.userTimezone || echo "agents.defaults.userTimezone not set" +openclaw cron list +openclaw logs --follow +``` + +Quick rules: + +- `Config path not found: agents.defaults.userTimezone` means the key is unset; heartbeat falls back to host timezone (or `activeHours.timezone` if set). +- Cron without `--tz` uses gateway host timezone. +- Heartbeat `activeHours` uses configured timezone resolution (`user`, `local`, or explicit IANA tz). +- ISO timestamps without timezone are treated as UTC for cron `at` schedules. + +Common signatures: + +- Jobs run at the wrong wall-clock time after host timezone changes. +- Heartbeat always skipped during your daytime because `activeHours.timezone` is wrong. + +Related: + +- [/automation/cron-jobs](/automation/cron-jobs) +- [/gateway/heartbeat](/gateway/heartbeat) +- [/automation/cron-vs-heartbeat](/automation/cron-vs-heartbeat) +- [/concepts/timezone](/concepts/timezone) diff --git a/docs/channels/matrix.md b/docs/channels/matrix.md index 56b363fdd9..86e25ee9bc 100644 --- a/docs/channels/matrix.md +++ b/docs/channels/matrix.md @@ -202,6 +202,32 @@ Once verified, the bot can decrypt messages in encrypted rooms. | Location | ✅ Supported (geo URI; altitude ignored) | | Native commands | ✅ Supported | +## Troubleshooting + +Run this ladder first: + +```bash +openclaw status +openclaw gateway status +openclaw logs --follow +openclaw doctor +openclaw channels status --probe +``` + +Then confirm DM pairing state if needed: + +```bash +openclaw pairing list matrix +``` + +Common failures: + +- Logged in but room messages ignored: room blocked by `groupPolicy` or room allowlist. +- DMs ignored: sender pending approval when `channels.matrix.dm.policy="pairing"`. +- Encrypted rooms fail: crypto support or encryption settings mismatch. + +For triage flow: [/channels/troubleshooting](/channels/troubleshooting). + ## Configuration reference (Matrix) Full configuration: [Configuration](/gateway/configuration) diff --git a/docs/channels/signal.md b/docs/channels/signal.md index fc211f1538..72abe2f28d 100644 --- a/docs/channels/signal.md +++ b/docs/channels/signal.md @@ -168,6 +168,32 @@ Config: - Groups: `signal:group:`. - Usernames: `username:` (if supported by your Signal account). +## Troubleshooting + +Run this ladder first: + +```bash +openclaw status +openclaw gateway status +openclaw logs --follow +openclaw doctor +openclaw channels status --probe +``` + +Then confirm DM pairing state if needed: + +```bash +openclaw pairing list signal +``` + +Common failures: + +- Daemon reachable but no replies: verify account/daemon settings (`httpUrl`, `account`) and receive mode. +- DMs ignored: sender is pending pairing approval. +- Group messages ignored: group sender/mention gating blocks delivery. + +For triage flow: [/channels/troubleshooting](/channels/troubleshooting). + ## Configuration reference (Signal) Full configuration: [Configuration](/gateway/configuration) diff --git a/docs/channels/slack.md b/docs/channels/slack.md index 1343ebf77d..d692431dad 100644 --- a/docs/channels/slack.md +++ b/docs/channels/slack.md @@ -537,6 +537,32 @@ Slack tool actions can be gated with `channels.slack.actions.*`: scopes you expect (`chat:write`, `reactions:write`, `pins:write`, `files:write`) or those operations will fail. +## Troubleshooting + +Run this ladder first: + +```bash +openclaw status +openclaw gateway status +openclaw logs --follow +openclaw doctor +openclaw channels status --probe +``` + +Then confirm DM pairing state if needed: + +```bash +openclaw pairing list slack +``` + +Common failures: + +- Connected but no channel replies: channel blocked by `groupPolicy` or not in `channels.slack.channels` allowlist. +- DMs ignored: sender not approved when `channels.slack.dm.policy="pairing"`. +- API errors (`missing_scope`, `not_in_channel`, auth failures): bot/app tokens or Slack scopes are incomplete. + +For triage flow: [/channels/troubleshooting](/channels/troubleshooting). + ## Notes - Mention gating is controlled via `channels.slack.channels` (set `requireMention` to `true`); `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`) also count as mentions. diff --git a/docs/channels/troubleshooting.md b/docs/channels/troubleshooting.md index 8a6cdca906..0ba3728f5f 100644 --- a/docs/channels/troubleshooting.md +++ b/docs/channels/troubleshooting.md @@ -1,30 +1,116 @@ --- -summary: "Channel-specific troubleshooting shortcuts (Discord/Telegram/WhatsApp/iMessage)" +summary: "Fast channel level troubleshooting with per channel failure signatures and fixes" read_when: - - A channel connects but messages don’t flow - - Investigating channel misconfiguration (intents, permissions, privacy mode) + - Channel transport says connected but replies fail + - You need channel specific checks before deep provider docs title: "Channel Troubleshooting" --- # Channel troubleshooting -Start with: +Use this page when a channel connects but behavior is wrong. + +## Command ladder + +Run these in order first: ```bash +openclaw status +openclaw gateway status +openclaw logs --follow openclaw doctor openclaw channels status --probe ``` -`channels status --probe` prints warnings when it can detect common channel misconfigurations, and includes small live checks (credentials, some permissions/membership). +Healthy baseline: -## Channels +- `Runtime: running` +- `RPC probe: ok` +- Channel probe shows connected/ready -- Discord: [/channels/discord#troubleshooting](/channels/discord#troubleshooting) -- Telegram: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting) -- WhatsApp: [/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick) -- iMessage (legacy): [/channels/imessage#troubleshooting-macos-privacy-and-security-tcc](/channels/imessage#troubleshooting-macos-privacy-and-security-tcc) +## WhatsApp -## Telegram quick fixes +### WhatsApp failure signatures -- Logs show `HttpError: Network request for 'sendMessage' failed` or `sendChatAction` → check IPv6 DNS. If `api.telegram.org` resolves to IPv6 first and the host lacks IPv6 egress, force IPv4 or enable IPv6. See [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting). -- Logs show `setMyCommands failed` → check outbound HTTPS and DNS reachability to `api.telegram.org` (common on locked-down VPS or proxies). +| Symptom | Fastest check | Fix | +| ------------------------------- | --------------------------------------------------- | ------------------------------------------------------- | +| Connected but no DM replies | `openclaw pairing list whatsapp` | Approve sender or switch DM policy/allowlist. | +| Group messages ignored | Check `requireMention` + mention patterns in config | Mention the bot or relax mention policy for that group. | +| Random disconnect/relogin loops | `openclaw channels status --probe` + logs | Re-login and verify credentials directory is healthy. | + +Full troubleshooting: [/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick) + +## Telegram + +### Telegram failure signatures + +| Symptom | Fastest check | Fix | +| --------------------------------- | ----------------------------------------------- | --------------------------------------------------------- | +| `/start` but no usable reply flow | `openclaw pairing list telegram` | Approve pairing or change DM policy. | +| Bot online but group stays silent | Verify mention requirement and bot privacy mode | Disable privacy mode for group visibility or mention bot. | +| Send failures with network errors | Inspect logs for Telegram API call failures | Fix DNS/IPv6/proxy routing to `api.telegram.org`. | + +Full troubleshooting: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting) + +## Discord + +### Discord failure signatures + +| Symptom | Fastest check | Fix | +| ------------------------------- | ----------------------------------- | --------------------------------------------------------- | +| Bot online but no guild replies | `openclaw channels status --probe` | Allow guild/channel and verify message content intent. | +| Group messages ignored | Check logs for mention gating drops | Mention bot or set guild/channel `requireMention: false`. | +| DM replies missing | `openclaw pairing list discord` | Approve DM pairing or adjust DM policy. | + +Full troubleshooting: [/channels/discord#troubleshooting](/channels/discord#troubleshooting) + +## Slack + +### Slack failure signatures + +| Symptom | Fastest check | Fix | +| -------------------------------------- | ----------------------------------------- | ------------------------------------------------- | +| Socket mode connected but no responses | `openclaw channels status --probe` | Verify app token + bot token and required scopes. | +| DMs blocked | `openclaw pairing list slack` | Approve pairing or relax DM policy. | +| Channel message ignored | Check `groupPolicy` and channel allowlist | Allow the channel or switch policy to `open`. | + +Full troubleshooting: [/channels/slack#troubleshooting](/channels/slack#troubleshooting) + +## iMessage and BlueBubbles + +### iMessage and BlueBubbles failure signatures + +| Symptom | Fastest check | Fix | +| -------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------- | +| No inbound events | Verify webhook/server reachability and app permissions | Fix webhook URL or BlueBubbles server state. | +| Can send but no receive on macOS | Check macOS privacy permissions for Messages automation | Re-grant TCC permissions and restart channel process. | +| DM sender blocked | `openclaw pairing list imessage` or `openclaw pairing list bluebubbles` | Approve pairing or update allowlist. | + +Full troubleshooting: + +- [/channels/imessage#troubleshooting-macos-privacy-and-security-tcc](/channels/imessage#troubleshooting-macos-privacy-and-security-tcc) +- [/channels/bluebubbles#troubleshooting](/channels/bluebubbles#troubleshooting) + +## Signal + +### Signal failure signatures + +| Symptom | Fastest check | Fix | +| ------------------------------- | ------------------------------------------ | -------------------------------------------------------- | +| Daemon reachable but bot silent | `openclaw channels status --probe` | Verify `signal-cli` daemon URL/account and receive mode. | +| DM blocked | `openclaw pairing list signal` | Approve sender or adjust DM policy. | +| Group replies do not trigger | Check group allowlist and mention patterns | Add sender/group or loosen gating. | + +Full troubleshooting: [/channels/signal#troubleshooting](/channels/signal#troubleshooting) + +## Matrix + +### Matrix failure signatures + +| Symptom | Fastest check | Fix | +| ----------------------------------- | -------------------------------------------- | ----------------------------------------------- | +| Logged in but ignores room messages | `openclaw channels status --probe` | Check `groupPolicy` and room allowlist. | +| DMs do not process | `openclaw pairing list matrix` | Approve sender or adjust DM policy. | +| Encrypted rooms fail | Verify crypto module and encryption settings | Enable encryption support and rejoin/sync room. | + +Full troubleshooting: [/channels/matrix#troubleshooting](/channels/matrix#troubleshooting) diff --git a/docs/docs.json b/docs/docs.json index 7395ace49b..3a47206bec 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -664,7 +664,7 @@ }, { "source": "/troubleshooting", - "destination": "/gateway/troubleshooting" + "destination": "/help/troubleshooting" }, { "source": "/web/tui", @@ -966,6 +966,7 @@ "hooks/soul-evil", "automation/cron-jobs", "automation/cron-vs-heartbeat", + "automation/troubleshooting", "automation/webhook", "automation/gmail-pubsub", "automation/poll", @@ -976,6 +977,7 @@ "group": "Media and devices", "pages": [ "nodes/index", + "nodes/troubleshooting", "nodes/images", "nodes/audio", "nodes/camera", diff --git a/docs/gateway/heartbeat.md b/docs/gateway/heartbeat.md index f9ab1caf2f..fa13040916 100644 --- a/docs/gateway/heartbeat.md +++ b/docs/gateway/heartbeat.md @@ -13,6 +13,8 @@ title: "Heartbeat" Heartbeat runs **periodic agent turns** in the main session so the model can surface anything that needs attention without spamming you. +Troubleshooting: [/automation/troubleshooting](/automation/troubleshooting) + ## Quick start (beginner) 1. Leave heartbeats enabled (default is `30m`, or `1h` for Anthropic OAuth/setup-token) or set your own cadence. diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md index 5f9d51f1dd..32091dc547 100644 --- a/docs/gateway/troubleshooting.md +++ b/docs/gateway/troubleshooting.md @@ -1,778 +1,318 @@ --- -summary: "Quick troubleshooting guide for common OpenClaw failures" +summary: "Deep troubleshooting runbook for gateway, channels, automation, nodes, and browser" read_when: - - Investigating runtime issues or failures + - The troubleshooting hub pointed you here for deeper diagnosis + - You need stable symptom based runbook sections with exact commands title: "Troubleshooting" --- -# Troubleshooting 🔧 +# Gateway troubleshooting -When OpenClaw misbehaves, here's how to fix it. +This page is the deep runbook. +Start at [/help/troubleshooting](/help/troubleshooting) if you want the fast triage flow first. -Start with the FAQ’s [First 60 seconds](/help/faq#first-60-seconds-if-somethings-broken) if you just want a quick triage recipe. This page goes deeper on runtime failures and diagnostics. +## Command ladder -Provider-specific shortcuts: [/channels/troubleshooting](/channels/troubleshooting) - -## Status & Diagnostics - -Quick triage commands (in order): - -| Command | What it tells you | When to use it | -| ---------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------- | -| `openclaw status` | Local summary: OS + update, gateway reachability/mode, service, agents/sessions, provider config state | First check, quick overview | -| `openclaw status --all` | Full local diagnosis (read-only, pasteable, safe-ish) incl. log tail | When you need to share a debug report | -| `openclaw status --deep` | Runs gateway health checks (incl. provider probes; requires reachable gateway) | When “configured” doesn’t mean “working” | -| `openclaw gateway probe` | Gateway discovery + reachability (local + remote targets) | When you suspect you’re probing the wrong gateway | -| `openclaw channels status --probe` | Asks the running gateway for channel status (and optionally probes) | When gateway is reachable but channels misbehave | -| `openclaw gateway status` | Supervisor state (launchd/systemd/schtasks), runtime PID/exit, last gateway error | When the service “looks loaded” but nothing runs | -| `openclaw logs --follow` | Live logs (best signal for runtime issues) | When you need the actual failure reason | - -**Sharing output:** prefer `openclaw status --all` (it redacts tokens). If you paste `openclaw status`, consider setting `OPENCLAW_SHOW_SECRETS=0` first (token previews). - -See also: [Health checks](/gateway/health) and [Logging](/logging). - -## Common Issues - -### No API key found for provider "anthropic" - -This means the **agent’s auth store is empty** or missing Anthropic credentials. -Auth is **per agent**, so a new agent won’t inherit the main agent’s keys. - -Fix options: - -- Re-run onboarding and choose **Anthropic** for that agent. -- Or paste a setup-token on the **gateway host**: - - ```bash - openclaw models auth setup-token --provider anthropic - ``` - -- Or copy `auth-profiles.json` from the main agent dir to the new agent dir. - -Verify: - -```bash -openclaw models status -``` - -### OAuth token refresh failed (Anthropic Claude subscription) - -This means the stored Anthropic OAuth token expired and the refresh failed. -If you’re on a Claude subscription (no API key), the most reliable fix is to -switch to a **Claude Code setup-token** and paste it on the **gateway host**. - -**Recommended (setup-token):** - -```bash -# Run on the gateway host (paste the setup-token) -openclaw models auth setup-token --provider anthropic -openclaw models status -``` - -If you generated the token elsewhere: - -```bash -openclaw models auth paste-token --provider anthropic -openclaw models status -``` - -More detail: [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth). - -### Control UI fails on HTTP ("device identity required" / "connect failed") - -If you open the dashboard over plain HTTP (e.g. `http://:18789/` or -`http://:18789/`), the browser runs in a **non-secure context** and -blocks WebCrypto, so device identity can’t be generated. - -**Fix:** - -- Prefer HTTPS via [Tailscale Serve](/gateway/tailscale). -- Or open locally on the gateway host: `http://127.0.0.1:18789/`. -- If you must stay on HTTP, enable `gateway.controlUi.allowInsecureAuth: true` and - use a gateway token (token-only; no device identity/pairing). See - [Control UI](/web/control-ui#insecure-http). - -### CI Secrets Scan Failed - -This means `detect-secrets` found new candidates not yet in the baseline. -Follow [Secret scanning](/gateway/security#secret-scanning-detect-secrets). - -### Service Installed but Nothing is Running - -If the gateway service is installed but the process exits immediately, the service -can appear “loaded” while nothing is running. - -**Check:** - -```bash -openclaw gateway status -openclaw doctor -``` - -Doctor/service will show runtime state (PID/last exit) and log hints. - -**Logs:** - -- Preferred: `openclaw logs --follow` -- File logs (always): `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (or your configured `logging.file`) -- macOS LaunchAgent (if installed): `$OPENCLAW_STATE_DIR/logs/gateway.log` and `gateway.err.log` -- Linux systemd (if installed): `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` -- Windows: `schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` - -**Enable more logging:** - -- Bump file log detail (persisted JSONL): - - ```json - { "logging": { "level": "debug" } } - ``` - -- Bump console verbosity (TTY output only): - - ```json - { "logging": { "consoleLevel": "debug", "consoleStyle": "pretty" } } - ``` - -- Quick tip: `--verbose` affects **console** output only. File logs remain controlled by `logging.level`. - -See [/logging](/logging) for a full overview of formats, config, and access. - -### "Gateway start blocked: set gateway.mode=local" - -This means the config exists but `gateway.mode` is unset (or not `local`), so the -Gateway refuses to start. - -**Fix (recommended):** - -- Run the wizard and set the Gateway run mode to **Local**: - - ```bash - openclaw configure - ``` - -- Or set it directly: - - ```bash - openclaw config set gateway.mode local - ``` - -**If you meant to run a remote Gateway instead:** - -- Set a remote URL and keep `gateway.mode=remote`: - - ```bash - openclaw config set gateway.mode remote - openclaw config set gateway.remote.url "wss://gateway.example.com" - ``` - -**Ad-hoc/dev only:** pass `--allow-unconfigured` to start the gateway without -`gateway.mode=local`. - -**No config file yet?** Run `openclaw setup` to create a starter config, then rerun -the gateway. - -### Service Environment (PATH + runtime) - -The gateway service runs with a **minimal PATH** to avoid shell/manager cruft: - -- macOS: `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin` -- Linux: `/usr/local/bin`, `/usr/bin`, `/bin` - -This intentionally excludes version managers (nvm/fnm/volta/asdf) and package -managers (pnpm/npm) because the service does not load your shell init. Runtime -variables like `DISPLAY` should live in `~/.openclaw/.env` (loaded early by the -gateway). -Exec runs on `host=gateway` merge your login-shell `PATH` into the exec environment, -so missing tools usually mean your shell init isn’t exporting them (or set -`tools.exec.pathPrepend`). See [/tools/exec](/tools/exec). - -WhatsApp + Telegram channels require **Node**; Bun is unsupported. If your -service was installed with Bun or a version-managed Node path, run `openclaw doctor` -to migrate to a system Node install. - -### Skill missing API key in sandbox - -**Symptom:** Skill works on host but fails in sandbox with missing API key. - -**Why:** sandboxed exec runs inside Docker and does **not** inherit host `process.env`. - -**Fix:** - -- set `agents.defaults.sandbox.docker.env` (or per-agent `agents.list[].sandbox.docker.env`) -- or bake the key into your custom sandbox image -- then run `openclaw sandbox recreate --agent ` (or `--all`) - -### Service Running but Port Not Listening - -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 (service):` as the “what did we actually try?” lines. - -**Check:** - -- `gateway.mode` must be `local` for `openclaw gateway` and the service. -- If you set `gateway.mode=remote`, the **CLI defaults** to a remote URL. The service can still be running locally, but your CLI may be probing the wrong place. Use `openclaw gateway status` to see the service’s resolved port + probe target (or pass `--url`). -- `openclaw gateway status` and `openclaw doctor` surface the **last gateway error** from logs when the service looks running but the port is closed. -- Non-loopback binds (`lan`/`tailnet`/`custom`, or `auto` when loopback is unavailable) require auth: - `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`). -- `gateway.remote.token` is for remote CLI calls only; it does **not** enable local auth. -- `gateway.token` is ignored; use `gateway.auth.token`. - -**If `openclaw gateway status` shows a config mismatch** - -- `Config (cli): ...` and `Config (service): ...` should normally match. -- If they don’t, you’re almost certainly editing one config while the service is running another. -- Fix: rerun `openclaw gateway install --force` from the same `--profile` / `OPENCLAW_STATE_DIR` you want the service to use. - -**If `openclaw gateway status` reports service config issues** - -- The supervisor config (launchd/systemd/schtasks) is missing current defaults. -- Fix: run `openclaw doctor` to update it (or `openclaw gateway install --force` for a full rewrite). - -**If `Last gateway error:` mentions “refusing to bind … without auth”** - -- You set `gateway.bind` to a non-loopback mode (`lan`/`tailnet`/`custom`, or `auto` when loopback is unavailable) but didn’t configure auth. -- Fix: set `gateway.auth.mode` + `gateway.auth.token` (or export `OPENCLAW_GATEWAY_TOKEN`) and restart the service. - -**If `openclaw gateway 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. - -**Check:** - -```bash -openclaw gateway status -``` - -It will show the listener(s) and likely causes (gateway already running, SSH tunnel). -If needed, stop the service or pick a different port. - -### Extra Workspace Folders Detected - -If you upgraded from older installs, you might still have `~/openclaw` on disk. -Multiple workspace directories can cause confusing auth or state drift because -only one workspace is active. - -**Fix:** keep a single active workspace and archive/remove the rest. See -[Agent workspace](/concepts/agent-workspace#extra-workspace-folders). - -### Main chat running in a sandbox workspace - -Symptoms: `pwd` or file tools show `~/.openclaw/sandboxes/...` even though you -expected the host workspace. - -**Why:** `agents.defaults.sandbox.mode: "non-main"` keys off `session.mainKey` (default `"main"`). -Group/channel sessions use their own keys, so they are treated as non-main and -get sandbox workspaces. - -**Fix options:** - -- If you want host workspaces for an agent: set `agents.list[].sandbox.mode: "off"`. -- If you want host workspace access inside sandbox: set `workspaceAccess: "rw"` for that agent. - -### "Agent was aborted" - -The agent was interrupted mid-response. - -**Causes:** - -- User sent `stop`, `abort`, `esc`, `wait`, or `exit` -- Timeout exceeded -- Process crashed - -**Fix:** Just send another message. The session continues. - -### "Agent failed before reply: Unknown model: anthropic/claude-haiku-3-5" - -OpenClaw intentionally rejects **older/insecure models** (especially those more -vulnerable to prompt injection). If you see this error, the model name is no -longer supported. - -**Fix:** - -- Pick a **latest** model for the provider and update your config or model alias. -- If you’re unsure which models are available, run `openclaw models list` or - `openclaw models scan` and choose a supported one. -- Check gateway logs for the detailed failure reason. - -See also: [Models CLI](/cli/models) and [Model providers](/concepts/model-providers). - -### Messages Not Triggering - -**Check 1:** Is the sender allowlisted? +Run these first, in this order: ```bash openclaw 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 channel groups/guilds. -# Multi-agent: `agents.list[].groupChat.mentionPatterns` overrides global patterns. -grep -n "agents\\|groupChat\\|mentionPatterns\\|channels\\.whatsapp\\.groups\\|channels\\.telegram\\.groups\\|channels\\.imessage\\.groups\\|channels\\.discord\\.guilds" \ - "${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json}" -``` - -**Check 3:** Check the logs - -```bash +openclaw gateway status openclaw logs --follow -# or if you want quick filters: -tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" | grep "blocked\\|skip\\|unauthorized" +openclaw doctor +openclaw channels status --probe ``` -### Pairing Code Not Arriving +Expected healthy signals: -If `dmPolicy` is `pairing`, unknown senders should receive a code and their message is ignored until approved. +- `openclaw gateway status` shows `Runtime: running` and `RPC probe: ok`. +- `openclaw doctor` reports no blocking config/service issues. +- `openclaw channels status --probe` shows connected/ready channels. -**Check 1:** Is a pending request already waiting? +## No replies + +If channels are up but nothing answers, check routing and policy before reconnecting anything. ```bash -openclaw pairing list -``` - -Pending DM pairing requests are capped at **3 per channel** by default. If the list is full, new requests won’t generate a code until one is approved or expires. - -**Check 2:** Did the request get created but no reply was sent? - -```bash -openclaw logs --follow | grep "pairing request" -``` - -**Check 3:** Confirm `dmPolicy` isn’t `open`/`allowlist` for that channel. - -### Image + Mention Not Working - -Known issue: When you send an image with ONLY a mention (no other text), WhatsApp sometimes doesn't include the mention metadata. - -**Workaround:** Add some text with the mention: - -- ❌ `@openclaw` + image -- ✅ `@openclaw check this` + image - -### Session Not Resuming - -**Check 1:** Is the session file there? - -```bash -ls -la ~/.openclaw/agents//sessions/ -``` - -**Check 2:** Is the reset window too short? - -```json -{ - "session": { - "reset": { - "mode": "daily", - "atHour": 4, - "idleMinutes": 10080 // 7 days - } - } -} -``` - -**Check 3:** Did someone send `/new`, `/reset`, or a reset trigger? - -### Agent Timing Out - -Default timeout is 30 minutes. For long tasks: - -```json -{ - "reply": { - "timeoutSeconds": 3600 // 1 hour - } -} -``` - -Or use the `process` tool to background long commands. - -### WhatsApp Disconnected - -```bash -# Check local status (creds, sessions, queued events) openclaw status -# Probe the running gateway + channels (WA connect + Telegram + Discord APIs) +openclaw channels status --probe +openclaw pairing list +openclaw config get channels +openclaw logs --follow +``` + +Look for: + +- Pairing pending for DM senders. +- Group mention gating (`requireMention`, `mentionPatterns`). +- Channel/group allowlist mismatches. + +Common signatures: + +- `drop guild message (mention required` → group message ignored until mention. +- `pairing request` → sender needs approval. +- `blocked` / `allowlist` → sender/channel was filtered by policy. + +Related: + +- [/channels/troubleshooting](/channels/troubleshooting) +- [/start/pairing](/start/pairing) +- [/concepts/groups](/concepts/groups) + +## Dashboard control ui connectivity + +When dashboard/control UI will not connect, validate URL, auth mode, and secure context assumptions. + +```bash +openclaw gateway status +openclaw status +openclaw logs --follow +openclaw doctor +openclaw gateway status --json +``` + +Look for: + +- Correct probe URL and dashboard URL. +- Auth mode/token mismatch between client and gateway. +- HTTP usage where device identity is required. + +Common signatures: + +- `device identity required` → non-secure context or missing device auth. +- `unauthorized` / reconnect loop → token/password mismatch. +- `gateway connect failed:` → wrong host/port/url target. + +Related: + +- [/web/control-ui](/web/control-ui) +- [/gateway/authentication](/gateway/authentication) +- [/gateway/remote](/gateway/remote) + +## Gateway service not running + +Use this when service is installed but process does not stay up. + +```bash +openclaw gateway status +openclaw status +openclaw logs --follow +openclaw doctor +openclaw gateway status --deep +``` + +Look for: + +- `Runtime: stopped` with exit hints. +- Service config mismatch (`Config (cli)` vs `Config (service)`). +- Port/listener conflicts. + +Common signatures: + +- `Gateway start blocked: set gateway.mode=local` → local gateway mode is not enabled. +- `refusing to bind gateway ... without auth` → non-loopback bind without token/password. +- `another gateway instance is already listening` / `EADDRINUSE` → port conflict. + +Related: + +- [/gateway/background-process](/gateway/background-process) +- [/gateway/configuration](/gateway/configuration) +- [/gateway/doctor](/gateway/doctor) + +## Channel connected messages not flowing + +If channel state is connected but message flow is dead, focus on policy, permissions, and channel specific delivery rules. + +```bash +openclaw channels status --probe +openclaw pairing list openclaw status --deep - -# View recent connection events -openclaw logs --limit 200 | grep "connection\\|disconnect\\|logout" +openclaw logs --follow +openclaw config get channels ``` -**Fix:** Usually reconnects automatically once the Gateway is running. If you’re stuck, restart the Gateway process (however you supervise it), or run it manually with verbose output: +Look for: + +- DM policy (`pairing`, `allowlist`, `open`, `disabled`). +- Group allowlist and mention requirements. +- Missing channel API permissions/scopes. + +Common signatures: + +- `mention required` → message ignored by group mention policy. +- `pairing` / pending approval traces → sender is not approved. +- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → channel auth/permissions issue. + +Related: + +- [/channels/troubleshooting](/channels/troubleshooting) +- [/channels/whatsapp](/channels/whatsapp) +- [/channels/telegram](/channels/telegram) +- [/channels/discord](/channels/discord) + +## Cron and heartbeat delivery + +If cron or heartbeat did not run or did not deliver, verify scheduler state first, then delivery target. ```bash -openclaw gateway --verbose +openclaw cron status +openclaw cron list +openclaw cron runs --id --limit 20 +openclaw system heartbeat last +openclaw logs --follow ``` -If you’re logged out / unlinked: +Look for: + +- Cron enabled and next wake present. +- Job run history status (`ok`, `skipped`, `error`). +- Heartbeat skip reasons (`quiet-hours`, `requests-in-flight`, `alerts-disabled`). + +Common signatures: + +- `cron: scheduler disabled; jobs will not run automatically` → cron disabled. +- `cron: timer tick failed` → scheduler tick failed; check file/log/runtime errors. +- `heartbeat skipped` with `reason=quiet-hours` → outside active hours window. +- `heartbeat: unknown accountId` → invalid account id for heartbeat delivery target. + +Related: + +- [/automation/troubleshooting](/automation/troubleshooting) +- [/automation/cron-jobs](/automation/cron-jobs) +- [/gateway/heartbeat](/gateway/heartbeat) + +## Node paired tool fails + +If a node is paired but tools fail, isolate foreground, permission, and approval state. ```bash -openclaw channels logout -trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials" # if logout can't cleanly remove everything -openclaw channels login --verbose # re-scan QR +openclaw nodes status +openclaw nodes describe --node +openclaw approvals get --node +openclaw logs --follow +openclaw status ``` -### Media Send Failing +Look for: -**Check 1:** Is the file path valid? - -```bash -ls -la /path/to/your/image.jpg -``` - -**Check 2:** Is it too large? - -- Images: max 6MB -- Audio/Video: max 16MB -- Documents: max 100MB - -**Check 3:** Check media logs - -```bash -grep "media\\|fetch\\|download" "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" | tail -20 -``` - -### High Memory Usage - -OpenClaw keeps conversation history in memory. - -**Fix:** Restart periodically or set session limits: - -```json -{ - "session": { - "historyLimit": 100 // Max messages to keep - } -} -``` - -## Common troubleshooting - -### “Gateway won’t start — configuration invalid” - -OpenClaw now refuses to start when the config contains unknown keys, malformed values, or invalid types. -This is intentional for safety. - -Fix it with Doctor: +- Node online with expected capabilities. +- OS permission grants for camera/mic/location/screen. +- Exec approvals and allowlist state. + +Common signatures: + +- `NODE_BACKGROUND_UNAVAILABLE` → node app must be in foreground. +- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → missing OS permission. +- `SYSTEM_RUN_DENIED: approval required` → exec approval pending. +- `SYSTEM_RUN_DENIED: allowlist miss` → command blocked by allowlist. + +Related: + +- [/nodes/troubleshooting](/nodes/troubleshooting) +- [/nodes/index](/nodes/index) +- [/tools/exec-approvals](/tools/exec-approvals) + +## Browser tool fails + +Use this when browser tool actions fail even though the gateway itself is healthy. ```bash +openclaw browser status +openclaw browser start --browser-profile openclaw +openclaw browser profiles +openclaw logs --follow openclaw doctor -openclaw doctor --fix ``` -Notes: +Look for: -- `openclaw doctor` reports every invalid entry. -- `openclaw doctor --fix` applies migrations/repairs and rewrites the config. -- Diagnostic commands like `openclaw logs`, `openclaw health`, `openclaw status`, `openclaw gateway status`, and `openclaw gateway probe` still run even if the config is invalid. +- Valid browser executable path. +- CDP profile reachability. +- Extension relay tab attachment for `profile="chrome"`. -### “All models failed” — what should I check first? +Common signatures: -- **Credentials** present for the provider(s) being tried (auth profiles + env vars). -- **Model routing**: confirm `agents.defaults.model.primary` and fallbacks are models you can access. -- **Gateway logs** in `/tmp/openclaw/…` for the exact provider error. -- **Model status**: use `/model status` (chat) or `openclaw models status` (CLI). +- `Failed to start Chrome CDP on port` → browser process failed to launch. +- `browser.executablePath not found` → configured path is invalid. +- `Chrome extension relay is running, but no tab is connected` → extension relay not attached. +- `Browser attachOnly is enabled ... not reachable` → attach-only profile has no reachable target. -### I’m running on my personal WhatsApp number — why is self-chat weird? +Related: -Enable self-chat mode and allowlist your own number: +- [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting) +- [/tools/chrome-extension](/tools/chrome-extension) +- [/tools/browser](/tools/browser) -```json5 -{ - channels: { - whatsapp: { - selfChatMode: true, - dmPolicy: "allowlist", - allowFrom: ["+15555550123"], - }, - }, -} -``` +## If you upgraded and something suddenly broke -See [WhatsApp setup](/channels/whatsapp). +Most post-upgrade breakage is config drift or stricter defaults now being enforced. -### WhatsApp logged me out. How do I re‑auth? - -Run the login command again and scan the QR code: +### 1) Auth and URL override behavior changed ```bash -openclaw channels login +openclaw gateway status +openclaw config get gateway.mode +openclaw config get gateway.remote.url +openclaw config get gateway.auth.mode ``` -### Build errors on `main` — what’s the standard fix path? +What to check: -1. `git pull origin main && pnpm install` -2. `openclaw doctor` -3. Check GitHub issues or Discord -4. Temporary workaround: check out an older commit +- If `gateway.mode=remote`, CLI calls may be targeting remote while your local service is fine. +- Explicit `--url` calls do not fall back to stored credentials. -### npm install fails (allow-build-scripts / missing tar or yargs). What now? +Common signatures: -If you’re running from source, use the repo’s package manager: **pnpm** (preferred). -The repo declares `packageManager: "pnpm@…"`. +- `gateway connect failed:` → wrong URL target. +- `unauthorized` → endpoint reachable but wrong auth. -Typical recovery: +### 2) Bind and auth guardrails are stricter ```bash -git status # ensure you’re in the repo root -pnpm install -pnpm build +openclaw config get gateway.bind +openclaw config get gateway.auth.token +openclaw gateway status +openclaw logs --follow +``` + +What to check: + +- Non-loopback binds (`lan`, `tailnet`, `custom`) need auth configured. +- Old keys like `gateway.token` do not replace `gateway.auth.token`. + +Common signatures: + +- `refusing to bind gateway ... without auth` → bind+auth mismatch. +- `RPC probe: failed` while runtime is running → gateway alive but inaccessible with current auth/url. + +### 3) Pairing and device identity state changed + +```bash +openclaw devices list +openclaw pairing list +openclaw logs --follow openclaw doctor +``` + +What to check: + +- Pending device approvals for dashboard/nodes. +- Pending DM pairing approvals after policy or identity changes. + +Common signatures: + +- `device identity required` → device auth not satisfied. +- `pairing required` → sender/device must be approved. + +If the service config and runtime still disagree after checks, reinstall service metadata from the same profile/state directory: + +```bash +openclaw gateway install --force openclaw gateway restart ``` -Why: pnpm is the configured package manager for this repo. +Related: -### How do I switch between git installs and npm installs? - -Use the **website installer** and select the install method with a flag. It -upgrades in place and rewrites the gateway service to point at the new install. - -Switch **to git install**: - -```bash -curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard -``` - -Switch **to npm global**: - -```bash -curl -fsSL https://openclaw.ai/install.sh | bash -``` - -Notes: - -- The git flow only rebases if the repo is clean. Commit or stash changes first. -- After switching, run: - - ```bash - openclaw doctor - openclaw gateway restart - ``` - -### Telegram block streaming isn’t splitting text between tool calls. Why? - -Block streaming only sends **completed text blocks**. Common reasons you see a single message: - -- `agents.defaults.blockStreamingDefault` is still `"off"`. -- `channels.telegram.blockStreaming` is set to `false`. -- `channels.telegram.streamMode` is `partial` or `block` **and draft streaming is active** - (private chat + topics). Draft streaming disables block streaming in that case. -- Your `minChars` / coalesce settings are too high, so chunks get merged. -- The model emits one large text block (no mid‑reply flush points). - -Fix checklist: - -1. Put block streaming settings under `agents.defaults`, not the root. -2. Set `channels.telegram.streamMode: "off"` if you want real multi‑message block replies. -3. Use smaller chunk/coalesce thresholds while debugging. - -See [Streaming](/concepts/streaming). - -### Discord doesn’t reply in my server even with `requireMention: false`. Why? - -`requireMention` only controls mention‑gating **after** the channel passes allowlists. -By default `channels.discord.groupPolicy` is **allowlist**, so guilds must be explicitly enabled. -If you set `channels.discord.guilds..channels`, only the listed channels are allowed; omit it to allow all channels in the guild. - -Fix checklist: - -1. Set `channels.discord.groupPolicy: "open"` **or** add a guild allowlist entry (and optionally a channel allowlist). -2. Use **numeric channel IDs** in `channels.discord.guilds..channels`. -3. Put `requireMention: false` **under** `channels.discord.guilds` (global or per‑channel). - Top‑level `channels.discord.requireMention` is not a supported key. -4. Ensure the bot has **Message Content Intent** and channel permissions. -5. Run `openclaw channels status --probe` for audit hints. - -Docs: [Discord](/channels/discord), [Channels troubleshooting](/channels/troubleshooting). - -### Cloud Code Assist API error: invalid tool schema (400). What now? - -This is almost always a **tool schema compatibility** issue. The Cloud Code Assist -endpoint accepts a strict subset of JSON Schema. OpenClaw scrubs/normalizes tool -schemas in current `main`, but the fix is not in the last release yet (as of -January 13, 2026). - -Fix checklist: - -1. **Update OpenClaw**: - - If you can run from source, pull `main` and restart the gateway. - - Otherwise, wait for the next release that includes the schema scrubber. -2. Avoid unsupported keywords like `anyOf/oneOf/allOf`, `patternProperties`, - `additionalProperties`, `minLength`, `maxLength`, `format`, etc. -3. If you define custom tools, keep the top‑level schema as `type: "object"` with - `properties` and simple enums. - -See [Tools](/tools) and [TypeBox schemas](/concepts/typebox). - -## macOS Specific Issues - -### App Crashes when Granting Permissions (Speech/Mic) - -If the app disappears or shows "Abort trap 6" when you click "Allow" on a privacy prompt: - -**Fix 1: Reset TCC Cache** - -```bash -tccutil reset All bot.molt.mac.debug -``` - -**Fix 2: Force New Bundle ID** -If resetting doesn't work, change the `BUNDLE_ID` in [`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) (e.g., add a `.test` suffix) and rebuild. This forces macOS to treat it as a new app. - -### Gateway stuck on "Starting..." - -The app connects to a local gateway on port `18789`. If it stays stuck: - -**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 -openclaw gateway status -openclaw gateway stop -# Or: launchctl bootout gui/$UID/bot.molt.gateway (replace with bot.molt.; legacy com.openclaw.* still works) -``` - -**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 the CLI install** -Ensure the global `openclaw` CLI is installed and matches the app version: - -```bash -openclaw --version -npm install -g openclaw@ -``` - -## Debug Mode - -Get verbose logging: - -```bash -# Turn on trace logging in config: -# ${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json} -> { logging: { level: "trace" } } -# -# Then run verbose commands to mirror debug output to stdout: -openclaw gateway --verbose -openclaw channels login --verbose -``` - -## Log Locations - -| Log | Location | -| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Gateway file logs (structured) | `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (or `logging.file`) | -| Gateway service logs (supervisor) | macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` + `gateway.err.log` (default: `~/.openclaw/logs/...`; profiles use `~/.openclaw-/logs/...`)
Linux: `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager`
Windows: `schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` | -| Session files | `$OPENCLAW_STATE_DIR/agents//sessions/` | -| Media cache | `$OPENCLAW_STATE_DIR/media/` | -| Credentials | `$OPENCLAW_STATE_DIR/credentials/` | - -## Health Check - -```bash -# Supervisor + probe target + config paths -openclaw gateway status -# Include system-level scans (legacy/extra services, port listeners) -openclaw gateway status --deep - -# Is the gateway reachable? -openclaw health --json -# If it fails, rerun with connection details: -openclaw health --verbose - -# Is something listening on the default port? -lsof -nP -iTCP:18789 -sTCP:LISTEN - -# Recent activity (RPC log tail) -openclaw logs --follow -# Fallback if RPC is down -tail -20 /tmp/openclaw/openclaw-*.log -``` - -## Reset Everything - -Nuclear option: - -```bash -openclaw gateway stop -# If you installed a service and want a clean install: -# openclaw gateway uninstall - -trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}" -openclaw channels login # re-pair WhatsApp -openclaw gateway restart # or: openclaw gateway -``` - -⚠️ This loses all sessions and requires re-pairing WhatsApp. - -## Getting Help - -1. Check logs first: `/tmp/openclaw/` (default: `openclaw-YYYY-MM-DD.log`, or your configured `logging.file`) -2. Search existing issues on GitHub -3. Open a new issue with: - - OpenClaw version - - Relevant log snippets - - Steps to reproduce - - Your config (redact secrets!) - ---- - -_"Have you tried turning it off and on again?"_ — Every IT person ever - -🦞🔧 - -### Browser Not Starting (Linux) - -If you see `"Failed to start Chrome CDP on port 18800"`: - -**Most likely cause:** Snap-packaged Chromium on Ubuntu. - -**Quick fix:** Install Google Chrome instead: - -```bash -wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb -sudo dpkg -i google-chrome-stable_current_amd64.deb -``` - -Then set in config: - -```json -{ - "browser": { - "executablePath": "/usr/bin/google-chrome-stable" - } -} -``` - -**Full guide:** See [browser-linux-troubleshooting](/tools/browser-linux-troubleshooting) +- [/gateway/pairing](/gateway/pairing) +- [/gateway/authentication](/gateway/authentication) +- [/gateway/background-process](/gateway/background-process) diff --git a/docs/help/troubleshooting.md b/docs/help/troubleshooting.md index 2b201c5e9a..c050d1b0d6 100644 --- a/docs/help/troubleshooting.md +++ b/docs/help/troubleshooting.md @@ -1,98 +1,265 @@ --- -summary: "Troubleshooting hub: symptoms → checks → fixes" +summary: "Symptom first troubleshooting hub for OpenClaw" read_when: - - You see an error and want the fix path - - The installer says “success” but the CLI doesn’t work + - OpenClaw is not working and you need the fastest path to a fix + - You want a triage flow before diving into deep runbooks title: "Troubleshooting" --- # Troubleshooting +If you only have 2 minutes, use this page as a triage front door. + ## First 60 seconds -Run these in order: +Run this exact ladder in order: ```bash openclaw status openclaw status --all openclaw gateway probe -openclaw logs --follow +openclaw gateway status openclaw doctor +openclaw channels status --probe +openclaw logs --follow ``` -If the gateway is reachable, deep probes: +Good output in one line: -```bash -openclaw status --deep +- `openclaw status` → shows configured channels and no obvious auth errors. +- `openclaw status --all` → full report is present and shareable. +- `openclaw gateway probe` → expected gateway target is reachable. +- `openclaw gateway status` → `Runtime: running` and `RPC probe: ok`. +- `openclaw doctor` → no blocking config/service errors. +- `openclaw channels status --probe` → channels report `connected` or `ready`. +- `openclaw logs --follow` → steady activity, no repeating fatal errors. + +## Decision tree + +```mermaid +flowchart TD + A[OpenClaw is not working] --> B{What breaks first} + B --> C[No replies] + B --> D[Dashboard or Control UI will not connect] + B --> E[Gateway will not start or service not running] + B --> F[Channel connects but messages do not flow] + B --> G[Cron or heartbeat did not fire or did not deliver] + B --> H[Node is paired but camera canvas screen exec fails] + B --> I[Browser tool fails] + + C --> C1[/No replies section/] + D --> D1[/Control UI section/] + E --> E1[/Gateway section/] + F --> F1[/Channel flow section/] + G --> G1[/Automation section/] + H --> H1[/Node tools section/] + I --> I1[/Browser section/] ``` -## Common “it broke” cases + + + ```bash + openclaw status + openclaw gateway status + openclaw channels status --probe + openclaw pairing list + openclaw logs --follow + ``` -### `openclaw: command not found` + Good output looks like: -Almost always a Node/npm PATH issue. Start here: + - `Runtime: running` + - `RPC probe: ok` + - Your channel shows connected/ready in `channels status --probe` + - Sender appears approved (or DM policy is open/allowlist) -- [Install (Node/npm PATH sanity)](/install#nodejs--npm-path-sanity) + Common log signatures: -### Installer fails (or you need full logs) + - `drop guild message (mention required` → mention gating blocked the message in Discord. + - `pairing request` → sender is unapproved and waiting for DM pairing approval. + - `blocked` / `allowlist` in channel logs → sender, room, or group is filtered. -Re-run the installer in verbose mode to see the full trace and npm output: + Deep pages: -```bash -curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose -``` + - [/gateway/troubleshooting#no-replies](/gateway/troubleshooting#no-replies) + - [/channels/troubleshooting](/channels/troubleshooting) + - [/start/pairing](/start/pairing) -For beta installs: + -```bash -curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose -``` + + ```bash + openclaw status + openclaw gateway status + openclaw logs --follow + openclaw doctor + openclaw channels status --probe + ``` -You can also set `OPENCLAW_VERBOSE=1` instead of the flag. + Good output looks like: -### Gateway “unauthorized”, can’t connect, or keeps reconnecting + - `Dashboard: http://...` is shown in `openclaw gateway status` + - `RPC probe: ok` + - No auth loop in logs -- [Gateway troubleshooting](/gateway/troubleshooting) -- [Gateway authentication](/gateway/authentication) + Common log signatures: -### Control UI fails on HTTP (device identity required) + - `device identity required` → HTTP/non-secure context cannot complete device auth. + - `unauthorized` / reconnect loop → wrong token/password or auth mode mismatch. + - `gateway connect failed:` → UI is targeting the wrong URL/port or unreachable gateway. -- [Gateway troubleshooting](/gateway/troubleshooting) -- [Control UI](/web/control-ui#insecure-http) + Deep pages: -### `docs.openclaw.ai` shows an SSL error (Comcast/Xfinity) + - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/gateway/troubleshooting#dashboard-control-ui-connectivity) + - [/web/control-ui](/web/control-ui) + - [/gateway/authentication](/gateway/authentication) -Some Comcast/Xfinity connections block `docs.openclaw.ai` via Xfinity Advanced Security. -Disable Advanced Security or add `docs.openclaw.ai` to the allowlist, then retry. + -- Xfinity Advanced Security help: [https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security](https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security) -- Quick sanity checks: try a mobile hotspot or VPN to confirm it’s ISP-level filtering + + ```bash + openclaw status + openclaw gateway status + openclaw logs --follow + openclaw doctor + openclaw channels status --probe + ``` -### Service says running, but RPC probe fails + Good output looks like: -- [Gateway troubleshooting](/gateway/troubleshooting) -- [Background process / service](/gateway/background-process) + - `Service: ... (loaded)` + - `Runtime: running` + - `RPC probe: ok` -### Model/auth failures (rate limit, billing, “all models failed”) + Common log signatures: -- [Models](/cli/models) -- [OAuth / auth concepts](/concepts/oauth) + - `Gateway start blocked: set gateway.mode=local` → gateway mode is unset/remote. + - `refusing to bind gateway ... without auth` → non-loopback bind without token/password. + - `another gateway instance is already listening` or `EADDRINUSE` → port already taken. -### `/model` says `model not allowed` + Deep pages: -This usually means `agents.defaults.models` is configured as an allowlist. When it’s non-empty, -only those provider/model keys can be selected. + - [/gateway/troubleshooting#gateway-service-not-running](/gateway/troubleshooting#gateway-service-not-running) + - [/gateway/background-process](/gateway/background-process) + - [/gateway/configuration](/gateway/configuration) -- Check the allowlist: `openclaw config get agents.defaults.models` -- Add the model you want (or clear the allowlist) and retry `/model` -- Use `/models` to browse the allowed providers/models + -### When filing an issue + + ```bash + openclaw status + openclaw gateway status + openclaw logs --follow + openclaw doctor + openclaw channels status --probe + ``` -Paste a safe report: + Good output looks like: -```bash -openclaw status --all -``` + - Channel transport is connected. + - Pairing/allowlist checks pass. + - Mentions are detected where required. -If you can, include the relevant log tail from `openclaw logs --follow`. + Common log signatures: + + - `mention required` → group mention gating blocked processing. + - `pairing` / `pending` → DM sender is not approved yet. + - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → channel permission token issue. + + Deep pages: + + - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/gateway/troubleshooting#channel-connected-messages-not-flowing) + - [/channels/troubleshooting](/channels/troubleshooting) + + + + + ```bash + openclaw status + openclaw gateway status + openclaw cron status + openclaw cron list + openclaw cron runs --id --limit 20 + openclaw logs --follow + ``` + + Good output looks like: + + - `cron.status` shows enabled with a next wake. + - `cron runs` shows recent `ok` entries. + - Heartbeat is enabled and not outside active hours. + + Common log signatures: + + - `cron: scheduler disabled; jobs will not run automatically` → cron is disabled. + - `heartbeat skipped` with `reason=quiet-hours` → outside configured active hours. + - `requests-in-flight` → main lane busy; heartbeat wake was deferred. + - `unknown accountId` → heartbeat delivery target account does not exist. + + Deep pages: + + - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/gateway/troubleshooting#cron-and-heartbeat-delivery) + - [/automation/troubleshooting](/automation/troubleshooting) + - [/gateway/heartbeat](/gateway/heartbeat) + + + + + ```bash + openclaw status + openclaw gateway status + openclaw nodes status + openclaw nodes describe --node + openclaw logs --follow + ``` + + Good output looks like: + + - Node is listed as connected and paired for role `node`. + - Capability exists for the command you are invoking. + - Permission state is granted for the tool. + + Common log signatures: + + - `NODE_BACKGROUND_UNAVAILABLE` → bring node app to foreground. + - `*_PERMISSION_REQUIRED` → OS permission was denied/missing. + - `SYSTEM_RUN_DENIED: approval required` → exec approval is pending. + - `SYSTEM_RUN_DENIED: allowlist miss` → command not on exec allowlist. + + Deep pages: + + - [/gateway/troubleshooting#node-paired-tool-fails](/gateway/troubleshooting#node-paired-tool-fails) + - [/nodes/troubleshooting](/nodes/troubleshooting) + - [/tools/exec-approvals](/tools/exec-approvals) + + + + + ```bash + openclaw status + openclaw gateway status + openclaw browser status + openclaw logs --follow + openclaw doctor + ``` + + Good output looks like: + + - Browser status shows `running: true` and a chosen browser/profile. + - `openclaw` profile starts or `chrome` relay has an attached tab. + + Common log signatures: + + - `Failed to start Chrome CDP on port` → local browser launch failed. + - `browser.executablePath not found` → configured binary path is wrong. + - `Chrome extension relay is running, but no tab is connected` → extension not attached. + - `Browser attachOnly is enabled ... not reachable` → attach-only profile has no live CDP target. + + Deep pages: + + - [/gateway/troubleshooting#browser-tool-fails](/gateway/troubleshooting#browser-tool-fails) + - [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting) + - [/tools/chrome-extension](/tools/chrome-extension) + + + diff --git a/docs/nodes/index.md b/docs/nodes/index.md index 7b5aaa1a28..c8a787158f 100644 --- a/docs/nodes/index.md +++ b/docs/nodes/index.md @@ -19,6 +19,7 @@ Notes: - Nodes are **peripherals**, not gateways. They don’t run the gateway service. - Telegram/WhatsApp/etc. messages land on the **gateway**, not on nodes. +- Troubleshooting runbook: [/nodes/troubleshooting](/nodes/troubleshooting) ## Pairing + status diff --git a/docs/nodes/troubleshooting.md b/docs/nodes/troubleshooting.md new file mode 100644 index 0000000000..ce815cdf00 --- /dev/null +++ b/docs/nodes/troubleshooting.md @@ -0,0 +1,112 @@ +--- +summary: "Troubleshoot node pairing, foreground requirements, permissions, and tool failures" +read_when: + - Node is connected but camera/canvas/screen/exec tools fail + - You need the node pairing versus approvals mental model +title: "Node Troubleshooting" +--- + +# Node troubleshooting + +Use this page when a node is visible in status but node tools fail. + +## Command ladder + +```bash +openclaw status +openclaw gateway status +openclaw logs --follow +openclaw doctor +openclaw channels status --probe +``` + +Then run node specific checks: + +```bash +openclaw nodes status +openclaw nodes describe --node +openclaw approvals get --node +``` + +Healthy signals: + +- Node is connected and paired for role `node`. +- `nodes describe` includes the capability you are calling. +- Exec approvals show expected mode/allowlist. + +## Foreground requirements + +`canvas.*`, `camera.*`, and `screen.*` are foreground only on iOS/Android nodes. + +Quick check and fix: + +```bash +openclaw nodes describe --node +openclaw nodes canvas snapshot --node +openclaw logs --follow +``` + +If you see `NODE_BACKGROUND_UNAVAILABLE`, bring the node app to the foreground and retry. + +## Permissions matrix + +| Capability | iOS | Android | macOS node app | Typical failure code | +| ---------------------------- | --------------------------------------- | -------------------------------------------- | ----------------------------- | ------------------------------ | +| `camera.snap`, `camera.clip` | Camera (+ mic for clip audio) | Camera (+ mic for clip audio) | Camera (+ mic for clip audio) | `*_PERMISSION_REQUIRED` | +| `screen.record` | Screen Recording (+ mic optional) | Screen capture prompt (+ mic optional) | Screen Recording | `*_PERMISSION_REQUIRED` | +| `location.get` | While Using or Always (depends on mode) | Foreground/Background location based on mode | Location permission | `LOCATION_PERMISSION_REQUIRED` | +| `system.run` | n/a (node host path) | n/a (node host path) | Exec approvals required | `SYSTEM_RUN_DENIED` | + +## Pairing versus approvals + +These are different gates: + +1. **Device pairing**: can this node connect to the gateway? +2. **Exec approvals**: can this node run a specific shell command? + +Quick checks: + +```bash +openclaw devices list +openclaw nodes status +openclaw approvals get --node +openclaw approvals allowlist add --node "/usr/bin/uname" +``` + +If pairing is missing, approve the node device first. +If pairing is fine but `system.run` fails, fix exec approvals/allowlist. + +## Common node error codes + +- `NODE_BACKGROUND_UNAVAILABLE` → app is backgrounded; bring it foreground. +- `CAMERA_DISABLED` → camera toggle disabled in node settings. +- `*_PERMISSION_REQUIRED` → OS permission missing/denied. +- `LOCATION_DISABLED` → location mode is off. +- `LOCATION_PERMISSION_REQUIRED` → requested location mode not granted. +- `LOCATION_BACKGROUND_UNAVAILABLE` → app is backgrounded but only While Using permission exists. +- `SYSTEM_RUN_DENIED: approval required` → exec request needs explicit approval. +- `SYSTEM_RUN_DENIED: allowlist miss` → command blocked by allowlist mode. + +## Fast recovery loop + +```bash +openclaw nodes status +openclaw nodes describe --node +openclaw approvals get --node +openclaw logs --follow +``` + +If still stuck: + +- Re-approve device pairing. +- Re-open node app (foreground). +- Re-grant OS permissions. +- Recreate/adjust exec approval policy. + +Related: + +- [/nodes/index](/nodes/index) +- [/nodes/camera](/nodes/camera) +- [/nodes/location-command](/nodes/location-command) +- [/tools/exec-approvals](/tools/exec-approvals) +- [/gateway/pairing](/gateway/pairing)