Camera capture (agent)

OpenClaw hỗ trợ camera capture cho các workflow của Agent:

  • iOS node (kết nối qua Gateway): chụp ảnh (jpg) hoặc video clip ngắn (mp4, có thể bật/tắt audio) qua node.invoke.
  • Android node (kết nối qua Gateway): chụp ảnh (jpg) hoặc video clip ngắn (mp4, có thể bật/tắt audio) qua node.invoke.
  • macOS app (node qua Gateway): chụp ảnh (jpg) hoặc video clip ngắn (mp4, có thể bật/tắt audio) qua node.invoke.

Tất cả quyền truy cập camera đều được kiểm soát bởi cài đặt do người dùng quản lý.

iOS node

Cài đặt người dùng (mặc định bật)

  • iOS Settings tab → Camera → Allow Camera (camera.enabled)
    • Mặc định: bật (nếu thiếu key thì được coi là đã bật).
    • Khi tắt: các lệnh camera.* sẽ trả về CAMERA_DISABLED.

Lệnh (qua Gateway node.invoke)

  • camera.list

    • Response payload:
      • devices: mảng các { id, name, position, deviceType }

  • camera.snap

    • Params:
      • facing: front|back (mặc định: front)
      • maxWidth: number (tùy chọn; mặc định 1600 trên iOS node)
      • quality: 0..1 (tùy chọn; mặc định 0.9)
      • format: hiện tại là jpg
      • delayMs: number (tùy chọn; mặc định 0)
      • deviceId: string (tùy chọn; lấy từ camera.list)
    • Response payload:
      • format: "jpg"
      • base64: "<...>"
      • width, height
    • Payload guard: ảnh sẽ được nén lại để giữ payload base64 dưới 5 MB.

  • camera.clip

    • Params:
      • facing: front|back (mặc định: front)
      • durationMs: number (mặc định 3000, tối đa 60000)
      • includeAudio: boolean (mặc định true)
      • format: hiện tại là mp4
      • deviceId: string (tùy chọn; lấy từ camera.list)
    • Response payload:
      • format: "mp4"
      • base64: "<...>"
      • durationMs
      • hasAudio

Yêu cầu chạy foreground

Giống như canvas.*, iOS node chỉ cho phép các lệnh camera.* khi app đang chạy ở foreground. Nếu gọi khi ở background sẽ trả về NODE_BACKGROUND_UNAVAILABLE.

CLI helper (temp files + MEDIA)

Cách dễ nhất để lấy file đính kèm là dùng CLI helper, nó sẽ giải mã media ra file tạm và in ra MEDIA:<path>.

Ví dụ:

openclaw nodes camera snap --node <id>               # mặc định: cả front + back (2 dòng MEDIA)
openclaw nodes camera snap --node <id> --facing front
openclaw nodes camera clip --node <id> --duration 3000
openclaw nodes camera clip --node <id> --no-audio

Lưu ý:

  • nodes camera snap mặc định chụp cả hai camera (front và back) để Agent có cả hai góc nhìn.
  • File output là file tạm (trong thư mục temp của hệ điều hành) trừ khi các bạn tự build wrapper riêng.

Android node

Cài đặt người dùng (mặc định bật)

  • Android Settings sheet → Camera → Allow Camera (camera.enabled)
    • Mặc định: bật (nếu thiếu key thì được coi là đã bật).
    • Khi tắt: các lệnh camera.* sẽ trả về CAMERA_DISABLED.

Quyền truy cập (Permissions)

  • Android yêu cầu runtime permissions:
    • CAMERA cho cả camera.snap và camera.clip.
    • RECORD_AUDIO cho camera.clip khi includeAudio=true.

Nếu thiếu quyền, app sẽ hiện prompt yêu cầu khi có thể; nếu bị từ chối, các request camera.* sẽ fail với lỗi *_PERMISSION_REQUIRED.

Yêu cầu chạy foreground

Giống như canvas.*, Android node chỉ cho phép các lệnh camera.* khi app đang chạy ở foreground. Nếu gọi khi ở background sẽ trả về NODE_BACKGROUND_UNAVAILABLE.

Payload guard

Ảnh sẽ được nén lại để giữ payload base64 dưới 5 MB.

macOS app

Cài đặt người dùng (mặc định tắt)

macOS companion app có checkbox:

  • Settings → General → Allow Camera (openclaw.cameraEnabled)
    • Mặc định: tắt
    • Khi tắt: các request camera sẽ trả về “Camera disabled by user”.

CLI helper (node invoke)

Dùng openclaw CLI chính để gọi các lệnh camera trên macOS node.

Ví dụ:

openclaw nodes camera list --node <id>            # liệt kê camera ids
openclaw nodes camera snap --node <id>            # in ra MEDIA:<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          # in ra MEDIA:<path>
openclaw nodes camera clip --node <id> --duration-ms 3000      # in ra MEDIA:<path> (legacy flag)
openclaw nodes camera clip --node <id> --device-id <id>
openclaw nodes camera clip --node <id> --no-audio

Lưu ý:

  • openclaw nodes camera snap mặc định maxWidth=1600 trừ khi các bạn ghi đè.
  • Trên macOS, camera.snap sẽ đợi delayMs (mặc định 2000ms) sau khi warm-up/exposure settle trước khi chụp.
  • Photo payloads được nén lại để giữ base64 dưới 5 MB.

An toàn + giới hạn thực tế

  • Quyền truy cập camera và microphone sẽ kích hoạt các prompt xin quyền thông thường của hệ điều hành (và yêu cầu usage strings trong Info.plist).
  • Video clips bị giới hạn (hiện tại <= 60s) để tránh node payloads quá lớn (base64 overhead + message limits).

macOS screen video (OS-level)

Để quay video màn hình (không phải camera), dùng macOS companion:

openclaw nodes screen record --node <id> --duration 10s --fps 15   # in ra MEDIA:<path>

Lưu ý:

  • Yêu cầu quyền macOS Screen Recording (TCC).