跳转至

音频和语音留言

本页介绍入站转录和语音笔记处理。有关 OpenClaw 聊天客户端中的内联音频和视频播放器,请参阅媒体播放。

功能说明

启用音频理解(或自动检测)后,OpenClaw 会:

  1. 找到第一个音频附件(本地路径或 URL),并在需要时下载它。
  2. 在发送到每个模型条目之前强制检查 maxBytes。
  3. 按顺序运行第一个符合条件的模型条目(provider 或 CLI);如果某个条目失败或被跳过(大小/超时),则尝试下一个条目。
  4. 成功后,将 Body 替换为 [Audio] 块,并设置 {{Transcript}}。

转录成功后,CommandBody/RawBody 也会被设置为转录文本,以便斜杠命令仍然有效。使用 --verbose 时,日志会显示转录何时运行以及何时替换正文。

对于插件调用者,文件转录返回 decision.attachmentProcessing,以附件索引为键。"completed" 表示 CLI 或 provider 完成了输入处理,包括成功的空输出;"omitted" 表示没有任何一个完成。独立的转录产物(如 context:、### 和 Transcribe the audio.)在到达会议存储或 agent 输入之前被视为无语音的已完成音频。包含这些词语的实质性文本会被保留。这一事实与可用转录文本和附件显示标记是分开的。旧版 SDK 结果中缺失字段表示处理状态未知。对于 Discord 批量语音,已知的省略输入可防止不完整发声变成对话命令或活动运行控制;有效的捕获笔记仍会被保存。

自动检测(默认)

如果你尚未配置模型,且 tools.media.audio.enabled 不是 false,OpenClaw 会按以下顺序自动检测,并在第一个可用选项处停止:

  1. 活动回复模型,当其 provider 支持音频理解时。
  2. 已配置的 provider 认证——任何 models.providers.* 条目,只要有可用于支持音频转录的 provider 的认证。它会在本地 CLI 之前被检查,因此已配置的 API 密钥始终优先于 PATH 上的本地二进制文件。 同时配置多个 provider 时的优先级:Groq、OpenAI、xAI、Deepgram、Google、SenseAudio、ElevenLabs、Mistral。
  3. 本地 CLI(仅在没有解析出 provider 认证时)。OpenClaw 会构建一个有序的回退列表:
  4. whisper-cli,仅当当前进程中的早期模型调用观察到 Metal 或 CUDA 时,才排在 CPU 默认值之前
  5. sherpa-onnx-offline 使用其默认 CPU provider(需要 SHERPA_ONNX_MODEL_DIR 包含 tokens.txt、encoder.onnx、decoder.onnx 和 joiner.onnx)
  6. whisper-cli,当 Metal/CUDA 仅可构建,或所选后端未被观察到时
  7. parakeet-mlx 用于 Apple Silicon(支持 MLX;设备使用情况仍未被观察到)
  8. whisper(Python CLI;自动下载模型)

安装/链接来源是能力证据,而不是执行证据。它本身永远不会让某个候选项排在 CPU sherpa 之前。OpenClaw 不会在设置或状态检查期间加载模型,仅仅是为了检查后端。 自动检测到的 whisper.cpp 会保持其正常的模型运行日志启用,以便 OpenClaw 记录上游的 using … backend 行。显式 CLI 条目会保留其配置的输出标志。

Gemini CLI 和 Antigravity 不会被自动检测用于媒体理解。音频不会使用上述本地二进制文件之外的 CLI 回退。

要禁用自动检测,请设置 tools.media.audio.enabled: false。要自定义,请向 tools.media.models 添加带有能力标签的条目。

Note

二进制检测在 macOS/Linux/Windows 上是尽力而为的。确保 CLI 在 PATH 上(~ 会被展开),或者使用完整命令路径设置一个显式的 CLI 模型。

在不转录音频的情况下检查本地选择:

openclaw capability audio providers
openclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

provider 清单会分别报告本地回退胜出者与全局 provider 选择,以及有能力的、请求的和观察到的后端字段。转录运行后,/status 会在媒体行中报告请求或观察到的后端。显式的、支持音频的 tools.media.models CLI 条目仍会绕过自动选择;请使用其特定后端的标志,如 sherpa 的 --provider=cuda 或 whisper.cpp 的 --no-gpu/--device。

OpenAI 转录与 ChatGPT/Codex OAuth

OpenAI 音频使用标准的 /v1/audio/transcriptions 端点,并使用所选的 API 密钥或 ChatGPT/Codex OAuth 配置文件。OAuth 登录在账户允许的情况下可以转录;访问、配额和计费仍因账户而异。默认模型是 gpt-4o-transcribe;对于任一凭据类别,配置的模型、提示词和语言提示都会通过同一个 multipart 请求发送。自定义端点和请求覆盖需要 API 密钥配置文件。

当 OpenAI 插件在上传音频之前拒绝认证或配置时,自动选择可以尝试另一个 provider 或本地后端。该拒绝在尝试结果中仍然可见;缺少凭据只会让该候选项不可用。一旦某个 provider 尝试转录,上传或 HTTP 失败会被报告,而不会自动将录音发送给另一个 provider,也不会切换凭据类别。显式模型列表会保留其配置的回退顺序。

除非显式选择了某个配置文件或 OAuth 认证模式,否则显式配置的 OpenAI provider 密钥在音频方面优先于环境 OAuth。 为了在正常文本和推理中继续保持 OAuth 优先的同时,明确地将音频计费分离,可以创建一个专用 API 密钥配置文件,并且只将其选用于音频模型条目。这是可选的;仅仅为了选择转录模型并不需要 API 密钥。

对每个可以接收音频的 agent 重复这些步骤。对于单 agent 安装,只需对那个 agent 执行一次。

  1. 列出该 agent 的 OpenAI 配置文件,以便复制确切的 OAuth 配置文件 ID:
openclaw models auth list --agent AGENT_NAME_HERE --provider openai
  1. 创建专用的 API 密钥配置文件。此命令会提示输入密钥;请将密钥粘贴到提示符中,而不是放在命令行里:
openclaw models auth paste-api-key --agent AGENT_NAME_HERE --provider openai --profile-id openai:CUSTOM_PROFILE_NAME_HERE

示例:

openclaw models auth paste-api-key --agent smith --provider openai --profile-id openai:audio
  1. 在该 agent 的 OpenAI 认证顺序中,将 OAuth 配置文件放在第一位,音频 API 密钥配置文件放在第二位。将第一个配置文件 ID 替换为 list 命令所报告的精确 OAuth 配置文件 ID:
openclaw models auth order set --agent AGENT_NAME_HERE --provider openai openai:YOUR_OPENAI_ACCOUNT_EMAIL_ADDRESS openai:CUSTOM_PROFILE_NAME_HERE

示例:

openclaw models auth order set --agent smith --provider openai openai:youremailaddress@email.com openai:audio
  1. 配置 OpenAI 转录模型,并显式选择 API 密钥配置文件:
{
  tools: {
    media: {
      models: [
        {
          provider: "openai",
          model: "gpt-4o-transcribe",
          profile: "openai:audio",
          baseUrl: "https://api.openai.com/v1",
          capabilities: ["audio"],
        },
      ],
      audio: { enabled: true },
    },
  },
}

如果你选择了其他自定义配置文件名称,请在 profile 中使用该确切的配置文件 ID。你也可以将模型替换为 gpt-4o-mini-transcribe。

当 OpenClaw 能够明确选择兼容的 API 密钥配置文件时,profile 字段并非必需,但强烈建议填写。显式选择可确保音频路由的确定性,即使当前存在或以后添加了其他 OpenAI API 密钥配置文件。认证顺序仍会将 OAuth 配置文件保持在第一位,以供常规 provider 解析使用。

Warning

切勿仅为了在通过 ChatGPT/Codex OAuth 进行常规推理的安装中启用转录,就设置 models.providers.openai.apiKey。该设置是 provider 全局性的,而非仅限定于音频模型条目。

配置示例

Provider + CLI 回退方案(OpenAI + Whisper CLI)

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-4o-transcribe", capabilities: ["audio"] },
        {
          type: "cli",
          command: "whisper",
          args: ["--model", "base", "{{AttachmentPath}}"],
          timeoutSeconds: 45,
          capabilities: ["audio"],
        },
      ],
      audio: { enabled: true, preferredModel: "openai/gpt-4o-transcribe" },
    },
  },
}

仅 Provider(Deepgram)

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

仅 Provider(Mistral Voxtral)

{
  tools: {
    media: {
      models: [{ provider: "mistral", model: "voxtral-mini-latest", capabilities: ["audio"] }],
      audio: { enabled: true },
    },
  },
}

仅 Provider(SenseAudio)

{
  tools: {
    media: {
      models: [
        {
          provider: "senseaudio",
          model: "senseaudio-asr-pro-1.5-260319",
          capabilities: ["audio"],
        },
      ],
      audio: { enabled: true },
    },
  },
}

将转录回显到对话(可选启用)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
    },
  },
}

注意事项与限制

  • Provider 认证遵循标准模型认证顺序(认证配置文件、环境变量、models.providers.*.apiKey)。
  • Groq 设置详情:Groq。
  • 当使用 provider: "deepgram" 时,Deepgram 会读取 DEEPGRAM_API_KEY。设置详情:Deepgram。
  • Mistral 设置详情:Mistral。
  • 当使用 provider: "senseaudio" 时,SenseAudio 会读取 SENSEAUDIO_API_KEY。设置详情:SenseAudio。
  • 音频 provider 可以使用 tools.media.audio 下的默认值,也可以在其 tools.media.models[] 条目上覆盖 baseUrl、headers、providerOptions 和限制。
  • 将 tools.media.audio.language 留空以启用语言自动检测。Provider 转录请求会省略隐式的“Transcribe the audio.”提示,即使选择了英语也是如此;显式自定义提示和语言提示会被保留。请使用转录提示来提供音频语言中的上下文或拼写信息,而不是将其用作对下游 agent 的指令。
  • 内置音频大小上限为 20MB。可以通过条目级别的 maxBytes 覆盖来更改该限制;超出大小的音频会跳过该模型,并继续尝试下一个条目。
  • 小于 1024 字节的音频文件会在 provider/CLI 转录之前被跳过。
  • 音频的默认 maxChars 为未设置(完整转录)。设置 tools.media.audio.maxChars 或条目级 maxChars 可裁剪输出。
  • OpenAI 自动检测的默认模型是 gpt-4o-transcribe;如需更便宜/更快的选项,可设置 model: "gpt-4o-mini-transcribe"。
  • 转录结果可通过 {{Transcript}} 提供给模板。
  • tools.media.audio.echoTranscript 默认关闭;echoFormat 接受 {transcript} 占位符。
  • CLI 的标准输出(stdout)上限为 5MB;请保持 CLI 输出简洁。
  • CLI 的 args 应使用 {{AttachmentPath}} 作为本地音频文件路径。运行 openclaw doctor --fix 可迁移旧版 audio.transcription.command 配置中已弃用的 {input} 占位符(已停用的键:audio.transcription,已被 tools.media.models 取代)。{{MediaPath}} 仍作为已弃用的兼容别名保留。
  • tools.media.concurrency 用于限制媒体任务的并发数;它不是 GPU 调度器。

常驻本地 STT

自动检测到的本地 STT 仍为每次请求一个进程。OpenClaw 不会管理常驻的 whisper.cpp 服务器,因为标准的 Homebrew whisper-cpp 软件包禁用了该服务器,而上游示例没有配置有界准入队列。插件自有的常驻生命周期需要一个经过维护的打包 worker,该 worker 需具备健康检查/启动、模型驻留、有界排队、取消/超时、仅回环且免认证运行、无云回退等特性,之后才能安全启用。

代理环境支持

基于提供方的音频转录支持标准出站代理环境变量,与 undici 的 EnvHttpProxyAgent 语义一致:

  • HTTPS_PROXY / https_proxy
  • HTTP_PROXY / http_proxy
  • ALL_PROXY / all_proxy

小写变量优先于大写变量;NO_PROXY/no_proxy 条目(主机名、*.suffix 或 host:port)会绕过代理。如果未设置代理环境变量,则使用直接出站。如果代理配置失败(URL 格式错误),OpenClaw 会记录警告并回退到直接请求。

群组中的提及检测

在支持音频预检的渠道上,当群聊设置了 requireMention: true 时,OpenClaw 会在检查提及之前转录音频。这样,无字幕的语音消息在其转录文本包含已配置的提及模式时,可以通过提及门槛。特定渠道文档会描述那些要求键入式提及的传输方式。

工作原理:

  1. 如果语音消息没有文本正文,且群组要求提及,OpenClaw 会对第一个音频附件执行预检转录。
  2. 系统会检查转录文本中的提及模式(例如 @BotName、表情触发器)。
  3. 如果找到提及,消息将进入完整的回复流水线。

回退行为: 如果预检转录失败(超时、API 错误等),消息会回退到仅文本提及检测,因此混合消息(文本 + 音频)不会被丢弃。

按 Telegram 群组/主题退出:

  • 设置 channels.telegram.groups.<chatId>.disableAudioPreflight: true 以跳过该群组的预检转录提及检查。
  • 设置 channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight 以按主题覆盖(true 表示跳过,false 表示强制启用)。
  • 默认值为 false(当提及门槛条件匹配时启用预检)。

示例: 用户在设置了 requireMention: true 的 Telegram 群组中发送一条语音消息,内容为“嘿 @Claude,天气怎么样?”。语音消息被转录,提及被检测到,代理随后回复。

注意事项

  • 作用域规则采用首个匹配优先;chatType 会被规范化为 direct、group 或 channel。
  • 确保你的 CLI 以 0 退出并打印纯文本;JSON 输出需要通过 jq -r .text 进行处理。
  • 已知文件输出模式以文件为准:空的或缺失的推断转录文件不会产生转录文本,而不是回退到 CLI 进度输出。
  • 对于 parakeet-mlx,请使用 --output-format txt(或 all)配合 --output-dir 和默认 {filename} 输出模板。上游的 PARAKEET_OUTPUT_FORMAT 和 PARAKEET_OUTPUT_TEMPLATE 环境变量也会被遵循。OpenClaw 会读取 <output-dir>/<media-basename>.txt;默认 srt 格式、其他格式以及自定义输出模板仍继续使用 stdout。
  • 保持超时时间合理(timeoutSeconds,默认 60 秒),以避免阻塞回复队列。
  • 预检转录仅处理第一个未转录的音频附件以进行提及检测,即使主阶段偏好最后一个附件或处理所有附件。其他音频附件会在主媒体理解阶段遵循已配置的策略;空的预检结果不会将附件标记为已转录。
  • 当后续媒体或链接处理添加上下文时,预检转录文本会保留在面向模型的消息中。单独的渠道信封不会替换该已准备的文本。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw