OpenClaw speech-to-text gebruiken

OpenClaw, voorheen bekend als ClawBot en MoltBot, is een persoonlijke AI-agent die je op je eigen infrastructuur draait. Je bedient OpenClaw via een chatapp naar keuze, bijvoorbeeld WhatsApp, en kunt ook speech-to-text (STT) en/of text-to-speech (TTS) gebruiken; zo hoef je berichten niet te typen, maar kun je tegen OpenClaw praten. 

In deze handleiding leggen we uit hoe je gebruik maakt van speech-to-text met OpenClaw in Ubuntu/Debian, welke opties er zijn en wat de belangrijkste trade-offs/wins zijn.

Welke STT-opties heeft OpenClaw?

OpenClaw kent in essentie twee opties voor STT: 

• Gateway voice-note handling (automatic STT): Hiervoor wordt gebruik gemaakt van de tools.media.audio in je OpenClaw-configuratie (dit is de beste optie voor 'natural conversation'). OpenClaw kiest automatisch de eerst beschikbare provider tenzij specifiek geconfigureerd in de volgorde: 
  Local CLIs (e.g. local Whisper) → Gemini → OpenAI → Groq → Whisper-cpp CLI → sherpa-onnx, etc.
   
• Agent ‘skills’, namelijk openai-whisper / openai-whisper-api. Deze skills leren de agent een CLI-tool uit te voeren om een audiobestand uit te schrijven wanneer het besluit de betreffende skill te gebruiken.

STT snelheid vs nauwkeurigheid

De verschillen tussen de OpenAI-Whisper en OpenAI-Whisper-API skills

De onderliggende techniek is in beide gevallen de Whisper STT techniek van OpenAI. Er zijn echter enkele belangrijke verschillen:

Gateway voice-note handling STT configureren

Lokaal model (geen API)

In deze paragraaf installeer je de Gateway voice-note handling voor STT op basis van een aantal componenten:

• whisper.cpp: Een C++ implementatie voor Whisper die beter performt dan ‘standaard’ Whisper
• De Whisper CLI tool. 
• Een quantized model voor de STT waarbij een zorgvuldige balans tussen performance en nauwkeurigheid voorop staat. 
• FFmpeg voor compatibiliteit met verschillende typen audio
• OpenBLAS voor een performance boost

Stap 1

Installeer alle dependencies, inclusief tools (waar nodig), FFmpeg, bijbehorende FFmpeg-libraries en OpenBLAS:

sudo apt -y update
sudo apt install -y git cmake build-essential pkg-config ffmpeg libavcodec-dev libavformat-dev libavutil-dev libOpenBLAS-dev

Stap 2

Bouw Whisper vanaf scratch met FFmpeg en OpenBLAS support. 
Het laatste commando maakt de Whisper Command Line Interface (CLI) uitvoerbaar door het aan een directory toe te voegen die in de PATH-omgevingsvariabele is opgenomen.

cd /opt
sudo git clone https://github.com/ggml-org/whisper.cpp.git
cd whisper.cpp
sudo cmake -B build -DWHISPER_FFMPEG=yes -DGGML_BLAS=1 -DCMAKE_BUILD_TYPE=Release
sudo cmake --build build -j 4
sudo cp -f ./build/bin/whisper-cli /usr/local/bin/whisper-cli

Stap 3

Maak een directory om de STT-modellen in op te slaan en installeer een STT-model. 

Een overzicht van beschikbare modellen vind je op deze pagina. Vervang optioneel ggml-base.en-q5_1.bin door de naam van het gewenste model; tiny is sneller dan ‘base’, small is accurater. 

sudo mkdir -p /opt/whisper-models
cd /opt/whisper-models
sudo wget -O ggml-base.en-q5_1.bin \
  "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en-q5_1.bin"

Stap 4

Open de OpenClaw-configuratie in openclaw.json:

sudo nano ~/.openclaw/openclaw.json

Zoek naar het “tools” stukje. Daar staan doorgaans al twee “web” tools in gedefinieerd. Voeg daaronder een “media” blok toe zoals in het voorbeeld hieronder. Vervang daarbij: 

• 3 in “-t”, “3” door het aantal CPU-cores van je VPS met een minimum van twee en een maximum van het aantal cores van je VPS min 1 (e.g. 3 cores bij een VPS met 4 cores).
• Optioneel de directory en het model onder “command” en “--model” indien je die in de eerdere stappen zelf hebt aangepast.

  "tools": {
    "web": {
      "search": {
        "enabled": false
      },
      "fetch": {
        "enabled": false
      }
    },
    "media": {
      "audio": {
        "enabled": true,
        "models": [
          {
            "type": "cli",
            "command": "/usr/local/bin/whisper-cli",
            "args": [
              "--model", "/opt/whisper-models/ggml-base.en-q5_1.bin",
              "--file", "{{MediaPath}}",
              "-t", "3"
            ],
            "timeoutSeconds": 20
          }
        ]
      }
    }
  },

Sla de wijzigingen op en sluit het bestand (Ctrl + x > y > enter).

Stap 5

Herstart de OpenClaw gateway om de wijzigingen te verwerken:

openclaw gateway restart

That's it! Je kunt nu spraakberichten via je gekozen communication channel (e.g. WhatsApp) sturen die vervolgens automatisch en snel worden omgezet in tekst, waarna OpenClaw op basis van die tekst een bericht terugstuurt.

Cloud model (API key nodig)

Stap 1

OpenClaw leest omgevingsvariabelen o.a. uit ~/.openclaw/.env (en overschrijft bestaande waarden niet). Maak/open dat bestand: 

nano ~/.openclaw/.env

Voeg in het geopende bestand de API key toe die je gebruikt, sla de wijzigingen op en sluit het bestand (Ctrl + x > y > enter):

OPENAI_API_KEY="sk-..."
GROQ_API_KEY="gsk_..."
DEEPGRAM_API_KEY="dg_..." 

OpenAI tip: je kunt ook de onboarding wizard gebruiken; die vraagt om de OPENAI_API_KEY en automatiseert dit proces maar schrijft de key wel weg in ~/.openclaw/openclaw.json in plaats van .env. 

Stap 2 — tools.media.audio omzetten naar provider-model(len) 

Open ~/.openclaw/openclaw.json en vervang je huidige media.audio.models (CLI) door één of meer provider entries. Sla vervolgens je wijzigingen op en sluit het bestand (Ctrl + x > y > enter). 

nano ~/.openclaw/openclaw.json 

Optie A — OpenAI 

OpenClaw’s OpenAI implementatie ondersteunt:

• default model: gpt-4o-mini-transcribe (snel)
• accurater maar iets trager alternatief: gpt-4o-transcribe 

{
  "tools": {
    "media": {
      "audio": {
        "enabled": true,
        "models": [
          { "provider": "openai", "model": "gpt-4o-mini-transcribe" }
        ]
      }
    }
  }
}

Optie B — Groq (vaak “snappy” voor korte voice-notes) 

Groq beschikbare STT modellen: 

• whisper-large-v3-turbo (sneller/goedkoper) 
• whisper-large-v3 (iets accurater)

{
  "tools": {
    "media": {
      "audio": {
        "enabled": true,
        "models": [
          { "provider": "groq", "model": "whisper-large-v3-turbo" }
        ]
      }
    }
  }
}

Optie C — Deepgram (simpel + stabiel)

Deepgram beschikbare STT modellen: 

• flux-general-en
• nova-3
• nova-2

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

Stap 3 - optioneel

Je kunt meerdere modellen onder elkaar zetten in je configuratie. OpenClaw probeert dan eerst het eerste model; bij fail/timeout/oversize gaat OpenClaw door naar de volgende. Bijv. Groq → OpenAI → Deepgram → lokale CLI fallback. Dit ziet er bijvoorbeeld als volgt uit:

{
  "tools": {
    "media": {
      "audio": {
        "enabled": true,
        "maxBytes": 20971520,
        "models": [
          { "provider": "groq", "model": "whisper-large-v3-turbo" },
          { "provider": "openai", "model": "gpt-4o-mini-transcribe" },
          { "provider": "deepgram", "model": "nova-3" },
          {
            "type": "cli",
            "command": "/usr/local/bin/whisper-cli",
            "args": ["--model", "/opt/whisper-models/ggml-base.en-q5_1.bin", "--file", "{{MediaPath}}", "-t", "3"],
            "timeoutSeconds": 20
          }
        ]
      }
    }
  }
}

Stap 4

Herstart de OpenClaw-gateway om de wijzigingen te verwerken:

openclaw gateway restart

OpenClaw STT via skills configureren

De configuratie van OpenClaw STT is zeer eenvoudig. Er zijn wel een paar kanttekeningen bij het gebruik van skills:

• Skills performen trager dan tools, in dit geval de gateway voice-note handling tool.
• Skills geven de agent de optie om een CLI-tool te gebruiken, maar het is aan de agent/het LLM om te bepalen of de agent die skill gebruikt of niet. Dit is bij STT geen groot issue, maar wel bij TTS. 

Om STT via een skill te configureren klik je in het web-dashboard in het linkermenu op ‘Skills’. 

Scroll vervolgens naar beneden en klik afhankelijk van je voorkeur op ‘Enable’ achter (1) openai-whisper (lokaal gehost op je VPS) of (2) openai-whisper-api (gehost door OpenAI). Geef in het laatste geval ook je API-key op (3) en klik op ‘Save key’.

That's it! Je kunt nu spraakberichten via je gekozen communication channel (e.g. WhatsApp) sturen die vervolgens automatisch worden omgezet in tekst, waarna OpenClaw op basis van die tekst een bericht terugstuurt.