Camera capture (agent)

OpenClaw는 agent 워크플로를 위한 카메라 캡처를 지원합니다:

  • iOS node (Gateway를 통해 페어링됨): node.invoke를 통해 사진 (jpg) 또는 짧은 비디오 클립 (mp4, 오디오 옵션 포함) 캡처
  • Android node (Gateway를 통해 페어링됨): node.invoke를 통해 사진 (jpg) 또는 짧은 비디오 클립 (mp4, 오디오 옵션 포함) 캡처
  • macOS 앱 (Gateway를 통한 node): node.invoke를 통해 사진 (jpg) 또는 짧은 비디오 클립 (mp4, 오디오 옵션 포함) 캡처

모든 카메라 액세스는 사용자 제어 설정으로 제한됩니다.

iOS node

사용자 설정 (기본값 on)

  • iOS Settings 탭 → Camera → Allow Camera (camera.enabled)
    • 기본값: on (키가 없으면 활성화된 것으로 처리)
    • 비활성화 시: camera.* 명령은 CAMERA_DISABLED를 반환합니다.

명령 (Gateway node.invoke를 통해)

  • camera.list

    • 응답 페이로드:
      • devices: { id, name, position, deviceType } 배열

  • camera.snap

    • 매개변수:
      • facing: front|back (기본값: front)
      • maxWidth: number (선택 사항; iOS node에서 기본값 1600)
      • quality: 0..1 (선택 사항; 기본값 0.9)
      • format: 현재 jpg
      • delayMs: number (선택 사항; 기본값 0)
      • deviceId: string (선택 사항; camera.list에서 가져옴)
    • 응답 페이로드:
      • format: "jpg"
      • base64: "<...>"
      • width, height
    • 페이로드 보호: 사진은 base64 페이로드를 5MB 미만으로 유지하도록 재압축됩니다.

  • camera.clip

    • 매개변수:
      • facing: front|back (기본값: front)
      • durationMs: number (기본값 3000, 최대 60000로 제한)
      • includeAudio: boolean (기본값 true)
      • format: 현재 mp4
      • deviceId: string (선택 사항; camera.list에서 가져옴)
    • 응답 페이로드:
      • format: "mp4"
      • base64: "<...>"
      • durationMs
      • hasAudio

포그라운드 요구 사항

canvas.*와 마찬가지로 iOS node는 포그라운드에서만 camera.* 명령을 허용합니다. 백그라운드 호출은 NODE_BACKGROUND_UNAVAILABLE을 반환합니다.

CLI 도우미 (임시 파일 + MEDIA)

첨부 파일을 가져오는 가장 쉬운 방법은 디코딩된 미디어를 임시 파일에 쓰고 MEDIA:<path>를 출력하는 CLI 도우미를 사용하는 것입니다.

예시:

openclaw nodes camera snap --node <id>               # 기본값: front + back 모두 (2개의 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

참고:

  • nodes camera snap은 agent에게 두 뷰를 모두 제공하기 위해 기본적으로 양쪽 facing을 사용합니다.
  • 자체 래퍼를 구축하지 않는 한 출력 파일은 임시 파일입니다(OS 임시 디렉토리).

Android node

사용자 설정 (기본값 on)

  • Android Settings 시트 → Camera → Allow Camera (camera.enabled)
    • 기본값: on (키가 없으면 활성화된 것으로 처리)
    • 비활성화 시: camera.* 명령은 CAMERA_DISABLED를 반환합니다.

권한

  • Android는 런타임 권한이 필요합니다:
    • camera.snap 및 camera.clip 모두에 CAMERA
    • includeAudio=true일 때 camera.clip에 RECORD_AUDIO

권한이 없으면 앱이 가능한 경우 프롬프트를 표시합니다; 거부되면 camera.* 요청은 *_PERMISSION_REQUIRED 오류와 함께 실패합니다.

포그라운드 요구 사항

canvas.*와 마찬가지로 Android node는 포그라운드에서만 camera.* 명령을 허용합니다. 백그라운드 호출은 NODE_BACKGROUND_UNAVAILABLE을 반환합니다.

페이로드 보호

사진은 base64 페이로드를 5MB 미만으로 유지하도록 재압축됩니다.

macOS 앱

사용자 설정 (기본값 off)

macOS 컴패니언 앱은 체크박스를 제공합니다:

  • Settings → General → Allow Camera (openclaw.cameraEnabled)
    • 기본값: off
    • 비활성화 시: 카메라 요청은 "Camera disabled by user"를 반환합니다.

CLI 도우미 (node invoke)

macOS node에서 카메라 명령을 호출하려면 메인 openclaw CLI를 사용하세요.

예시:

openclaw nodes camera list --node <id>            # 카메라 ID 목록 표시
openclaw nodes camera snap --node <id>            # 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          # MEDIA:<path> 출력
openclaw nodes camera clip --node <id> --duration-ms 3000      # MEDIA:<path> 출력 (레거시 플래그)
openclaw nodes camera clip --node <id> --device-id <id>
openclaw nodes camera clip --node <id> --no-audio

참고:

  • openclaw nodes camera snap은 재정의하지 않는 한 기본적으로 maxWidth=1600입니다.
  • macOS에서 camera.snap은 캡처하기 전에 웜업/노출 안정화 후 delayMs(기본값 2000ms)를 기다립니다.
  • 사진 페이로드는 base64를 5MB 미만으로 유지하도록 재압축됩니다.

안전 + 실질적 제한

  • 카메라 및 마이크 액세스는 일반적인 OS 권한 프롬프트를 트리거합니다(Info.plist에 사용 문자열 필요).
  • 비디오 클립은 초대형 node 페이로드(base64 오버헤드 + 메시지 제한)를 방지하기 위해 제한됩니다(현재 <= 60s).

macOS 화면 비디오 (OS 수준)

카메라가 아닌 화면 비디오의 경우 macOS 컴패니언을 사용하세요:

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

참고:

  • macOS Screen Recording 권한(TCC) 필요.
← 문서로 돌아가기