OpenClaw Skill: 신뢰할 수 있는 화면 캡처를 위한 macOS Node Snapshot

Source: Dev.to

How It Works

mac-node-snapshot 스킬은 1초 길이의 영상을 10 fps로 녹화한 뒤, 그 녹화본에서 고품질 PNG 프레임 하나를 추출합니다. 이를 통해 macOS에서 흔히 발생하는 screencapture 권한 문제를 우회하고, 매번 안정적으로 이미지를 반환할 수 있습니다.

Quick Start Implementation

1. 임시 디렉터리를 생성합니다(스킬 폴더를 기준으로 상대 경로).
2. OpenClaw의 node screen.record를 사용해 화면을 1초 동안 녹화합니다.
3. ffmpeg를 이용해 영상에서 단일 PNG 프레임을 추출합니다.

모든 경로는 스킬 디렉터리를 기준으로 상대 경로이므로 구현이 간단하고 이식성이 높습니다.

Trigger Phrases

다음과 같은 자연어 요청이 들어오면 스킬이 활성화됩니다:

• “스크린샷 찍어줘”
• “내 화면에 뭐가 보여?”
• “화면 캡처해줘”
• “screen.record 로 스크린샷”

이러한 트리거 덕분에 일상적인 사용이 직관적입니다.

Technical Requirements

• 시스템에 ffmpeg가 설치되어 있어야 합니다. 없을 경우 사용자에게 설치를 안내하세요.
• macOS Screen Recording 권한이 시스템 설정에서 허용되어 있어야 합니다(보안상의 이유로 우회 불가).

Troubleshooting Common Issues

• node disconnection: 노드 상태를 확인하고 OpenClaw 앱이 실행 중이며 정상적으로 페어링되어 있는지 점검하세요.
• screenRecording returns false: 화면 녹화 권한이 부여되지 않은 경우이며, 시스템 설정에서 권한을 활성화하도록 안내하세요.
• Extracted frame is black: 화면이 잠겨 있거나 절전 상태였을 가능성이 있습니다. 캡처 전 디스플레이를 깨우세요.

Integration and Usage

스킬의 임시 디렉터리에서 캡처된 PNG 파일을 읽어 응답에 첨부합니다. 이는 다음과 같은 경우에 유용합니다:

• 자동화 시스템
• 원격 지원 시나리오
• 신뢰할 수 있는 화면 캡처가 필요한 애플리케이션

Advantages Over Traditional Methods

• 기본 screencapture 명령에 적용되는 권한 제한을 회피합니다.
• 복잡한 설정이 필요 없습니다.
• 헤드리스 혹은 GUI 제한이 있는 환경에서도 더 잘 동작합니다.

Best Practices

• ffmpeg가 설치되어 있는지 확인하세요.
• 화면 녹화 권한이 부여되었는지 검증하세요.
• 캡처를 시작하기 전에 디스플레이가 활성 상태(절전이나 잠금 해제)인지 확인하세요.

위 가이드라인을 따르면 개발자와 사용자는 macOS 화면 캡처와 관련된 일반적인 문제를 극복하고 다양한 상황에서 신뢰할 수 있는 스크린샷을 얻을 수 있습니다.

Skill location: snapshot/SKILL.md