语音输入与回复

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

可以在哪里使用

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

配置语音转文字

实时听写与语音陪聊

打开 设置 → 能力 → 语音，选择 XOPC 托管 或 自己的 API Key（阿里云 Qwen）。托管方式需要已登录的账户和可用的实时语音模型。阿里云听写与陪聊共用输入服务的密钥，不会覆盖已有的 Edge 消息朗读设置。

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

测试后到聊天页面使用麦克风听写或开启语音陪聊；实际对话还需要可用的智能体模型。消息自动朗读 单独控制普通消息的朗读；高级设置 收纳语言、停顿时间、输入服务、备用服务商和转写润色。

音频附件与消息通道

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

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

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

配置文字转语音

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

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

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

服务商选择

xopc 可以使用受支持的云端语音服务，也可以使用已配置的本地语音扩展。云端服务会按其政策处理音频，并可能按用量收费；本地服务在设备上处理，但需要兼容的软件和模型。

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

安全测试

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

故障排查

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

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