카메라 캡처

OpenClaw은 페어링된 iOS, Android, macOS Node의 에이전트 워크플로에서 카메라 캡처를 지원합니다. Gateway node.invoke를 통해 사진(jpg)이나 짧은 동영상 클립(mp4, 선택적 오디오 포함)을 캡처할 수 있습니다.

모든 카메라 접근은 플랫폼별로 사용자가 제어하는 설정에 의해 제한됩니다.

iOS Node

iOS 사용자 설정

• iOS Settings 탭 → Camera → Allow Camera (camera.enabled).
  • 기본값: 켜짐(키가 없으면 활성화된 것으로 간주).
  • 꺼져 있는 경우: camera.* 명령은 CAMERA_DISABLED를 반환합니다.

iOS 명령(Gateway node.invoke 사용)

• camera.list

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

• camera.snap

  • 매개변수:
    • facing: front|back(기본값: front)
    • maxWidth: 숫자(선택 사항, 기본값 1600)
    • quality: 0..1(선택 사항, 기본값 0.9, [0.05, 1.0] 범위로 제한)
    • format: 현재 jpg
    • delayMs: 숫자(선택 사항, 기본값 0, 내부적으로 최대 10000으로 제한)
    • deviceId: 문자열(선택 사항, camera.list에서 가져옴)
  • 응답 페이로드: format: "jpg", base64, width, height.
  • 페이로드 제한: base64 인코딩된 페이로드를 5MB 미만으로 유지하도록 사진을 재압축합니다.

• camera.clip

  • 매개변수:
    • facing: front|back(기본값: front)
    • durationMs: 숫자(기본값 3000, [250, 60000] 범위로 제한)
    • includeAudio: 불리언(기본값 true)
    • format: 현재 mp4
    • deviceId: 문자열(선택 사항, camera.list에서 가져옴)
  • 응답 페이로드: format: "mp4", base64, durationMs, hasAudio.

iOS 포그라운드 요구 사항

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

CLI 도우미

미디어 파일을 가져오는 가장 쉬운 방법은 CLI 도우미를 사용하는 것입니다. 이 도우미는 디코딩한 미디어를 임시 파일에 쓰고 저장된 경로를 출력합니다.

openclaw nodes camera snap --node <id>                 # 기본값: 전면 + 후면 모두(MEDIA 줄 2개)openclaw nodes camera snap --node <id> --facing frontopenclaw nodes camera clip --node <id> --duration 3000openclaw nodes camera clip --node <id> --no-audio

nodes camera snap의 기본값은 --facing both이며, 에이전트에 양쪽 시야를 제공하기 위해 전면과 후면을 모두 캡처합니다. 단일 방향을 명시하여 --device-id를 전달하세요(--device-id가 설정된 경우 both는 거부됨). 자체 래퍼를 만들지 않는 한 출력 파일은 임시 파일(OS 임시 디렉터리 내)입니다.

Android Node

Android 사용자 설정

• Android Settings 시트 → Camera → Allow Camera (camera.enabled).
  • 새로 설치할 경우 기본값은 꺼짐입니다. 이 설정이 도입되기 전에 설치된 기존 앱은 켜짐으로 마이그레이션되므로, 업그레이드 시 이전에 작동하던 카메라 접근 권한이 예고 없이 사라지지 않습니다.
  • 꺼져 있는 경우: camera.* 명령은 CAMERA_DISABLED: enable Camera in Settings를 반환합니다.

권한

• camera.snap과 camera.clip 모두 CAMERA 권한이 필요합니다. 권한이 없거나 거부된 경우 CAMERA_PERMISSION_REQUIRED를 반환합니다.
• includeAudio가 true인 camera.clip에는 RECORD_AUDIO 권한이 필요합니다. 권한이 없거나 거부된 경우 MIC_PERMISSION_REQUIRED를 반환합니다.

가능한 경우 앱에서 런타임 권한을 요청합니다.

Android 포그라운드 요구 사항

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

Android 명령(Gateway node.invoke 사용)

• camera.list

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

• camera.snap

  • 매개변수: facing(front|back, 기본값 front), quality(기본값 0.95, [0.1, 1.0] 범위로 제한), maxWidth(기본값 1600), deviceId(선택 사항, 알 수 없는 ID는 INVALID_REQUEST로 실패).
  • 응답 페이로드: format: "jpg", base64, width, height.
  • 페이로드 제한: base64를 5MB 미만으로 유지하도록 재압축합니다(iOS와 동일한 제한).

• camera.clip

  • 매개변수: facing(기본값 front), durationMs(기본값 3000, [200, 60000] 범위로 제한), includeAudio(기본값 true), deviceId(선택 사항).
  • 응답 페이로드: format: "mp4", base64, durationMs, hasAudio.
  • 페이로드 제한: base64 인코딩 전에 원본 MP4가 18MB로 제한됩니다. 크기를 초과하는 클립은 PAYLOAD_TOO_LARGE로 실패합니다(durationMs를 줄이고 다시 시도).

macOS 앱

macOS 사용자 설정

macOS 컴패니언 앱에는 다음 체크박스가 있습니다.

• Settings → General → Allow Camera (openclaw.cameraEnabled).
  • 기본값: 꺼짐.
  • 꺼져 있는 경우: 카메라 요청은 CAMERA_DISABLED: enable Camera in Settings를 반환합니다.

CLI 도우미(Node 호출)

기본 openclaw CLI를 사용하여 macOS Node에서 카메라 명령을 호출합니다.

openclaw nodes camera list --node <id>                     # 카메라 ID 나열openclaw nodes camera snap --node <id>                     # 저장된 경로 출력openclaw nodes camera snap --node <id> --max-width 1280openclaw nodes camera snap --node <id> --delay-ms 2000openclaw nodes camera snap --node <id> --device-id <id>openclaw nodes camera clip --node <id> --duration 10s       # 저장된 경로 출력openclaw nodes camera clip --node <id> --duration-ms 3000   # 저장된 경로 출력(레거시 플래그)openclaw nodes camera clip --node <id> --device-id <id>openclaw nodes camera clip --node <id> --no-audio

• openclaw nodes camera snap은 재정의하지 않는 한 기본적으로 maxWidth=1600을 사용합니다.
• camera.snap은 워밍업/노출 안정화 후 캡처하기 전에 delayMs(기본값 2000ms, [0, 10000] 범위로 제한) 동안 대기합니다.
• 사진 페이로드는 base64를 5MB 미만으로 유지하도록 재압축됩니다.

안전 및 실제 제한 사항

• 카메라와 마이크 접근 시 일반적인 OS 권한 요청 메시지가 표시되며, Info.plist에 사용 목적 문자열이 필요합니다.
• 과도하게 큰 Node 페이로드(base64 오버헤드 및 메시지 제한)를 방지하기 위해 동영상 클립은 최대 60초로 제한됩니다.

macOS 화면 동영상(OS 수준)

카메라가 아닌 화면 동영상에는 macOS 컴패니언을 사용하세요.

openclaw nodes screen record --node <id> --duration 10s --fps 15   # 저장된 경로 출력

macOS Screen Recording 권한(TCC)이 필요합니다.

관련 문서

• 이미지 및 미디어 지원
• 미디어 이해
• 위치 명령