Настройка Karabiner-Elements для переназначения клавиш на macOS

Переназначение клавиш на Mac через Karabiner-Elements делается в двух режимах: Simple Modifications (1→1) и Complex Modifications (условия, Hyper, tap/hold). Главное — один раз выдать правильные разрешения macOS и проверять key_code в EventViewer.

Установка и разрешения macOS

Karabiner-Elements работает через перехват ввода и виртуальное HID-устройство, поэтому без разрешений переназначение может “не применяться”, даже если приложение установлено.

Проверьте 3 пункта в системных настройках:

1. Login Items / Background Services — фоновые элементы Karabiner должны быть включены.
2. Input Monitoring (Мониторинг ввода) — разрешите Karabiner читать нажатия.
3. Driver Extensions — включите виртуальное устройство (VirtualHIDDevice).

Simple Modifications: быстрые переназначения 1→1

Используйте Simple Modifications, когда нужно простое соответствие “клавиша → клавиша”, без логики удержания:

• caps_lock → escape
• left_command ↔ left_option (удобно после Windows/Linux)
• right_option → right_control

Практика: начните именно с Simple — их проще отлаживать, и они реже конфликтуют.

Complex Modifications: Hyper Key, tap/hold и условия

Complex Modifications нужны для “магии”: tap vs hold, разные правила по устройствам, ограничения по приложениям и т. п. Конфиг лежит здесь:

~/.config/karabiner/karabiner.json

Ниже — два самых популярных рецепта (их добавляют как отдельные rule в Complex Modifications).

Caps Lock: удержание = Control, одиночное = Escape

{
  "description": "Caps Lock: Control when held, Escape when tapped",
  "manipulators": [
    {
      "type": "basic",
      "from": { "key_code": "caps_lock", "modifiers": { "optional": ["any"] } },
      "to": [{ "key_code": "left_control" }],
      "to_if_alone": [{ "key_code": "escape" }]
    }
  ]
}

Hyper Key на Caps Lock (⌃⌥⇧⌘), одиночное = Escape

{
  "description": "Caps Lock: Hyper when held, Escape when tapped",
  "manipulators": [
    {
      "type": "basic",
      "from": { "key_code": "caps_lock", "modifiers": { "optional": ["any"] } },
      "to": [
        {
          "key_code": "left_shift",
          "modifiers": ["left_command", "left_control", "left_option"]
        }
      ],
      "to_if_alone": [{ "key_code": "escape" }]
    }
  ]
}

Почему Hyper удобен: сочетание ⌃⌥⇧⌘ почти нигде не занято, поэтому вы получаете “чистые” хоткеи вида Hyper+H/J/K/L без конфликтов.

Частые ошибки

• Нажатия не меняются вообще: не выдан Input Monitoring / выключены фоновые службы / не включён Driver Extension.
• Не тот key_code: на ISO/нестандартных клавиатурах часто приходят коды вроде non_us_backslash. Проверяйте в EventViewer, что реально прилетает.
• Конфликт Complex-правил: манипуляторы проверяются сверху вниз, и обычно срабатывает первое подходящее правило. Поднимите нужное выше или сузьте условия.
• Ожидали “tap”, получили “hold”: слишком короткие/длинные тайминги или привычка удерживать клавишу чуть дольше. Начните с простого правила, затем подстраивайте поведение.

FAQ

Где лучше делать переназначения — в Simple или Complex?
Если это “1→1” без условий — Simple. Всё, что связано с удержанием, Hyper, условиями по устройствам/приложениям — Complex.

Можно ли сделать разные правила для встроенной и внешней клавиатуры?
Да. Самый надёжный путь — определить устройство в EventViewer и добавить condition по Vendor/Product ID (или настроить устройства в интерфейсе Karabiner).

Как понять, почему правило не сработало?

1. Откройте EventViewer и убедитесь, что нажатие видно. 2) Проверьте разрешения. 3) Убедитесь, что правило в списке Complex стоит выше конфликтующих и “ловит” правильный key_code.