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-agentqwen-audio-agent 是一个让 AI Agent 保持会说、会做、在线的实时语音运行时它通过 Gateway 把语音前台与后台 Agent 连接起来。本文是一份面向新手的qwen-audio-agent 故障排查完全手册教你按客户端 → Gateway → 语音前台 / 后台 Agent的分层思路定位问题快速解决 10 个最常见的连接、音频与后端故障让你少走弯路。先分清问题在哪一层故障排查总思路 排障第一步不是改配置而是判断问题发生在哪一层客户端 → Gateway → 语音前台 / 后台 Agent / 前台工具两条新手最常踩的认知陷阱Gateway 连通 ≠ 模型已连上网关状态正常不代表语音前台的 Key、额度没问题后台显示已安装 ≠ 凭据有效安装检查不验证登录、API Key 和剩余额度。收集诊断信息的标准动作遇到任何故障先执行这三条命令确认版本、环境与配置doctor是只读诊断不启动模型、后台或麦克风也不自动修改配置qwenaudio --version qwenaudio doctor qwenaudio setupsetup只检查后台程序与接入组件不会验证登录、API Key 或额度。诊断命令的实现可参考 cli/src/launcher.mjs完整说明见官方文档 docs/operations/troubleshooting.zh.md。 下面 10 个问题按**连接与配置5 个、麦克风与播放4 个、后台与工具1 个**分类直接对号入座。一、连接与配置类故障5 个1. Gateway 未连接客户端显示离线现象WebUI / TUI / 桌面端都连不上提示 Gateway 不可达。排查步骤确认 Gateway 进程是否真的在运行终端前台、用户后台服务或桌面内置三种方式互不通用核对客户端地址与实际端口默认是127.0.0.1:3101⚠️ 注意桌面运行时和 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重启了也没用。处理用qwenaudio config确认你改的是当前实例实际使用的配置文件路径检查环境变量或源码.env.local是否覆盖了文件配置重启实际在运行的那个 Gateway——终端运行要Ctrl-C后重跑原命令后台服务执行qwenaudio gateway restart。4.gateway restart提示后台服务尚未安装原因gateway restart只管理用户后台服务gateway install安装的那种不会重启终端前台进程或桌面内置 Gateway。处理运行方式正确重启方式终端前台原终端Ctrl-C退出再执行原启动命令用户后台服务qwenaudio gateway restart桌面内置退出应用后重新打开5. 客户端被占用或突然被接管规则同一用户在一个 Gateway 上只有一个活动连接。新客户端确认接管后旧连接会被断开后台任务不会因此取消。处理如果你发现连接莫名断开检查是否有另一台设备 / 另一个客户端登录了同一 Gateway确认接管或关闭其中一端即可。规则说明见 docs/getting-started/concepts.zh.md。二、麦克风与音频类故障4 个6. 麦克风没有收音排查清单从上到下依次检查应用 / 浏览器是否授予了麦克风权限系统输入设备是否选对了尤其多设备时是否被静音、或系统处于休眠状态TUI 用户Linux / Windows 默认半双工播放回复时麦克风会暂停属于设计行为。7. 有文字转写但听不到回答声音处理检查系统输出设备与音量、客户端播放状态使用本地语音服务时额外查看其 TTS 日志桌面版可从设置 → 应用程序 → 日志打开日志目录定位。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 工具找不到命令后台执行失败先用qwenaudio setup --backend 名称检查安装再用后台自己的入口检查登录状态和模型配置记住Gateway 不负责猜测默认模型——没指定时沿用 Agent 自身配置。MCP 命令找不到检查 MCP 配置里的command与系统 PATH新装命令后重启 Gateway后台服务执行gateway restart刷新路径缓存MCP 变量要写进该 Gateway 使用的config.env不要依赖另一个终端临时export后台服务不会保留。资料库打不开或导入失败时确认已开启资料库、路径属于 Gateway 主机复杂文档还要求可用的隔离转换能力。MCP 配置详见 docs/reference/frontend-mcp.zh.md。四、进阶看日志、提反馈 ✅日志在哪里来源默认位置桌面版设置 → 应用程序 → 日志打开日志目录CLI 默认日志~/.config/qwaudio/state/logs桌面代管的 Gateway~/.config/qwaudio/state/desktop/logs桌面客户端日志应用数据目录下logs/开发版还可以按单轮记录整理时间线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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考