跳到主要内容

常见问题

录音相关​

录音没有声音 / 转写结果为空​

  1. 检查麦克风是否被系统识别
  2. 确认录音工具已安装（parecord）
  3. 查看日志输出：RUST_LOG=altgo=debug altgo

录音启动慢​

首次启动录音时设备初始化可能需要几秒，后续会更快。

按键相关​

按右 Alt 没有反应​

先在主页空态点“检测触发键”。它会等你按一次键，把抓到的键名与键码和当前配置的触发键对照。按键照常录音，所以按下去就能顺手验证转写。按结果分几种情况：

  • 提示“触发键可用”：按键能到达 altgo，问题在录音或转写环节，按“录音相关”与“转写相关”两节排查。
  • 显示你按下的是另一个键：收到的键与配置不一致，记下界面上的两个键码，到设置页用“按下以设置”把触发键改成实际按下的那个。
  • 显示抓到的键是其他程序注入的（仅 Windows）：按键到达了 altgo，但带着“由其他程序合成”的标记，这类事件一律被忽略，所以不会起录。改键工具、键盘厂商驱动与部分输入法都会这样注入按键，停掉或改掉它们的映射即可。
  • 提示没有收到任何按键：按键没有到达 altgo，按下面的清单排查。

Linux：

  1. 用户是否在 input 组并已重新登录？无法读取 /dev/input/event* 时，按键监听会失败：sudo usermod -aG input "$USER" 后注销/重启再试。
  2. 确认 xinput 可用：which xinput（X11 路径）。
  3. 检查 Alt 绑定：xmodmap -pke | grep Alt。配置里默认 key_name = "Alt_R"，与设置页“按下以设置”一致即可。
  4. Wayland：仍依赖能访问 evdev。若仅用 XWayland 且无权限，现象与未加 input 组类似。剪贴板在 Wayland 上建议安装 wl-copy（或 xclip/xsel 经 XWayland）。
  5. 若使用 IME，可适当增大 min_press_duration 减轻误触。

Windows：

altgo 在 Windows 上用的是全局低级键盘钩子，其他程序注册同一个热键不会让钩子收不到按键，所以“被别的软件占用”通常不是原因。钩子本身失灵集中在三种情况：SetWindowsHookExW 失败、回调超时被系统摘钩、键位重映射工具在更底层把按键换掉。用 RUST_LOG=altgo=debug altgo 启动，日志里应当出现带 key 与 vk 字段的 Windows keyboard hook installed。要报问题时把这段日志与检测卡上的原始键码一并附上，键码只在与配置的触发键不一致时显示在诊断行里。

设置页的“按下以设置”在监听器正常运行时直接读监听器的按键，altgo 窗口有焦点也能捕获。如果管道没在跑（例如当前键名解析不出，监听器启动失败），捕获会退回临时钩子。Windows 上这个临时钩子挂得晚，窗口有焦点时可能收不到按键，此时先把焦点切到其他窗口再按一次，界面上的失败提示也会说明这一点。Linux 的回退是自起 evtest 子进程，不受焦点影响，失败提示说的是设备读权限。

误触发 / IME 冲突​

增加 min_press_duration 的值（默认 100 ms）来过滤短按抖动：

[key_listener]
min_press_duration = 200

转写相关​

能录音但没有转写结果​

  1. 确认录音结束后悬浮窗是否进入“处理中”。
  2. 本地引擎确认已在设置页下载模型。在线引擎确认 API Key、服务地址与模型名正确。
  3. 查看日志：RUST_LOG=altgo=debug altgo，检查 transcription failed、模型路径与润色服务请求失败信息。

中文识别效果不好​

  1. 确认 language = "zh" 设置正确。
  2. 本地引擎确认模型文件完整下载（model.int8.onnx 与 tokens.txt 均存在）。
  3. 在线引擎确认所选模型支持中文，并在服务商控制台检查请求是否被截断或限流。

在线转写失败怎么办​

在线转写不回退本地，失败时直接报错。依次检查 [transcriber] backend 是否为 "online"，[transcriber.online] protocol 是否为 mimo_chat、chat_input_audio 或 transcriptions，API Key、服务地址与模型名是否有效，网络能否到达服务商。日志里搜索 transcription failed。

在线转写需要联网吗​

需要。本地转写下载模型后可以断网使用，在线转写每次请求都要到达服务商。

本地模型在哪里下载？​

在设置页的“转写”分区下载。可选 SenseVoice（约 230 MB，中英日韩粤自动检测）、SenseVoice 粤语增强（约 237 MB）与 FireRedASR2 CTC（约 740 MB，中英混说更强）。也可以从模型清单对应的 Hugging Face 仓库手动下载 model.int8.onnx 与 tokens.txt 放入模型目录。

润色相关​

润色太慢​

  1. 降低润色级别（heavy、medium、light 逐级降低）
  2. 使用更快的模型，或切到本地润色（设置页把“润色引擎”改为本地）。本地档首次调用要等运行时启动与模型加载，之后每句约 0.15 到 0.3 秒
  3. 设置 level = "none" 关闭润色

润色改变了原意​

使用 light 级别，只修正标点和错别字，不改变内容。或者使用自定义 system prompt：

[polisher]
level = "light"
system_prompt = "只修正标点和错别字，不要改变原文的意思和语气"

本地档另有保真校验：数字、网址与路径被改动，或结果被压缩成摘要、凭空多出内容、出现格式标记时，直接回退转写原文，不会把改坏的结果发出去。

本地润色需要联网吗​

不需要。运行时与模型下载完之后，本地润色全程在本机进行，转写文本不会离开这台机器。只有可选的远端润色引擎才需要联网。

本地润色要占多少磁盘和内存​

运行时约占 47 MiB（Windows x64 解包后），模型 Qwen3-0.6B 约 397 MB、Qwen3-1.7B 约 1.1 GB。运行时提交内存约 1 GB（0.6B）或 1.5 GB（1.7B），进程工作集峰值实测约 1.3 GB 与 2.5 GB，空闲十分钟后会自动退出释放内存。

剪贴板与悬浮窗​

提示成功但粘贴出来是旧内容 / 剪贴板失败​

  1. 安装 xclip、xsel 或 wl-copy 之一，并确保在图形会话内运行 altgo。
  2. 若其他程序锁定了剪贴板，稍后重试即可。
  3. 在主页历史列表使用复制按钮（WebView 手势复制有时比后端剪贴板更稳）。悬浮窗只作展示，结果已自动写入剪贴板。
  4. 调试：RUST_LOG=altgo=debug altgo 查看是否有 clipboard 相关错误。

通用​

如何后台运行？​

# Linux
nohup altgo &
# 或使用 systemd user service

如何查看日志？​

# Linux
RUST_LOG=altgo=debug altgo

可用的日志级别：debug、info、warn、error