OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

媒体与设备

音频和语音消息

功能说明

启用音频理解（或自动检测到可用方式）后，OpenClaw 会：

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

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

自动检测（默认）

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

  1. 当前回复模型，前提是其提供商支持音频理解。
  2. 已配置的提供商身份验证 — 任何具有可用身份验证、且对应提供商支持音频转录的 models.providers.* 条目。此项会在本地 CLI 之前检查，因此配置的 API key 始终优先于 PATH 中的本地二进制文件。 配置多个提供商时的优先级：Groq、OpenAI、xAI、Deepgram、Google、SenseAudio、ElevenLabs、Mistral。
  3. 本地 CLI（仅当未解析到提供商身份验证时）。OpenClaw 会构建一个有序的回退列表：
    • whisper-cli，仅当当前进程中较早的模型调用已检测到 Metal 或 CUDA 时，才排在 CPU 默认选项之前
    • 使用默认 CPU 提供商的 sherpa-onnx-offline（需要设置 SHERPA_ONNX_MODEL_DIR，其中包含 tokens.txt、encoder.onnx、decoder.onnx 和 joiner.onnx）
    • whisper-cli，当 Metal/CUDA 仅具备构建能力，或选定后端尚未被实际检测到时
    • Apple Silicon 上的 parakeet-mlx（具备 MLX 能力；设备使用情况仍未实际检测）
    • whisper（Python CLI；自动下载模型）

安装/链接来源只能作为能力证据，不能作为执行证据。仅凭这一点，候选项绝不会排到 CPU sherpa 之前。OpenClaw 不会仅为探测后端而在设置或状态检查期间加载模型。 自动检测到的 whisper.cpp 会保留其正常的模型运行日志，以便 OpenClaw 记录上游的 using … backend 行。显式 CLI 条目则保留其配置的输出标志。

用于媒体理解的 Gemini CLI 自动检测已替换为沙箱隔离的 Antigravity CLI（agy）回退，用于图像/视频；除上述本地二进制文件外，音频不使用其他 CLI 回退。

若要禁用自动检测，请设置 tools.media.audio.enabled: false。若要自定义，请设置 tools.media.audio.models。

无需转录音频即可检查本地选择：

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

提供商清单会单独报告本地回退的胜出项以及全局提供商选择，并显示具备能力、请求使用和实际检测到的后端字段。转录运行后，/status 会在媒体行中报告请求使用或实际检测到的后端。显式 tools.media.audio.models CLI 条目仍会绕过自动选择；请使用其后端专用标志，例如 sherpa 的 --provider=cuda 或 whisper.cpp 的 --no-gpu/--device。

配置示例

提供商 + CLI 回退（OpenAI + Whisper CLI）

json5
{  tools: {    media: {      audio: {        enabled: true,        maxBytes: 20971520,        models: [          { provider: "openai", model: "gpt-4o-transcribe" },          {            type: "cli",            command: "whisper",            args: ["--model", "base", "{{MediaPath}}"],            timeoutSeconds: 45,          },        ],      },    },  },}

仅使用提供商，并通过作用域控制

json5
{  tools: {    media: {      audio: {        enabled: true,        scope: {          default: "allow",          rules: [{ action: "deny", match: { chatType: "group" } }],        },        models: [{ provider: "openai", model: "gpt-4o-transcribe" }],      },    },  },}

仅使用提供商（Deepgram）

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

仅使用提供商（Mistral Voxtral）

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

仅使用提供商（SenseAudio）

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

将转录文本回显到聊天（选择启用）

json5
{  tools: {    media: {      audio: {        enabled: true,        echoTranscript: true, // default is false        echoFormat: '📝 "{transcript}"', // optional, supports {transcript}        models: [{ provider: "openai", model: "gpt-4o-transcribe" }],      },    },  },}

注意事项和限制

  • 提供商身份验证遵循标准模型身份验证顺序（身份验证配置文件、环境变量、models.providers.*.apiKey）。
  • Groq 设置详情：Groq。
  • 使用 provider: "deepgram" 时，Deepgram 会读取 DEEPGRAM_API_KEY。设置详情：Deepgram。
  • Mistral 设置详情：Mistral。
  • 使用 provider: "senseaudio" 时，SenseAudio 会读取 SENSEAUDIO_API_KEY。设置详情：SenseAudio。
  • 音频提供商可以通过 tools.media.audio 覆盖 baseUrl、headers 和 providerOptions。
  • 默认大小上限为 20MB（tools.media.audio.maxBytes）。对于该模型，超出大小限制的音频会被跳过，并尝试下一个条目。
  • 小于 1024 字节的音频文件会在提供商/CLI 转录之前被跳过。
  • 音频的默认 maxChars 未设置（保留完整转录文本）。设置 tools.media.audio.maxChars 或各条目的 maxChars 可截短输出。
  • OpenAI 自动检测的默认模型为 gpt-4o-transcribe；设置 model: "gpt-4o-mini-transcribe" 可使用成本更低、速度更快的选项。
  • 使用 tools.media.audio.attachments 处理多条语音消息（mode: "all" 加 maxAttachments，默认值为 1）。
  • 模板可通过 {{Transcript}} 访问转录文本。
  • tools.media.audio.echoTranscript 默认关闭；启用后，会在智能体处理之前将转录确认发送回原始聊天。
  • tools.media.audio.echoFormat 用于自定义回显文本（占位符：{transcript}；默认值为 📝 "{transcript}"）。
  • CLI 标准输出上限为 5MB；请保持 CLI 输出简洁。
  • CLI args 应使用 {{MediaPath}} 表示本地音频文件路径。运行 openclaw doctor --fix，可迁移旧版 audio.transcription.command 配置中已弃用的 {input} 占位符（已停用的键：audio.transcription，由 tools.media.audio.models 取代）。
  • tools.media.concurrency 限制媒体任务数量；它并非 GPU 调度器。

常驻本地 STT

自动检测的本地 STT 仍采用每个请求一个进程的方式。OpenClaw 目前不管理常驻 whisper.cpp 服务器，因为标准 Homebrew whisper-cpp 软件包禁用了该服务器，而上游示例未配置有界准入队列。要安全启用由插件所有的常驻生命周期，需要有一个持续维护的打包工作进程，支持健康检查/启动、模型常驻、有界队列、取消/超时、仅 local loopback 且无身份验证的运行方式，并且不能回退到云端。

代理环境支持

基于提供商的音频转录遵循标准出站代理环境变量，与 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 格式、其他格式以及自定义输出模板仍使用标准输出。
  • 请将超时设置在合理范围内（timeoutSeconds，默认 60 秒），以免阻塞回复队列。
  • 预检转录仅处理用于提及检测的第一个音频附件。其他音频附件会在主要媒体理解阶段处理。

相关内容

Was this useful?
On this page

On this page