macOS 快捷键冲突不再抓瞎：用 HotkeyClash 扫描系统、应用与 Karabiner 的按键争端

对于 Mac 重度用户来说，同时运行 Raycast、Karabiner、窗口管理器以及系统快捷键时，经常会碰到一个诡异的问题：某个用得滚瓜烂熟的组合键突然失效了，你却完全搞不清到底是哪个“神仙”把它抢走了。

HookeyClash 正是来解决这种“按键争端”的。它是由 Wunderlandmedia 开发的一款 macOS 菜单栏工具，核心职责就是诊断系统、正在运行的应用，以及 Karabiner/skhd 等自动化工具之间的快捷键冲突。

它是如何排查冲突的？

这款工具会扫描以下三类来源，帮你把潜在的雷区统统挖出来：

第一类：正在运行的 App。
HookeyClash 会通过 macOS 的辅助功能 API 读取各个应用菜单栏里配置的快捷键。因此，在首次使用时，你需要为它授予辅助功能权限。

第二类：本地自动化配置。
它能够解析 Karabiner-Elements 的 karabiner.json 和 skhd 的 skhdrc 配置文件，这意味着那些由自动化工具定义的快捷键也一样会被纳入冲突检查的范围。

第三类：macOS 系统快捷键。
像 Spotlight、Mission Control、截图这类系统级的全局组合键，常常会与第三方工具发生静默冲突，这正是 HookeyClash 重点覆盖的排查对象。

它如何定义“冲突”？

HookeyClash 对冲突的判断非常务实，分了层级，而不是一刀切：

• 明确冲突：当两个全局快捷键撞在一起时，会被直接标记出来。
• 潜在冲突：如果一个全局快捷键和某个 App 菜单里的快捷键重叠，它就会被视为潜在冲突。因为这类问题通常很隐蔽，只会在那个特定的应用处于前台时才会发生。

只做检测，不替你做决定

一个很清晰的边界是：HookeyClash 只负责检测与展示。

它绝不会自作主张地去修改你的任何快捷键设定。在查出冲突之后，你需要亲自去系统设置、Raycast、Karabiner、skhd 或者对应的应用里，手动调整配置。

这种克制反而让人安心。毕竟，快捷键的修改牵涉到系统底层和多个第三方工具的复杂配置，如果擅自自动修改，很容易引发更麻烦的问题。HookeyClash 的定位更像个精准的排查仪表盘——它负责告诉你“哪里撞了”，而“如何修”的决定权完全在你手上。

极简与克制

在软件设计上，HookeyClash 也保持着同样的风格：

• 零外部依赖，基于 Apple 原生框架开发。
• 没有遥测数据收集，也没有账号体系或云端同步功能。
• 系统要求为 macOS 14+，同时支持 Apple Silicon 和 Intel 芯片。

目前，主流的安装方式是通过 GitHub Releases 下载 DMG 或 ZIP 安装包。当然，如果你喜欢动手，也可以使用 Xcode 16+ 克隆源码自行编译。请注意，通过 Homebrew cask 安装还只是一个未来计划，不能当作已支持的特性。

根据项目的路线图，未来还有不少值得期待的方向，包括：支持解析 Keyboard Maestro、BetterTouchTool、Hammerspoon、Alfred、Raycast 等更多工具的配置；增加“测试此快捷键”模式；支持导出 Markdown 格式的冲突报告；以及实现启动或退出时的自动重新扫描。

关于项目

项目由 Wunderlandmedia 开发，主要使用 Swift（89%） 编写，采用 GPL-2.0 协议 开源。

项目地址：https://github.com/Wunderlandmedia/HotkeyClash