mirror of
https://github.com/openclaw/openclaw.git
synced 2026-02-19 18:39:20 -05:00
docs: add symptom-first troubleshooting hub and deep runbooks (#11196)
* docs(troubleshooting): add symptom-first troubleshooting runbooks * docs(troubleshooting): fix approvals command examples * docs(troubleshooting): wrap symptom cases in accordions * docs(automation): clarify userTimezone missing-key behavior * docs(troubleshooting): fix first-60-seconds ladder order
This commit is contained in:
Seb Slight
@@ -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).
|
||||
|
||||
122
docs/automation/troubleshooting.md
Normal file
122
docs/automation/troubleshooting.md
Normal file
@@ -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 <jobId> --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 <jobId> --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)
|
||||
@@ -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)
|
||||
|
||||
@@ -168,6 +168,32 @@ Config:
|
||||
- Groups: `signal:group:<groupId>`.
|
||||
- Usernames: `username:<name>` (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)
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -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
|
||||
<AccordionGroup>
|
||||
<Accordion title="No replies">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
openclaw channels status --probe
|
||||
openclaw pairing list <channel>
|
||||
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:
|
||||
</Accordion>
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose
|
||||
```
|
||||
<Accordion title="Dashboard or Control UI will not connect">
|
||||
```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.
|
||||
</Accordion>
|
||||
|
||||
- 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
|
||||
<Accordion title="Gateway will not start or service installed but not running">
|
||||
```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
|
||||
</Accordion>
|
||||
|
||||
### When filing an issue
|
||||
<Accordion title="Channel connects but messages do not flow">
|
||||
```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)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Cron or heartbeat did not fire or did not deliver">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
openclaw cron status
|
||||
openclaw cron list
|
||||
openclaw cron runs --id <jobId> --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)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Node is paired but tool fails camera canvas screen exec">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
openclaw nodes status
|
||||
openclaw nodes describe --node <idOrNameOrIp>
|
||||
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)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Browser tool fails">
|
||||
```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)
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
112
docs/nodes/troubleshooting.md
Normal file
112
docs/nodes/troubleshooting.md
Normal file
@@ -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 <idOrNameOrIp>
|
||||
openclaw approvals get --node <idOrNameOrIp>
|
||||
```
|
||||
|
||||
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 <idOrNameOrIp>
|
||||
openclaw nodes canvas snapshot --node <idOrNameOrIp>
|
||||
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 <idOrNameOrIp>
|
||||
openclaw approvals allowlist add --node <idOrNameOrIp> "/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 <idOrNameOrIp>
|
||||
openclaw approvals get --node <idOrNameOrIp>
|
||||
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)
|
||||
Reference in New Issue
Block a user