故障排查
401 Unauthorized
检查：
- 是否带上了
Authorization请求头 - 是否使用了
Bearer <token>格式 /v1/*是否使用的是 external API key- 该 key 是否已经被吊销
本地语音模型未激活
如果桌面录音或 /v1/audio/transcriptions 在转录前就失败，请检查：
- 打开 设置 -> Local speech models
- 下载一个内置模型，例如
Whisper Base、Whisper Small或SenseVoice，或手动放入兼容的 Whisper.cpp.bin模型 - 激活当前宿主要使用的模型
这个排查只适用于 设置 -> Routing and models -> STT mode 设为 Local 的情况。
设置改了但似乎没有生效
现在设置会在每次调整后自动保存。
如果听写优先级、Provider 或路由切换后看起来没有生效，请检查：
- 先等设置页底部状态从
保存中...恢复 - 重新打开 设置，确认刚才修改的值仍然被选中
- 等自动保存完成后再重新尝试一次听写
已切到云端 STT 但转录仍然失败
请检查：
- 设置 -> Routing and models -> STT mode 已切到
Cloud - 已选择可用的云端 STT provider
- 该 provider profile 没有被禁用
- 该 provider 的 API key 已经配置
- 云端 STT model 名称与该 provider 匹配
测试平台里的 Smart Clean 看起来没有变化
这通常不是 bug。
Prompt Lab 里的 Smart Clean 只执行本地清洗规则，不会调用 Provider、模型、Preset 或 Prompt Override。若输入里没有明显的低风险口头语、重复词或改口，它就可能保持原文不变，同时显示类似 本地规则 · <1ms 的耗时。
测试平台里的 Polished 提示 Add the API key for groq in Settings first
这表示云端请求在真正发出前就被拦住了，因为当前选中的文本变换 Provider 没有可用 API key。
请检查：
- 设置 -> Provider profiles 里已经为对应 Provider 填好了 API key
- 该 provider profile 处于启用状态
- 所选模型对这个 Provider 是有效的
然后重新打开测试平台或重新运行对比。
测试平台里的 Prompt Override 像是没有生效
Prompt Override 只对 Polished 生效。
如果你把自定义 Prompt 填进 Smart Clean 列，它不会被使用，因为 V1 的 Smart Clean 被设计成纯本地规则链路。
whisper-rs-sys 编译失败
如果你在 Windows 上执行 npm run dev 或 cargo check 时卡在 whisper-rs-sys：
- 先尝试
npm run cargo:check，它会优先自动探测常见的 Windowslibclang安装位置 - 确认机器上有可用的 64-bit
libclang.dll - 把
LIBCLANG_PATH指向该 DLL 所在目录 - 重新打开终端后再重试
这属于本地 Whisper 运行时的构建前提，不是接口配置错误。
Windows 上的 ONNX Runtime 或 SenseVoice 启动失败
如果桌面 App 在准备内置 SenseVoice 运行时时失败，请检查：
- 尽量通过仓库脚本启动，例如
npm run dev、npm run build、npm run cargo:check - 不要直接在绕过
scripts/with-libclang.mjs的 shell 里运行cargo - 只有在脚本明确提示下载包损坏时，才删除残留的 ONNX Runtime 临时文件后重试
仓库的启动脚本现在会自动下载并接入 Windows 所需的 ONNX Runtime 文件。
macOS 上全局快捷键没有触发
请检查：
- 系统设置 -> 隐私与安全性 -> 辅助功能 中，已经允许你当前实际启动 VILab 的终端、Codex 宿主或打包后的 VILab.app
- 你当前运行的是已经包含 macOS 事件监听式快捷键后端的新版本
- 当前快捷键里至少包含
Command或Control - 当前组合没有撞上明显的系统保留快捷键，例如
Cmd+Space或Cmd+Option+Space
当前 macOS 默认快捷键是 Cmd+Shift+Option+D。
macOS 上录音结束后能转写，但动画看起来几乎没反应
如果最终仍然能输出转录文本，通常说明麦克风音频已经正常传入模型。
请检查：
- App 已获得麦克风权限
- 当前运行版本是
0.1.6或更高版本，这个版本增强了 macOS 录音动画使用的电平映射 - 你测试的是最新一次
npm run dev会话，或重新打包后的新 App
这种现象通常是 UI 电平映射偏弱，不是转录链路本身失败。
Windows Release 启动后闪退
如果 Windows 的安装包点击后立刻退出，请按这个顺序提交问题：
- 打开
%APPDATA%\\com.vilab.desktop\\startup-trace.log - 到 GitHub Issues 提一个 issue
- 把
startup-trace.log附上去，同时说明 Windows 版本、安装包版本，以及是否在首次启动时出现该问题
如果 %APPDATA%\\com.vilab.desktop\\startup-trace.log 没有生成或是空的，也请在 issue 里直接说明。
服务不可达
检查：
- 桌面 App 是否正在运行
- Server URL 是否配置正确
- 宿主机防火墙是否已放行服务端口
- 客户端调用的是否是可达的局域网 IP 或主机名
局域网客户端无法连接
检查：
- 服务是否仍然只绑定在
127.0.0.1 - 客户端与宿主机是否在同一网络
- 安全软件是否拦截了服务端口
模型不支持
/v1/audio/transcriptions 目前只接受：
/health返回的当前公开 STT 模型别名
如果传入其他 model 值，服务会返回 400 Unsupported model。
音频格式不支持
当前本地 HTTP 转录接口只接受 WAV。
如果你传入其他容器或编码，请先转换成 WAV 再调用 /v1/audio/transcriptions。