mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-19 04:41:44 +00:00
f7d7148cf0
Source-grounded rewrite of 529 published docs pages with per-unit information-loss verification: 1,713 factual corrections cited to src/**, generated surfaces regenerated, frontmatter titles preserved for i18n, release notes pages untouched. All docs gates green. Closes #100141
121 lines
6.5 KiB
Markdown
121 lines
6.5 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"
|
|
---
|
|
|
|
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're calling.
|
|
- Exec approvals show the 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
|
|
|
|
Three separate gates control whether a node command succeeds:
|
|
|
|
1. **Device pairing**: can this node connect to the gateway?
|
|
2. **Gateway node command policy**: is the RPC command ID allowed by `gateway.nodes.allowCommands` / `denyCommands` and platform defaults?
|
|
3. **Exec approvals**: can this node run a specific shell command locally?
|
|
|
|
Node pairing is an identity/trust gate, not a per-command approval surface. For `system.run`, the per-node policy lives in that node's exec approvals file (`openclaw approvals get --node ...`), not in the gateway pairing record.
|
|
|
|
Quick checks:
|
|
|
|
```bash
|
|
openclaw devices list
|
|
openclaw nodes status
|
|
openclaw approvals get --node <idOrNameOrIp>
|
|
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"
|
|
```
|
|
|
|
- Pairing missing: approve the node device first.
|
|
- `nodes describe` missing a command: check the gateway node command policy and whether the node actually declared that command on connect.
|
|
- Pairing fine but `system.run` fails: fix exec approvals/allowlist on that node.
|
|
|
|
For approval-backed `host=node` runs, the gateway also binds execution to the prepared canonical `systemRunPlan`. If a later caller mutates the command, cwd, or session metadata before the approved run is forwarded, the gateway rejects the run as an approval mismatch instead of trusting the edited payload.
|
|
|
|
## Common node error codes
|
|
|
|
| Code | Meaning |
|
|
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `NODE_BACKGROUND_UNAVAILABLE` | App is backgrounded; bring it to the 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. On Windows node hosts, shell-wrapper forms like `cmd.exe /c ...` are treated as allowlist misses in allowlist mode unless approved via the ask flow. |
|
|
|
|
## 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 the node app (foreground).
|
|
- Re-grant OS permissions.
|
|
- Recreate/adjust the exec approval policy.
|
|
|
|
## Related
|
|
|
|
- [Nodes overview](/nodes)
|
|
- [Camera nodes](/nodes/camera)
|
|
- [Location command](/nodes/location-command)
|
|
- [Exec approvals](/tools/exec-approvals)
|
|
- [Gateway pairing](/gateway/pairing)
|
|
- [Gateway troubleshooting](/gateway/troubleshooting)
|
|
- [Channel troubleshooting](/channels/troubleshooting)
|