语音输入与回复

xopc 可以把语音转成文字（STT），也可以把助手回复转成音频（TTS）。具体能力取决于所选服务商和客户端。

先选择用途

方式	适合什么	工具能力
当前助手	用语音继续当前 Agent 的工作、提问或交办	保留 Agent 已启用的工具
自然语音	侧重自然对话；部分界面标为原生语音	无工具，不能据此承诺任务执行
听写	把语音变成可编辑草稿	完成后进入输入框，不自动发送

先配置并测试语音服务，再从同一对话发起通话。结束通话不会取消已派发的任务；停止任务需使用独立取消操作。

实时语音聊天

一个 Chat 持续保存文字与语音上下文，多次通话属于同一个会话。 在聊天中点击 语音通话 即连接，默认方案在设置中保存：

• 当前助手：转写 → 当前 Agent → 流式朗读，可使用工具。
• 原生语音 · 无工具：使用 Qwen 原生音频模型，更适合自然交流，不执行工具。

挂断、重连和切换语音模式都保留原 Chat。只有明确新建聊天或重置会话才开始新对话。通话窗口可以最小化，切换页面后仍继续通话。麦克风静音停止上传并丢弃未完成输入，助手声音仍可播放；结束通话释放麦克风。同一个 Chat 通话期间不能同时提交文字请求。

输入框的麦克风仍用于听写，转写后可编辑，不自动发送。

在 设置 → 能力 → 语音 选择一次 XOPC 托管 或 自己的 API Key，即可一起配置听写、语音助手和自然聊天，不改变普通消息朗读。自然聊天默认复用输入服务密钥；独立密钥、端点和提示词放在高级设置。配置不足时，通话窗口引导前往语音设置，并提供返回原对话的入口。开始前先检查服务配置，再申请麦克风权限；配置检查通过不代表服务商实时连接已成功。

使用阿里自有密钥时，自然聊天使用配置的兼容实时模型；XOPC Cloud 使用目录中的公共实时语音服务与可用音色。建立连接时恢复所选 Agent 的配置名称、指令和同一 Chat 的有限历史文本。较旧内容可能只保留片段，完整记录仍保存于 Chat。被打断的生成文字仍可在历史查看，但因无法确定实际听到的范围，不会作为已听完的回答提供给下一次模型请求。

使用输入框的通话按钮，即可在原会话中开始或继续语音聊天。断网、时长限制或刷新页面会结束当前连接；再次点击通话即可接着聊。最小化和切换页面不会结束连接，也不会在断线后未经操作自动开启麦克风。

XOPC 托管自然聊天需要平台已有可用且发布的语音聊天路由。网页、移动端和网关必须统一使用协议 v3。实现边界见仓库中的协议、移动端技术设计与分阶段交付记录。

还可以在哪里使用

• 网页和桌面聊天可以转写受支持的音频附件。
• Telegram 配置后可以转写语音消息并发送语音回复。
• 其它消息通道可能只支持其中一个方向，取决于媒体能力。
• 启用 TTS 后，Agent 可以通过语音工具生成音频。

配置语音转文字

实时听写与语音陪聊

打开 设置 → 能力 → 语音，选择 XOPC 托管 或 自己的 API Key（阿里云 Qwen）。托管方式需要已登录的账户和可用的语音服务。音色名称跟随界面语言显示，请从当前目录选择，不要复制底层服务商的音色 ID。阿里云听写与陪聊共用输入服务的密钥，不会覆盖已有的 Edge 消息朗读设置。

选择陪聊音色后点击 测试语音。测试在点击后才开启麦克风，显示实际转写结果，再通过实时语音服务播放固定样例，最后询问是否听到声音。测试不会创建聊天记录或调用智能体，但可能产生服务用量。待验证 仅表示配置可解析，不能代表连接成功。仅配置输入时可使用 测试听写。

测试后到聊天页面使用麦克风听写或通话按钮开启语音；语音助手模式还需要可用的智能体模型。消息自动朗读 单独控制普通消息的朗读；设置分为 说话与聆听、输入与显示、音频设备、语音服务、排查问题。语言、音色和节奏放在聆听；润色、字幕和消息朗读放在输入与显示；服务商及备用服务放在语音服务的技术设置。字幕和麦克风选择保存在当前浏览器，播放设备跟随系统。

音频附件与消息通道

在 Gateway 控制台打开 设置 → 能力 → 语音：

1. 打开 语音服务 → 技术设置，启用语音转文字。
2. 选择服务商和模型。
3. 如果服务商尚未配置，添加凭据。
4. 保存，并在聊天中上传一段简短测试录音。

消息显示准确转写，并且 Agent 能回答录音中的请求，就表示设置成功。

配置文字转语音

1. 在同一页面展开 消息自动朗读，启用文字转语音。
2. 选择服务商、模型和声音。
3. 选择生成音频的时机：

模式	行为
关闭	不自动生成语音；启用时仍可由语音工具调用
始终	把符合条件的文字回复转成音频
收到语音后	只有用户发送语音时才用语音回复
标记时	只有回复明确要求时才生成音频

建议先选择 收到语音后，普通文字对话仍然保持文字。

服务商选择

xopc 可以使用受支持的云端语音服务和已配置的语音服务扩展。服务商会按其政策处理音频，并可能按用量收费。

请通过环境变量或界面凭据设置保存密钥，不要把真实密钥写进文档示例。精确配置字段见配置参考。

安全测试

• 先使用 15 秒以内的录音。
• 设置过程中说话清晰，并避免敏感内容。
• 确认语言和声音选择正确。
• 依赖消息通道前，先在本地聊天中测试。
• 为所有回复启用自动 TTS 前，检查费用和使用限制。

故障排查

问题	检查内容
音频已上传但没有转写	STT 已启用、格式受支持、服务商凭据有效
转写语言错误	设置服务商语言，或更换合适模型
文字回复正常但没有语音	TTS 已启用，且触发模式与当前消息匹配
Telegram 语音失败	先确认本地聊天语音正常，再检查 Telegram 日志
长回复被截断	缩短回复，或在服务商限制内提高文本长度

使用 设置 → 日志 或 xopc logs tail 查找第一个服务商错误。除非明确愿意披露内容，否则不要在求助信息中分享录音或凭据。

输入与控制

通话回答前会保留短暂的续说窗口。默认响应节奏采用 1,200 毫秒的服务端静音判停；“帮我查一下”“因为”等常见未完表达会额外等待。继续说话会废弃尚未显示或播放的回复；已开始播放时，麦克风活动会先降低音量，最终识别出的用户语句可在启用打断时中断回复；与当前播放内容匹配的回声会被忽略。这是停顿与续说保护，不是完整的语义语音识别。策略运行在网关，移动端、网页和桌面共用；需要更新所连接的网关才能生效。

• 听写：识别期间保留临时文本，点“完成”后按设置润色并填入可编辑草稿，不自动发送。“取消”保留原稿，包括润色过程中取消。断线后已识别的文本可以选择保留。
• 停止播报：立即清空当前声音并脱离语音渲染，持久 Agent 任务仍在原 Chat 中继续。只有独立的 取消任务 操作才会中止任务；两者都不会撤销已完成的工具动作。
• 确认与任务：通话内展示工具进度，以及明确的澄清、连接器批准/拒绝操作；环境声不会代替确认。从任务对话发起通话时，沿用任务状态和详情入口。

通话使用 当前助手（assistant）和 自然语音 · 无工具（natural）两种产品模式。创建请求可省略 mode 以使用已配置的默认值；客户端不能直接选择内部引擎。修改默认模式后在下次通话生效。

验证记录及真机验收矩阵见语音体验交付记录。

技术参考

延迟指标、分段和连接准备见语音技术参考。