hangeul-keymap-setup

macOS에서 원하는 키를 한/영 전환 전용 키로 쓰기 위한 셸 스크립트입니다. 지정한 키를 F17로 리매핑한 뒤, 그 F17을 입력 소스 전환 단축키로 지정하는 방식입니다. 고를 수 있는 키는 오른쪽 커맨드(⌘, 기본값) / 오른쪽 Alt / 한/영 전용 키 세 가지이며, 여러 개를 동시에 지정할 수도 있습니다. 리매핑 대상 키도 --dst 옵션으로 F13~F19 중 원하는 값으로 바꿀 수 있습니다.

Karabiner-Elements 같은 별도 앱이나 커널 확장 없이, macOS에 기본 내장된 hidutil과 launchd만 사용합니다.

요구 사항

• macOS 10.12 (Sierra) 이상
• Apple Silicon / Intel 모두 동작
• 관리자(sudo) 권한

어떤 키를 전환 키로 쓸지 고르기

옵션	대상 키
--right-cmd	오른쪽 커맨드(⌘) — 옵션을 안 주면 기본값
--right-alt	오른쪽 Alt(Option)
--hangeul-key	한/영 전용 키 (HID LANG1)

여러 개를 동시에 지정할 수 있고, 지정한 키는 모두 매핑 대상 키(기본값 F17, --dst로 변경 가능)를 보냅니다. 여러 키를 지정했더라도 시스템 설정에는 그중 아무 키나 하나만 등록하면 됩니다(아래 설치 후 설정 참고).

내 키보드에는 어떤 옵션이 맞는지 아래 표를 참고하세요.

키보드	권장 옵션
애플 키보드 / 맥용 배열	옵션 없이 기본값 (오른쪽 커맨드)
윈도우용 풀사이즈 104키	기본값 그대로. 스페이스 오른쪽의 오른쪽 Win 키가 오른쪽 커맨드와 같은 HID 코드(0x7000000E7)를 보냅니다
오른쪽 Win 키가 없는 배열 (텐키리스 일부, 노트북 등)	--right-alt
한글 배열 (한/영 키가 따로 있음)	--right-alt --hangeul-key 둘 다
어느 쪽인지 모르겠음	세 개 다 지정해도 무방합니다

한글 배열 키보드의 한/영 키는 모델에 따라 LANG1을 보내기도 하고 101키 호환 모드에서 오른쪽 Alt로 인식되기도 합니다. 어느 쪽인지 모르겠다면 둘 다 걸어두면 됩니다.

왜 F17인가

macOS 시스템 설정의 단축키 입력 칸은 ⌘/⌥/⌃/⇧ 같은 수식키를 단독으로는 단축키로 등록받지 않습니다. 오른쪽 커맨드만 눌러서는 아무것도 안 잡히는 이유입니다. 그래서 수식키를 먼저 "단독으로 눌렀을 때 keydown이 발생하는 일반 키"로 바꿔준 뒤, 그 일반 키를 단축키로 등록하는 우회가 필요합니다.

그 일반 키로 쓸 수 있는 후보는 macOS 단축키 레코더가 인식하면서도 실제 키보드에 물리 키가 거의 없는 F13~F20 구간입니다(F21 이상은 macOS에 virtual keycode 자체가 없어 쓸 수 없습니다).

이 중 F20은 후보에서 제외했습니다. HID 코드 자체는 있어 리매핑 (hidutil)은 되지만, macOS Sequoia에서 실제로 테스트한 결과 시스템 설정 > 키보드 단축키 > 입력 소스의 이전 입력 소스 선택 칸이 F20 입력을 등록받지 않는 것을 확인했습니다. 물리 키가 없다는 장점이 오히려 macOS 자체도 이 키를 단축키로 취급하지 않는다는 뜻이었던 셈입니다. 리매핑은 되는데 단축키 등록만 안 되는, 골라도 아무 일도 일어나지 않는 값이라 목록에서 뺐습니다.

남은 F13~F19 중 이 스크립트는 F17을 기본값으로 씁니다.

• F13/F14/F15는 윈도우 키보드의 PrintScreen/ScrollLock/Pause가 같은 HID 코드를 보내는 경우가 있어 충돌 여지가 있습니다.
• F16~F19는 애플 풀사이즈 알루미늄 키보드(A1243 등) 일부 모델에 실제 물리 키가 있어 그 키보드에서는 원래 기능을 잃습니다(다만 흔한 모델은 아닙니다).

즉 F17이어야 할 기술적 필연성이 있는 건 아니고, F13F19 중 무난한 값을 기본값으로 골랐을 뿐입니다. Stream Deck, Keyboard Maestro, BetterTouchTool 등에서 이미 F17을 다른 용도로 쓰고 있다면 --dst 옵션으로 F13F19 중 다른 값을 지정하세요.

sudo ./hangeul-keymap-setup.sh install --dst F16

설치

chmod +x hangeul-keymap-setup.sh

# 1) 모든 키보드, 오른쪽 커맨드 (가장 흔한 경우)
sudo ./hangeul-keymap-setup.sh install

# 2) 특정 키보드 한 대에만
sudo ./hangeul-keymap-setup.sh install --device

# 3) 윈도우용/한글 배열 키보드 한 대에 여러 키 지정
sudo ./hangeul-keymap-setup.sh install --device --right-alt --hangeul-key

--device를 쓰면 연결된 HID 장치 목록이 출력되고, 적용할 키보드의 VendorID / ProductID를 입력받습니다. 내장 키보드는 그대로 두고 외장 키보드에만 적용하고 싶을 때 유용합니다. 대화식으로 입력을 받으므로 curl | sudo sh 처럼 파이프로 바로 실행하면 동작하지 않습니다.

연결된 장치 목록만 먼저 보려면 ./hangeul-keymap-setup.sh list (sudo 불필요).

명령 / 옵션 레퍼런스

명령	설명	sudo
install	키 리매핑을 설치하고 즉시 적용	필요
uninstall	리매핑을 제거	필요
list	연결된 HID 장치 목록만 확인	불필요

install에 붙일 수 있는 옵션:

옵션	설명
--device	특정 키보드 한 대에만 적용 (목록에서 선택)
--right-cmd	오른쪽 커맨드(⌘) 키를 사용
--right-alt	오른쪽 Alt(Option) 키를 사용
--hangeul-key	한/영 전용 키(LANG1)를 사용
--dst <F13~F19>	리매핑 대상 키를 지정 (기본값 F17)

키 옵션은 여러 개를 동시에 지정할 수 있고, 같은 옵션을 중복 지정해도 무시됩니다. 키 옵션을 하나도 지정하지 않으면 --right-cmd가 기본값으로 적용됩니다. --dst를 지정하지 않으면 F17로 리매핑되며, 왜 F17인지는 왜 F17인가 절을 참고하세요.

설치 후 설정 (필수)

스크립트는 키 리매핑까지만 합니다. 시스템 설정에서 아래를 직접 지정해야 실제로 한/영 전환이 동작합니다. 설치가 끝나면 같은 내용이 터미널에도 안내됩니다.

1. F17을 전환 키로 등록 (필수) — 시스템 설정 > 키보드 > 키보드 단축키... > 입력 소스에서 이전 입력 소스 선택을 더블클릭하고 리매핑한 키를 누릅니다. (체크박스가 꺼져 있다면 함께 켜주세요.) 여러 키를 지정했다면 아무 키나 하나만 눌러 등록하면 됩니다. --dst로 다른 키를 지정했다면 F17 대신 그 키가 등록됩니다.
2. Caps Lock 한/영 전환 끄기 (권장) — 시스템 설정 > 키보드 > 텍스트 입력 > 입력 소스 옆 [편집...]에서 Caps Lock 키로 ABC 입력 소스 전환을 끕니다. (영문 표기: Use Caps Lock key to switch to and from ABC.) macOS 12 이하에서는 시스템 환경설정 > 키보드 > 입력 소스 탭에 같은 항목이 있습니다. 전환 키가 두 개면 현재 입력 상태를 착각하기 쉬우므로 함께 정리하는 걸 권합니다.
3. Caps Lock 키를 완전히 죽이기 (선택) — 2번만 꺼도 한/영 전환은 안 되지만 대문자 고정 기능은 남습니다. 아예 쓰지 않으려면 시스템 설정 > 키보드 > 키보드 단축키... > 보조 키에서 Caps Lock 키를 동작 없음으로 바꿔주세요. 이 설정은 키보드별로 따로 저장되므로, 창 위쪽 적용 대상에서 사용 중인 키보드를 각각 선택해 설정해야 합니다.

제대로 적용됐는지 확인

hidutil property --get "UserKeyMapping"

리매핑이 적용됐다면 아래처럼 HIDKeyboardModifierMappingSrc / HIDKeyboardModifierMappingDst 값이 출력됩니다. 출력은 16진수가 아니라 10진수임에 주의하세요.

(
        {
        HIDKeyboardModifierMappingDst = 30064771180;
        HIDKeyboardModifierMappingSrc = 30064771303;
    }
)

아래 표로 10진수 값이 어떤 키에 해당하는지 확인할 수 있습니다.

키	16진수	10진수
오른쪽 Alt(Option)	0x7000000E6	30064771302
오른쪽 커맨드 / 오른쪽 Win	0x7000000E7	30064771303
한/영 키 (LANG1)	0x700000090	30064771216

--dst로 지정 가능한 매핑 대상 키는 아래와 같습니다 (기본값 F17). F20은 시스템 설정 단축키 등록이 되지 않아 지원하지 않습니다(왜 F17인가 참고).

키	16진수	10진수
F13	0x700000068	30064771176
F14	0x700000069	30064771177
F15	0x70000006A	30064771178
F16	0x70000006B	30064771179
F17 (기본값)	0x70000006C	30064771180
F18	0x70000006D	30064771181
F19	0x70000006E	30064771182

위 예시는 오른쪽 커맨드(30064771303)가 F17(30064771180)으로 매핑된 상태입니다.

LaunchDaemon이 제대로 등록됐는지는 아래 명령으로 확인할 수 있습니다.

sudo launchctl print system/local.hangeul-keymap

문제 해결

• 키를 눌러도 한/영이 안 바뀐다 — 설치 후 설정 1번을 안 한 경우가 대부분입니다. 리매핑은 키를 F17(또는 --dst로 지정한 키)으로 바꿔줄 뿐, 단축키 등록은 사람이 직접 해야 합니다.
• 시스템 설정 단축키 칸에 아무것도 안 잡힌다 — 리매핑이 적용되지 않은 것입니다. 위 제대로 적용됐는지 확인으로 확인하고, 안 잡혀 있으면 install을 다시 실행하세요.
• 내 키보드의 한/영 키가 LANG1인지 오른쪽 Alt인지 모르겠다 — --right-alt --hangeul-key를 함께 지정하면 어느 쪽이든 동작합니다. 실제로 보내는 쪽만 매핑되고 나머지는 아무 영향이 없습니다.
• --device로 설치했는데 안 먹는다 — 목록에서 고른 VendorID/ProductID가 실제 사용 중인 키보드가 맞는지 list로 다시 확인하세요. 무선 키보드는 리시버(동글) 쪽 ID로 잡히기도 합니다.

제거

sudo ./hangeul-keymap-setup.sh uninstall

LaunchDaemon을 내리고 plist를 지운 뒤 현재 세션의 리매핑까지 해제합니다. 이전 버전(local.keymap)으로 설치했던 plist가 남아 있다면 그것도 함께 정리합니다.

설치할 때 사람이 직접 바꾼 시스템 설정(입력 소스 전환 단축키, Caps Lock 관련 설정 두 가지)은 스크립트가 건드릴 수 없으므로, 제거 후 출력되는 안내를 보고 되돌려주세요.

특히 전환 단축키(F17 또는 --dst로 지정했던 키)를 그대로 둔 채 Caps Lock 전환도 꺼져 있으면 한/영 전환 수단이 하나도 남지 않을 수 있습니다. 둘 중 하나는 꼭 되살려주세요.

동작 방식

/Library/LaunchDaemons/local.hangeul-keymap.plist를 만들어, 부팅 시 아래와 같은 명령이 실행되도록 등록합니다. 지정한 키가 여러 개면 그만큼 엔트리가 늘어납니다. 예를 들어 --right-alt --hangeul-key로 설치하면:

hidutil property --set '{"UserKeyMapping":[
  {"HIDKeyboardModifierMappingSrc":0x7000000E6,
   "HIDKeyboardModifierMappingDst":0x70000006C},
  {"HIDKeyboardModifierMappingSrc":0x700000090,
   "HIDKeyboardModifierMappingDst":0x70000006C}]}'

--dst로 다른 키를 지정하면 두 엔트리의 HIDKeyboardModifierMappingDst 값이 그 키의 코드로 바뀝니다 (아래 표 참고).

--device로 설치하면 같은 딕셔너리에 "HIDMatch":{"VendorID":..., "ProductID":...}가 추가되어, 지정한 키보드 한 대에만 리매핑이 적용됩니다.

사용된 HID 코드는 아래와 같습니다. 좌/우 키는 서로 다른 값을 가집니다.

키	코드
오른쪽 Alt(Option)	0x7000000E6
오른쪽 커맨드 / 오른쪽 Win	0x7000000E7
한/영 키 (LANG1)	0x700000090
F13~F19 (--dst로 선택 가능)	0x700000068 ~ 0x70000006E
F17 (매핑 대상, 기본값)	0x70000006C

이 외에 시스템 파일을 수정하거나 백그라운드에 상주하는 프로세스는 없습니다.

알려진 제한

• 블루투스 키보드를 껐다 켜거나 새 키보드를 연결한 뒤 리매핑이 풀렸다는 보고가 있습니다. 이 경우 재부팅하거나 install을 다시 실행하면 됩니다.
• --device 모드로 설치한 경우, uninstall의 즉시 해제가 적용되지 않을 수 있습니다. 재부팅하면 확실히 초기화됩니다.
• 리매핑한 키의 본래 기능은 사용할 수 없게 됩니다. 오른쪽 Alt를 쓰는 경우 Option 조합 특수문자(®, ≠, … 등)를 오른쪽 키로는 입력할 수 없습니다. 왼쪽 키는 그대로 남아 있어 실사용에 큰 지장은 없습니다.
• 시스템 설정 > 보조 키에서 Command/Option을 서로 바꿔 놓았더라도, hidutil은 그보다 낮은 계층에서 동작하므로 매핑 대상은 물리적인 키 위치 기준입니다.
• 리매핑 대상이 늘어날수록 원래 기능을 잃는 키도 늘어납니다. 필요한 키만 고르는 편이 낫고, 특히 오른쪽 커맨드는 맥에서 자주 쓰이므로 윈도우용 키보드가 아니라면 굳이 여러 개를 걸 이유가 없습니다.
• F13~F19 중 하나를 Stream Deck, Keyboard Maestro, BetterTouchTool 등 다른 앱의 단축키로 이미 쓰고 있다면 기본값(F17)과 충돌할 수 있습니다. --dst로 겹치지 않는 다른 키를 지정하세요.
• F20은 --dst로 지정할 수 없습니다. HID 리매핑은 되지만 macOS Sequoia의 시스템 설정 단축키 입력 칸이 F20을 등록받지 않는 것을 확인했습니다.

라이선스

MIT