openclaw-openclaw/docs/nodes/camera.md

summary, read_when, title

summary	read_when	title
Camera capture (iOS/Android nodes + macOS app) for agent use: photos (jpg) and short video clips (mp4)	Adding or modifying camera capture on iOS/Android nodes or macOS Extending agent-accessible MEDIA temp-file workflows	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.

openclaw nodes camera snap --node <id>                 # default: both front + back (2 MEDIA lines)
openclaw nodes camera snap --node <id> --facing front
openclaw nodes camera clip --node <id> --duration 3000
openclaw nodes camera clip --node <id> --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.

openclaw nodes camera list --node <id>                     # list camera ids
openclaw nodes camera snap --node <id>                     # prints saved path
openclaw nodes camera snap --node <id> --max-width 1280
openclaw nodes camera snap --node <id> --delay-ms 2000
openclaw nodes camera snap --node <id> --device-id <id>
openclaw nodes camera clip --node <id> --duration 10s       # prints saved path
openclaw nodes camera clip --node <id> --duration-ms 3000   # prints saved path (legacy flag)
openclaw nodes camera clip --node <id> --device-id <id>
openclaw nodes camera clip --node <id> --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:

openclaw nodes screen record --node <id> --duration 10s --fps 15   # prints saved path

Requires macOS Screen Recording permission (TCC).

Related

• Image and media support
• Media understanding
• Location command