mirror of
https://github.com/openclaw/openclaw.git
synced 2026-08-05 07:01:37 +00:00
edecdbd05e
* refactor(config): consolidate media model lists * refactor(config): unify memory configuration * refactor(config): consolidate TTS ownership * refactor(config): move typing policy to agents * refactor(config): retire product-level config surfaces * refactor(config): share scoped tool policy type * chore(config): refresh generated baselines * fix(config): honor agent typing overrides * fix(config): migrate sibling config consumers * refactor(infra): keep base64url decoder private * fix(config): strip invalid legacy TTS values * chore(config): refresh rebased baseline hash * fix(doctor): route legacy messages.tts.realtime voice to talk during tts move * refactor(config): polish final layout names * refactor(config): freeze retired tuning defaults * feat(config): add fast mode default symmetry * refactor(config): key agent entries by id * docs(config): update final layout reference * test(config): cover final layout migrations * chore(config): refresh final layout baselines * fix(config): align final layout runtime readers * fix(config): align remaining readers * fix(config): stabilize final layout migrations * fix(config): finalize config projection proof * fix(config): address final layout review * docs(release): preserve historical config names * fix(config): complete keyed agent migration * fix(config): close final migration gaps * fix(config): finish full-branch review * fix(config): complete runtime secret detection * fix(config): close final review findings * fix(config): finish canonical docs and heartbeat migration * fix(config): integrate latest main after rebase * refactor(env): isolate test-only controls * refactor(env): isolate build and development controls * refactor(env): collapse process identity indirection * refactor(env): remove duplicate config and temp aliases * docs(env): define the operator-facing allowlist * ci(env): ratchet production variable count * fix(env): remove stale provider helper import * fix(env): make ratchet sorting explicit * test(env): keep test seam in dead-code audit * test(env): cover ratchet growth and boundary; document surface budgets * docs(config): document tier-eval consolidations * docs(config): clarify speech preference ownership * test(memory): align retired tuning fixtures * refactor(memory): freeze engine heuristics * refactor(config): apply tier-eval tranche * refactor(tts): move persona shaping to providers * refactor(compaction): move prompt policy to providers * test(config): align hookified prompt fixtures * chore(deadcode): classify test-only exports * chore(github): remove unused spawn helper * chore(deadcode): classify queue diagnostics * chore(deadcode): remove unused lane snapshot export * chore(plugin-sdk): ratchet consolidated surface * fix(config): integrate latest main after rebase
127 lines
7.6 KiB
Markdown
127 lines
7.6 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` |
|
|
| `computer.act` | n/a | n/a | Accessibility + Screen Recording | `COMPUTER_DISABLED`, `ACCESSIBILITY_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.commands.allow` / `gateway.nodes.commands.deny` 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. |
|
|
| `COMPUTER_DISABLED` | Enable **Allow Computer Control** in the macOS app, then approve the pairing update. |
|
|
| `ACCESSIBILITY_REQUIRED` | Grant Accessibility to the current OpenClaw app bundle in macOS System Settings. |
|
|
| `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.
|
|
|
|
For computer control, also verify that a vision-capable agent exposes the `computer` tool, `screen.snapshot` succeeds with Screen Recording permission, and `/phone status` shows the temporary or persistent gateway authorization you intended. A `gateway.nodes.commands.deny` entry always overrides `gateway.nodes.commands.allow`.
|
|
|
|
## Related
|
|
|
|
- [Nodes overview](/nodes)
|
|
- [Camera nodes](/nodes/camera)
|
|
- [Location command](/nodes/location-command)
|
|
- [Computer use](/nodes/computer-use)
|
|
- [Exec approvals](/tools/exec-approvals)
|
|
- [Gateway pairing](/gateway/pairing)
|
|
- [Gateway troubleshooting](/gateway/troubleshooting)
|
|
- [Channel troubleshooting](/channels/troubleshooting)
|