人工智能AI Agent即时通讯后端本地部署语音【免费下载链接】openclaw-cn中文社区版OpenClaw同原版保持定期更新已内置钉钉、企业微信、飞书、QQ、微信以及国内网络环境优化。你的专属个人AI助手。支持所有操作系统和平台。项目地址https://gitcode.com/gh_mirrors/op/openclaw-cn点击查看免费下载本文是 openclaw-cn中文社区版 OpenClaw / Clawdbot项目中 Deepgram 语音转写Speech-to-Text功能的完整接入指南。它讲解如何通过tools.media.audio配置把收到的语音消息上传到 Deepgram 并转成文字、注入回复管道同时结合 Deepgram 实现源码、配置类型定义 与 测试用例带你理解从收到音频到LLM 拿到转写文本的完整链路。读完本文你将能独立完成 API 密钥配置、模型与语言参数调优、代理端点覆盖以及多模型回退等实战配置。Deepgram 在 openclaw-cn 中的角色接收语音消息的转写引擎Deepgram 是一个语音转文字Speech-to-TextAPI 服务。在 openclaw-cn 中它被注册为媒体理解Media Understanding体系下的一个音频转写供应商通过tools.media.audio配置生效专门负责接收侧inbound的音频/语音消息转写——也就是别人发来的语音条、音频文件而不是助手自己生成的语音。其工作模式是收到带音频附件的消息后定位第一个音频附件本地路径或 URL必要时先下载把音频文件通过POST上传到 Deepgram 的预录音转写端点将转写结果以{{Transcript}}模板变量与[Audio]块的形式注入回复管道供后续的 LLM 与命令解析使用。需要特别强调的是这不是流式转写。仓库中的 Deepgram 供应商实现调用的是预录音prerecorded转写接口一次上传、一次返回全文不会输出实时中间结果。从源码看Deepgram 供应商在 媒体理解供应商注册表 中以deepgram为 id 注册能力capabilities仅声明为[audio]对应实现见 deepgram/index.tsexport const deepgramProvider: MediaUnderstandingProvider { id: deepgram, capabilities: [audio], transcribeAudio: transcribeDeepgramAudio, };快速开始两步启用 Deepgram 音频转写第 1 步设置 API 密钥Deepgram 采用最简单的环境变量方式即可完成认证。在环境或配置加载处设置DEEPGRAM_API_KEYdg_...从 model-auth.ts 的供应商密钥映射 可以看到deepgram供应商对应的环境变量就是DEEPGRAM_API_KEY。仓库的 live 测试 audio.live.test.ts 也直接通过process.env.DEEPGRAM_API_KEY读取密钥并支持用DEEPGRAM_MODEL、DEEPGRAM_BASE_URL环境变量覆盖模型与端点方便你在不修改配置文件的前提下做验证。第 2 步在配置中启用音频媒体理解在clawdbot.config.json5或等价配置入口中写入{ tools: { media: { audio: { enabled: true, models: [{ provider: deepgram, model: nova-3 }] } } } }启用后每当收到音频附件Clawdbot 就会把音频文件上传到 Deepgram并把转写结果注入回复管道。若只想验证转写是否生效可参考 docs/nodes/audio.md 中提到的Provider-only (Deepgram)最小配置它与上面的示例等价。配置参数详解模型、语言与 Deepgram 专属选项完整的音频媒体理解配置项定义在 types.tools.ts并经过 zod-schema.core.ts 的运行时校验。以下是 Deepgram 相关的核心参数。model模型 ID类型字符串默认值nova-3作用指定 Deepgram 使用的转写模型。模型默认值有两处源码佐证一处是 defaults.ts 的 DEFAULT_AUDIO_MODELS 中deepgram: nova-3另一处是 deepgram/audio.ts 的 DEFAULT_DEEPGRAM_AUDIO_MODEL。即便你在配置中省略modelrunner 也会回落到这个默认值。若显式配置但值为空字符串实现里同样会回落到默认模型function resolveModel(model?: string): string { const trimmed model?.trim(); return trimmed || DEFAULT_DEEPGRAM_AUDIO_MODEL; }language语言提示可选类型字符串作用为转写提供语言提示例如中文可指定zh。指定语言后该值会作为language查询参数附加到 Deepgram/listen请求上。示例配置{ tools: { media: { audio: { enabled: true, models: [ { provider: deepgram, model: nova-3, language: zh } ] } } } }language也可以在tools.media.audio.language层级统一定义优先级为模型条目entry上的language 能力级config.languagecfg.tools.media.audio.language见 runner.ts 的音频调用段。适合所有模型统一用中文提示的场景。providerOptions.deepgramDeepgram 专属转写选项这些选项最终会被转成 Deepgram/listen接口的查询参数snake_case。支持的三个开关配置键对应查询参数作用detect_languagedetect_language启用语言自动检测punctuatepunctuate启用标点符号逗号、句号等smart_formatsmart_format启用智能格式化数字、日期、金额等规范化带 Deepgram 选项的完整示例{ tools: { media: { audio: { enabled: true, providerOptions: { deepgram: { detect_language: true, punctuate: true, smart_format: true } }, models: [{ provider: deepgram, model: nova-3 }] } } } }从 zod-schema.core.ts 的 DeepgramAudioSchema 可见这三个字段均为可选布尔值且 schema 是 strict 的——拼写错误的键会被校验拒绝。兼容性说明旧的 deepgram 顶层字段已废弃仓库在 types.tools.ts 和 zod-schema.core.ts 中保留了一组已标记 deprecated的顶层deepgram字段detectLanguage/punctuate/smartFormat用于兼容旧配置。runner 在 resolveProviderQuery 中会优先采用providerOptions.deepgram再以旧字段兜底同时通过normalizeDeepgramQueryKeys把 camelCase 写法如detectLanguage归一化为 snake_casedetect_language后发给 Deepgram。如果你使用的是较新版本建议统一写在providerOptions.deepgram下。底层原理一次 Deepgram 转写请求的完整调用链理解请求细节有助于排查问题和做性能预估。核心实现位于 src/media-understanding/providers/deepgram/audio.ts其调用链如下端点组装默认 base URL 为https://api.deepgram.com/v1常量DEFAULT_DEEPGRAM_AUDIO_BASE_URL实际请求地址为${baseUrl}/listenmodel、language以及所有 providerOptions 都以查询参数形式拼入 URLconst url new URL(${baseUrl}/listen); url.searchParams.set(model, model); if (params.language?.trim()) url.searchParams.set(language, params.language.trim());认证与请求头若未显式提供authorization则设置authorization: Token ${apiKey}同时按音频 MIME 类型设置content-type无 MIME 时回落为application/octet-stream。上传方式使用fetchWithTimeoutGuarded发起POST请求体是原始音频字节Uint8Array而非 base64并携带调用方传入的超时timeoutMs。响应解析从 Deepgram 返回的 JSON 中逐层取results.channels[0].alternatives[0].transcript作为最终转写文本若取不到文本则抛出Audio transcription response missing transcript错误。失败处理HTTP 非 2xx 时读取响应体并抛出Audio transcription failed (HTTP status)便于上层 fallback 逻辑捕获并尝试下一个模型。值得注意的是 runner.ts 的音频执行段provider 模式下会先通过resolveApiKeyForProvider解析密钥要求必须拿到 apiKey再合并三层配置来源——models.providers.deepgram供应商级、tools.media.audio能力级、models条目级——得到最终的baseUrl、headers与 provider 查询参数。认证顺序与密钥来源Deepgram 的认证遵循项目统一的标准供应商认证顺序。文档明确指出DEEPGRAM_API_KEY是最简单的方式这与 model-auth.ts 的实现一致deepgram直接映射到DEEPGRAM_API_KEY环境变量。若你配置了认证 profile密钥解析会按标准顺序依次尝试 profile 存储、环境变量、models.providers.*.apiKey等来源环境变量始终是零配置首选。通过 baseUrl 与 headers 覆盖端点代理/自建网关场景当你的网络环境需要走代理或需要把请求转发到兼容 Deepgram 协议的自建网关时可在tools.media.audio下覆盖端点与请求头{ tools: { media: { audio: { enabled: true, baseUrl: https://your-proxy.example.com/v1, headers: { X-Custom-Header: value }, models: [{ provider: deepgram, model: nova-3 }] } } } }对应的行为有测试用例直接验证runner.deepgram.test.ts 构造了供应商级、能力级、条目级三层baseUrl/headers并存的情况断言最终生效的是条目级baseUrlhttps://entry.example而 headers 会按 供应商级 → 能力级 → 条目级 的顺序合并X-Provider、X-Config、X-Entry同时存在。这意味着baseUrl是就近覆盖模型条目上的优先级最高headers是合并叠加越靠近条目的键值越靠后、可覆盖同名键。同时该测试还验证了providerOptions的合并语义条目级的detectLanguage: false覆盖能力级的detect_language: true最终发送给 Deepgram 的查询参数为detect_languagefalse, punctuatefalse, smart_formattrue且不会残留 camelCase 键。转写结果的注入{{Transcript}} 与 [Audio] 块转写成功后结果会按照统一的媒体理解输出格式注入消息上下文。相关逻辑在 format.ts 与 apply.ts单条音频转写时Body被替换为[Audio]块[Audio] Transcript: 转写文本如果原始消息里还带有用户文字则会保留为User text:段[Audio] User text: 用户附带文字 Transcript: 转写文本多条音频mode: allmaxAttachments时块标题带序号如[Audio 1/2]、[Audio 2/2]多段之间用空行分隔。同时ctx.Transcript被设置为转写文本多条时按Audio 1:... / Audio 2:...拼接模板中可直接使用{{Transcript}}。命令解析层面见 apply.ts转写成功后CommandBody/RawBody也会被设为转写文本或原始用户文字从而保证语音下达的斜杠命令slash command依然能正常解析。对应断言可在 apply.test.ts 中看到例如expect(ctx.Body).toBe([Audio]\nTranscript:\ntranscribed text);与其他音频规则的协同大小限制、超时与多模型回退文档强调输出遵循与其他供应商相同的音频规则。这些规则的默认值定义在 defaults.ts大小限制音频默认maxBytes为 20MB20 * MB。超限的附件会触发 skiprunner 会继续尝试列表中的下一个模型见 runner.ts 的 runAttachmentEntries。超时音频默认timeoutSeconds为 60 秒可在能力级或条目级覆盖。输出长度音频默认maxChars为未设置保留完整转写需要截断时可配置tools.media.audio.maxChars或条目级maxChars。多模型回退models是一个有序数组第一个成功且输出非空的条目胜出失败/跳过后自动尝试下一个每个条目的成败与原因都会记录进MediaUnderstandingDecisions便于在 verbose 日志中追踪。并发控制tools.media.concurrency控制媒体理解任务的最大并发数默认值为 2defaults.ts。未配置时的自动探测顺序如果你没有显式配置tools.media.audio.models且enabled未被设为false系统会按 docs/nodes/audio.md 描述的自动探测顺序尝试并在第一个可用选项处停止本地 CLI若已安装sherpa-onnx-offline、whisper-cliwhisper-cpp、whisperPythonGemini CLIgemini通过read_many_files读取音频Provider 密钥OpenAI → Groq → Deepgram → Google对应 runner.ts 的 AUTO_AUDIO_KEY_PROVIDERS。也就是说即使你不写任何 Deepgram 配置只要环境里有DEEPGRAM_API_KEY系统也会把它作为音频转写的候选供应商之一反之如果你想完全关闭自动探测设置tools.media.audio.enabled: false即可。验证与测试仓库为 Deepgram 音频转写提供了两级测试可直接用于验证配置正确性单元级合并逻辑测试runner.deepgram.test.ts用 mock provider 验证providerOptions、baseUrl、headers的三层合并与键名归一化不依赖真实网络。真实转写 live 测试audio.live.test.ts需要设置DEEPGRAM_API_KEY且开启 live 开关如OPENCLAW_LIVE_TESTtrue才会运行。它默认下载 Deepgram 官方示例音频.wav并调用transcribeDeepgramAudio断言转写文本非空并可通过DEEPGRAM_MODEL、DEEPGRAM_BASE_URL环境变量切换模型与端点。这两个文件也是排查配置没问题但转写失败时的最佳参照前者说明参数是否被正确透传后者说明密钥与网络是否可用。注意事项小结转写是非流式的一次上传、一次返回全文长音频请合理预估 60 秒默认超时必要时调大timeoutSeconds。认证优先走标准顺序DEEPGRAM_API_KEY是零配置的最简方式自建代理时用tools.media.audio.baseUrlheaders覆盖。providerOptions.deepgram中的键使用 snake_casedetect_language、punctuate、smart_format旧的顶层deepgram.detectLanguage等字段虽仍兼容但已标记废弃新配置应迁移到providerOptions.deepgram。音频超过 20MB 默认上限会被跳过并尝试下一个模型想处理多条语音用tools.media.audio.attachments.mode: all配合maxAttachments。转写文本会同时注入{{Transcript}}模板变量、[Audio]块Body以及CommandBody/RawBody因此语音下达的命令也能正常执行。赞分享人工智能AI Agent即时通讯后端本地部署语音【免费下载链接】openclaw-cn中文社区版OpenClaw同原版保持定期更新已内置钉钉、企业微信、飞书、QQ、微信以及国内网络环境优化。你的专属个人AI助手。支持所有操作系统和平台。项目地址https://gitcode.com/gh_mirrors/op/openclaw-cn点击查看免费下载相关推荐OpenClaw 接入 Deepgram为语音留言启用 Nova-3 音频转写OpenClaw 接入 Deepgram为语音留言启用 Nova 3 音频转写 Deepgram 是 OpenClaw 内置的语音转文字speech to人工智能大模型LLM 网关AI Agent即时通讯openclaw-cnClawdbot语音消息自动转写指南音频下载、转录与回复注入openclaw cnClawdbot语音消息自动转写指南音频下载、转录与回复注入 本文是 openclaw cn中文社区版 OpenClaw核心代码人工智能AI Agent即时通讯后端本地部署语音基于 ai-sdk/deepgram 的语音转写与语音合成实战AI SDK Deepgram Provider 能力全解析基于 ai sdk/deepgram 的语音转写与语音合成实战AI SDK Deepgram Provider 能力全解析 本篇文章以 ai sdk/de人工智能AI 应用AI Agent工具调用MCP Clients创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考