부록 C. 트러블슈팅 & FAQ

매크로가 동작하지 않을 때 확인할 사항과 자주 묻는 질문을 정리했다.

매크로를 만들었는데 실행되지 않는다. 분명히 같은 설정인데 어제는 되고 오늘은 안 된다. 이런 상황은 KM을 쓰다 보면 반드시 겪는다.

대부분의 문제는 원인이 정해져 있다. 권한, 그룹 설정, 트리거 충돌, 타이밍. 이 네 가지를 순서대로 점검하면 거의 모든 문제를 해결할 수 있다.

매크로가 동작하지 않을 때

1. 권한 설정 확인

KM은 macOS의 접근성 API를 통해 다른 앱을 제어한다. 권한이 없으면 매크로는 아무것도 할 수 없다. macOS를 업데이트하면 권한이 초기화되는 경우가 있다. 매크로가 갑자기 멈췄다면 권한부터 확인한다.

시스템 설정 > 개인정보 보호 및 보안 에서 다음 네 가지를 점검한다.

접근성(Accessibility)

가장 중요한 권한이다. 메뉴 선택, 버튼 클릭, 텍스트 입력 등 UI 조작에 필요하다.

시스템 설정 > 개인정보 보호 및 보안 > 접근성
목록에서 "Keyboard Maestro"와 "Keyboard Maestro Engine" 두 항목을 모두 켠다
하나만 켜면 에디터에서는 동작하지만 백그라운드 실행이 안 될 수 있다

macOS Ventura(13) 이후 접근성 권한 UI가 변경되었다. 이전 버전에서는 시스템 환경설정 > 보안 및 개인정보 보호 > 개인정보 보호 탭에서 설정한다.

화면 녹화(Screen Recording)

Found Image 조건이나 화면 캡처 관련 액션을 사용할 때 필요하다. 이 권한이 없으면 화면의 픽셀 정보를 읽을 수 없다.

시스템 설정 > 개인정보 보호 및 보안 > 화면 녹화
"Keyboard Maestro Engine"을 켠다

macOS Sonoma(14)부터 화면 녹화 권한을 주기적으로 재확인하는 팝업이 뜬다. "한 달간 허용"을 선택하면 한 달 뒤 다시 묻는다. 매크로가 갑자기 이미지를 못 찾는다면 이 권한이 만료되었을 가능성이 높다.

자동화(Automation)

AppleScript로 다른 앱을 제어할 때 필요하다. 예를 들어 Finder에게 파일 목록을 요청하거나, Chrome에게 탭 정보를 요청하는 경우다.

시스템 설정 > 개인정보 보호 및 보안 > 자동화
"Keyboard Maestro Engine" 아래에 제어 대상 앱(Finder, Chrome 등)이 나열된다
필요한 앱을 모두 켠다

처음 실행할 때 "허용하시겠습니까?" 팝업이 뜬다. 이때 거부하면 이후 팝업이 다시 뜨지 않는다. 거부한 권한을 다시 허용하려면 위 설정 화면에서 직접 켜야 한다.

전체 디스크 접근(Full Disk Access)

셸 스크립트에서 파일을 읽거나 쓸 때 필요할 수 있다. 특히 Desktop, Documents, Downloads 폴더에 접근하는 경우다.

시스템 설정 > 개인정보 보호 및 보안 > 전체 디스크 접근
"Keyboard Maestro Engine"을 켠다

모든 매크로에 필요한 것은 아니다. 파일 관련 액션에서 "Operation not permitted" 오류가 나올 때 확인한다.

권한 설정 후에는 KM Engine을 재시작해야 적용된다. 메뉴 막대의 KM 아이콘 > "Quit Engine"을 선택한 뒤, KM 앱을 다시 연다. Engine이 자동으로 다시 시작된다.

2. 매크로 그룹 활성화 확인

매크로가 올바르게 만들어졌는데도 실행되지 않는다면 그룹 설정을 확인한다.

그룹이 비활성화된 경우

KM 에디터 왼쪽 패널에서 매크로 그룹 이름 옆에 체크 표시가 있어야 한다. 체크가 해제되어 있으면 그 그룹 안의 모든 매크로가 비활성화된다.

Available in 설정이 잘못된 경우

매크로 그룹에는 "Available in" 옵션이 있다.

All Applications: 모든 앱에서 동작한다.
These Applications: 지정한 앱에서만 동작한다.
Excluded Applications: 지정한 앱을 제외한 모든 앱에서 동작한다.

"These Applications"으로 설정해 놓고 다른 앱에서 실행하려고 하면 당연히 동작하지 않는다. 의도한 설정인지 확인한다.

특히 주의할 점이 있다. 앱을 삭제 후 재설치하면 앱의 내부 식별자(Bundle ID)가 바뀔 수 있다. 이 경우 "These Applications" 목록에서 해당 앱을 제거하고 다시 추가해야 한다.

매크로 자체의 활성화 여부

그룹과 별개로, 개별 매크로에도 활성화/비활성화 토글이 있다. 매크로 이름 아래의 체크박스를 확인한다.

3. 트리거 충돌 확인

단축키가 동작하지 않는 가장 흔한 이유는 충돌이다.

같은 단축키를 사용하는 다른 매크로

KM 안에서 같은 단축키를 가진 매크로가 여러 개일 수 있다. 이 경우 KM은 충돌 팔레트를 표시한다. 의도한 동작이 아니라면 단축키를 변경한다.

KM 메뉴 > Edit > Find를 사용하면 특정 단축키를 사용하는 모든 매크로를 검색할 수 있다.

다른 앱과의 충돌

다른 앱이 같은 단축키를 먼저 가로채는 경우가 있다. 대표적인 예:

Raycast, Alfred 같은 런처 앱
BetterTouchTool, Hammerspoon 같은 자동화 앱
개별 앱의 커스텀 단축키 (예: VS Code, IntelliJ)

해결 방법은 두 가지다.

다른 앱의 단축키를 변경한다.
KM의 단축키를 변경한다.

macOS 시스템 단축키와의 충돌

macOS 자체 단축키는 최우선으로 처리된다. 예를 들어 Cmd+Space(Spotlight), Cmd+Tab(앱 전환)은 KM이 가로챌 수 없다.

시스템 설정 > 키보드 > 키보드 단축키에서 사용하지 않는 시스템 단축키를 끌 수 있다. Mission Control, Spotlight 관련 단축키가 자주 충돌한다.

4. 타이밍 문제

매크로가 "가끔" 실패한다면 타이밍 문제일 가능성이 높다.

앱이 완전히 로드되기 전에 액션 실행

Activate Application 액션 직후에 Menu Select를 실행하면 실패할 수 있다. 앱이 활성화되는 데 시간이 걸리기 때문이다.

해결 방법:

Pause Until 액션을 사용한다. "front window"가 존재할 때까지 기다리는 조건을 건다.
Pause 액션으로 0.3~0.5초 대기를 넣는다. 단순하지만 효과적이다.

웹 페이지 로딩 대기

Chrome에서 페이지를 열고 바로 조작하면 실패한다. JavaScript가 아직 로드되지 않았을 수 있다.

Pause Until 조건으로 특정 요소가 나타날 때까지 대기한다.
또는 Execute JavaScript in Chrome 액션에서 document.readyState === 'complete'를 체크한다.

딜레이 조정 방법

KM 환경설정에서 기본 딜레이를 조정할 수 있다.

KM 메뉴 > Preferences > General
"Default key delay"와 "Default action delay" 값을 확인한다

기본값은 0이다. 느린 Mac이나 무거운 앱을 다룰 때는 0.05~0.1초 정도로 설정하면 안정성이 높아진다.

개별 액션에서도 "Pause before executing"을 설정할 수 있다. 액션을 우클릭하면 해당 옵션이 나온다.

매크로 디버깅 방법

문제의 원인을 모를 때는 체계적으로 디버깅한다. KM은 여러 디버깅 도구를 제공한다.

KM 로그 확인

KM 메뉴 > Window > Macro Log를 연다. 매크로 실행 기록이 시간순으로 표시된다.

로그에서 확인할 수 있는 정보:

매크로가 언제 트리거되었는지
각 액션의 실행 결과
오류 메시지

"Failure"나 "Error"가 표시된 행을 찾는다. 오류 메시지가 원인을 알려주는 경우가 많다.

로그가 너무 많으면 필터 기능을 사용한다. 특정 매크로 이름이나 그룹 이름으로 검색할 수 있다.

단계별 실행

매크로를 한 액션씩 실행하는 방법이다.

KM 에디터에서 매크로를 선택한다.
실행하고 싶은 액션을 선택한다.
Control+Option+Command+T를 누르면 해당 액션 하나만 실행된다.

또는 액션을 우클릭하고 "Try Action"을 선택해도 된다.

이 방법으로 어느 액션에서 문제가 발생하는지 정확히 찾을 수 있다.

변수 값 확인

매크로 실행 중 변수 값이 예상과 다를 수 있다.

KM 메뉴 > Window > Variables를 연다. 현재 설정된 모든 변수와 값을 실시간으로 볼 수 있다.

변수를 검색할 수도 있다. 디버깅하려는 변수 이름을 입력하면 빠르게 찾을 수 있다.

알림 액션으로 중간 값 출력

가장 실용적인 디버깅 방법이다.

의심되는 액션 사이에 Notification 액션을 추가한다. 알림 메시지에 %Variable%Local_result%처럼 변수 값을 넣는다. 매크로를 실행하면 각 단계의 값이 알림으로 표시된다.

디버깅이 끝나면 추가한 Notification 액션을 삭제하거나 비활성화한다. 액션을 선택하고 우클릭 > "Disable Action"을 선택하면 삭제하지 않고 비활성화할 수 있다.

Display Text 액션을 사용해도 된다. Notification보다 더 많은 텍스트를 표시할 수 있다.

자주 묻는 질문 (FAQ)

Q. KM 라이선스 가격은?

2025년 기준 USD $36이다. 한 번 구매하면 영구 라이선스다. 메이저 버전 업그레이드(예: 11 -> 12) 시 할인된 가격으로 업그레이드할 수 있다. 공식 사이트(https://www.keyboardmaestro.com)에서 구매한다.

Q. 한 대 이상의 Mac에서 사용할 수 있나?

한 라이선스로 본인 소유의 Mac 여러 대에서 사용할 수 있다. 단, 동시에 사용하는 것이 본인 한 명이어야 한다. 회사와 집에서 각각 한 대씩 쓰는 것은 허용된다.

Q. 매크로를 다른 사람과 공유할 수 있나?

가능하다. 두 가지 방법이 있다.

파일 내보내기: KM 에디터에서 매크로를 선택하고 File > Export를 선택한다. .kmmacros 파일이 생성된다. 이 파일을 전달하면 된다.
클립보드 복사: 매크로를 선택하고 Cmd+C로 복사한다. 텍스트 형태로 붙여넣을 수 있다. 받는 사람이 KM에 붙여넣으면 매크로가 추가된다.

공유받은 .kmmacros 파일은 더블클릭하면 KM에 자동으로 추가된다.

Q. KM 없이 .kmmacros 파일을 열 수 있나?

.kmmacros 파일은 XML 형식이다. 텍스트 에디터로 열어서 내용을 읽을 수 있다. 하지만 실행하려면 KM이 설치되어 있어야 한다.

XML 구조를 분석하면 매크로의 트리거, 액션, 설정값을 파악할 수 있다. 이 책에서 다루는 매크로 분석이 바로 이 방법이다.

Q. AppleScript와 JavaScript 중 어떤 것을 사용해야 하나?

상황에 따라 다르다.

AppleScript가 적합한 경우:

Finder, Mail, Calendar 등 Apple 기본 앱을 제어할 때
시스템 이벤트(키 입력, 마우스 클릭)를 시뮬레이션할 때
macOS 고유 기능(알림 센터, Spotlight)과 연동할 때

JavaScript(JXA)가 적합한 경우:

JSON 파싱 등 데이터 처리가 필요할 때
웹 관련 작업(URL 인코딩, 정규식)을 할 때
JavaScript 문법에 더 익숙할 때

Chrome/Safari에서 실행하는 JavaScript 는 별개다. 이것은 웹 페이지의 DOM을 조작하는 용도다. JXA(JavaScript for Automation)와 혼동하지 않도록 주의한다.

Q. 매크로 실행 중 다른 매크로를 실행할 수 있나?

가능하다. 세 가지 방법이 있다.

Execute Macro 액션: 다른 매크로를 서브루틴처럼 호출한다. 호출된 매크로가 끝날 때까지 기다린다.
Trigger Macro by Name: 이름으로 매크로를 실행한다. 비동기로 실행되므로 기다리지 않는다.
단축키 트리거: 한 매크로 안에서 다른 매크로의 단축키를 시뮬레이션한다. 권장하지 않는다.

서브매크로 패턴은 ch11에서 자세히 다룬다.

Q. 매크로가 너무 느릴 때 어떻게 하나?

느린 원인을 먼저 파악한다.

불필요한 딜레이 제거:

Pause 액션이 과도하게 들어가 있지 않은지 확인한다.
Pause Until 조건이 너무 느슨하지 않은지 확인한다.

UI 조작 대신 직접 실행:

Menu Select로 메뉴를 클릭하는 대신, 해당 기능의 단축키를 Type Keystroke로 입력하는 것이 빠르다.
Click at Found Image보다 AppleScript로 직접 제어하는 것이 빠르다.

셸 스크립트 최적화:

외부 명령어를 여러 번 호출하는 대신, 한 번의 스크립트로 묶는다.
파이프라인을 활용하여 중간 파일 생성을 줄인다.

변수 활용:

같은 값을 여러 번 계산하지 않는다.
한 번 계산한 결과를 변수에 저장하고 재사용한다.

Q. 보안상 주의할 점은?

KM은 강력한 권한을 가진 도구다. 주의할 점이 있다.

비밀번호와 민감 정보:

매크로에 비밀번호를 평문으로 저장하지 않는다.
macOS 키체인(Keychain)과 연동하여 민감 정보를 관리한다.
Execute Shell Script에서 security find-generic-password 명령어로 키체인에 접근할 수 있다.

매크로 공유 시 주의:

.kmmacros 파일을 공유할 때 개인정보가 포함되어 있지 않은지 확인한다.
파일 경로, 사용자 이름, API 키 등이 매크로에 하드코딩되어 있을 수 있다.
공유 전에 XML을 열어서 민감 정보를 제거한다.

셸 스크립트 보안:

외부에서 받은 매크로의 셸 스크립트 내용을 반드시 확인한다.
rm -rf, curl | sh 같은 위험한 명령어가 포함되어 있을 수 있다.
신뢰할 수 있는 출처에서만 매크로를 가져온다.

KM 유용한 설정

매크로 팔레트

매크로 그룹을 팔레트로 표시할 수 있다. 화면에 작은 창이 떠서 매크로 목록을 보여준다. 클릭하거나 단축키로 실행한다.

설정 방법:

매크로 그룹을 선택한다.
"Shows a palette" 또는 "Shows a palette for one action"을 선택한다.
트리거(단축키)를 지정하면 해당 단축키를 누를 때 팔레트가 나타난다.

팔레트에 표시되는 매크로 이름 앞에 숫자나 문자를 붙이면 해당 키로 바로 실행할 수 있다. 예: "1. 회의 모드", "2. 퇴근 모드"

상태 메뉴

메뉴 막대에 KM 아이콘이 표시된다. 클릭하면 매크로를 실행하거나 설정을 변경할 수 있다.

특정 매크로 그룹을 상태 메뉴에 표시하려면:

매크로 그룹을 선택한다.
"Shows a status menu"를 체크한다.
메뉴 막대에 해당 그룹의 매크로가 나타난다.

자주 쓰는 매크로를 상태 메뉴에 등록하면 단축키를 외우지 않아도 된다.

클립보드 히스토리

KM은 클립보드 히스토리 기능을 내장하고 있다. 과거에 복사한 내용을 다시 붙여넣을 수 있다.

기본 단축키: Cmd+Shift+V (KM 설정에서 변경 가능)

최근 복사한 항목 목록이 팝업으로 표시된다.
텍스트, 이미지 모두 저장된다.
검색 기능으로 과거 항목을 빠르게 찾을 수 있다.
즐겨찾기(Named Clipboard)를 등록하면 자주 쓰는 텍스트를 영구 저장할 수 있다.

매크로 백업

매크로 데이터는 다음 경로에 저장된다:

~/Library/Application Support/Keyboard Maestro/Keyboard Maestro Macros.plist

자동 백업 설정:

KM은 자체적으로 매크로 변경 시 백업을 생성한다. 백업 파일은 같은 디렉토리에 저장된다.

수동 백업 방법:

File > Export > Export All Macros를 선택한다.
.kmmacros 파일로 전체 매크로를 내보낸다.
이 파일을 iCloud, Dropbox, Git 등으로 관리한다.

권장 백업 전략:

주 1회 전체 매크로를 내보내서 클라우드에 저장한다.
중요한 매크로를 수정하기 전에 개별 내보내기를 한다.
Git으로 .kmmacros 파일을 버전 관리하면 변경 이력을 추적할 수 있다.

복원 방법:

백업한 .kmmacros 파일을 더블클릭하면 KM에 매크로가 추가된다. 기존 매크로와 이름이 같으면 별도 매크로로 추가되므로, 복원 전에 기존 매크로를 정리한다.

문제가 계속될 때

위의 방법으로 해결되지 않는다면 다음을 시도한다.

KM Engine 재시작: 메뉴 막대 KM 아이콘 > Quit Engine. KM 앱을 다시 열면 Engine이 자동 시작된다.
Mac 재시작: 권한 변경 후에는 재시작이 필요한 경우가 있다.
KM 재설치: 드물지만 KM 자체가 손상될 수 있다. 재설치 전에 매크로를 반드시 백업한다.
KM 공식 포럼: https://forum.keyboardmaestro.com 에 질문을 올리면 개발자와 커뮤니티가 답변한다. 영어로 작성해야 한다.
KM 공식 문서: https://wiki.keyboardmaestro.com 에서 액션별 상세 설명을 확인한다.

매크로 디버깅은 처음에는 번거롭게 느껴진다. 하지만 몇 번 경험하면 패턴이 보인다. 대부분의 문제는 이 부록에서 다룬 범위 안에서 해결된다.