mirror of
https://github.com/openclaw/openclaw.git
synced 2026-02-19 18:39:20 -05:00
9a3f62cb86
* 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
113 lines
3.9 KiB
Markdown
113 lines
3.9 KiB
Markdown
---
|
|
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)
|