Audio and Voice Notes

这个功能就像是给 OpenClaw 装上了一对“耳朵”。当你发来一段语音或者一个音频文件，它会努力去听，然后把听到的话写下来。

它是怎么工作的呢？

1. 找到音频：它会先找到你消息里的第一个音频文件，如果需要的话，会把它先下载下来。
2. 检查大小：它会看看这个音频文件是不是太大了（默认不能超过 20MB），太大了它可能就听不了。
3. 找人帮忙听：它会按照你告诉它的顺序，找一个“帮手”来把音频变成文字。这个帮手可能是一个安装在电脑上的小工具（我们叫它“CLI”），也可能是像 OpenAI、Google 这样的大公司提供的在线服务（我们叫它“Provider”）。
4. 一个不行换一个：如果第一个帮手失败了或者超时了，它会很聪明地去找列表里的下一个帮手试试。
5. 成功啦：一旦有帮手成功把语音变成文字，它就会把原来的消息内容换成 [Audio] 标记，并且把写好的文字存到一个叫 {{Transcript}} 的魔法小盒子里，以后可以用。

自动找帮手（默认方式） 如果你没有特别告诉它该找谁帮忙，OpenClaw 会自己按照这个顺序去找，找到第一个能用的就停下来：

1. 先看看电脑上有没有安装能离线工作的小工具，比如 sherpa-onnx-offline、whisper-cli 或 whisper。
2. 如果没有，就试试用 gemini 这个工具。
3. 如果还不行，最后就去找在线的服务商，顺序是 OpenAI → Groq → Deepgram → Google。

你可以关掉这个自动寻找功能，只要把 tools.media.audio.enabled 设置成 false 就行。如果你想自己指定找谁帮忙，就设置 tools.media.audio.models。

一些重要的提醒和规则

• 文件不能太大：默认音频文件不能超过 20MB（就是 maxBytes: 20971520），太大了当前帮手处理不了，就会跳过去找下一个。
• 文件也不能太小：如果音频文件特别特别小（小于 1024 字节），它可能就直接跳过了，因为里面可能没声音。
• 需要密码（API Key）：如果你用在线服务商（Provider），需要像告诉它秘密口令一样，设置好 apiKey。
• 可以控制谁用：你可以用 scope 规则来决定，比如只允许在私聊里用这个功能，在群聊里就不允许。
• 可以把文字念给你听：如果你打开 echoTranscript: true，它把语音转成文字后，会先把这段文字发回聊天里给你看一眼，然后再继续处理。你还可以用 echoFormat 来打扮一下这段文字的样子。
• 在群里提到我才理你：在需要“@提到”机器人才会回复的群里，如果有人发语音，OpenClaw 会先偷偷把语音转成文字，检查里面有没有“@”它。如果有，它才会回复。如果不想这样，可以针对某个群设置 disableAudioPreflight: true 来关掉。

配置例子（看看别人是怎么做的） 这里有几个别人写好的“小纸条”（配置例子），告诉你该怎么设置：

• 先用在线服务，不行再用本地工具：先让 OpenAI 试试，如果不行，再用电脑上的 whisper 工具。
• 只用在线服务，并且控制使用场合：只用 OpenAI，并且规定只能在私聊里用，群聊里不让用。
• 只用某个特定的在线服务：比如只用 Deepgram 或者 Mistral 公司的服务。
• 打开“念给你听”功能：打开 echoTranscript，这样转成文字后你会先看到。

需要小心的地方

• 如果你用电脑上的小工具（CLI），要确保它能在命令行里找到（就是要在 PATH 里）。
• 小工具运行后，要说“成功”（退出码是 0），并且只把文字打印出来，不要打印别的乱七八糟的东西。
• 给帮手设置一个合理的等待时间（timeoutSeconds，默认 60 秒），别让它等太久，不然会卡住。
• 在群里检查有没有被“@”的时候，它只处理第一个音频附件。