Gold Keyboard Remaps 是一个 KernelSU 模块。它拦截指定的 Linux 输入事件,创建虚拟键盘,再把按键转换为单键、组合键或应用启动动作。
- 自动识别外接 USB、蓝牙和 HID 键盘,也支持手动选择输入节点。
- 支持单键映射、组合键映射和多个输出键。
- 保留独立的
Anland配置方案,进入沉浸时自动使用,退出后恢复原方案。 - 支持按键捕获,减少手动查找 Linux 按键名称的工作。
- 支持通过单键或组合键启动应用;在 ColorOS 上可选小窗启动和重复按键关闭。
- 提供 KernelSU WebUI,用于查看设备、编辑规则、保存配置和暂停模块。
- 已获得 root,并安装支持 WebUI 的 KernelSU Manager。
- 设备内核提供
/dev/uinput,外接键盘能出现在/dev/input/event*。 - 模块必须包含编译好的
bin/fn-remap,并具有0755权限。 - 只有使用 ColorOS 小窗或系统截屏规则时才需要
bin/coloros-window-launcher.jar;普通按键映射和普通应用启动不依赖它。
请使用维护者提供的 KernelSU 模块 ZIP:
- 打开 KernelSU Manager,进入“模块”。
- 选择“从存储安装”,选中模块 ZIP。
- 安装完成后重启设备,并确认模块已启用。
- 在模块详情中打开 WebUI。
本仓库当前是源码和部署材料,不是完整的可刷入 ZIP。直接压缩仓库根目录会因为缺少 bin/fn-remap 而无法运行。
最终模块目录至少应包含以下内容:
Gold_Keyboardremaps/
├── module.prop
├── service.sh
├── action.sh
├── customize.sh # 安装时清理旧版 Meta 布局
├── keylayout.sh # 升级清理脚本
├── config.conf
├── input-status # 运行时生成,见下
├── bin/
│ ├── fn-remap
│ ├── keyboardctl
│ └── coloros-window-launcher.jar # 可选
└── webroot/
├── index.html
├── app.js
└── style.css
input-status 由 fn-remap 在运行时写入(原子替换),不需要打包,也不应手动编辑。
它记录转发器当前实际独占(EVIOCGRAB)的物理节点,供 Anland 判断哪些节点不能碰。
Anland 的 Gold 输入来源直接独占本模块的虚拟输出节点,读取重映射后的原始事件并送入容器。
沉浸期间这些键盘事件不会经过 Android 的 KeyEvent 分发;退出后解除独占,安卓恢复接收。
物理键盘继续由 Gold 读取、重映射,Anland 不会绕过配置直接接管同一物理键盘。
profile=Anland 中的独立规则会保留。Anland 会话通过 anland-profile 请求文件触发方案切换,
退出后移除请求并恢复 active_profile 指定的方案。请求文件只选择方案,不承担事件传输。
如果配置里没有 Anland 方案,继续使用当前规则。
keylayout.sh 现在只清理旧版生成的 Meta 特殊布局。升级后重启,使安卓重新加载原生布局;
请同时使用支持 Gold 原始输入的新版 Anland。
fn_remap.c 需要使用 Android 目标架构编译为 bin/fn-remap。如果要启用 ColorOS 小窗或系统截屏,需要使用 Android SDK 的 android.jar 编译 ColorOS.java,并把生成的类打包为 bin/coloros-window-launcher.jar。
仓库中的 install-webui.sh 和 install-into-existing-module.sh 是刷机后更新现有模块的脚本,不是完整构建系统。它们会从 /data/local/tmp/gold-keyboardremaps 或 /data/local/tmp 读取已经准备好的二进制和脚本。
仓库提供 .github/workflows/manual-build.yml。在 GitHub 的 Actions 页面选择 “Manual Build and Release”,点击 “Run workflow” 后设置:
abi:选择目标设备架构,默认arm64-v8a;也可构建armeabi-v7a或x86_64。publish_release:默认关闭。关闭时只生成 Actions 构建产物;开启时会创建 GitHub Release 并上传 ZIP 和 SHA-256 校验文件。prerelease:仅发布时使用,默认开启,创建测试版;关闭后创建正式版。release_tag:仅发布时需要。留空会生成类似v1.0-build.123的标签。
每个 ZIP 都只包含一种 ABI,请下载与设备架构一致的文件。
打开“输入节点”并点击“刷新节点”。推荐开启“自动选择外接物理键盘”;如果设备有多个键盘,可以关闭自动模式后手动勾选节点。
触摸屏、触摸板和手写笔会显示为暂不支持,不应选择它们作为键盘输入源。
- 在“按键映射”标题左侧点击“添加”,点击“添加单键”后会直接打开输入选择界面。
- 在输入选择界面选择一个按键,或点击“捕获按键 5 秒”后按下目标键,再点击“完成选择”返回规则选择界面。
- 在规则选择界面点击“按键输出”,选择一个或多个输出键并点击“完成选择”。
- 输入和功能两侧都显示已选择内容后,点击“保存规则”,再点击底部“保存并应用”。
- 点击“添加”,再点击“添加组合”;点击选项后会直接打开输入选择界面。
- 点击“捕获组合 5 秒”,在倒计时内依次按下组合键,再点击“完成选择”。
- 点击“按键输出”并选择输出键,或打开“键盘视图”进行多选,再点击“完成选择”。
- 输入和功能两侧都完成后,点击“保存规则”,再点击“保存并应用”。
输出键中的修饰键会先按下,释放时按相反顺序释放。规则只有在点击“保存并应用”后才会写入配置并重启输入转发器。
点击“添加”后,可以直接选择“打开应用”,也可以先完成“添加单键”或“添加组合”的输入选择,再在规则选择界面点击“打开应用”。刷新并选择应用,点击“完成选择”返回后,确认输入和功能两侧都完成,再点击“保存规则”。可以选择:
- “以小窗形式打开”:需要 ColorOS 和
coloros-window-launcher.jar,系统或应用不支持时可能退回普通窗口。 - “再次按下时关闭 App”:再次触发时返回桌面,应用保留在后台。
默认配置包含 Ctrl + Shift + Z 启动 QQ 的示例规则。如果设备没有 QQ,请在 WebUI 中删除或修改该规则。
点击“添加”后选择“自定义 Shell 命令”,输入要执行的命令即可。默认使用 Android shell 用户执行;勾选“使用 root 权限执行”后会通过 KernelSU root 执行。命令支持多行,WebUI 会使用 Base64 写入配置并提供“测试命令”按钮。Shell 动作和按键输出、应用启动一样,必须先完成输入按键和功能两侧才能保存。
在 KernelSU 模块详情中点击模块操作按钮即可切换状态。暂停后输入转发器会停止,恢复后会自动重新启动。修改映射前如果担心按键失控,可以先暂停模块。
首次运行没有配置文件时,模块会自动创建以下规则:
F23 -> Fn
Fn + 1..0 -> F1..F10
Fn + - -> F11
Fn + = -> F12
Ctrl + Shift + Z -> QQ 小窗(示例)
其中 F23 通常是设备厂商上报的功能键,实际名称以“按键捕获”结果为准。
配置文件位置:
/data/adb/modules/Gold_Keyboardremaps/config.conf
支持以下格式:
version=1
# 自动选择键盘。同一块键盘同时以两种传输方式出现时(例如触点底座 + 蓝牙),
# 优先选择蓝牙,因为那通常是用户在系统设置里主动配对的那一路。
device=auto
# 手动选择,格式为:设备路径|总线|厂商|产品
# 总线取值见 linux/input.h:0003=USB,0005=蓝牙,0019=内置/触点
device=/dev/input/event9|0019|22d9|3869
# 按键映射
mapping=KEY_F23=>KEY_FN
mapping=KEY_LEFTCTRL+KEY_LEFTSHIFT+KEY_Z=>KEY_C
# 启动应用,mode 为 normal 或 freeform,可选 toggle
launch=KEY_LEFTCTRL+KEY_LEFTSHIFT+KEY_Z=>com.example.app/.MainActivity|normal
launch=KEY_LEFTCTRL+KEY_LEFTSHIFT+KEY_Q=>com.example.app/.MainActivity|freeform|toggle
# 自定义 Shell 命令(WebUI 会自动使用 Base64 保存命令内容)
shell=KEY_LEFTCTRL+KEY_LEFTSHIFT+KEY_H=>shell|b64:aW5wdXQga2V5ZXZlbnQgSE9NRQ==
shell=KEY_LEFTCTRL+KEY_LEFTSHIFT+KEY_R=>root|b64:cmVib290按键之间使用 +,输入和输出之间使用 =>。每个组合最多 8 个按键。捕获到内置表中没有的按键时,会显示为 CODE_数字,可以直接写入映射。
应用启动规则按声明顺序触发:先按前置键,再按组合中的最后一个键。例如
KEY_LEFTCTRL+KEY_LEFTSHIFT+KEY_Z 需要先按 Ctrl 和 Shift,最后按 Z。这样普通的
Shift+Z 会立即透传,不会等待松键。
Shell 规则同样在组合中的最后一个键按下时执行。shell 模式通过 Android shell 用户执行,
root 模式通过 KernelSU root 执行;两种模式都不会把命令输出转发到按键设备。
手动修改后,可在 root shell 中重启转发器:
su -c '/system/bin/sh /data/adb/modules/Gold_Keyboardremaps/bin/keyboardctl restart'su -c '/system/bin/sh /data/adb/modules/Gold_Keyboardremaps/bin/keyboardctl input-status'成功时输出一行规范结果,例如:
GOLDCTL1 input-status ok code=ready boot_id=<启动 ID> generation=<n> instance=<token> count=2 nodes=event12,event3
没有任何节点被独占时,count=0 且 nodes=-。节点按字典序排列(因此
event12 排在 event3 之前),event01 这类带前导零的名字不会出现。
这个命令是纯读取:不领取租约、不发送信号、不执行探测、不改变任何状态。 转发器成功独占的节点不会因为有人查询而释放。
无法给出可信答案时,程序输出规范错误行并以非零状态退出,例如
code=stale(快照心跳已停止,说明写入它的进程已经不在了)或
code=no-snapshot(还没有任何快照)。调用方必须把这种情况当作“未知”,
而不是“没有占用”——读不到的 Gold 不等于空闲的 Gold。
转发器默认只会在关机(
pkill/ 关闭模块)时停止刷新该文件,此时快照会过期, 查询返回code=stale。这是刻意的:过期状态不能被伪装成“未占用”。
- 确认页面是从 KernelSU Manager 打开的,而不是普通浏览器。
- 确认模块已启用并已重启设备。
- 确认
bin/fn-remap存在且可执行。
- 插拔外接键盘后点击“刷新节点”。
- 关闭自动模式并尝试手动选择外接键盘节点。
- 使用 root shell 检查:
getevent -il /dev/input/eventX。
捕获只监听当前选中的外接键盘,并且模块不能处于暂停状态。单键模式识别到第一个按键就结束;组合模式会持续监听完整时长。
确认点击了“保存并应用”,状态显示“运行中”,并查看日志:
/data/adb/modules/Gold_Keyboardremaps/fn-remap.log
如果日志提示无法创建虚拟键盘,请检查内核是否提供 /dev/uinput,以及是否有其他输入拦截模块与本模块冲突。
新版模块会通过 /system/bin/sh 调用控制脚本,并在开机时修正 bin 目录中的执行权限。对于已经安装的旧版本,可先在 root shell 中执行以下命令恢复:
su -c 'chmod 0755 /data/adb/modules/Gold_Keyboardremaps/bin/fn-remap /data/adb/modules/Gold_Keyboardremaps/bin/keyboardctl && /system/bin/sh /data/adb/modules/Gold_Keyboardremaps/bin/keyboardctl ensure'小窗功能依赖 ColorOS 的窗口服务、应用支持情况和 coloros-window-launcher.jar。普通 AOSP 或非 ColorOS 设备应取消“以小窗形式打开”,改用普通启动。
在 KernelSU Manager 中禁用或卸载模块,然后按提示重启。卸载前建议先暂停模块,并确认外接键盘可以正常输入。
本模块以 root 权限读取并独占选中的输入节点,再通过 uinput 创建虚拟键盘。错误的设备选择或映射可能暂时导致键盘没有响应;首次修改建议保留触摸屏或 adb 作为备用控制方式。