Z-Waif快捷键完全手册:自定义热键提升AI女友交互体验

原创2026-11-15 09:17:051,879 阅读

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 交互体验越来越顺滑!

登录后查看全文
z-waif