コマンドラダー
- node が接続済みで、role
nodeとして paired になっている nodes describeに、呼び出したい capability が含まれている- exec approvals が期待どおりの mode / allowlist になっている
foreground 要件
canvas.*、camera.*、screen.* は iOS / Android node では foreground 専用です。
簡易確認と対処:
NODE_BACKGROUND_UNAVAILABLE が出た場合は、node app を foreground に戻してから再試行してください。
権限マトリクス
| Capability | iOS | Android | macOS node app | Typical failure code |
|---|---|---|---|---|
camera.snap, camera.clip | Camera（clip 音声には mic も必要） | Camera（clip 音声には mic も必要） | Camera（clip 音声には mic も必要） | *_PERMISSION_REQUIRED |
screen.record | Screen Recording（+ mic は任意） | Screen capture prompt（+ mic は任意） | Screen Recording | *_PERMISSION_REQUIRED |
location.get | While Using または Always（mode に依存） | mode に応じた foreground / background location | Location permission | LOCATION_PERMISSION_REQUIRED |
system.run | n/a（node host 経路） | n/a（node host 経路） | Exec approvals が必要 | SYSTEM_RUN_DENIED |
pairing と approvals の違い
この 2 つは別の gate です。- Device pairing: この node が gateway へ接続できるか
- Exec approvals: この node が特定の shell command を実行できるか
system.run だけ失敗する場合は、exec approvals / allowlist を見直してください。
よくある node error code
NODE_BACKGROUND_UNAVAILABLE→ app が background。foreground に戻すCAMERA_DISABLED→ node settings で camera toggle が無効*_PERMISSION_REQUIRED→ OS 権限が未付与または拒否されているLOCATION_DISABLED→ location mode が offLOCATION_PERMISSION_REQUIRED→ 要求した location mode が許可されていないLOCATION_BACKGROUND_UNAVAILABLE→ app は background だが While Using 権限しかないSYSTEM_RUN_DENIED: approval required→ exec request に明示承認が必要SYSTEM_RUN_DENIED: allowlist miss→ command が allowlist mode によって拒否された Windows node host では、cmd.exe /c ...のような shell-wrapper 形式は、ask flow で承認しない限り allowlist mode では allowlist miss として扱われます。
すばやい復旧ループ
- device pairing を再承認する
- node app を開き直す（foreground にする）
- OS 権限を再付与する
- exec approval policy を作り直す / 調整する