---
title: macOS 26.4 beta 1下Karabiner失效问题&应急方案
date: 2026-02-21
tags:
  - macOS
excerpt: 升级到 macOS 26.4 beta 后，Karabiner-Elements 的内置键盘映射失效。已确认这是系统层面的权限收紧，短期内无法通过用户侧授权或重签名解决。可行的替代方案是使用 Apple 官方的 hidutil 命令实现常见的单键映射，并通过 LaunchAgent 持久化配置。
---

> [!NOTE]
> macOS 26.4 beta 3下Karabiner-Elements已可以正常工作
>
> My Karabiner-Elements Version: 15.9

## Problem

[Issue #4402](https://github.com/pqrs-org/Karabiner-Elements/issues/4402#issuecomment-3916863747) 中有人定位到了问题：Karabiner Element 缺少 **`com.apple.hid.manager.user-access-protected`** 这个 entitlement。

```log
error    20:29:23.547646+0100    Karabiner-Core-Service    IOServiceOpen failed: 0xe00002c7
error    20:29:23.548438+0100    kernel    IOHIDLibUserClient:0x100001850 Insufficient permissions to access device for PID: 3591, missing entitlement: com.apple.hid.manager.user-access-protected
error    20:29:23.548444+0100    kernel    AppleHIDTransportHIDDevice:0x100000aac failed to create user client: 0xe00002c7
```

### Entitlement？🤨

>  Entitlements are key–value pairs that grant an app access to system‑protected resources or capabilities.
>
>  —— Apple Developer Documentation: _Security Entitlements_

大致了解了一下，entitlement就是应用访问受保护资源所需申请的权限，运行 `{sh} codesign -d --entitlements - <path>` 可以查看 App 申请的权限:

<script data-swup-reload-script type="module" src="/js/components/text-image-section.js"></script>
<text-image-section image="https://tse2.mm.bing.net/th/id/OIP.G9RcJ0iFGId0JV1xodaE2QHaFa?rs=1&pid=ImgDetMain&o=7&rm=3" alt="403 forbidden" width="250px">

而 `com.apple.hid.manager.user-access-protected` 是 Apple 内部使用的私有 entitlement，第三方 App 无法申请。

在macOS 26.4 beta 1中，对内置键盘启用了更严格的 HID(Human Interface Devices) 权限检查，因此 Karabiner-Elements 无权访问。

</text-image-section>

## Workaround

`hidutil` 是 Apple 官方提供的 HID 映射工具，支持简单的单键映射需求

- <kbd style="font-size: 1.5em;">⇪</kbd> to <kbd style="font-size: 1.5em;">⌘</kbd>
- Right <kbd style="font-size: 1.5em;">⌘</kbd> to Left <kbd style="font-size: 1.5em;">⌃</kbd>

例如对上面的映射需求，在终端执行 `{sh} hidutil property --set <json_content>` 即可，例如:

```sh
$ hidutil property --set '{"UserKeyMapping":[
            {
              "HIDKeyboardModifierMappingSrc": 0x700000039,
              "HIDKeyboardModifierMappingDst": 0x7000000E3
            },
            {
              "HIDKeyboardModifierMappingSrc": 0x7000000E7,
              "HIDKeyboardModifierMappingDst": 0x7000000E0
            },
        ]}'

# [OUTPUT]
UserKeyMapping:(
        {
        HIDKeyboardModifierMappingDst = 30064771299;
        HIDKeyboardModifierMappingSrc = 30064771129;
    },
        {
        HIDKeyboardModifierMappingDst = 30064771296;
        HIDKeyboardModifierMappingSrc = 30064771303;
    }
)
```

### Persistence

`hidutil` 的设置在重启后会失效。可以在 `~/Library/LaunchAgents/` 创建个 plist 文件，它会在开机后自动执行。不想手动写的，可以用可视化 App👉 [hidutil key remapping generator](https://hidutil-generator.netlify.app/)

```xml ~/Library/LaunchAgents/com.local.KeyRemapping.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.local.KeyRemapping</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/hidutil</string>
        <string>property</string>
        <string>--set</string>
        <string>{"UserKeyMapping":[{"HIDKeyboardModifierMappingSrc":0x700000039,"HIDKeyboardModifierMappingDst":0x700000029}]}</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>
```

## Outro

哔站推送视频，说 macOS 26.4 beta 1 版本中的 safari 支持 compact mode 了，虽然我不用 safari，为了图新鲜就升级了

一开始以为和往常一样，简单的重启电脑/重装 Karabiner 就好了。然而这次没效果

去 GitHub 搜一下 issue 才知道，Apple 收紧权限，短时间内 Karabiner 算是寄了

<div class="rip-container">

R.I.P, my beloved friends

- Chrome DevTools Theming 🪦
- IntelliCode extensions in VS Code 🪦
- macOS's Launchpad 🪦
- ~~Karabiner-Elements on macOS Tahoe betas~~ 🪦

</div>

<style>
.rip-container {
  margin: 2.5rem auto;
  padding: 2rem 2.5rem;
  max-width: 480px;
  background: linear-gradient(
    135deg,
    var(--mantle),
    var(--crust)
  );
  border: 1px solid var(--surface0);
  border-radius: 2px;
  text-align: center;
  font-family: var(--font-serif);
  color: var(--subtext0);
}

.rip-container p {
  color: var(--rosewater);
  font-family: "homemade-apple", var(--font-handwriting);
  font-style: italic;
  font-size: 1.35em;
  font-weight: 400;
  letter-spacing: 0.02em;
  margin-bottom: 1.5rem;
}

.rip-container ul {
  list-style: none;
  padding: 0;
  margin: 0;
  font-size: 0.9em;
  letter-spacing: 0.01em;
}

.rip-container li {
  padding: 0.35rem 0;
  opacity: 0.75;
  transition: opacity 0.2s ease;
}

.rip-container li:hover {
  opacity: 1;
}
</style>