企业官网建设流程全解析

qwen-audio-agent故障排查完全手册：快速解决10个常见连接、音频与后端问题

【免费下载链接】qwen-audio-agentA realtime voice runtime that keeps Agents talking, working, and present. Real-time Voice Runtime for AI Agents项目地址: https://gitcode.com/gh_mirrors/qw/qwen-audio-agent

qwen-audio-agent 是一个让 AI Agent 保持"会说、会做、在线"的实时语音运行时，它通过 Gateway 把语音前台与后台 Agent 连接起来。本文是一份面向新手的qwen-audio-agent 故障排查完全手册：教你按"客户端 → Gateway → 语音前台 / 后台 Agent"的分层思路定位问题，快速解决 10 个最常见的连接、音频与后端故障，让你少走弯路。

先分清问题在哪一层：故障排查总思路 🧭

排障第一步不是改配置，而是判断问题发生在哪一层：

客户端 → Gateway → 语音前台 / 后台 Agent / 前台工具

两条新手最常踩的"认知陷阱"：

• Gateway 连通 ≠ 模型已连上：网关状态正常，不代表语音前台的 Key、额度没问题；
• 后台显示已安装 ≠ 凭据有效：安装检查不验证登录、API Key 和剩余额度。

收集诊断信息的标准动作

遇到任何故障，先执行这三条命令，确认版本、环境与配置（doctor是只读诊断：不启动模型、后台或麦克风，也不自动修改配置）：

qwenaudio --version qwenaudio doctor qwenaudio setup

setup只检查后台程序与接入组件，不会验证登录、API Key 或额度。诊断命令的实现可参考 cli/src/launcher.mjs，完整说明见官方文档 docs/operations/troubleshooting.zh.md。

📌 下面 10 个问题按**连接与配置（5 个）、麦克风与播放（4 个）、后台与工具（1 个）**分类，直接对号入座。

一、连接与配置类故障（5 个）🔌

1. Gateway 未连接，客户端显示离线

现象：WebUI / TUI / 桌面端都连不上，提示 Gateway 不可达。

排查步骤：

1. 确认 Gateway 进程是否真的在运行（终端前台、用户后台服务或桌面内置，三种方式互不通用）；
2. 核对客户端地址与实际端口，默认是127.0.0.1:3101；
3. ⚠️ 注意：桌面运行时和 CLI 默认是两个独立实例，桌面版查不到 CLI 的 Gateway 是正常现象，别查错实例。

运行方式详解见 docs/operations/gateway.zh.md，各目录与路径见 docs/configuration.zh.md。

2. Gateway 已连接，但语音前台异常

现象：网关绿灯，可说话后没有转写或报 Provider 错误。

处理：检查config.env中前台服务地址、API Key、额度以及 Provider 报错信息。不要仅凭桌面悬浮球的动画判断连通——动画不等于 Realtime 连接成功。前台配置方法见 docs/configuration/frontend.zh.md。

3. 修改配置后没变化

现象：改了config.env重启了也没用。

处理：

1. 用qwenaudio config确认你改的是当前实例实际使用的配置文件路径；
2. 检查环境变量或源码.env.local是否覆盖了文件配置；
3. 重启实际在运行的那个 Gateway——终端运行要Ctrl-C后重跑原命令；后台服务执行qwenaudio gateway restart。

4.gateway restart提示"后台服务尚未安装"

原因：gateway restart只管理用户后台服务（gateway install安装的那种），不会重启终端前台进程或桌面内置 Gateway。

处理：

5. 客户端被占用或突然被"接管"

规则：同一用户在一个 Gateway 上只有一个活动连接。新客户端确认接管后，旧连接会被断开（后台任务不会因此取消）。

处理：如果你发现连接莫名断开，检查是否有另一台设备 / 另一个客户端登录了同一 Gateway；确认接管或关闭其中一端即可。规则说明见 docs/getting-started/concepts.zh.md。

二、麦克风与音频类故障（4 个）🎧

6. 麦克风没有收音

排查清单（从上到下依次检查）：

1. 应用 / 浏览器是否授予了麦克风权限；
2. 系统输入设备是否选对了（尤其多设备时）；
3. 是否被静音、或系统处于休眠状态；
4. TUI 用户：Linux / Windows 默认半双工，播放回复时麦克风会暂停，属于设计行为。

7. 有文字转写，但听不到回答声音

处理：

1. 检查系统输出设备与音量、客户端播放状态；
2. 使用本地语音服务时，额外查看其 TTS 日志；
3. 桌面版可从"设置 → 应用程序 → 日志"打开日志目录定位。

8. 扬声器回声导致误打断

现象：AI 刚开口就被自己的声音"打断"，来回卡壳。

处理：

• Linux / Windows 的 TUI 优先使用半双工模式；
• 必须用无 AEC 的全双工（qwenaudio tui --audio-mode full）时，请佩戴耳机；
• macOS 默认带 CoreAudio AEC 全双工，一般不受影响。详见 docs/getting-started/tui.zh.md。

9. 远程浏览器拿不到麦克风

原因：浏览器只在可信 HTTPS 安全上下文中开放麦克风，普通远程 HTTP 地址（尤其是局域网 IP）拿不到输入设备。

处理：改用可信 HTTPS 入口（Tailnet 或自有 HTTPS 反向代理）并在浏览器允许权限，不要为收音问题关闭浏览器安全设置。步骤见 docs/operations/remote-access.zh.md，浏览器端行为见 docs/getting-started/webui.zh.md。

三、后端与工具类故障（1 个）🛠️

10. 后台 Agent 执行失败 / MCP 工具找不到命令

后台执行失败：

1. 先用qwenaudio setup --backend <名称>检查安装；
2. 再用后台自己的入口检查登录状态和模型配置；
3. 记住：Gateway 不负责猜测默认模型——没指定时沿用 Agent 自身配置。

MCP 命令找不到：

1. 检查 MCP 配置里的command与系统 PATH；
2. 新装命令后重启 Gateway；后台服务执行gateway restart刷新路径缓存；
3. MCP 变量要写进该 Gateway 使用的config.env，不要依赖另一个终端临时export（后台服务不会保留）。

资料库打不开或导入失败时，确认已开启资料库、路径属于 Gateway 主机；复杂文档还要求可用的隔离转换能力。MCP 配置详见 docs/reference/frontend-mcp.zh.md。

四、进阶：看日志、提反馈 ✅

日志在哪里

开发版还可以按单轮记录整理时间线：

qwenaudio doctor --turn <turnId>

提交 Issue 前的安全提醒

提交问题请附：版本、操作系统、客户端 / Gateway 运行方式、复现步骤、发生时间、相关日志片段。

⚠️切勿附上API Key、配对码、设备令牌、完整配置文件或未经检查的私密对话。

结语

掌握"先分层、再查连接、后查音频与后台"的排查路径，配合qwenaudio doctor只读诊断和上表 10 个高频问题的处理方案，绝大多数 qwen-audio-agent 故障都能快速定位解决。建议把 快速开始 与 安装指南 放在手边，先确认基础环境正确，再按本手册逐层排查，排障效率会高得多。

【免费下载链接】qwen-audio-agentA realtime voice runtime that keeps Agents talking, working, and present. Real-time Voice Runtime for AI Agents项目地址: https://gitcode.com/gh_mirrors/qw/qwen-audio-agent