openclaw-openclaw/docs/nodes/troubleshooting.md at sqlite/sessions-transcripts-storage-flip

mirror of https://github.com/openclaw/openclaw.git synced 2026-07-08 18:34:19 +08:00

Files

Peter Steinberger f7d7148cf0 docs: rewrite published docs grounded in current source (#100142 )

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

2026-07-05 00:32:47 -04:00

6.5 KiB

Raw Permalink Blame History

summary, read_when, title

summary

read_when

title

Troubleshoot node pairing, foreground requirements, permissions, and tool failures

Node is connected but camera/canvas/screen/exec tools fail

You need the node pairing versus approvals mental model

Node troubleshooting

Use this page when a node is visible in status but node tools fail.

Command ladder

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Then run node-specific checks:

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:

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:

Device pairing: can this node connect to the gateway?
Gateway node command policy: is the RPC command ID allowed by gateway.nodes.allowCommands / denyCommands and platform defaults?
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:

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

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.

6.5 KiB Raw Permalink Blame History