카메라 캡처

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

• iOS 노드(Gateway를 통해 페어링됨): node.invoke를 통해 사진(jpg) 또는 짧은 비디오 클립(mp4, 선택적 오디오 포함)을 캡처합니다.
• Android 노드(Gateway를 통해 페어링됨): node.invoke를 통해 사진(jpg) 또는 짧은 비디오 클립(mp4, 선택적 오디오 포함)을 캡처합니다.
• macOS 앱(Gateway를 통한 노드): node.invoke를 통해 사진(jpg) 또는 짧은 비디오 클립(mp4, 선택적 오디오 포함)을 캡처합니다.

모든 카메라 접근은 사용자가 제어하는 설정 뒤에서 제한됩니다.

iOS 노드

사용자 설정(기본값 켜짐)

• iOS 설정 탭 → 카메라 → 카메라 허용(camera.enabled)
  • 기본값: 켜짐(키가 없으면 활성화된 것으로 처리됨).
  • 꺼져 있을 때: camera.* 명령은 CAMERA_DISABLED를 반환합니다.

명령(Gateway node.invoke를 통해)

• camera.list

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

• camera.snap

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

• camera.clip

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

포그라운드 요구 사항

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

CLI 헬퍼

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

예:

openclaw nodes camera snap --node <id>               # default: both front + back (2 MEDIA lines)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은 에이전트에 두 시야를 모두 제공하기 위해 기본적으로 양쪽 방향을 사용합니다.
• 자체 래퍼를 만들지 않는 한 출력 파일은 임시 파일입니다(OS 임시 디렉터리 안).

Android 노드

Android 사용자 설정(기본값 켜짐)

• Android 설정 시트 → 카메라 → 카메라 허용(camera.enabled)
  • 기본값: 켜짐(키가 없으면 활성화된 것으로 처리됨).
  • 꺼져 있을 때: camera.* 명령은 CAMERA_DISABLED를 반환합니다.

권한

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

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

Android 포그라운드 요구 사항

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

Android 명령(Gateway node.invoke를 통해)

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

페이로드 보호

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

macOS 앱

사용자 설정(기본값 꺼짐)

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

• 설정 → 일반 → 카메라 허용(openclaw.cameraEnabled)
  • 기본값: 꺼짐
  • 꺼져 있을 때: 카메라 요청은 "사용자가 카메라를 비활성화했습니다"를 반환합니다.

CLI 헬퍼(노드 호출)

macOS 노드에서 카메라 명령을 호출하려면 기본 openclaw CLI를 사용하세요.

예:

openclaw nodes camera list --node <id>            # list camera idsopenclaw nodes camera snap --node <id>            # prints saved pathopenclaw 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          # prints saved pathopenclaw 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은 재정의하지 않는 한 기본값으로 maxWidth=1600을 사용합니다.
• macOS에서 camera.snap은 준비/노출 안정화 후 캡처하기 전에 delayMs(기본값 2000ms)만큼 기다립니다.
• 사진 페이로드는 base64가 5MB 미만으로 유지되도록 재압축됩니다.

안전 + 실제 제한

• 카메라와 마이크 접근은 일반적인 OS 권한 프롬프트를 트리거합니다(그리고 Info.plist의 사용 설명 문자열이 필요합니다).
• 비디오 클립은 지나치게 큰 노드 페이로드(base64 오버헤드 + 메시지 제한)를 피하기 위해 제한됩니다(현재 <= 60s).

macOS 화면 비디오(OS 수준)

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

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

참고:

• macOS 화면 기록 권한(TCC)이 필요합니다.

관련 항목

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