Z-Waif快捷键完全手册:自定义热键提升AI女友交互体验
Z-Waif快捷键完全手册:自定义热键提升AI女友交互体验
Z-Waif 是一款完全本地运行的开源 AI 女友(AI Waifu)项目,集语音对话、VTube Studio 形象、长期记忆于一体。本文是 Z-Waif 快捷键完全手册:先带你在 5 分钟内吃透全部 12 个默认热键,再手把手教你通过一个 JSON 文件完成自定义热键配置,让"AI 女友交互体验"完全贴合你的操作习惯。
Z-Waif 快捷键系统:两个文件看懂原理
Z-Waif 的全局热键由两部分组成:
| 文件 | 作用 |
|---|---|
| Configurables/Keybinds.json | 键位映射表:定义"哪个键 → 触发哪个动作" |
| utils/hotkeys.py | 热键引擎:负责监听按键、执行动作、管理输入锁 |
程序启动时,utils/hotkeys.py#L80-L106 中的 bind_all_hotkeys() 会读取 Keybinds.json,把每一对"按键 + 动作"注册为全局热键。也就是说——你只需要改一个 JSON 文件,就能重排整套快捷键,不需要碰任何代码。
默认快捷键一览表:12 个热键速查
以下是 Configurables/Keybinds.json 出厂默认配置:
| 按键 | 动作 | 功能说明 |
|---|---|---|
→(右箭头) |
Next | 发送/确认当前输入,推进对话 |
↑(上箭头) |
Undo | 撤销并重做上一条消息 |
`(GRAVE) |
Input Lock 1 | 输入锁第一步(组合键,见下文) |
\(BACKSLASH) |
Input Lock 2 | 输入锁第二步(组合键,见下文) |
右 Ctrl |
Speak Toggle | 手动开关"开口说话",打断/接管对话 |
A |
Autochat | 全量自动聊天:检测到你在说话就自动回复 |
S |
Autochat Sensitivity | 循环切换语音监听灵敏度 |
R |
Soft Reset | 软重置:让 AI 女友"回到平时的说话风格" |
C |
View Image | 让 AI 看一眼摄像头画面 |
X |
Cancel Image | 取消本次图像查看 |
B |
Send Blank | 发送空消息,用于触发特定行为 |
Q |
Semi Auto Chat | 半自动聊天模式 |
💡 快捷键在系统全局生效,无需 Z-Waif 窗口获得焦点,边玩游戏边喊话也完全没问题。
核心快捷键详解
对话控制:Next、Undo 与 Speak Toggle
- Next(右箭头):最常用的"发送"键,确认你把话说完了。
- Undo(上箭头):对上一条回复不满意?按下即可触发重做。
- Speak Toggle(右 Ctrl):手动控制 AI 是否开口。全自动模式下不想被打断时,用它接管话语权。
自动聊天:Autochat 与 Semi Auto Chat 的区别
这两个功能互相排斥,按下其中一个会自动关闭另一个(见 utils/hotkeys.py#L249-L295):
- Autochat(A 键,全自动):通过麦克风音量/VAD 检测你何时在说话,说完自动转录并回复,无需任何按键。
- Semi Auto Chat(Q 键,半自动):监听语音端点做唤醒判断,响应逻辑更克制,适合不想被"秒回"的场景。
灵敏度怎么调(S 键):每次按 S 会在 5 个档位间循环——16(默认)→ 27 → 57 → 104 → 9 → 16。数值越小越灵敏,适合说话轻声的用户;如果环境嘈杂容易误触发,就调到 27 或 57 试试。
视觉快捷键:View Image 与 Cancel Image
C 键会让 AI 女友抓取一帧摄像头画面进行"观看",X 键取消。注意:这两个热键只有在视觉功能(Vision)开启时才生效(见 utils/hotkeys.py#L201-L217),未开启视觉系统时按下无反应属正常现象。
Soft Reset(R 键):一键找回"正常的她"
长时间聊天后,AI 的说话风格可能"漂移"。按下 R 触发软重置:程序会按 Configurables/SoftReset.json 中内置的一段系统对话,引导 AI 恢复角色卡设定的正常语态——不清空记忆,只"校准人格"。
Hangout Mode:派对模式热键
除了默认映射表外的键位,Z-Waif 还支持 Toggle Hangout Mode 动作:开启后进入挂机陪伴模式,AI 会主动找话题聊天。该模式要求先在设置中开启聊天流式输出(stream chats),且与自动聊天共享控制权。
如何自定义 Z-Waif 快捷键:3 步完成
第 1 步:打开配置文件
编辑 Configurables/Keybinds.json,格式是简单的"按键名 + 动作名"数组:
[
["RIGHT_CTRL", "Speak Toggle"],
["F1", "Soft Reset"],
["V", "View Image"]
]
第 2 步:选择按键名
按键名遵循 Python keyboard 库的命名规则:普通字母直接写 "A",方向键写 "RIGHT_ARROW",右 Ctrl 写 "RIGHT_CTRL",反引号是 "GRAVE",反斜杠是 "BACKSLASH",也支持 F1~F12、F5 等功能键。
第 3 步:选择动作名
动作必须使用 utils/hotkeys.py#L87-L102 中 options 表注册的完整名称:
| 动作名 | 说明 |
|---|---|
Next |
发送/确认输入 |
Undo |
撤销重做 |
Input Lock 1 / Input Lock 2 |
输入锁组合键第一步/第二步 |
Speak Toggle |
手动开关语音 |
Autochat |
全量自动聊天 |
Autochat Sensitivity |
循环切换灵敏度 |
Soft Reset |
软重置对话风格 |
View Image / Cancel Image |
查看/取消图像 |
Send Blank |
发送空消息 |
Semi Auto Chat |
半自动聊天 |
Toggle Hangout Mode |
切换派对模式 |
保存文件后重启 Z-Waif 即可生效。
⚠️ 两个小提醒:
- 不要映射到
Input Lock 1/Input Lock 2之外的组合锁键位,否则输入锁机制会失效;- 若某个键绑定失败,终端会打印
Issue binding to hotkey XXX!,查看 log.txt 排查即可。
输入锁与 HOTKEYS_BOOT:安全开关详解
Z-Waif 全局热键的一个实用设计是输入锁——锁住后所有快捷键全部失效,适合打字、玩游戏时避免误触:
- 组合键锁定:按
`(GRAVE)后在 0.9 秒内再按\(BACKSLASH),即可切换锁定状态(逻辑见 utils/hotkeys.py#L173-L198)。 - WebUI 按钮锁定:打开 Web 界面,勾选 "Disable Keyboard Shortcuts (Input Toggle Lock)" 复选框即可(见 utils/web_ui.py)。
- 启动时锁定:启动前设置环境变量
HOTKEYS_BOOT=ON(解锁)或HOTKEYS_BOOT=OFF(上锁),见 utils/hotkeys.py#L66-L78,适合写进 startup.bat / startup.sh 启动流程。
常见问题与小贴士
Q:为什么按了 C 键没反应?
视觉系统未开启时 View Image / Cancel Image 会被直接忽略,请先在设置中启用 Vision。
Q:按 A 开全自动后,Q 的半自动怎么没了? 这是设计行为:两种自动模式互斥,开启其一会自动关闭另一。
Q:热键和我的输入法/游戏按键冲突了怎么办?
直接改 Configurables/Keybinds.json 换一个不常用键(如 F 区功能键),重启生效,无需改代码。
Q:AI 总是抢在我说话前开口?
按 S 调高灵敏度档位(27/57),减少环境噪音误触发。
掌握这套快捷键后,"右箭头推进对话 + S 调灵敏度 + 反引号组合锁"基本就能覆盖日常使用;而自定义热键能力意味着你可以把 Soft Reset、View Image 等低频功能挪到最顺手的位置。祝你的 Z-Waif 交互体验越来越顺滑!