macOS hidutil 키 매핑 가이드

hidutil은 macOS에 내장된 도구로, 별도의 앱 없이 커널 레벨에서 키보드 키를 바꿀 때 사용합니다.

1. 핵심 명령어 요약

1.1. 키 매핑 적용 (예: Caps Lock → Left Control)

가장 많이 사용하는 설정입니다. 터미널에 복사해서 붙여넣으세요.

hidutil property --set '{"UserKeyMapping":
  [{"HIDKeyboardModifierMappingSrc":0x700000039,
    "HIDKeyboardModifierMappingDst":0x7000000E0}]
}'

1.2. 현재 적용된 설정 확인

hidutil property --get "UserKeyMapping"

1.3. 모든 설정 초기화 (원래대로)

hidutil property --set '{"UserKeyMapping":[]}'

2. 주요 키 코드

매핑할 때 Src(원래 키)와 Dst(바꿀 키)에 아래 코드를 조합해서 넣으면 됩니다.

3. 특정 키보드에만 적용하기

노트북 키보드는 그대로 두고, 특정 외장 키보드만 바꾸고 싶을 때 사용합니다.

1. hidutil list 명령어를 실행합니다. Devices: 섹션에서 대상 키보드의 VendorID와 ProductID를 확인합니다.
   • 내장 키보드를 제외하고 싶다면 Built-In 값이 0인 키보드를 고릅니다.
   • 같은 제조사/모델 키보드가 여러 개라면 LocationID까지 같이 지정해야 대상을 더 좁힐 수 있습니다.
2. 아래 형식으로 명령어를 실행합니다.

hidutil property --matching '{"VendorID": 0x1234, "ProductID": 0x5678}' --set '{"UserKeyMapping": [...] }'

동일한 VendorID/ProductID 장치가 여러 개 있을 때는 다음처럼 LocationID를 추가합니다.

hidutil property --matching '{"VendorID": 0x1234, "ProductID": 0x5678, "LocationID": 0xabcd}' --set '{"UserKeyMapping": [...] }'

4. 주의사항

1. 휘발성 설정: 터미널에서 hidutil 명령어로 바로 설정한 내용은 재부팅하면 사라집니다. 또한 마지막 키보드 서비스가 제거되는 경우에도 매핑이 사라질 수 있습니다. (영구 적용은 5번 참고)
2. 복잡한 매핑의 한계: 단순히 단일 키 몇 개를 바꾸는 데는 훌륭하지만, Fn 조합이나 조건부 키 매핑이 필요하다면 Karabiner-Elements 사용을 권장합니다.

5. 재부팅 후에도 유지하기

hidutil 설정은 휘발성이므로 재부팅하면 초기화됩니다. macOS의 LaunchAgent를 사용하여 로그인 시 자동으로 설정을 적용하도록 만들 수 있습니다.

5.1. .plist 파일 생성

~/Library/LaunchAgents/ 폴더에 com.user.hidutil.plist 파일을 만듭니다. (파일 이름은 자유롭습니다)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.user.hidutil</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/hidutil</string>
        <string>property</string>
        <string>--set</string>
        <string>{"UserKeyMapping":[{"HIDKeyboardModifierMappingSrc":0x700000039,"HIDKeyboardModifierMappingDst":0x7000000E0}]}</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

*위 예시는 Caps Lock을 Left Control로 바꾸는 설정입니다.*

5.2. 서비스 등록 및 실행

터미널에서 아래 명령어를 입력하여 macOS 시스템에 등록합니다.

# 파일 권한 확인 (보통은 기본값으로 충분합니다)
chmod 644 ~/Library/LaunchAgents/com.user.hidutil.plist

# 서비스 등록
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.user.hidutil.plist

# 즉시 실행
launchctl kickstart -k gui/$(id -u)/com.user.hidutil

5.3. 설정 삭제 (필요할 때)

더 이상 사용하지 않으려면 아래 명령어로 해제한 뒤 파일을 삭제하세요.

launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.user.hidutil.plist
rm ~/Library/LaunchAgents/com.user.hidutil.plist

6. 참고 자료

• Apple Archive: HID Usage Tables
• hidutil-generator (Web Tool)

Written by Gemini 3.1-pro-preview via Gemini CLI