Karabiner에서 kanata로 전환하기

Karabiner-Elements에서 kanata로 전환하는 전체 과정을 정리한 문서.

1단계: Karabiner-Elements 완전 제거

kanata를 설치하기 전에 Karabiner를 완전히 제거한다. 단순히 프로세스를 죽이는 것으로는 부족하다.

제거 방법

수동으로 제거하는 경우

# Karabiner 앱 삭제
sudo rm -rf /Applications/Karabiner-Elements.app
sudo rm -rf /Applications/Karabiner-EventViewer.app

# Karabiner 바이너리 디렉토리 삭제 (핵심!)
sudo rm -rf '/Library/Application Support/org.pqrs/Karabiner-Elements'

# 재부팅 (메모리에 남은 프로세스 정리)
sudo reboot

2단계: kanata 설치

Homebrew로 설치

brew install kanata

설치 확인:

which kanata        # /opt/homebrew/bin/kanata
kanata --version    # kanata 1.11.0

3단계: Karabiner VirtualHID 드라이버 확인

kanata는 macOS에서 키 이벤트를 출력하기 위해 Karabiner의 VirtualHID 드라이버를 사용한다.

이미 설치되어 있는지 확인

ls '/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/'

Karabiner를 쓰고 있었다면 이미 설치되어 있다.

드라이버 활성화

'/Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager' activate

4단계: 설정 파일 준비

설정 파일 위치

~/.config/kanata/kanata.kbd

현재 설정 요약

문법 검증

kanata --check --cfg ~/.config/kanata/kanata.kbd

5단계: 수동 실행으로 테스트

VirtualHID daemon을 먼저 실행하고, 이어서 kanata를 실행한다.

VirtualHID daemon 실행

sudo '/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/Applications/Karabiner-VirtualHIDDevice-Daemon.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Daemon'

kanata 실행 (별도 터미널)

sudo kanata --cfg ~/.config/kanata/kanata.kbd

정상 동작 시 나타나는 로그:

Starting kanata proper
driver connected: true

테스트가 끝나면 두 프로세스 모두 Ctrl+C로 종료한다.

6단계: 자동 실행 설정 (launchd)

테스트가 정상이면 부팅 시 자동 실행되도록 launchd에 등록한다.

설치 스크립트 실행

sudo ~/.config/kanata/scripts/install-launchd.sh

이 스크립트가 하는 일:

1. plist 파일을 /Library/LaunchDaemons/에 복사
2. VirtualHID 드라이버 activate
3. local.kanata.vhid 데몬 등록 및 시작
4. local.kanata 데몬 등록 및 시작

등록 확인

sudo launchctl print system/local.kanata.vhid | head -20
sudo launchctl print system/local.kanata | head -20

state = running이면 정상.

7단계: Karabiner 설정 백업 (선택)

1단계에서 Karabiner-Elements는 이미 제거되었다. 기존 설정을 보관하고 싶다면:

# 백업
cp -r ~/.config/karabiner ~/.config/karabiner.bak

# 제거
rm -rf ~/.config/karabiner

System Settings → General → Login Items에서 Karabiner 관련 항목이 남아있으면 제거한다.

일상 운영

자주 쓰는 명령어

로그 위치

/tmp/kanata.out.log        # kanata 표준 출력
/tmp/kanata.err.log        # kanata 에러 로그
/tmp/kanata-vhid.out.log   # VirtualHID 표준 출력
/tmp/kanata-vhid.err.log   # VirtualHID 에러 로그

트러블슈팅

Permission denied (root-only 소켓)

Permission denied [/Library/Application Support/org.pqrs/tmp/rootonly/vhidd_server]

root 권한 없이 실행했을 때 발생. sudo를 붙이거나 launchd 서비스로 실행한다.

exclusive access and device already open

exclusive access and device already open

kanata가 이미 실행 중. 중복 실행은 불가능하다.

# 기존 인스턴스 확인 및 정리
ps aux | grep kanata
sudo launchctl bootout system/local.kanata 2>/dev/null || true
sudo pkill -x kanata 2>/dev/null || true

IOHIDDeviceOpen not permitted

IOHIDDeviceOpen error: (iokit/common) not permitted

가장 흔한 원인: Karabiner 프로세스가 아직 키보드를 잡고 있음. Karabiner를 완전히 제거하고 재부팅하면 해결된다.

재부팅 후에도 발생하면 macOS 권한 설정 필요:

• System Settings → Privacy & Security → Input Monitoring → kanata 추가
• System Settings → Privacy & Security → Accessibility → kanata 추가
• 파일 선택 창에서 Cmd+Shift+G → /opt/homebrew/bin/kanata 입력

잘 쓰던 kanata가 갑자기 안 먹힐 때 (재발 케이스)

증상별 로그 (/tmp/kanata.out.log, /tmp/kanata.err.log):

복구 (검증됨, 2026-07):

# 정식 스크립트 한 방 = grabber 비활성화 + 데몬/kanata 재등록·시작까지 끝
sudo ~/.config/kanata/scripts/install-launchd.sh

권한이 리셋됐다면 System Settings에서 낡은 kanata 항목을 삭제 후 재추가한다 (brew 업데이트로 바이너리 경로 pin이 stale해지기 때문):

• Privacy & Security → Input Monitoring: 기존 kanata 삭제 → + → Cmd+Shift+G → /opt/homebrew/bin/kanata → ON
• Privacy & Security → Accessibility: 동일하게 재추가 → ON

compiled to never allow cmd

이것은 오류가 아니다. kanata의 외부 셸 명령 실행 기능(cmd action)이 비활성화된 빌드라는 의미. macOS의 Command 키(lmet) 매핑과는 무관하다.

참고 링크

• kanata GitHub
• kanata Configuration Guide
• kanata Releases
• Karabiner DriverKit VirtualHIDDevice
• Homebrew kanata

트러블슈팅 (추가): VirtualHIDDevice가 너무 최신이라 안 붙을 때

connect_failed asio.system:2
Waiting for DriverKit virtual keyboard... (n.n s/10.0s)
output backend unavailable — releasing input devices

감별 (이 케이스 확정 조건):

• kanata·VHID 데몬 프로세스 둘 다 정상 실행 중
• grabber 프로세스 없음 (pgrep -fl "karabiner_console_user_server|Karabiner-Core-Service" 비어있음)
• 권한 로그(Input Monitoring/Accessibility) 안 뜸
• 순수하게 kanata가 데몬 소켓에 못 붙음 (asio.system:2 = ENOENT)

근본원인: Karabiner VirtualHIDDevice driver가 kanata 지원 버전보다 최신으로 자동 업데이트됨. kanata의 번들 karabiner-driverkit crate(1.11.0=0.2.0, 1.12.0=0.3.1)는 특정 driver 릴리스 IPC로 빌드되는데, pqrs가 minor 버전 사이에 protocol을 바꿔서 더 새 driver는 안 붙는다. (2026-07 사고: 7/10에 driver가 daemon version 8.0.0 / client_protocol_version 7로 올라감 → 재부팅으로 활성화되며 깨짐.)

curl -fsSL https://raw.githubusercontent.com/jtroo/kanata/v1.12.0/docs/setup-macos.md | grep -i 'supported driver'

진단 명령:

tail /var/log/karabiner/virtual_hid_device_service.log   # version / driver_version / client_protocol_version
strings /opt/homebrew/bin/kanata | grep karabiner-driverkit   # kanata의 crate 버전

복구 — VHID를 지원버전(v6.2.0)으로 다운그레이드 (sudo 비번 + 시스템확장 GUI 승인 + 재부팅 필요):

# pkg: https://github.com/pqrs-org/Karabiner-DriverKit-VirtualHIDDevice/releases/tag/v6.2.0
sudo /Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager deactivate
sudo installer -pkg Karabiner-DriverKit-VirtualHIDDevice-6.2.0.pkg -target /
sudo /Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager forceActivate
# → System Settings > Privacy & Security에서 org.pqrs.Karabiner-DriverKit-VirtualHIDDevice 확장 승인 → 재부팅

재부팅 후 자동 실행. 안 되면 sudo ~/.config/kanata/scripts/install-launchd.sh.

재발 방지: VirtualHIDDevice 자동 업데이트가 원인. kanata 업그레이드/driver 업데이트 시 항상 버전 짝을 맞춘다.