카메라 캡처 (에이전트)

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: boolean (기본값 true)
  - format: 현재 mp4
  - deviceId: 문자열 (선택사항; camera.list에서 제공)
- 응답 페이로드:
  - format: "mp4"
  - base64: "<...>"
  - durationMs
  - hasAudio

포그라운드 요구사항

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

CLI 헬퍼 (임시 파일 + MEDIA)

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

예시:

openclaw nodes camera snap --node <id>               # 기본값: 전면 + 후면 모두 (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은 에이전트에게 양쪽 뷰를 제공하기 위해 기본적으로 양쪽 방향을 캡처합니다.
출력 파일은 임시 파일(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)
- 기본값: 비활성화
- 비활성화 시: 카메라 요청은 “Camera disabled by user”를 반환합니다.

CLI 헬퍼 (node invoke)

메인 openclaw CLI를 사용하여 macOS 노드에서 카메라 명령어를 실행합니다.

예시:

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에 사용 설명 문자열 필요).
동영상 클립은 노드 페이로드 초과(base64 오버헤드 + 메시지 제한)를 방지하기 위해 현재 <= 60초로 제한됩니다.

macOS 화면 녹화 (OS 수준)

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

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

참고:

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