音频和语音留言

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

功能说明¶

当音频理解功能已启用（或自动检测）时，OpenClaw：

1. 定位第一个音频附件（本地路径或 URL），并在需要时下载它。
2. 在发送到每个模型条目之前强制执行 maxBytes。
3. 按顺序运行第一个符合条件的模型条目（提供商或 CLI）；如果某个条目失败或跳过（大小/超时），则尝试下一个条目。
4. 成功时，用 [Audio] 块替换 Body，并设置 {{Transcript}}。

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

对于插件调用方，文件转录会返回按附件索引键控的 decision.attachmentProcessing。"completed" 表示 CLI 或提供商完成了输入处理，包括成功的空输出；"omitted" 表示没有任何条目完成。诸如 context:、### 和 Transcribe the audio. 之类的独立转录产物，在到达会议存储或智能体输入之前，会被视为已完成但无语音的音频。包含这些词的实际文本会被保留。这一事实与可用的转录文本和附件显示标记相互独立。在旧版 SDK 结果中缺少该字段表示处理状态未知。对于 Discord 批量语音，已知的已省略输入可防止不完整话语变成会话命令或活动运行控制；有效的捕获笔记仍会保存。

自动检测（默认）¶

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

1. 活动回复模型，当其提供商支持音频理解时。
2. 已配置的提供商认证 — 任何为支持音频转录的提供商提供可用认证的 models.providers.* 条目。此检查先于本地 CLI 进行，因此已配置的 API 密钥始终优先于 PATH 上的本地二进制文件。 当配置多个提供商时，优先级为：Groq、OpenAI、xAI、Deepgram、Google、SenseAudio、ElevenLabs、Mistral。

3. 本地 CLI（仅在未解析到提供商认证时）。OpenClaw 会构建一个有序的回退列表：

4. whisper-cli — 仅当当前进程中较早的模型调用观察到 Metal 或 CUDA 时，才排在 CPU 默认项之前

5. sherpa-onnx-offline，使用其默认 CPU 提供商（需要 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 添加带能力标记的条目。

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

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

提供商清单会单独报告本地回退胜出者，与全局提供商选择分开，此外还包含 capable、requested 和 observed 后端字段。转录运行后，/status 会在媒体行中报告请求或观察到的后端。显式具备音频能力的 tools.media.models CLI 条目仍会绕过自动选择；请使用其后端特定标志，例如 sherpa 的 --provider=cuda 或 whisper.cpp 的 --no-gpu/--device。

结合 ChatGPT/Codex OAuth 的 OpenAI 转录¶

OpenAI 音频使用标准的 /v1/audio/transcriptions 端点，配合所选的 API 密钥或 ChatGPT/Codex OAuth 配置文件。当账户允许时，OAuth 登录可以进行转录；访问权限、配额和计费仍取决于具体账户。默认模型是 gpt-4o-transcribe；配置的模型、提示词和语言提示会通过同一个 multipart 请求发送，无论使用哪种凭据类别。自定义端点和请求覆盖需要 API 密钥配置文件。

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

除非显式选择了配置文件或 OAuth 认证模式，否则对于音频，显式配置的 OpenAI 提供商密钥优先于环境中的 OAuth。为了在将 OAuth 保留为常规文本和推理的首选方式的同时，显式分离音频计费，请创建一个专用的 API 密钥配置文件，并仅在音频模型条目上选择它。这是可选的；仅选择转录模型并不需要 API 密钥。

请对每个可以接收音频的智能体重复这些步骤。对于单智能体安装，请为该智能体运行一次。

1. 列出智能体的 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. 在代理的 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 配置文件放在第一位，用于常规提供商解析。

配置示例¶

提供商 + 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" },
    },
  },
}

仅提供商（Deepgram）¶

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

仅提供商（Mistral Voxtral）¶

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

仅提供商（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}"',
      },
    },
  },
}

注意事项和限制¶

• 提供商身份验证遵循标准模型身份验证顺序（身份验证配置文件、环境变量、models.providers.*.apiKey）。
• Groq 设置详情：Groq。
• 当使用 provider: "deepgram" 时，Deepgram 会读取 DEEPGRAM_API_KEY。设置详情：Deepgram。
• Mistral 设置详情：Mistral。
• 当使用 provider: "senseaudio" 时，SenseAudio 会读取 SENSEAUDIO_API_KEY。设置详情：SenseAudio。
• 音频提供商可以使用 tools.media.audio 下的默认值，或者在其 tools.media.models[] 条目中覆盖 baseUrl、headers、providerOptions 和限制。
• 保持 tools.media.audio.language 未设置以进行语言自动检测。提供商转录请求会省略隐式“Transcribe the audio.”提示，即使选择英语也是如此；显式自定义提示和语言提示会被保留。请使用转录提示来提供音频语言中的上下文或拼写，而不是作为给下游代理的指令。
• 内置音频大小上限为 20MB。条目级 maxBytes 覆盖可以更改它；对于该模型，超尺寸音频会被跳过，并尝试下一个条目。
• 小于 1024 字节的音频文件会在提供商/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 包禁用了该服务器，而上游示例没有配置有界准入队列。插件拥有的常驻生命周期需要一个受维护的打包工作进程，具备健康/启动、模型驻留、有界排队、取消/超时、仅限回环且无身份验证的操作，并且没有云回退，之后才能安全启用。

代理环境支持¶

基于提供商的音频转录遵循标准出站代理环境变量，与 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 秒），以避免阻塞回复队列。
• 预检转录仅处理第一个未转录的音频附件用于提及检测，即使主阶段偏好最后一个附件或处理所有附件。额外的音频附件会在主媒体理解阶段遵循已配置的策略；空的预检结果不会将附件标记为已转录。
• 当后续媒体或链接处理添加上下文时，预检转录文本会保留在面向模型的消息中。单独的频道信封不会替换该已准备好的文本。

相关¶

• 媒体播放
• 媒体理解
• 对话模式
• 语音唤醒
• 媒体概览 — 媒体工具如何协同工作