--- summary: "Camera capture (iOS/Android nodes + macOS app) for agent use: photos (jpg) and short video clips (mp4)" read_when: - Adding or modifying camera capture on iOS/Android nodes or macOS - Extending agent-accessible MEDIA temp-file workflows title: "Camera capture" --- OpenClaw supports camera capture for agent workflows on paired **iOS**, **Android**, and **macOS** nodes: capture a photo (`jpg`) or a short video clip (`mp4`, with optional audio) via Gateway `node.invoke`. All camera access is gated behind a user-controlled setting per platform. ## iOS node ### iOS user setting - iOS Settings tab → **Camera** → **Allow Camera** (`camera.enabled`). - Default: **on** (missing key is treated as enabled). - When off: `camera.*` commands return `CAMERA_DISABLED`. ### iOS commands (via Gateway `node.invoke`) - `camera.list` - Response payload: `devices` — array of `{ id, name, position, deviceType }`. - `camera.snap` - Params: - `facing`: `front|back` (default: `front`) - `maxWidth`: number (optional; default `1600`) - `quality`: `0..1` (optional; default `0.9`, clamped to `[0.05, 1.0]`) - `format`: currently `jpg` - `delayMs`: number (optional; default `0`, internally capped at `10000`) - `deviceId`: string (optional; from `camera.list`) - Response payload: `format: "jpg"`, `base64`, `width`, `height`. - Payload guard: photos are recompressed to keep the base64-encoded payload under 5MB. - `camera.clip` - Params: - `facing`: `front|back` (default: `front`) - `durationMs`: number (default `3000`, clamped to `[250, 60000]`) - `includeAudio`: boolean (default `true`) - `format`: currently `mp4` - `deviceId`: string (optional; from `camera.list`) - Response payload: `format: "mp4"`, `base64`, `durationMs`, `hasAudio`. ### iOS foreground requirement Like `canvas.*`, the iOS node only allows `camera.*` commands in the **foreground**. Background invocations return `NODE_BACKGROUND_UNAVAILABLE`. ### CLI helper The easiest way to get media files is via the CLI helper, which writes decoded media to a temp file and prints the saved path. ```bash openclaw nodes camera snap --node # default: both front + back (2 MEDIA lines) openclaw nodes camera snap --node --facing front openclaw nodes camera clip --node --duration 3000 openclaw nodes camera clip --node --no-audio ``` `nodes camera snap` defaults to `--facing both`, capturing both front and back to give the agent both views; pass `--device-id` with a single explicit facing (`both` is rejected when `--device-id` is set). Output files are temporary (in the OS temp directory) unless you build your own wrapper. ## Android node ### Android user setting - Android Settings sheet → **Camera** → **Allow Camera** (`camera.enabled`). - **Fresh installs default to off.** Existing installs that predate this setting are migrated to **on** so upgrades do not silently lose previously working camera access. - When off: `camera.*` commands return `CAMERA_DISABLED: enable Camera in Settings`. ### Permissions - `CAMERA` is required for both `camera.snap` and `camera.clip`; missing/denied permission returns `CAMERA_PERMISSION_REQUIRED`. - `RECORD_AUDIO` is required for `camera.clip` when `includeAudio` is `true`; missing/denied permission returns `MIC_PERMISSION_REQUIRED`. The app prompts for runtime permissions when possible. ### Android foreground requirement Like `canvas.*`, the Android node only allows `camera.*` commands in the **foreground**. Background invocations return `NODE_BACKGROUND_UNAVAILABLE: command requires foreground`. ### Android commands (via Gateway `node.invoke`) - `camera.list` - Response payload: `devices` — array of `{ id, name, position, deviceType }`. - `camera.snap` - Params: `facing` (`front|back`, default `front`), `quality` (default `0.95`, clamped to `[0.1, 1.0]`), `maxWidth` (default `1600`), `deviceId` (optional; unknown id fails with `INVALID_REQUEST`). - Response payload: `format: "jpg"`, `base64`, `width`, `height`. - Payload guard: recompressed to keep base64 under 5MB (same budget as iOS). - `camera.clip` - Params: `facing` (default `front`), `durationMs` (default `3000`, clamped to `[200, 60000]`), `includeAudio` (default `true`), `deviceId` (optional). - Response payload: `format: "mp4"`, `base64`, `durationMs`, `hasAudio`. - Payload guard: raw MP4 is capped at 18MB before base64 encoding; oversize clips fail with `PAYLOAD_TOO_LARGE` (reduce `durationMs` and retry). ## macOS app ### macOS user setting The macOS companion app exposes a checkbox: - **Settings → General → Allow Camera** (`openclaw.cameraEnabled`). - Default: **off**. - When off: camera requests return `CAMERA_DISABLED: enable Camera in Settings`. ### CLI helper (node invoke) Use the main `openclaw` CLI to invoke camera commands on the macOS node. ```bash openclaw nodes camera list --node # list camera ids openclaw nodes camera snap --node # prints saved path openclaw nodes camera snap --node --max-width 1280 openclaw nodes camera snap --node --delay-ms 2000 openclaw nodes camera snap --node --device-id openclaw nodes camera clip --node --duration 10s # prints saved path openclaw nodes camera clip --node --duration-ms 3000 # prints saved path (legacy flag) openclaw nodes camera clip --node --device-id openclaw nodes camera clip --node --no-audio ``` - `openclaw nodes camera snap` defaults to `maxWidth=1600` unless overridden. - `camera.snap` waits `delayMs` (default 2000ms, clamped to `[0, 10000]`) after warm-up/exposure settle before capturing. - Photo payloads are recompressed to keep base64 under 5MB. ## Safety + practical limits - Camera and microphone access trigger the usual OS permission prompts (and require usage strings in `Info.plist`). - Video clips are capped at 60s to avoid oversized node payloads (base64 overhead plus message limits). ## macOS screen video (OS-level) For _screen_ video (not camera), use the macOS companion: ```bash openclaw nodes screen record --node --duration 10s --fps 15 # prints saved path ``` Requires macOS **Screen Recording** permission (TCC). ## Related - [Image and media support](/nodes/images) - [Media understanding](/nodes/media-understanding) - [Location command](/nodes/location-command)