Deepgram 配置指南：语音转文字 (STT)

在 OpenClaw 中配置 Deepgram 语音转文字提供商，用于自动转录 inbound 音频消息和电话语音流。你只需设置 DEEPGRAM_API_KEY 环境变量，并在 tools.media.audio 配置中启用 Deepgram 模型即可。启用后，OpenClaw 会通过 Deepgram 的 API 或 WebSocket 实时转录音频，并将结果注入回复管道。支持语言检测、标点、智能格式化等可选参数，默认使用 nova-3 模型。

Deepgram 是一个语音转文字 API。在 OpenClaw 中，它主要用于两种场景：

• 入站音频/语音消息转录：通过 tools.media.audio 配置。OpenClaw 将完整的音频文件上传至 Deepgram，并将转录结果注入回复管道（{{Transcript}} + [Audio] 块）。
• 电话语音流实时转录 (STT)：通过 plugins.entries.voice-call.config.streaming 配置。OpenClaw 将实时 G.711 u-law 音频帧转发至 Deepgram 的 WebSocket listen 端点，并逐步输出部分或最终转录结果。

详情	值
官网	deepgram.com
文档	developers.deepgram.com
认证方式	DEEPGRAM_API_KEY
默认模型	nova-3

快速开始

1. 设置 API Key
   将你的 Deepgram API Key 添加至环境变量：

   DEEPGRAM_API_KEY=dg_...

2. 启用音频提供商
   在 OpenClaw 配置中启用 Deepgram 音频模型：

   {
     tools: {
       media: {
         audio: {
           enabled: true,
           models: [{ provider: "deepgram", model: "nova-3" }],
         },
       },
     },
   }

3. 发送一条语音消息
   通过已连接的任意渠道（如 WhatsApp、Telegram）发送一条音频消息。OpenClaw 会自动通过 Deepgram 进行转录，并将文本注入回复管道。

配置选项

选项	配置路径	描述
model	tools.media.audio.models[].model	Deepgram 模型 ID（默认：nova-3）
language	tools.media.audio.models[].language	语言提示（可选）
detect_language	tools.media.audio.providerOptions.deepgram.detect_language	启用语言检测（可选）
punctuate	tools.media.audio.providerOptions.deepgram.punctuate	启用标点符号（可选）
smart_format	tools.media.audio.providerOptions.deepgram.smart_format	启用智能格式化（可选）

带语言提示的示例：

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "deepgram", model: "nova-3", language: "en" }],
      },
    },
  },
}

带 Deepgram 高级选项的示例：

{
  tools: {
    media: {
      audio: {
        enabled: true,
        providerOptions: {
          deepgram: {
            detect_language: true,
            punctuate: true,
            smart_format: true,
          },
        },
        models: [{ provider: "deepgram", model: "nova-3" }],
      },
    },
  },
}

电话语音流实时 STT 配置

Deepgram 插件也为电话语音 (Voice Call) 插件提供了实时转录能力。需在 Voice Call 插件的 streaming 配置段中指定 Deepgram 作为提供商。

设置	配置路径	默认值
API Key	plugins.entries.voice-call.config.streaming.providers.deepgram.apiKey	回退到 DEEPGRAM_API_KEY
模型	...deepgram.model	nova-3
语言	...deepgram.language	(不设置)
编码	...deepgram.encoding	mulaw
采样率	...deepgram.sampleRate	8000
端点检测时长 (ms)	...deepgram.endpointingMs	800
返回中间结果	...deepgram.interimResults	true

电话语音流 Deepgram 配置示例：

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          streaming: {
            enabled: true,
            provider: "deepgram",
            providers: {
              deepgram: {
                apiKey: "${DEEPGRAM_API_KEY}",
                model: "nova-3",
                endpointingMs: 800,
                language: "en-US",
              },
            },
          },
        },
      },
    },
  },
}

注意：电话语音流接收的是 8 kHz G.711 u-law 格式的音频。Deepgram 流式提供商默认使用 encoding: "mulaw" 和 sampleRate: 8000，因此 Twilio 媒体的音频帧可以直接转发而无需额外转换。

注意事项

• 认证：遵循标准提供商认证顺序。直接使用 DEEPGRAM_API_KEY 是最简单的配置方式。
• 代理与自定义端点：若需使用代理，可通过 tools.media.audio.baseUrl 和 tools.media.audio.headers 覆盖接口地址和请求头。
• 输出行为：输出行为遵循与其他提供商相同的音频规则（包括大小限制、超时设置及转录注入逻辑）。

常见问题

Deepgram API Key 从哪里获取？

登录 Deepgram 控制台，在左侧导航栏找到 "API Keys" 并创建。将生成的密钥（格式为 dg_...）设置为环境变量 DEEPGRAM_API_KEY。

怎么切换 Deepgram 使用的模型？

在 tools.media.audio.models[].model 中修改模型 ID，例如从 nova-3 改为 nova-2。目前默认模型为 nova-3。

电话语音流 (Voice Call) 无法识别怎么办？

请确认 Voice Call 插件的 streaming 配置中 provider 被设为 "deepgram"，并且 apiKey 设置正确（可直接设置或通过环境变量回退）。若音频格式不匹配，请检查 encoding 和 sampleRate 是否与你的电话系统（如 Twilio）的参数一致（默认使用 mulaw 编码和 8000 采样率）。