ControllerKeys for macOS
May 28, 2026 · View on GitHub
ControllerKeys for macOS
一款原生 macOS 应用程序，可将 Xbox、Xbox Elite Series 2、DualSense（PS5）、DualShock 4（PS4）、Nintendo Joy-Con、Switch Pro 手柄、Steam Controller 以及 300+ 款第三方手柄的输入映射为键盘快捷键、鼠标移动、滚动/缩放/平移操作、宏、脚本、Webhook 和系统命令。支持带滑动输入的屏幕键盘、DualSense 与 Steam Controller 触摸板和陀螺仪、JavaScript 脚本引擎、按应用自动切换配置文件、实时低延迟输入模式，以及通过 Wi-Fi 在两台 Mac 之间无缝传递手柄控制权。
我开发这款应用是因为我想用 Xbox 手柄进行 vibe coding（氛围编程），同时保留所有常用快捷键。
市面上的同类应用要么功能不足，要么不够灵活。
随着 Whisper 语音转录技术的兴起，只需将任意按键绑定到你喜欢的语音转录程序（我用的是开源的 VoiceInk），仅凭手柄就能实现完整的文字输入。
后来我发现，PS5 DualSense 手柄自带的触摸板非常适合用来控制鼠标。ControllerKeys 现已支持 DualSense、DualSense Edge、DualShock 4、Xbox Series X|S、Xbox Elite Series 2、Nintendo Joy-Con、Switch Pro 手柄、Steam Controller 以及 300+ 款第三方手柄。
为什么选择这款应用？
macOS 上有其他手柄映射工具，但没有一款能满足我的所有需求：
| 功能 | ControllerKeys | Joystick Mapper | Enjoyable | Controlly |
|---|---|---|---|---|
| DualSense 触摸板与象限映射 | ✅ | ❌ | ❌ | ❌ |
| Steam Controller 支持（无需 Steam） | ✅ | ❌ | ❌ | ❌ |
| 多点触控手势 | ✅ | ❌ | ❌ | ❌ |
| 陀螺仪瞄准与手势 | ✅ | ❌ | ❌ | ❌ |
| JavaScript 脚本引擎 | ✅ | ❌ | ❌ | ❌ |
| 滑动输入屏幕键盘 | ✅ | ❌ | ❌ | ❌ |
| 组合键映射（多键组合） | ✅ | ❌ | ❌ | ✅ |
| 按键序列连招 | ✅ | ❌ | ❌ | ❌ |
| 层级（替代映射集） | ✅ | ❌ | ❌ | ❌ |
| 层级独立摇杆模式 | ✅ | ❌ | ❌ | ❌ |
| 自定义摇杆方向绑定（WASD、方向键等） | ✅ | ❌ | ❌ | ❌ |
| 宏与系统命令 | ✅ | ❌ | ❌ | ❌ |
| HTTP Webhook 与 OBS 控制 | ✅ | ❌ | ❌ | ❌ |
| 实时低延迟按键模式 | ✅ | ❌ | ❌ | ❌ |
| Mac 之间手柄无缝传递（Universal Control 风格） | ✅ | ❌ | ❌ | ❌ |
| 链接手柄（手柄连接时自动切换配置） | ✅ | ❌ | ❌ | ❌ |
| 配置快照与撤销（历史标签） | ✅ | ❌ | ❌ | ❌ |
| 屏幕键盘与命令轮盘 | ✅ | ❌ | ❌ | ❌ |
| 附设置指南的社区配置文件 | ✅ | ❌ | ❌ | ❌ |
| 应用专属自动切换 | ✅ | ❌ | ❌ | ❌ |
| OBS 直播画面叠加层 | ✅ | ❌ | ❌ | ❌ |
| Xbox Elite Series 2 背键 | ✅ | ❌ | ❌ | ❌ |
| Nintendo Joy-Con 与 Pro 手柄 | ✅ | ❌ | ❌ | ❌ |
| DualSense Edge（Pro）支持 | ✅ | ❌ | ❌ | ❌ |
| DualShock 4（PS4）触摸板与陀螺仪 | ✅ | ❌ | ❌ | ❌ |
| DualSense LED 与麦克风控制 | ✅ | ❌ | ❌ | ❌ |
| 拖放交换映射 | ✅ | ❌ | ❌ | ❌ |
| 使用统计与年度总结 | ✅ | ❌ | ❌ | ❌ |
| 多语言（EN / 简中 / 繁中 / DE / JA） | ✅ | ❌ | ❌ | ❌ |
| 第三方手柄（约 313 款） | ✅ | ✅ | ✅ | ✅ |
| 原生 Apple Silicon 支持 | ✅ | ❌ | ❌ | ✅ |
| 持续维护中（2026） | ✅ | ❌ | ❌ | ✅ |
| 开源 | ✅ | ❌ | ✅ | ❌ |
Joystick Mapper 是一款付费应用，已多年未更新，缺乏对现代手柄的支持。Enjoyable 是开源项目，但自 2014 年起已停止维护，不支持 DualSense。Controlly 是一款较新的优秀应用，但不支持 DualSense 触摸板手势、屏幕键盘或快捷命令。Steam 的手柄映射仅在 Steam 游戏内有效，无法全局使用。
ControllerKeys 是唯一一款完整支持 DualSense 触摸板的选择，非常适合 vibe coding 和沙发计算等需要精确鼠标控制的场景。
功能特性
-
按键映射：将任意手柄按键映射为键盘快捷键
- 仅修饰键映射（⌘、⌥、⇧、⌃）
- 仅按键映射
- 修饰键 + 按键组合
- 长按触发替代操作
- 双击触发额外操作
- 和弦映射（多个按键 → 单个操作）
- 按键序列（有序组合，如 上-上-下-下）
- 自定义提示标签
-
层级：创建替代按键映射集，通过按住指定按键激活
- 最多 3 个层级（基础层 + 2 个附加层）
- 按住激活按键时临时启用
- 未映射按键穿透到下层
- 为层级命名（如"战斗模式"、"导航模式"）
- 每个层级可独立设置 DualSense/DualShock 4 灯带颜色（从 12 色调色板自动分配）
- 层级独立摇杆模式：每个层级可独立将左/右摇杆设为鼠标 / 滚动 / WASD / 自定义；松开激活键即恢复基础模式
- 层级感知手柄缩略图：通过
BASE/LAYER <名称>标签和层级配色的轮廓，直观显示当前层级覆盖了哪些按键、摇杆、肩键、方向键与触摸板区域
-
自定义摇杆方向映射：将摇杆模式设为自定义后，8 个方向（4 个基本方向 + 4 个对角线）即变为可在手柄图上直接绑定的"按键"
- 一键预设 WASD 或方向键
- 对角线方向同时按住基本方向键（如 W+D 实现 Factorio 等游戏中的右前移动）
- 摇杆方向支持长按、双击、组合键与按键序列，与物理按键完全一致
-
实时输入低延迟模式：可按配置文件启用的 Input 选项，按下时立即发送 key-down、松开时立即发送 key-up，跳过组合键检测窗口以降低延迟
- 双击、长按、按住自动重复以及组合键映射仍走标准时序路径，保留高级交互行为
-
Universal Control 风格 Mac-to-Mac 接力：在两台运行 ControllerKeys 的 Mac 之间配对，将手柄光标推到指定屏幕边缘即可把鼠标、键盘和映射操作接力到第二台 Mac
- 接收方 Mac 会以自身的活动配置文件执行映射，因此在主机上打开 Finder 的组合键也会在远端打开 Finder
- 仅在本地网络生效（私有/链接本地 IPv4/IPv6、Tailscale
100.64.0.0/10、本机） - 帧使用 HMAC-SHA256 验证，密钥保存于钥匙串中；超大、重放或被篡改的帧会被丢弃
- 滑动输入、屏幕叠加层与按键卡死清理也通过同一通道接力
-
链接手柄：将配置文件绑定到特定物理手柄，连接时自动激活（前台应用有自己的关联配置时，链接应用仍优先）
-
JavaScript 脚本：使用 JavaScriptCore 驱动的自定义自动化脚本
- 完整 API：
press()、hold()、click()、type()、paste()、delay()、shell()、openURL()、openApp()、notify()、haptic()等 - 应用感知脚本：
app.name、app.bundleId、app.is()实现上下文敏感操作 - 触发上下文（
trigger.button、trigger.pressType、trigger.holdDuration） screenshotWindow()API 截取当前聚焦窗口- 每脚本独立的持久状态，跨调用保留
- 内置示例库，包含即用脚本
- 带语法参考和 AI 提示助手的脚本编辑器
- 完整 API：
-
宏：多步骤操作序列
- 按键、输入文本、延迟、粘贴、Shell 命令、Webhook 和 OBS 步骤
- 可配置输入速度
- 可分配到按键、组合键、长按和双击
-
系统命令：超越按键模拟的自动化操作
- 启动应用：打开任意应用程序
- Shell 命令：静默运行或在终端窗口中执行命令
- 打开链接：在默认浏览器中打开 URL
-
HTTP Webhook：从手柄按键和组合键发送 HTTP 请求
- 支持 GET、POST、PUT、DELETE 和 PATCH 方法
- 可配置请求头和请求体
- 在光标上方显示响应状态的视觉反馈
- 成功或失败时的触觉反馈
-
OBS WebSocket 命令：直接从手柄按键控制 OBS Studio
-
摇杆控制：
- 左摇杆 → 鼠标移动（或 WASD 键）
- 右摇杆 → 滚动（或方向键）
- 可配置灵敏度和死区
- 按住修饰键（默认 RT）进入精确鼠标模式，带光标高亮
- 可禁用摇杆输入
-
陀螺仪瞄准与手势（DualSense/DualShock 4）：
- 陀螺仪瞄准：在精确模式下使用陀螺仪进行精确鼠标控制
- 1-Euro 滤波器实现无抖动平滑跟踪
- 手势映射：前后倾斜和左右转向触发操作
- 每配置文件独立的手势灵敏度和冷却时间滑块
-
触摸板控制（DualSense / DualShock 4 / Steam Controller）：
- 单指点击 → 左键点击
- 双指点击 → 右键点击
- 双指滑动 → 滚动
- 双指捏合 → 缩放
- 象限重映射：将触摸板分为 4 个区域，每个区域可分别配置触摸和点击的操作
- DualSense 与 Steam 触摸板均支持独立的滚动方向反转设置
-
屏幕键盘、命令和应用：使用屏幕键盘小组件快速选择应用、命令或键盘按键
- 滑动输入：在字母上滑动即可输入单词（SHARK2 算法）
- 方向键导航，浮动高亮
- 一键输入可配置的文本和终端命令
- 使用内置变量自定义输出文本
- 可自定义应用栏中显示和隐藏应用
- 带图标的网站链接
- 媒体键控制（播放、音量、亮度）
- 全局键盘快捷键切换显示
- 自动缩放以适应较小显示器
-
命令轮盘：GTA 5 风格的径向菜单，用于快速切换应用/网站
- 右摇杆导航，松开即激活
- 导航时触觉反馈
- 修饰键切换应用和网站
- 摇杆满偏时可强制退出和新建窗口
-
OBS 直播画面叠加层：浮动叠加层显示当前按下的按键，用于直播采集
-
激光笔叠加层：用于演示的屏幕指针
-
目录导航器：手柄驱动的文件浏览叠加层
- 右摇杆导航，B 键确认，Y 键关闭
- 鼠标支持和位置记忆
-
光标提示：在光标上方显示已执行操作的视觉反馈
- 按下按键时显示操作名称或宏名称
- 双击（2×）、长按（⏱）和组合键（⌘）操作徽章
- 按住修饰键时显示紫色"hold"徽章
-
年度总结：使用统计数据，附带可分享的个性类型卡片
- 追踪每次按键、宏、Webhook、应用启动等操作
- 基于使用模式的连续使用追踪和个性类型分析
- 将分享卡片复制到剪贴板，方便发布到社交媒体
-
配置文件系统：创建和切换多个映射配置
- 社区配置文件：浏览并导入预制配置，可选附带的 markdown 设置指南会在映射列表上方就地渲染（每个代码块都带复制按钮）
- 应用专属自动切换：将配置文件关联到应用程序
- 链接手柄自动切换：将配置文件绑定到特定物理手柄，连接时即激活
- Stream Deck V2 配置文件导入
- 自定义配置文件图标
- 侧边栏状态指示：配置行显示链接应用图标，以及表示实时模式、链接手柄、自定义图标和默认配置的紧凑徽章
-
历史与快照：在任何破坏性操作（删除配置、导入配置、恢复快照）前自动静默生成完整配置快照，并在专用的历史标签中展示
- 可恢复任意快照——恢复本身也会先生成快照，所以撤销操作也可撤销
- 快照保存在
~/.controllerkeys/snapshots/（最多保留 20 个）
-
导入安全提示：当导入的配置包含 Shell 命令、脚本或带 Shell 跟进的 Webhook 时，会弹出明确的同意面板，逐条列出所有可执行代码的入口——杜绝第三方配置静默执行
-
可视化界面：交互式手柄形状 UI，轻松配置
- 基于窗口大小的自动缩放 UI
- 按键映射交换，快速交换两个按键的映射
- VoiceOver 无障碍支持
- 分组标签导航：标签按 Map / Automate / Hardware / Activity 分组排列，并带 SF Symbol 图标；输入日志改为紧凑的"时间线"
- 可配置的区块可见性：可在"按键"标签中隐藏输入日志、组合键/序列/手势映射列表或触摸板区域
- 窗口背景不透明度滑块（设置 → 外观）用于调节液态玻璃在桌面之上的色调浓度
- 支持英文、简体中文、繁体中文、德语和日语
-
DualSense 支持：完整的 PlayStation 5 DualSense 手柄支持
- 完整触摸板支持，含多点触控手势
- 陀螺仪瞄准和手势检测
- USB 连接模式下可自定义 LED 颜色
- USB 连接模式下支持 DualSense 内置麦克风
- 麦克风静音按键映射
- 低电量（20%）、极低电量（10%）和充满（100%）时的电量通知
-
DualSense Edge（Pro）支持：完整支持 Edge 专属控制
- 功能按键和背部按键
- Edge 按键可用作层级激活器
-
DualShock 4（PS4）支持：完整的 PlayStation 4 DualShock 4 手柄支持
- 触摸板鼠标控制和手势（与 DualSense 相同）
- 全 UI 使用 PlayStation 风格按键标签和图标
- 通过 HID 监控支持 PS 按键（USB 和蓝牙）
-
Xbox Elite Series 2 支持：完整支持 Elite 专属硬件
- 4 个背键（P1–P4）可识别并映射
- 蓝牙模式下通过 IOKit HID 实现 Guide 键功能
- 无论固件版本如何，UI 中显示正确的手柄名称
- 同时兼容 Classic BT 和 BLE 两种固件
-
Steam Controller 支持：通过原始 HID 直接识别，无需运行 Steam
- 所有按键、摇杆、扳机、握把键以及电量报告均直接解析
- 两个方形触摸板可在整板或象限模式下使用，支持双触摸板捏合缩放及按区域绑定点击/触摸操作
- 使用 Steam Controller 原始陀螺仪比例实现陀螺仪瞄准与手势映射
- 支持触摸板触觉反馈，UI 中提供专属 Steam Controller 预览布局与 Steam 标识按键图标
- 自动屏蔽 macOS GameController 重复路径，避免输入被双重处理或触发额外的默认命令
-
第三方手柄支持：通过 SDL 数据库支持约 313 款手柄
- 8BitDo、罗技、PowerA、Hori 等
- 无需手动配置
-
辅助功能缩放支持：在 macOS 辅助功能缩放启用时，手柄输入仍能正常工作
- 光标、点击和滚动位置正确映射到缩放后的坐标
-
手柄锁定开关：锁定/解锁所有手柄输入，带触觉反馈
更多截图
Xbox Series X|S
组合键映射
摇杆设置
屏幕键盘小组件
屏幕键盘
DualSense（PS5）
按键映射
组合键映射
摇杆设置
屏幕键盘小组件
触摸板设置
多点触控触摸板
LED 自定义
麦克风设置
屏幕键盘
系统要求
- macOS 14.0 或更高版本
- Xbox Series X|S、Xbox Elite Series 2、DualSense（PS5）、DualSense Edge、DualShock 4（PS4）、Nintendo Joy-Con/Switch Pro、Steam Controller 或兼容的第三方手柄
- 辅助功能权限（用于输入模拟）
- 自动化权限（用于通过终端执行命令）
安装
下载 ControllerKeys - 获取最新的签名公证版本。
- 从 Gumroad 购买并下载 DMG 文件
- 打开 DMG，将应用拖入
/Applications - 启动应用，按提示授予辅助功能权限
- 使用屏幕键盘的终端命令功能时，系统会请求自动化权限
应用已使用 Apple 开发者 ID 证书签名并经过 Apple 公证，因此不会出现 Gatekeeper 警告。
信任与透明度
本应用需要辅助功能权限来模拟键盘和鼠标输入。我们理解这是一项敏感权限，因此本项目完全开源。
为什么这款应用是安全的：
-
开源：完整源代码可供审计。你可以验证应用对输入数据的全部操作。
-
无遥测或回传：应用不会主动连接任何服务器。仅在你明确配置 Webhook、OBS WebSocket 命令或导入社区配置文件时才会产生网络访问。
-
不收集数据：应用不会记录、存储或传输任何输入数据。手柄输入被实时转换为键盘/鼠标事件后立即丢弃。
-
签名与公证：发布版本使用 Apple 开发者 ID 证书签名并经过 Apple 公证，确保二进制文件与源代码一致且未被篡改。
辅助功能权限的用途：
- 模拟键盘按键（当你按下手柄按键时）
- 模拟鼠标移动（当你移动左摇杆时）
- 模拟滚轮事件（当你移动右摇杆时）
应用使用 Apple 的 CGEvent API 生成这些输入事件。这与辅助功能工具、自动化软件和其他输入重映射工具使用的是同一套 API。
项目结构
XboxControllerMapper/
├── XboxControllerMapperApp.swift # 应用入口
├── Info.plist # 应用配置
├── XboxControllerMapper.entitlements # 沙盒/权限
│
├── Models/
│ ├── ControllerButton.swift # Xbox 按键枚举
│ ├── KeyMapping.swift # 映射配置
│ ├── Profile.swift # 配置文件及覆盖
│ ├── ChordMapping.swift # 多键组合
│ └── JoystickSettings.swift # 摇杆配置
│
├── Services/
│ ├── ControllerService.swift # 手柄连接
│ ├── InputSimulator.swift # 键盘/鼠标模拟
│ ├── ProfileManager.swift # 配置文件持久化
│ ├── AppMonitor.swift # 前台应用检测
│ └── MappingEngine.swift # 映射协调
│
├── Views/
│ ├── MainWindow/
│ │ ├── ContentView.swift # 主窗口
│ │ ├── ControllerVisualView.swift # 手柄可视化
│ │ └── ButtonMappingSheet.swift # 按键配置
│ ├── MenuBar/
│ │ └── MenuBarView.swift # 菜单栏弹出窗口
│ └── Components/
│ └── KeyCaptureField.swift # 快捷键捕获
│
└── Utilities/
└── KeyCodeMapping.swift # 键码常量
默认映射
| 按键 | 默认操作 |
|---|---|
| A | 回车 |
| B | Escape |
| X | 空格 |
| Y | Tab |
| LB | ⌘（按住） |
| RB | ⌥（按住） |
| LT | ⇧（按住） |
| RT | ⌃（按住） |
| 方向键 | 箭头键 |
| Menu | ⌘ + Tab |
| View | 调度中心 |
| Xbox | 启动台 |
| 左摇杆按下 | 左键点击 |
| 右摇杆按下 | 右键点击 |
| 左摇杆 | 鼠标 |
| 右摇杆 | 滚动 |
使用方法
- 通过蓝牙或 USB 连接手柄（系统设置 → 蓝牙）
- 启动 ControllerKeys
- 按提示授予辅助功能权限
- 点击手柄可视化界面上的任意按键来配置映射
- 使用菜单栏图标快速启用/禁用和切换配置文件
参与贡献
欢迎贡献代码！如果你想参与：
- Fork 本仓库
- 创建功能分支（
git checkout -b feature/amazing-feature） - 进行修改
- 如果可能，请使用 Xbox 和 DualSense 手柄进行充分测试
- 提交更改（
git commit -m 'Add amazing feature'） - 推送到分支（
git push origin feature/amazing-feature） - 创建 Pull Request
请确保代码遵循现有风格，并对复杂逻辑添加适当注释。
功能建议
有新功能的想法？欢迎提出！
- 在 GitHub 上创建 Issue，添加
feature request标签 - 描述功能及其解决的问题
- 如果适用，附上示意图或示例
呼声较高的功能更有可能被实现。欢迎为你认为有用的现有功能建议投票。
问题与 Bug 报告
发现 Bug？请协助报告：
- 查看现有 Issue 以避免重复
- 创建新 Issue，包含以下信息：
- macOS 版本
- 手柄型号（Xbox Series X|S、Xbox One、DualSense 等）
- 连接方式（蓝牙或 USB）
- 复现步骤
- 预期行为与实际行为
- 如适用，附上截图
提供的细节越多，诊断和修复问题就越容易。
许可证
源代码可查看 - 详见 LICENSE。
源代码开放用于透明度和安全审计。官方二进制文件可在 Gumroad 购买。