Kanata：开源跨平台键盘重映射工具 #

Kanata 是什么？ #

Kanata 是一款开源、跨平台的键盘重映射（keyboard remapper）工具，通过一份纯文本配置文件，把任意物理按键重新定义为其他按键、组合键、宏或层切换动作。它面向希望摆脱厂商驱动限制、追求个性化键盘布局的开发者、文字工作者和效率爱好者。与只支持单一品牌的键盘改键软件不同，Kanata 工作在操作系统底层输入层，因此对键盘型号、轴体和品牌没有任何要求，普通键盘也能获得类似高端客制化键盘的分层与双功能键体验。配置文件使用类 Lisp 的 S-expression 语法，支持热重载，修改后无需重启软件即可生效。

Kanata 有哪些亮点特色？ #

• 跨平台统一配置：同一份 kanata.kbd 配置文件可在 Windows、macOS 和 Linux 上复用，换设备或换系统时无需重新学习一套工具链，配置迁移成本极低。
• tap-hold 双功能键：单个按键点按与长按可绑定不同动作，例如轻按 CapsLock 输出 Escape、长按则作为 Ctrl 使用，是 Kanata 最受欢迎的核心能力之一。
• 多层键盘（Layers）：支持定义任意数量的映射层，并通过专用按键在层之间切换，实现"一键进入符号层/数字层/方向键层"的高效输入方案。
• 宏与按键序列：可录制多步宏动作，也能把多个按键的同时按下识别为一条命令（chords），用于触发常用快捷键或应用程序。
• 应用感知的层切换：可根据当前处于焦点的应用程序或窗口自动切换映射层，让同一个按键在编辑器中是 Ctrl、在浏览器中是导航键。
• 配置热重载：保存配置文件后即时生效，无需重启 Kanata，也无需注销系统，调试新布局时的迭代速度非常快。
• 内置 TCP 服务器：可开启本地 TCP 服务端口，用外部脚本或程序动态触发按键动作，方便与自动化流程集成。
• 开源免费、社区活跃：采用 LGPL 系列开源许可（具体许可条款以官方仓库为准），源码托管于 GitHub，持续接受社区提交的问题反馈与功能改进。

免费下载 Kanata #

以下为官方提供的各平台安装包，点击链接即可下载。请根据自己的操作系统与 CPU 架构选择对应版本。

说明：各安装包的具体版本号官网未说明。如果你更倾向自行编译，也可以通过 Rust 的 Cargo 工具链从源码构建，具体命令以官方仓库说明为准。

Kanata 如何使用？ #

Kanata 的使用方式围绕"配置文件 + 后台运行"展开，基本流程如下：

1. 准备配置文件。在任意目录新建一个文本文件（社区通用命名为 kanata.kbd），用类 Lisp 的 S-expression 语法书写映射规则。一个最小的结构包含三部分：defcfg 全局配置、defsrc 声明需要接管的物理按键、deflayer 定义映射后的输出。

   (defcfg
     process-unmapped-keys yes
   )
   
   (defsrc
     caps h j k l
   )
   
   (deflayer base
     esc  left down up right
   )
   

   上面这段配置的含义是：接管 CapsLock 与 h/j/k/l 五个键，在默认层中把 CapsLock 变成 Esc，把 hjkl 变成方向键。更多动作类型（tap-hold、macro、layer-switch 等）请参考官方文档。

2. 启动 Kanata 并指定配置文件。在终端或命令行中执行 kanata --cfg 配置文件路径，程序会读取配置并立即接管键盘。

3. 验证按键是否生效。打开任意文本框，按下被映射的按键，确认输出符合预期。若无反应，优先检查权限问题（见下文常见问题）。

4. 按需切换映射层或触发宏。配置中如果定义了层切换键，按下它即可临时进入另一个映射层，松开或再次按下返回默认层。

5. 修改配置并热重载。直接编辑配置文件并保存，Kanata 会自动重新加载，无需重启进程。调试新布局时建议保留一个已知可用的配置作为回退方案。

此外，Kanata 支持开启 TCP 服务端口，通过外部程序发送指令动态触发按键，适合与自动化脚本联动。具体参数名称与用法以官方文档为准。

Kanata 的常见问题？ #

Kanata 需要安装额外驱动吗？

视平台而定。Windows 上运行 Kanata 通常需要管理员权限，并根据官方说明配合底层输入驱动使用；macOS 上需要安装虚拟 HID 驱动（社区通常使用 Karabiner 系列的 DriverKit 驱动）并授予输入监控权限；Linux 上则需要 /dev/uinput 的读写权限，一般通过添加 udev 规则解决。具体驱动版本与安装步骤请以官方文档为准，官网未说明统一的驱动安装器。

运行时提示权限不足或按键无效怎么办？

最常见的原因是权限缺失。Linux 用户请确认当前账户在 input 用户组或已配置 /dev/uinput 的 udev 规则；macOS 用户需在"系统设置 → 隐私与安全性"中为终端或 Kanata 授权"输入监控"与"辅助功能"；Windows 用户请以管理员身份运行。授权后需要重启 Kanata 才能生效。

支持哪些操作系统和 CPU 架构？

官方提供 Windows、macOS 与 Linux 三个平台的构建产物，涵盖 x64 与 arm64 架构（macOS 与 Windows 提供 arm64 包，Linux 提供 x64 包）。Linux ARM 等其他架构官网未说明是否提供预编译包，可尝试自行编译。

修改配置文件后需要重启吗？

不需要。Kanata 支持配置热重载，保存文件后新布局即时生效，这也是它比多数厂商改键软件更高效的环节之一。

Wayland 环境下能用吗？

Linux 桌面环境差异较大。参考社区常见反馈，Kanata 在 X11 下兼容性更好；Wayland 下受限于合成器的输入接口，部分依赖窗口信息的功能（如按应用切换层）可能不可用或表现不同，建议以官方文档与 issue 区说明为准。

Kanata 与 QMK/VIA、AutoHotkey 有什么区别？

Kanata 工作在操作系统层面，因此不挑键盘硬件，任何普通键盘都能用；相比 AutoHotkey 这类脚本工具，它更专注键盘映射本身，提供 tap-hold、多层布局、按键序列等更接近固件层面的语义，配置文件也更结构化。

Kanata 如何安装？ #

Windows #

1. 下载 windows-binaries-x64.zip（或 ARM 设备选择 windows-binaries-arm64.zip）。
2. 将压缩包解压到固定目录，例如 C:\Program Files\kanata\，避免放在临时目录。
3. 根据官方文档安装所需的底层输入驱动（Windows 平台通常需要额外的拦截驱动支持）。
4. 以管理员身份打开 PowerShell 或 CMD，切换到解压目录，执行 kanata.exe --cfg 配置路径 验证是否生效。
5. 如需开机自启，可创建计划任务并勾选"使用最高权限运行"。

macOS #

1. 下载对应架构的压缩包：Apple Silicon 芯片选择 macos-binaries-arm64.zip，Intel 芯片选择 macos-binaries-x64.zip。
2. 解压后将可执行文件移动到 /usr/local/bin/ 等 PATH 目录下。
3. 安装官方要求的虚拟 HID 驱动（社区常用 Karabiner 的 DriverKit 驱动）。
4. 在"系统设置 → 隐私与安全性"中授予输入监控与辅助功能权限。
5. 终端执行 kanata --cfg 配置路径 启动。也可以使用 Homebrew 等包管理器安装，具体 formula/cask 名称官网未说明。

Linux #

1. 下载 linux-binaries-x64.zip 并解压，或使用 cargo install kanata 从源码构建安装。
2. 为当前用户配置 /dev/uinput 访问权限，常见做法是新建 udev 规则并把自己加入相应用户组，然后重新登录。
3. 终端执行 kanata --cfg 配置路径。若使用 interception-tools 方案，需要按官方说明安装对应组件并传入相应启动参数。
4. 如需开机自启，可编写 systemd 用户服务单元。

提示：无论哪个平台，建议先从一个极简配置开始验证链路是否通畅，再逐步加入复杂的 tap-hold 与多层逻辑。

Kanata 如何卸载？ #

Windows #

1. 先结束正在运行的 kanata.exe 进程（任务管理器中结束，或关闭对应终端窗口）。
2. 如果设置了开机自启的计划任务，请在"任务计划程序"中删除该任务。
3. 删除 Kanata 的安装目录，例如 C:\Program Files\kanata\。
4. 如果安装过配套的底层输入驱动，请在"控制面板 → 程序和功能"中将其卸载，否则可能影响其他键盘软件的运行。
5. 手动删除个人配置文件（通常位于你自选的目录，Kanata 不会自动清理）。

macOS #

1. 结束 Kanata 进程。
2. 删除可执行文件，例如 sudo rm /usr/local/bin/kanata。
3. 如果通过 Homebrew 安装，执行 brew uninstall 对应的 formula/cask。
4. 若不再需要虚拟 HID 驱动，可在系统设置或驱动自带的卸载程序中移除。
5. 删除个人配置文件与相关日志。

Linux #

1. 结束进程，若配置了 systemd 服务，先执行 systemctl --user stop 与 systemctl --user disable 并删除对应单元文件。
2. 删除二进制文件；若通过 Cargo 安装，可执行 cargo uninstall kanata。
3. 删除之前为 /dev/uinput 添加的 udev 规则文件，并重新加载 udev 规则。
4. 删除个人配置文件。若曾把自己加入 input 用户组且不再需要，可一并移除该组成员身份。

说明：Kanata 为绿色运行方式，主体不写入系统注册表或系统级配置目录，卸载后一般不会残留服务，但配置文件、日志与 udev 规则需要用户手动清理。