Ses ve sesli notlar

Ne işe yarar

Ses anlama etkinleştirildiğinde (veya otomatik algılandığında) OpenClaw:

1. İlk ses ekini (yerel yol veya URL) bulur ve gerekirse indirir.
2. Her model girdisine göndermeden önce maxBytes sınırını uygular.
3. Uygun ilk model girdisini sırayla çalıştırır (sağlayıcı veya CLI); bir girdi başarısız olursa ya da atlanırsa (boyut/zaman aşımı), sonraki girdi denenir.
4. Başarı durumunda Body değerini bir [Ses] bloğuyla değiştirir ve {{Transcript}} değerini ayarlar.

Döküm başarıyla oluşturulduğunda, eğik çizgi komutlarının çalışmaya devam etmesi için CommandBody/RawBody değerleri de döküme ayarlanır. --verbose kullanıldığında günlükler, dökümün ne zaman çalıştığını ve gövdenin ne zaman değiştirildiğini gösterir.

Otomatik algılama (varsayılan)

Modelleri yapılandırmadıysanız ve tools.media.audio.enabled değeri false değilse OpenClaw, aşağıdaki sırayla otomatik algılama yapar ve çalışan ilk seçenekte durur:

1. Sağlayıcısı ses anlamayı desteklediğinde etkin yanıt modeli.
2. Yapılandırılmış sağlayıcı kimlik doğrulaması — ses dökümünü destekleyen bir sağlayıcı için kimlik doğrulaması bulunan herhangi bir models.providers.* girdisi. Bu denetim yerel CLI'lerden önce yapılır; dolayısıyla yapılandırılmış bir API anahtarı, PATH üzerindeki yerel ikili dosyaya her zaman üstün gelir. Birden fazla sağlayıcı yapılandırıldığında öncelik sırası: Groq, OpenAI, xAI, Deepgram, Google, SenseAudio, ElevenLabs, Mistral.
3. Yerel CLI'ler (yalnızca sağlayıcı kimlik doğrulaması çözümlenmediyse). OpenClaw sıralı bir geri dönüş listesi oluşturur:
   • Yalnızca mevcut süreçteki daha önceki bir model çağrısı Metal veya CUDA gözlemlediyse CPU varsayılanlarından önce whisper-cli
   • Varsayılan CPU sağlayıcısında sherpa-onnx-offline (tokens.txt, encoder.onnx, decoder.onnx ve joiner.onnx içeren SHERPA_ONNX_MODEL_DIR gerektirir)
   • Metal/CUDA yalnızca derleme açısından destekleniyorsa veya seçilen arka uç başka bir şekilde gözlemlenmemişse whisper-cli
   • Apple Silicon üzerinde parakeet-mlx (MLX desteklidir; cihaz kullanımı gözlemlenmemiş olarak kalır)
   • whisper (Python CLI; modelleri otomatik olarak indirir)

Kurulum/bağlantı kaynağı, çalıştırma kanıtı değil yetenek kanıtıdır. Tek başına hiçbir zaman bir adayı CPU sherpa'nın önüne taşımaz. OpenClaw, yalnızca bir arka ucu yoklamak için kurulum veya durum denetimleri sırasında model yüklemez. Otomatik algılanan whisper.cpp, OpenClaw'ın üst kaynaktaki using … backend satırını kaydedebilmesi için normal model çalıştırma günlüklerini etkin tutar. Açık CLI girdileri, yapılandırılmış çıktı bayraklarını korur.

Medya anlama için Gemini CLI otomatik algılamasının yerini, görüntü/video için korumalı alanda çalışan Antigravity CLI (agy) geri dönüşü almıştır; ses, yukarıdaki yerel ikili dosyaların ötesinde bir CLI geri dönüşü kullanmaz.

Otomatik algılamayı devre dışı bırakmak için tools.media.audio.enabled: false ayarını yapın. Özelleştirmek için tools.media.audio.models ayarını yapın.

Ses dökümü oluşturmadan yerel seçimi inceleyin:

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

Sağlayıcı envanteri, yerel geri dönüş kazananını genel sağlayıcı seçiminden ayrı olarak ve desteklenen, istenen ve gözlemlenen arka uç alanlarıyla birlikte bildirir. Döküm çalıştıktan sonra /status, medya satırında istenen veya gözlemlenen arka ucu bildirir. Açık tools.media.audio.models CLI girdileri otomatik seçimi yine atlar; sherpa için --provider=cuda veya whisper.cpp için --no-gpu/--device gibi arka uca özgü bayraklarını kullanın.

Yapılandırma örnekleri

Sağlayıcı + CLI geri dönüşü (OpenAI + Whisper CLI)

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

Kapsam geçidiyle yalnızca sağlayıcı

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

Yalnızca sağlayıcı (Deepgram)

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

Yalnızca sağlayıcı (Mistral Voxtral)

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

Yalnızca sağlayıcı (SenseAudio)

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

Dökümü sohbete geri gönderme (isteğe bağlı)

{  tools: {    media: {      audio: {        enabled: true,        echoTranscript: true, // varsayılan değer false        echoFormat: '📝 "{transcript}"', // isteğe bağlı, {transcript} destekler        models: [{ provider: "openai", model: "gpt-4o-transcribe" }],      },    },  },}

Notlar ve sınırlar

• Sağlayıcı kimlik doğrulaması, standart model kimlik doğrulama sırasını izler (kimlik doğrulama profilleri, ortam değişkenleri, models.providers.*.apiKey).
• Groq kurulum ayrıntıları: Groq.
• provider: "deepgram" kullanıldığında Deepgram, DEEPGRAM_API_KEY değerini alır. Kurulum ayrıntıları: Deepgram.
• Mistral kurulum ayrıntıları: Mistral.
• provider: "senseaudio" kullanıldığında SenseAudio, SENSEAUDIO_API_KEY değerini alır. Kurulum ayrıntıları: SenseAudio.
• Ses sağlayıcıları, tools.media.audio aracılığıyla baseUrl, headers ve providerOptions değerlerini geçersiz kılabilir.
• Varsayılan boyut sınırı 20 MB'dir (tools.media.audio.maxBytes). Sınırı aşan ses, ilgili model için atlanır ve sonraki girdi denenir.
• 1024 bayttan küçük ses dosyaları, sağlayıcı/CLI dökümünden önce atlanır.
• Ses için varsayılan maxChars değeri ayarlanmamıştır (tam döküm). Çıktıyı kırpmak için tools.media.audio.maxChars veya girdi başına bir maxChars ayarlayın.
• OpenAI otomatik algılama varsayılanı gpt-4o-transcribe modelidir; daha ucuz/hızlı bir seçenek için model: "gpt-4o-mini-transcribe" ayarını yapın.
• Birden fazla sesli notu işlemek için tools.media.audio.attachments kullanın (mode: "all" ve maxAttachments; varsayılan 1).
• Döküm, şablonlarda {{Transcript}} olarak kullanılabilir.
• tools.media.audio.echoTranscript varsayılan olarak kapalıdır; ajan işlemesinden önce kaynak sohbete bir döküm onayı göndermek için etkinleştirin.
• tools.media.audio.echoFormat, geri gönderilen metni özelleştirir (yer tutucu: {transcript}; varsayılan 📝 "{transcript}").
• CLI standart çıktısı 5 MB ile sınırlıdır; CLI çıktısını kısa tutun.
• CLI args, yerel ses dosyası yolu için {{MediaPath}} kullanmalıdır. Eski audio.transcription.command yapılandırmalarındaki kullanım dışı {input} yer tutucularını taşımak için openclaw doctor --fix çalıştırın (kullanımdan kaldırılmış anahtar: audio.transcription; yerine tools.media.audio.models getirilmiştir).
• tools.media.concurrency, medya görevlerini sınırlar; bir GPU zamanlayıcısı değildir.

Kalıcı yerel STT

Otomatik algılanan yerel STT, istek başına süreç şeklinde çalışmaya devam eder. OpenClaw şu anda kalıcı bir whisper.cpp sunucusunu yönetmez; çünkü standart Homebrew whisper-cpp paketi bu sunucuyu devre dışı bırakırken üst kaynak örneğinde yapılandırılmış, sınırlı bir kabul kuyruğu yoktur. Plugin tarafından yönetilen kalıcı bir yaşam döngüsünün güvenle etkinleştirilebilmesi için sağlık/başlangıç denetimi, modelin bellekte tutulması, sınırlı kuyruklama, iptal/zaman aşımı, yalnızca local loopback üzerinden kimlik doğrulamasız çalışma ve bulut geri dönüşü olmayan, bakımı sürdürülen paketlenmiş bir çalışan gerekir.

Proxy ortamı desteği

Sağlayıcı tabanlı ses dökümü, undici'nin EnvHttpProxyAgent semantiğine uygun olarak standart giden proxy ortam değişkenlerini dikkate alır:

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

Küçük harfli değişkenler büyük harflilere göre önceliklidir; NO_PROXY/no_proxy girdileri (ana makine adları, *.suffix veya host:port) proxy'yi atlar. Hiçbir proxy ortam değişkeni ayarlanmamışsa doğrudan çıkış kullanılır. Proxy kurulumu başarısız olursa (hatalı biçimlendirilmiş URL), OpenClaw bir uyarı günlüğe kaydeder ve doğrudan getirmeye geri döner.

Gruplarda bahsetme algılama

Ses ön denetimini destekleyen kanallarda, bir grup sohbeti için requireMention: true ayarlandığında OpenClaw, bahsetmeleri denetlemeden önce sesin dökümünü oluşturur. Bu sayede altyazısız bir sesli not, dökümü yapılandırılmış bir bahsetme kalıbı içerdiğinde bahsetme geçidini aşabilir. Kanala özgü belgeler, bunun yerine yazılı bir bahsetme gerektiren aktarımları açıklar.

Nasıl çalışır:

1. Bir sesli mesajın metin gövdesi yoksa ve grup bahsetmeleri gerektiriyorsa OpenClaw, ilk ses eki için ön denetim dökümü gerçekleştirir.
2. Döküm, bahsetme kalıpları (örneğin @BotName, emoji tetikleyicileri) açısından denetlenir.
3. Bir bahsetme bulunursa mesaj, tam yanıt işlem hattından geçmeye devam eder.

Geri dönüş davranışı: Ön denetim dökümü başarısız olursa (zaman aşımı, API hatası vb.), karma mesajların (metin + ses) hiçbir zaman düşürülmemesi için mesaj yalnızca metne dayalı bahsetme algılamasına geri döner.

Telegram grubu/konusu başına devre dışı bırakma:

• İlgili grup için ön denetim dökümündeki bahsetme denetimlerini atlamak üzere channels.telegram.groups.<chatId>.disableAudioPreflight: true ayarını yapın.
• Konu başına geçersiz kılmak için channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight ayarını yapın (atlamak için true, zorla etkinleştirmek için false).
• Varsayılan değer false değeridir (bahsetme geçitli koşullar eşleştiğinde ön denetim etkindir).

Örnek: Bir kullanıcı, requireMention: true ayarlı bir Telegram grubunda "Hey @Claude, hava nasıl?" diyen bir sesli not gönderir. Sesli notun dökümü oluşturulur, bahsetme algılanır ve ajan yanıt verir.

Dikkat edilmesi gerekenler

• Kapsam kurallarında ilk eşleşme kazanır; chatType, direct, group veya channel değerlerinden birine normalleştirilir.
• CLI'nizin 0 koduyla çıktığından ve düz metin yazdırdığından emin olun; JSON çıktısının jq -r .text aracılığıyla işlenmesi gerekir.
• Bilinen dosya çıktı modları belirleyicidir: çıkarımla belirlenen döküm dosyasının boş veya eksik olması, CLI ilerleme çıktısına geri dönmek yerine hiç döküm üretmez.
• parakeet-mlx için --output-dir ve varsayılan {filename} çıktı şablonuyla birlikte --output-format txt (veya all) kullanın. Üst kaynaktaki PARAKEET_OUTPUT_FORMAT ve PARAKEET_OUTPUT_TEMPLATE ortam değişkenleri de dikkate alınır. OpenClaw, <output-dir>/<media-basename>.txt dosyasını okur; varsayılan srt biçimi, diğer biçimler ve özel çıktı şablonları standart çıktıyı kullanmaya devam eder.
• Yanıt kuyruğunun engellenmesini önlemek için zaman aşımlarını makul tutun (timeoutSeconds, varsayılan 60 sn).
• Ön denetim dökümü, bahsetme algılaması için yalnızca ilk ses ekini işler. Ek ses ekleri, ana medya anlama aşamasında işlenir.

İlgili konular

• Medya anlama
• Konuşma modu
• Sesle uyandırma