# 开始使用 Voice Key

> 了解如何在 Windows、macOS 和 Linux 安装 Voice Key，下载本地识别模型，配置麦克风与权限，开始语音输入。

## 1. 安装桌面应用

从官方 GitHub Releases 下载最新版本，选择 Windows x64 安装程序、适合 Intel 或 Apple 芯片的 macOS 磁盘映像，或 Linux x86_64 安装包。当前版本尚未签名，Windows SmartScreen 或 macOS Gatekeeper 可能提示，请先确认安装包来源。

## 2. 设置麦克风与权限

在设置中选择麦克风。macOS 用户还需要在「系统设置 → 隐私与安全性」中授予麦克风和辅助功能权限，后者用于监听快捷键和向其他应用输入文字。

## 3. 下载一种识别模型

经典模式使用 SenseVoice，约需下载 240 MB，在录音结束后输出文字，支持普通话、英语、粤语、日语和韩语。流式模式使用 X-ASR，约需下载 586 MB，在悬浮窗口中显示中英文识别中的文字。模型按需下载，保存在本机应用数据目录，两种模式不能同时运行。

## 4. 尝试第一次输入

在常用应用中选中文本框，按住配置的快捷键说话，松开后结束识别并输入文字。Windows 和 Linux 的默认快捷键是 Control+Shift+Space，macOS 是 Option，可在设置中修改。单次录音最长五分钟。

## 5. 决定是否使用 AI

基础本地识别不需要 ASR API Key。如需润色或翻译，可配置受支持的模型服务及凭据。相关文本会发送给该服务商，并可能产生第三方费用。下载模型后，关闭这两个功能即可离线完成基础语音输入。

## Windows 安装说明

下载适用于 x64 Windows 的 .exe 安装程序。如果 SmartScreen 提示，请先确认安装程序来自官方发布页面。当前版本尚未签名。

## macOS 安装说明

下载与 Mac 芯片架构匹配的 .dmg，将 Voice Key 移入「应用程序」。如果 Gatekeeper 阻止运行未签名应用，请查阅仓库中的 macOS 安装说明。使用前需开启麦克风和辅助功能权限。

## Linux 与 Omarchy

Linux X11 用户可以使用 x86_64 AppImage，启动前需赋予可执行权限，部分发行版需要安装 FUSE 2。Arch 或 Omarchy 用户可以选择 pacman 安装包。Omarchy / Hyprland 用户需在「设置 → Linux & Omarchy Integration」中安装集成。其他 Wayland 合成器暂不完整支持快捷键按下与释放流程。

## 需要帮助？

通过 GitHub Issues 反馈可复现的问题，并附上操作系统和识别模式。请勿附带凭据、私人转录文本或原始录音。

## Links

- [Releases](https://github.com/BuildWithAIs/voicekey/releases/latest)
- [Source](https://github.com/BuildWithAIs/voicekey)