AI 자동화

OpenClaw AppleScript: macOS 네이티브 앱 에이전트 제어 (2026)

OpenClaw AppleScript Automator macOS 데스크톱 자동화 2026
고지: KuzCloud는 Mac 호스팅 가이드를 게시합니다. 본 글은 기술 문서입니다. OpenClaw는 서드파티 OSS입니다 — openclaw.dev를 참조하세요.
요약: 대부분의 OpenClaw 배포는 터미널의 텍스트와 셸에서 멈춥니다. macOS에서는 OpenClaw 스킬(SKILL.md)과 osascript(AppleScript)를 호출하거나 Automator 워크플로를 실행하는 작은 브리지 스크립트를 결합해 에이전트에 물리적 데스크톱 몸체를 줄 수 있습니다. Keynote를 열고 PDF를 내보내고, 시스템 볼륨을 조절하거나 디스플레이 밝기를 낮출 수 있으며, 채팅 트리거는 게이트웨이에 남습니다. TCC 프롬프트(손쉬운 사용 / 자동화)를 예상하고, 전체 GUI 제어는 고권한으로 취급하세요.

텍스트 전용 OpenClaw가 macOS 성능을 남기는 이유

OpenClaw는 저장소, CI 훅, 다중 에이전트 팬아웃에 뛰어납니다. Mac mini나 MacBook에서는 동일한 데몬이 SSH로 헤드리스 실행되는 경우가 많아 파일을 편집하고 npm test를 실행하지만, Mail, Keynote, Music, 시스템 설정에는 손대지 않습니다.

워크플로가 개발자형이 아니라 운영자형일 때 이 격차가 중요해집니다:

  • 이해관계자가 팀 채널에 「deck v3 PDF 내보내기」를 올림
  • 화면 공유 녹화 전에 밝기를 낮추고 싶음
  • 야간 작업으로 슬라이드를 아카이브해야 하는데 UI를 직접 건드리고 싶지 않음

macOS에는 이미 접착제가 있습니다: AppleScript는 스크립트 가능한 앱과 대화하고, Automator는 반복 가능한 UI 매크로를 셸에서 실행할 수 있는 .workflow로 패키징합니다. OpenClaw의 스킬 시스템이 세 번째 다리입니다 — 모델이 호출할 수 있는 문서화된 도구입니다. 이들을 연결하면 에이전트는 샌드박스 속 챗봇이 아니라 데스크톱에 손을 댄 로컬 컨시어지가 됩니다.

본 가이드는 OpenClaw가 설치되어 있다고 가정합니다(설치 참고). 데스크톱 자동화에 집중하며 오케스트레이션 이론은 다루지 않습니다.

아키텍처: 게이트웨이 → 스킬 → 브리지 → AppleScript / Automator

데이터 흐름 한 문장: 채널 메시지 → OpenClaw 게이트웨이 → 스킬 핸들러 → /usr/local/bin/openclaw-mac-bridge → osascript 또는 automator → 네이티브 앱 또는 System Events.

계층책임일반 경로
게이트웨이채팅/Webhook을 에이전트로 라우팅openclaw 데몬
스킬(SKILL.md)인자, 안전 규칙, 예시 문서화~/.openclaw/skills/mac-desktop/SKILL.md
브리지(bash)입력 검증, 로깅, macOS 호출~/bin/openclaw-mac-bridge
AppleScript앱 동사(Keynote, Finder)인라인 또는 ~/Scripts/*.applescript
AutomatorAppleScript가 취약할 때 녹화 UI~/Library/Services/Export-Keynote-PDF.workflow

Apple은 AppleScript 언어 가이드에서 스크립트 가능한 앱을 설명합니다. System Events를 통한 GUI 스크립팅에는 시스템 설정 → 개인정보 보호 및 보안에서 터미널(또는 osascript)에 손쉬운 사용 권한이 필요합니다.

보안 입장: 브리지 스크립트는 전용 자동화 Mac(또는 지울 수 있는 VM/세션)에서만 실행하세요. 전체 데스크톱 제어와 에이전트 셸 접근은 root에 준하는 UX — Worker의 샌드박스 비활성화와 동급 위험입니다.

의사결정 매트릭스: AppleScript vs Automator vs 셸만

필요AppleScriptAutomator 워크플로셸(openclaw 도구만)
Keynote PDF 내보내기네이티브 export 명령API 없을 때 메뉴 클릭 녹화아니오
볼륨 / 밝기System Events과함osascript 원라이너
스크립트 불가 Electron 앱취약UI 녹화가 종종 더 쉬움아니오
원격 Linux CI해당 없음해당 없음예
감사 가능, 버전 관리git의 .applescriptgit의 .workflow 번들SKILL.md만
헤드리스 SSH MacGUI 세션 로그인 시 동작그래픽 세션 필요동작

규칙: 앱 사전에 동사가 있으면 AppleScript 우선; 메뉴 막대 전용 동작은 Automator로 폴백; 파일/Git 작업은 셸 유지.

단계별 Runbook: 브리지 + SKILL.md + 세 가지 동작

1단계 — 브리지 스크립트 생성

~/bin/openclaw-mac-bridge로 저장하고 chmod +x:

#!/usr/bin/env bash set -euo pipefail ACTION="${1:-}"; shift || true LOG="${HOME}/.openclaw/logs/mac-bridge.log" mkdir -p "$(dirname "$LOG")" log() { printf '%s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$*" >>"$LOG"; } case "$ACTION" in keynote-export-pdf) DECK="${1:?path to .key required}" OUT="${2:?output .pdf path required}" osascript <<EOF tell application "Keynote" activate open POSIX file "$DECK" delay 2 export front document to POSIX file "$OUT" as PDF close front document saving no end tell EOF log "keynote-export-pdf OK $OUT" ;; set-volume) PCT="${1:?0-100}" osascript -e "set volume output volume $PCT" log "set-volume $PCT" ;; set-brightness) PCT="${1:?0-100}" osascript <<EOF tell application "System Events" tell appearance preferences set brightness to ($PCT / 100) end tell end tell EOF log "set-brightness $PCT" ;; run-automator) WF="${1:?workflow path required}" automator "$WF" log "run-automator $WF" ;; *) echo "Usage: openclaw-mac-bridge {keynote-export-pdf|set-volume|set-brightness|run-automator} ..." >&2 exit 2 ;; esac

Apple Silicon macOS 14+에서 appearance preferences를 통한 밝기 조절은 로그인된 GUI 세션이 필요할 수 있습니다. 채팅에 연결하기 전 로컬에서 테스트하세요.

2단계 — mac-desktop 스킬용 SKILL.md 작성

경로: ~/.openclaw/skills/mac-desktop/SKILL.md(OpenClaw 스킬 루트에 맞게 조정):

# mac-desktop Control this Mac's GUI via openclaw-mac-bridge. Only run actions the user explicitly requested. ## Commands - keynote-export-pdf <path.key> <out.pdf> - set-volume <0-100> - set-brightness <0-100> - run-automator <path.workflow> ## Safety - Never export to paths outside ~/Documents/OpenClaw-Exports/ - Refuse destructive Finder/ Mail actions unless user names the target file

에이전트 설정에 스킬 등록(릴리스마다 다름 — openclaw.json의 기존 skills: ["git", "nodejs"] 항목을 따르세요).

3단계 — 에이전트 도구 정책에서 브리지 허용

오케스트레이터가 샌드박스 Worker를 쓰면 데스크톱 스킬은 오케스트레이터 에이전트에만 두고 해당 agent ID에 sandbox.mode: off를 설정합니다. 코드만 편집하는 Worker에는 mac-desktop을 주지 마세요.

4단계 — Automator 워크플로 구축(선택)

  1. Automator → 빠른 작업 열기
  2. 녹화: Keynote → 파일 → 내보내기 → PDF(~/Documents/OpenClaw-Exports/에 저장)
  3. ~/Library/Services/ 아래 Export-Keynote-PDF.workflow로 저장
  4. 테스트: automator ~/Library/Services/Export-Keynote-PDF.workflow

Keynote 버전에서 AppleScript 내보내기가 실패하면 openclaw-mac-bridge run-automator …로 연결하세요.

5단계 — macOS 개인정보 권한 부여

  1. 시스템 설정 → 개인정보 보호 및 보안 → 자동화 — 터미널/iTerm(또는 node)이 Keynote 제어 허용
  2. 손쉬운 사용 — 동일 호스트에서 System Events 밝기 스크립트 허용
  3. 브리지를 수동으로 한 번 더 실행하고 프롬프트 승인

6단계 — 채팅 트리거 연결(개념)

채널 규칙(Discord/Telegram/Webhook)에서 구문을 오케스트레이터 작업에 매핑:

When message matches ^/deck pdf (.+)$, call mac-desktop keynote-export-pdf with captured path.

정확한 훅 구문은 OpenClaw 채널 플러그인에 따라 다릅니다 — 마법 라우팅이 아니라 오케스트레이터 시스템 프롬프트 + 허용 도구로 취급하세요.

7단계 — openclaw doctor와 드라이런으로 검증

openclaw doctor ~/bin/openclaw-mac-bridge set-volume 25 ~/bin/openclaw-mac-bridge keynote-export-pdf "$HOME/Desktop/demo.key" "$HOME/Documents/OpenClaw-Exports/demo.pdf"

PDF 바이트와 ~/.openclaw/logs/mac-bridge.log 로그 줄을 확인하세요.

8단계 — 프로덕션 가드레일

  • 전용 사용자 계정 automation — Keynote 전용 로그인 키체인 항목
  • 속도 제한: 채널당 시간당 최대 6회 GUI 동작
  • 허용 목록: ~/Documents/Decks/ 아래 deck 경로
  • DB/API는 MCP 도구와 결합; GUI는 mac-desktop 스킬만

문제 해결

오류: execution error: Not authorized to send Apple events to Keynote

패턴: osascript stderr에 (-1743) 또는 「Not authorized」.

수정: 시스템 설정 → 개인정보 보호 및 보안 → 자동화 → 터미널 앱 → Keynote 활성화. 헤드리스 SSH면 화면 공유 세션에서 한 번 실행해 프롬프트를 표시하세요.

오류: System Events got an error: Can’t set brightness

패턴: 볼륨은 성공하지만 밝기에서 실패.

수정: 터미널에 손쉬운 사용 부여; 로그인된 GUI 세션 확보(콘솔 없는 launchd 아님). 폴백: AppleScript 대신 Automator 「밝기 변경」 동작 사용.

시나리오 A — 그룹 채팅 「PDF 보내줘」

팀 봇이 「투자자 미팅용 keynote 내보내기」를 듣습니다. 오케스트레이터가 deck 이름을 파싱하고 keynote-export-pdf를 호출한 뒤 별도 파일 도구로 PDF를 업로드하고 SHA256과 경로로 답합니다. 지연: M4에서 40슬라이드 deck 약 8–15초(디스크 + Keynote 콜드 스타트). RAM: Keynote 피크 약 400–900 MB — 16 GB에서 단일 OpenClaw 데몬 옆에 무리 없음; 동일 GUI 호스트에서 병렬 팬아웃은 피하세요.

시나리오 B — 녹화 전 환경 리셋

OBS 캡처 전 에이전트가 set-volume 35와 set-brightness 60을 실행하고 Automator로 메뉴 막대 extras를 숨깁니다. 함의: 이들은 전역 변경 — 같은 스킬 세션에서 롤백(set-volume 70)을 문서화하세요.

만약 당신이…이렇게 하세요
파일/Git/CI만 필요GUI 스킬 건너뛰기; 셸 도구 유지
Keynote/Pages/Finder 필요오케스트레이터 에이전트의 AppleScript 브리지 + SKILL.md
앱에 사전 없음Automator 워크플로 + run-automator
원격 Mac에서 에이전트 실행지속 GUI 로그인 확보; 원격 OpenClaw 설정 참고
3개 이상 병렬 에이전트 필요하나의 GUI 세션을 공유하지 마세요 — mac-desktop 호출 직렬화

FAQ

OpenClaw가 헤드리스 SSH 세션에서 AppleScript를 실행할 수 있나요?

대상 사용자에게 활성 WindowServer 세션(화면 공유 로그인 또는 로컬 콘솔)이 있을 때만 가능합니다. GUI 로그인 없는 순수 SSH는 Keynote와 System Events UI 스크립팅에서 실패합니다.

OpenClaw 다중 에이전트 오케스트레이션과 어떻게 다른가요?

다중 에이전트 오케스트레이션은 추론 Worker를 분할합니다. 데스크톱 자동화는 단일 호스트 특권 도구 — 하나의 오케스트레이터에서만 실행하고, 세 코더가 동시에 Keynote를 치는 팬아웃은 하지 마세요.

AppleScript는 프로덕션에 안전한가요?

강력하지만 기본적으로 안전하지 않습니다. mac-desktop을 프로덕션 셸처럼 취급하세요: 허용 목록, 로깅, 전용 Mac, 동일 사용자 세션에 개인 이메일 없음.

Claude Code나 Copilot CLI와 함께 쓸 수 있나요?

해당 CLI에는 OpenClaw 스킬 라우터가 없습니다. 셸 도구에서 동일 브리지 스크립트를 재사용할 수 있지만 중앙 채널 라우팅은 잃습니다 — 스택 선택은 벤치마크 비교를 참고하세요.

네트워크 제약과 원격 Mac 패턴은 어떻게 하나요?

npm/API 경로를 안정시키려면 많은 팀이 게이트웨이를 상시 가동 원격 Mac에서 실행합니다 — OpenClaw 원격 설정과 같은 패턴입니다. AppleScript는 그 Mac의 데스크톱에서 실행되며, 로컬 노트북에서가 아닙니다.

관련 가이드

데스크톱 스킬을 프로덕션 채팅 트리거에 연결하기 전에 멀티 에이전트 오케스트레이션과 원격 Mac 설정을 확인하세요.