语音输入与播放

配置语音

1. 打开设置 → 语音。语音卡片使用兼容 OpenAI 的服务器端适配器，独立于对话模型提供商。
2. 输入 API 密钥，以及可选的基础 URL、转写模型、语音模型和默认语音。
3. 若输入和输出需要不同服务，启用为输入和输出使用不同供应商，然后填写输入/输出密钥、基础 URL 和模型字段。
4. 选择播放模式和输出格式，然后保存（存在未保存更改时可用）。测试前检查测试按钮旁的状态：已配置、部分已配置或缺少 API 密钥；保存失败时会显示保存失败。

语音设置和密钥属于所连接 CodeNomad 服务器配置，而非所选项目或 OpenCode 提供商连接。共享配置的其他客户端使用这些设置。保存的密钥会隐藏：空密钥字段保留已保存值；清除已保存的密钥会在保存时安排移除。某一方向既无自身端点也无密钥时可使用共享设置；单独端点需要自己的密钥，单独密钥也需要对应端点。更改端点时，请显式提供目标密钥并验证保存配置；端点变化会清除该槽位已保存密钥，而非发送到另一主机。

后端也可使用 OPENAI_API_KEY 和 OPENAI_BASE_URL 作为共享默认值。清除已保存密钥不会移除环境提供的凭据；若想移除后备凭据，请更改后端环境并重启。

这些是向配置服务发出的请求，不保证每个兼容端点都实现每个模型、语音或格式。保存失败会显示错误；进一步更改前检查配置。

测试输入和输出

1. 先保存端点、密钥、模型和语音更改。
2. 选择测试输入，授予麦克风权限，讲话后选择停止录音。检查返回转写。
3. 选择测试播放听示例；停止示例结束播放。

播放测试立即使用所选播放模式/格式，但端点、密钥、模型和语音来自已保存设置。测试输入不会发送对话提示词。测试仍会向配置的语音提供商发送音频/文本，可能产生费用。

流式播放失败时，选择缓冲后播放，尝试 mp3，保存后重新测试。“已配置”确认的是设置，而非提供商认证成功或编解码播放成功。重试前检查服务器主机能否访问端点、提供商模型/语音名和配额。

口述提示词

1. 在语音中保持提示词语音输入为启用状态（默认开启）。
2. 在输入框中打开更多操作，选择开始语音输入，并允许此设备访问麦克风。
3. 讲完后，在同一菜单中选择停止录音并转写；处理期间会显示正在转写音频。
4. 正常发送提示词前检查并编辑插入文本。

转写会在当前选择位置插入文本；不会自动提交到 OpenCode。只有 STT 已配置且客户端支持录音时才显示该菜单条目。即使 CodeNomad 在远程服务器运行，录音也使用客户端设备麦克风。

菜单条目缺失时，检查开关和 STT 配置。权限错误时，在浏览器和操作系统隐私设置中都允许麦克风。远程浏览器录音需要安全上下文，通常为可信 HTTPS；参阅移动访问和直接远程访问。切换离开或关闭输入框会结束录音生命周期；不要依赖未发送音频可恢复。请在文字草稿中检查结果。

朗读消息

1. TTS 可用时，在消息上使用朗读消息，或在工具调用上使用同一操作。
2. 在同一控件上使用停止播放结束朗读；开始另一段朗读会停止当前朗读。
3. 在语音中更改保存的语音、模型、模式或格式，供后续请求使用。

播放使用 CodeNomad 文本投影，而非对截图进行旁白：二进制/图片字节和权限回执不是语音内容。不会运行提示词或更改所选 OpenCode 模型。即使格式可选，浏览器音频支持和提供商响应仍可能阻止播放。

自动对话语音使用输入框更多操作菜单中的开启对话模式；它作用于该项目标签页，重新加载后不会保留。开启期间，CodeNomad 会在你发送的每条提示词中要求智能体以简短的 spoken 围栏摘要开始回复。只有该完整块会被朗读，且仅限活动主会话；不会自动朗读每条回复或子智能体。关闭对话模式会停止其队列，并不再要求提供摘要。开始麦克风输入也会停止活动对话语音。开关在语音输入可用或对话模式已启用时显示，且需要正常 TTS 才能启用。

数据流与隐私

麦克风音频从客户端传到 CodeNomad 后端，再到配置的 STT 端点。待合成文本通过后端传到配置的 TTS 端点；返回音频在客户端播放。API 密钥保留在服务器端，不会以保存值形式返回设置表单。

请选择可信赖、可处理口述或朗读材料的端点。这不保证离线转写，OpenCode 凭据也不会自动授权语音。完成后停止录音/播放；更改密钥或端点影响后续请求，而非已发送到提供商的数据。向其他用户公开服务器前请参阅安全。