​

Ses / Sesli Notlar (2026-01-17)

​

Çalışanlar

• Medya anlama (ses): Ses anlama etkinse (veya otomatik algılanıyorsa), OpenClaw:
  1. İlk ses ekini bulur (yerel yol veya URL) ve gerekirse indirir.
  2. Her model girdisine göndermeden önce maxBytes sınırını uygular.
  3. Sırayla ilk uygun model girdisini çalıştırır (sağlayıcı veya CLI).
  4. Başarısız olursa veya atlanırsa (boyut/zaman aşımı), bir sonraki girdiyi dener.
  5. Başarılı olursa Body değerini bir [Audio] bloğuyla değiştirir ve {{Transcript}} ayarlar.
• Komut ayrıştırma: Döküm başarılı olduğunda, slash komutlarının çalışmaya devam etmesi için CommandBody/RawBody döküm metnine ayarlanır.
• Ayrıntılı günlükleme: --verbose modunda döküm çalıştığında ve gövdeyi değiştirdiğinde günlük yazarız.

​

Otomatik algılama (varsayılan)

1. Sağlayıcısı ses anlamayı destekliyorsa etkin yanıt modeli.
2. Yerel CLI’lar (kuruluysa)
   • sherpa-onnx-offline (SHERPA_ONNX_MODEL_DIR içinde encoder/decoder/joiner/tokens gerektirir)
   • whisper-cli (whisper-cpp içinden; WHISPER_CPP_MODEL veya paketlenmiş tiny modeli kullanır)
   • whisper (Python CLI; modelleri otomatik indirir)
3. read_many_files kullanan Gemini CLI (gemini)
4. Sağlayıcı auth
   • Sesi destekleyen yapılandırılmış models.providers.* girdileri önce denenir
   • Paketlenmiş fallback sırası: OpenAI → Groq → Deepgram → Google → Mistral

​

Yapılandırma örnekleri

​

Sağlayıcı + CLI fallback (OpenAI + Whisper CLI)

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

​

Kapsam geçitlemeli 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-mini-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" }],
      },
    },
  },
}

​

Dökümü sohbete yansıt (isteğe bağlı)

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

​

Notlar ve sınırlar

• Sağlayıcı auth’u standart model auth sırasını izler (auth profilleri, env 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.
• Deepgram kurulum ayrıntıları: Deepgram (ses dökümü).
• Mistral kurulum ayrıntıları: Mistral.
• Ses sağlayıcıları tools.media.audio üzerinden baseUrl, headers ve providerOptions değerlerini geçersiz kılabilir.
• Varsayılan boyut sınırı 20MB’dir (tools.media.audio.maxBytes). Büyük boyutlu ses bu model için atlanır ve sonraki girdi denenir.
• 1024 bayttan küçük çok küçük/boş ses dosyaları sağlayıcı/CLI dökümünden önce atlanır.
• Ses için varsayılan maxChars ayarsızdır (tam döküm). Çıktıyı kırpmak için tools.media.audio.maxChars veya girdi başına maxChars ayarlayın.
• OpenAI otomatik varsayılanı gpt-4o-mini-transcribe şeklindedir; daha yüksek doğruluk için model: "gpt-4o-transcribe" ayarlayın.
• Birden fazla sesli notu işlemek için tools.media.audio.attachments kullanın (mode: "all" + maxAttachments).
• Döküm şablonlara {{Transcript}} olarak sunulur.
• tools.media.audio.echoTranscript varsayılan olarak kapalıdır; döküm onayını ajan işlemeden önce kaynak sohbete geri göndermek için bunu etkinleştirin.
• tools.media.audio.echoFormat, yansıtılan metni özelleştirir (yer tutucu: {transcript}).
• CLI stdout sınırı 5MB’dir; CLI çıktısını kısa tutun.

​

Proxy ortam desteği

• HTTPS_PROXY
• HTTP_PROXY
• https_proxy
• http_proxy

​

Gruplarda mention algılama

1. Bir sesli mesajın metin gövdesi yoksa ve grup mention gerektiriyorsa OpenClaw bir “preflight” dökümü yapar.
2. Döküm, mention desenleri açısından denetlenir (ör. @BotName, emoji tetikleyicileri).
3. Bir mention bulunursa mesaj tam yanıt işlem hattısına devam eder.
4. Döküm mention algılama için kullanılır; böylece sesli notlar mention geçidini aşabilir.

• Preflight sırasında döküm başarısız olursa (zaman aşımı, API hatası vb.), mesaj yalnızca metin tabanlı mention algılamasına göre işlenir.
• Bu, karma mesajların (metin + ses) hiçbir zaman yanlışlıkla düşürülmemesini sağlar.

• O grup için preflight döküm mention denetimlerini atlamak üzere channels.telegram.groups.<chatId>.disableAudioPreflight: true ayarlayın.
• Konu başına geçersiz kılmak için channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight ayarlayın (true atlar, false zorla etkinleştirir).
• Varsayılan false’dur (mention geçitli koşullar eşleştiğinde preflight etkindir).

​

Dikkat edilmesi gerekenler

• Kapsam kuralları ilk eşleşme kazanır mantığıyla çalışır. chatType, direct, group veya room olarak normalize edilir.
• CLI’nizin 0 ile çıktığından ve düz metin yazdırdığından emin olun; JSON çıktısı jq -r .text ile işlenmelidir.
• parakeet-mlx için --output-dir geçirirseniz OpenClaw, --output-format txt olduğunda (veya atlandığında) <output-dir>/<media-basename>.txt dosyasını okur; txt dışındaki çıktı biçimleri stdout ayrıştırmasına geri döner.
• Yanıt kuyruğunu engellememek için zaman aşımlarını makul tutun (timeoutSeconds, varsayılan 60 sn).
• Preflight dökümü mention algılama için yalnızca ilk ses ekini işler. Ek sesler ana medya anlama aşamasında işlenir.