OpenClaw 에이전트를 위한 카메라 캡처 가이드

에이전트가 텍스트만 처리하는 것이 아니라, 실제 세상을 직접 보고 판단해야 할 때가 있죠. 하지만 매번 수동으로 사진을 찍어서 업로드하거나 복잡한 API를 연동하는 작업은 개발 흐름을 끊기게 만들고 구현하기도 까다롭습니다.

OpenClaw를 사용하면 Gateway에 연결된 기기의 카메라를 에이전트가 직접 제어할 수 있어요. 사진 촬영부터 짧은 영상 캡처까지, CLI와 API를 통해 간단하게 구현하는 방법을 소개할게요.

필요한 것

시작하기 전에 다음 항목들이 준비되었는지 확인해 주세요.

• Gateway와 페어링된 iOS node, Android node 또는 macOS app
• node.invoke 권한 및 OpenClaw CLI

빠른 시작

가장 빠르게 카메라를 테스트하는 방법은 CLI helper를 사용하는 거예요. 아래 명령어를 터미널에 입력하면 즉시 사진이나 영상을 캡처할 수 있습니다.

# 특정 노드에서 사진 촬영 (기본적으로 전면/후면 모두 촬영)
openclaw nodes camera snap --node \<id\>

# 특정 노드에서 3초간 비디오 캡처
openclaw nodes camera clip --node \<id\> --duration 3000

# macOS 노드에서 화면 녹화 (10초, 15fps)
openclaw nodes screen record --node \<id\> --duration 10s --fps 15

캡처된 파일은 OS 임시 디렉토리에 저장되며, 터미널에 MEDIA:<경로> 형태로 출력됩니다.

iOS & Android Node 설정

모바일 노드에서 카메라를 사용하려면 몇 가지 규칙을 지켜야 해요.

권한 및 설정

• iOS: 설정 탭 → Camera → Allow Camera가 켜져 있어야 합니다. (기본값 ON)
• Android: 설정 시트 → Camera → Allow Camera가 켜져 있어야 하며, 실행 시점에 CAMERA 및 RECORD_AUDIO 권한 허용이 필요합니다. (기본값 ON)
• 설정이 꺼져 있으면 CAMERA_DISABLED 에러를 반환합니다.

주요 특징

• Foreground 필수: iOS와 Android 모두 앱이 포그라운드 상태일 때만 카메라 명령을 수행할 수 있습니다. 백그라운드 상태라면 NODE_BACKGROUND_UNAVAILABLE 에러가 발생해요.
• 자동 압축: base64 페이로드 크기를 5MB 이하로 유지하기 위해 사진은 자동으로 재압축됩니다.

macOS App 활용

macOS용 컴패니언 앱은 보안을 위해 기본 설정이 조금 다릅니다.

• 사용자 설정: Settings → General → Allow Camera 체크박스를 직접 켜야 합니다. (기본값 OFF)
• 지연 시간: macOS에서는 하드웨어 예열 및 노출 조절을 위해 촬영 전 delayMs(기본 2000ms)만큼 대기한 후 캡처를 진행합니다.

# 특정 카메라 ID 확인
openclaw nodes camera list --node \<id\>

# 특정 기기로 지연 시간을 설정하여 촬영
openclaw nodes camera snap --node \<id\> --delay-ms 2000 --device-id \<id\>

문제 해결

문제가 발생했다면 아래 케이스를 확인해 보세요.

• CAMERA_DISABLED: 앱 내 설정에서 카메라 허용이 꺼져 있습니다. 설정을 확인해 주세요.
• NODE_BACKGROUND_UNAVAILABLE: 모바일 기기의 화면이 꺼져 있거나 앱이 백그라운드에 있습니다. 앱을 화면에 띄워주세요.
• *_PERMISSION_REQUIRED: 안드로이드에서 시스템 권한 요청을 거절한 경우입니다. 앱 설정에서 권한을 수동으로 허용해야 합니다.
• 비디오 캡처 실패: 영상 클립은 최대 60초로 제한됩니다. durationMs 값이 범위를 초과하지 않았는지 확인하세요.

에이전트가 세상을 보는 눈을 갖게 되었나요? 더 궁금한 점이 있다면 AI Setup Assistant에게 물어보세요.

다음 단계

• Node.js Gateway API reference
• Managing Node Permissions