【免费下载链接】tapq
Multi-modal voice agent for your AI agents. Talk with Claude Code, Codex, and others by voice: answer their prompts, give instructions, ask what they did. Or just nod.
TapQ 是一个多模态语音 agent：当 Claude Code、Codex、Cursor、OpenCode 这些 AI 编码助手停下来等你批准、提问或选择时，它把提示读进你耳边，你用声音或点头手势回答，全程不用看屏幕。没有 AirPods 也能用 TapQ——它会自动降级为纯语音模式（voice-only）。本文带你搞清楚降级模式下的预期行为、正确启动姿势，以及官方排查手册里的常见坑点，一次配好不再踩雷。
没有 AirPods 时，TapQ 会变成什么样
先说结论：无 AirPods 是官方支持的正常配置，不是故障。启动后你会看到/听到这些行为（详见 TROUBLESHOOTING.md）：
- 就绪横幅显示
AirPods motion: unavailable (voice-only; gestures return when AirPods connect) - 启动约 1.5 秒后朗读一次提醒 "No AirPods detected. Running voice only."，之后保持安静
- 手势、点按、倾斜通道全部失效；音量滑动手势被主动关闭（这样音量键回归调音量，而不是移动选项）
- 遇到选项题时它会教你可用的答案方式："Say next, previous, or select."
- 会话中途插上 AirPods，下一条提示自动恢复手势——不用重启、不用重新配置
⚠️ 最关键的一点差异：纯语音模式下
--wearer-gate（佩戴者归因）自动失效（fail open）。归因依赖的是耳机里的 IMU 运动信号来确认"这是不是你自己的声音"，没有 IMU 就无从判断，麦克风听到的指令会直接通过。在开放工位或多人房间里要留意这一点。
无 AirPods 场景的正确启动姿势
TapQ 目前为源码分发（macOS 14+、Swift 6），先克隆并构建：
git clone https://gitcode.com/gh_mirrors/ta/tapq
cd tapq
swift build && swift test
然后按需求选择启动方式：
# 纯反应式循环：提示被朗读、用固定词表（yes/no/next…）回答，设备端识别、无需 API Key
scripts/run-runtime-app.sh serve
# 完整语音 agent：指令、提问、目标、follow-up（需要 OPENAI_API_KEY）
scripts/run-runtime-app.sh serve --voice-backend openai-realtime \
--voice-trust environment --voice-instructions
无耳机场景下几个标志位的含义（完整参数见 docs/CLI.md）：
| 标志 | 作用 | 无 AirPods 时的建议 |
|---|---|---|
--voice-trust environment | 把麦克风的语音当作用户本人，口述指令不再要求 --wearer-gate | ✅ 推荐，官方就是为"耳机在盒里、电脑在桌上"这个场景设计的 |
--wearer-gate | 佩戴者归因门禁 | 可以保留，纯语音下自动不生效，插上耳机后重新生效 |
--voice-instructions | 允许口述指令给 agent | 搭配 --voice-trust environment 使用 |
--no-voice | 不申请麦克风/语音权限 | 仅需要运动输入时才用 |
--no-announcements | 抑制非阻塞性播报 | 不想听 "No AirPods" 提醒时开启 |
注意一个诚实的代价：在 --voice-trust environment 下，任何麦克风能听到的人都能下达指令——但谁都无法批准任何操作，审批只来自佩戴者的手势或语音（见 docs/VOICE_ONLY_AGENT_PLAN.md 的设计说明）。
8 个最常见的坑点及修复方法
以下内容整理自 TROUBLESHOOTING.md，按出现频率排序：
1. 没有 Motion / Speech / Microphone 权限
通过官方脚本启动，它使用本地签名的 headless app 容器，权限身份稳定：
scripts/run-runtime-app.sh serve
批准后在 系统设置 → 隐私与安全性 中检查 Motion & Fitness、Speech Recognition、Microphone 三项授权。
2. AirPods 已连接，但没有运动数据到达
逐项确认：耳机支持 headphone motion（AirPods Pro 全系、AirPods 3 及以后、AirPods Max）→ 已连接且佩戴 → 被选为当前音频输出设备 → 没有被其他进程占用运动流。然后重启 runtime。可以用抓取命令隔离"采集"和"识别"两个环节：
scripts/run-runtime-app.sh capture --duration 5 --output -
没有任何记录，说明是设备采集或权限问题，而不是手势分类器的问题。
3. Tap（点按）校准太弱
保持头部静止，用指尖快速、清晰地轻敲耳罩外侧壳体，不要挤压或按压耳机柄——校准寻找的是偏离静息基线的尖锐加速度尖峰。手势和点按的画像相互独立，可以只重试点按：
scripts/run-runtime-app.sh calibration run tap
swift run tapq calibration show tap
4. 交互过程中手势突然失灵
开启诊断输出，观察运动可用性、窗口起止事件、点按候选被拒的原因和断连/重连事件：
TAPQ_DEBUG=1 scripts/run-runtime-app.sh serve --no-voice
第一次点按被识别后，TapQ 会输出一段有界的采样轨迹，帮你区分"没听到第二次敲击"和"时序/姿态被拒"。
5. 语音命令不匹配
识别器固定为英文（en-US），与系统语言无关。用短命令测试：yes、no、next、previous、select。同时确认语音识别与麦克风授权已开启，且启动时没带 --no-voice。
6. 朗读提示语含糊、两种语言混杂
TapQ 默认用 macOS 系统合成器的 en-US 语音。如果听起来像在混读，多半是运行时选了非英文语音——检查 --speech-voice 与 TAPQ_SPEECH_VOICE，并在 TAPQ_DEBUG=1 下找 voice.unavailable 警告（表示指定语音未安装，macOS 回退到了系统语言语音）。注意它选的是语音不是翻译：可以在 macOS 语音设置里下载增强/ premium 语音，把它的 identifier 传给 --speech-voice。
7. Claude Code 不触发 TapQ
tapq integration claude status
移动过 checkout 或 runtime app 之后必须重装，因为 hook 配置里存的是绝对路径：
tapq integration claude install --permission-policy native
native 模式下，已有的 allow 规则和 bypassPermissions 可能合理地绕过 TapQ——这是设计行为，不是 bug。状态显示安装不完整或提示出现两次时，先 uninstall 再重装。
8. Codex 不触发 TapQ
tapq integration codex status
"已配置"不等于"已信任"：打开交互式 Codex 会话执行 /hooks，确认 PreToolUse、PermissionRequest、Stop、UserPromptSubmit 四个注册项被信任。Codex 会故意跳过未信任的新 hook，所以 /hooks 才是权威检查。此外，只读命令、allow 规则、沙箱内操作等也可能合理地绕过 TapQ。
容易误判的"坑"——其实是设计如此
🔍 这几点不是故障，理解后能省掉大量排查时间：
- 超时 / 没听到手势 / 没回答：窗口关闭，hook 不带答案返回，agent 正常显示屏幕提示。TapQ 从不猜测。
- 语音后端失败不会跨后端降级：指定
--voice-backend openai-realtime后，它就构成整条语音管线；一旦失败，本次运行的语音通道彻底断开（响亮的诊断日志 + 一句本地语音提醒），唯一恢复方式是重启 runtime——但手势、点按、屏幕回退和 broker 都还活着。这个"fail loud, never silently fall back"的完整决策见 docs/VOICE_BACKEND_FAILURE_PLAN.md。 - 多选题、多重提问：一律留在 agent 自己的屏幕流程里处理。
- Linux 上实时命令不可用：可移植内核和管理 CLI 可以在 Linux 构建测试，但
serve、capture、calibration run需要 macOS。 - 分享日志前先脱敏：调试输出可能含工具名、路径、请求标识；Claude 设置与 Codex hooks 文件可能含敏感命令或凭据，不要直接贴到公开 issue。
一分钟自检清单
配完按这个清单过一遍：
-
tapq serve正在运行，就绪横幅显示 voice-only（无耳机时） - 隐私与安全性中 Motion、Speech、Microphone 均已授权
- 所用 agent 的集成已安装：
tapq integration <agent> status正常 - 无耳机 + 需要口述指令时：
--voice-trust environment已开启 - 需要会话功能时：
OPENAI_API_KEY已在启动环境中 - 遇到怪问题时：
TAPQ_DEBUG=1复现一次，收集诊断日志
延伸阅读
- 官方排查手册：TROUBLESHOOTING.md
- 全部命令与标志参考：docs/CLI.md
- 语音后端失败策略：docs/VOICE_BACKEND_FAILURE_PLAN.md
- 纯语音 agent 规划（voice-trust 设计背景）：docs/VOICE_ONLY_AGENT_PLAN.md
- 本地 broker 安全边界：SECURITY.md
- 运行脚本：scripts/run-runtime-app.sh
【免费下载链接】tapq
Multi-modal voice agent for your AI agents. Talk with Claude Code, Codex, and others by voice: answer their prompts, give instructions, ask what they did. Or just nod.
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
