OpenClaw text-to-speech 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 chat-app naar keuze zoals 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 text-to-speech met OpenClaw in Ubuntu/Debian, welke opties beschikbaar zijn en wat bij de verschillende keuzes je trade-offs/wins zijn.

Welke TTS-opties heeft OpenClaw?

OpenClaw kent enkele opties voor TTS : 

• De ingebouwde TTS tool (aanbevolen): Ondersteunt zowel OpenAI als ElevenLabs als Edge (gratis).
   
• SAG: Een ‘skill’ gekoppeld aan ElevenLabs. Je hebt een ElevenLabs API key nodig voor deze optie.
   
• sherpa-onnx-tts: Lokale TTS waarbij enige aanvullende configuratie via command-line nodig is. De kwaliteit is vergelijkbaar met Edge.
   
• Onofficieel: espeak-ng: De snelste optie die lokaal op je VPS draait. Klinkt een stuk robotischer en configureer je via command-line.

TTS snelheid vs natuurgetrouwheid

De ingebouwde TTS-tool

OpenClaw heeft een ingebouwde TTS-tool die fijn is om mee te werken; je kan namelijk op veel plekken de TTS-tool beheren:

• De chat in het web-dashboard
• De OpenClaw command-line-tool TUI (openclaw tui)
• Een communication-channel zoals Whatsapp. Let wel dat wanneer de tool aan staat dit reacties via een communication-channel zal vertragen, simpelweg omdat alle reacties dan ook via TTS in spraak worden omgezet.

API key(s) toevoegen

Voeg eerst via command-line je API key(s) toe als volgt, niet in een chatgesprek:

echo OPENAI_API_KEY=sk-proj-......... >> ~/.openclaw/.env
echo ElevenLabs_API_KEY=sk_.......... >> ~/.openclaw/.env

Start simpelweg een gesprek met OpenClaw via een van deze opties en gebruik de onderstaande commando's om de TTS-tool te beheren

De TTS status controleren

/tts status

TTS aanzetten

/tts on

TTS uitzetten

/tts off

TTS provider veranderen

Gebruik als optie openai, ElevenLabs of edge:

/tts provider openai

SAG TTS configureren

De SAG TTS skill is gekoppeld aan ElevenLabs. ElevenLabs maakt de meest natuurgetrouwe stemmen voor TTS, 

Of OpenClaw de SAG-skill gebruikt hangt af van of de agent het idee heeft dat het die skill moet gebruiken. Of het tot die conclusie komt hangt o.a. van de kwaliteit van het gebruikte LLM én de instructie die je OpenClaw geeft (aan te passen in ~/.openclaw/workspace/TOOLS.md en SOUL.md). Resultaten kunnen gemixed zijn en als snelheid en betrouwbaarheid je voorkeur heeft, raden we de TTS-tool aan. 

Stap 1

Schakel SAG in door in het OpenClaw-dashboard naar ‘Skills’ te gaan (1), je ElevenLabs API-key in te vullen en op te slaan (2) en op ‘Enable’ (3) te klikken.

Stap 2

OpenClaw slaat out-of-the-box de API key op in openclaw.json. Om veiligheidsredenen raden we aan dit aan te passen, open openclaw.json:

nano ~/.openclaw/openclaw.json

Pas vervolgens in het ‘Skills’-deel de SAG-vermelding aan als volgt:

  "skills": {
    "install": {
      "nodeManager": "npm"
    },
    "entries": {
      "sag": {
        "enabled": true,
        "apiKey": "${SAG_API_KEY}"
      }
    }
  },

Voeg vervolgens in .env de daadwerkelijke API-key toe (vervang sk_etc door je eigen API-key):

echo SAG_API_KEY=sk_3c34083<redacted>b39d5a91e6c7d3 >> ~/.openclaw/.env

Sherpa-onnx-tts

Stap 1

OpenClaw heeft een skill genaamd sherpa-onnx-tts die lokaal uitgevoerd wordt en geen cloud TTS-dienst vereist. 

Download eerst de sherpa-onnx runtime:

mkdir -p ~/.openclaw/tools/sherpa-onnx-tts/runtime
cd ~/.openclaw/tools/sherpa-onnx-tts/runtime

curl -L -o sherpa-onnx-runtime.tar.bz2 \
  https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.24/sherpa-onnx-v1.12.24-linux-x64-shared.tar.bz2

tar -xjf sherpa-onnx-runtime.tar.bz2 --strip-components=1

De laatste versie op moment van schrijven is 1.12.24. Een overzicht van de beschikbare versies vind je op https://github.com/k2-fsa/sherpa-onnx/releases/.

Stap 2

Download een sherpa-onnx model. In dit voorbeeld downloaden we lessac-medium (US English). Vervang lessac-medium eventueel door lessac-low (sneller) of lessac-high (betere kwaliteit). Een volledig overzicht van beschikbare modellen vind je op https://github.com/k2-fsa/sherpa-onnx/releases/tag/tts-models.

mkdir -p ~/.openclaw/tools/sherpa-onnx-tts/models
cd ~/.openclaw/tools/sherpa-onnx-tts/models

curl -L -o vits-piper-en_US-lessac-medium.tar.bz2 \
  https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-en_US-lessac-medium.tar.bz2

tar -xjf vits-piper-en_US-lessac-medium.tar.bz2
rm vits-piper-en_US-lessac-medium.tar.bz2

Stap 3

Open openclaw.json om te verwijzen naar de sherpa-onnx runtime en het gekozen model:

nano ~/.openclaw/openclaw.json

 skills: {
   entries: {
     "sherpa-onnx-tts": { 
       "enabled": true 
     }
   }
 }

Vaak staan er hier al enkele entries. Het geheel kan er dan als volgt uitzien:

  "skills": {
    "install": {
      "nodeManager": "npm"
    },
    "entries": {
      "sherpa-onnx-tts": {
        "enabled": true
      },
      "openai-whisper": {
        "enabled": false
      },
      "openai-whisper-api": {
        "enabled": false
      }
    }
  },

Espeak-ng (experimenteel)

Stap 1

Installeer espeak-ng en de FFmpeg-encoder indien je die nog niet hebt.

sudo apt -y update
sudo apt -y install -y espeak-ng ffmpeg

Stap 2

Maak een 'fast TTS' script dat straks door de OpenClaw-skill gebruikt kan worden. Voor veiligheid wordt tekst via environment variables omgezet naar audio in plaats van direct via shell arguments.

mkdir -p ~/.openclaw/skills/fast-tts/bin
nano ~/.openclaw/skills/fast-tts/bin/fast-tts
chmod +x ~/.openclaw/skills/fast-tts/bin/fast-tts

#!/usr/bin/env bash
set -euo pipefail

: "${TTS_TEXT:?Set TTS_TEXT in env}"
TTS_CHANNEL="${TTS_CHANNEL:-whatsapp}"
TTS_SPEED="${TTS_SPEED:-185}"
TTS_VOICE="${TTS_VOICE:-}"
TTS_APPEND_VOICE_MARKER="${TTS_APPEND_VOICE_MARKER:-0}"

require_bin() {
  if ! command -v "$1" >/dev/null 2>&1; then
    echo "ERROR: missing dependency: $1" >&2
    exit 127
  fi
}

require_bin espeak-ng
require_bin ffmpeg

script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
base_dir="$(cd "$script_dir/.." && pwd -P)"

# Prefer OpenClaw's media root so local-path safety checks accept the file.
default_out="$base_dir/media/outbound"
if [[ -n "${HOME:-}" ]]; then
  default_out="$HOME/.openclaw/media/outbound"
fi
OUT_DIR="${OUT_DIR:-$default_out}"
mkdir -p "$OUT_DIR"

fname="tts-$(date +%Y%m%d-%H%M%S)-$RANDOM.ogg"
out="$OUT_DIR/$fname"

wav="$(mktemp "$OUT_DIR/tts-XXXXXX.wav")"
trap 'rm -f "$wav"' EXIT

espeak_cmd=(espeak-ng -s "$TTS_SPEED" -w "$wav" --stdin)
if [[ -n "$TTS_VOICE" ]]; then
  espeak_cmd+=(-v "$TTS_VOICE")
fi

# Read text from stdin so content does not appear in argv/process listings.
printf '%s\n' "$TTS_TEXT" | "${espeak_cmd[@]}"

ffmpeg -hide_banner -loglevel error -y \
  -i "$wav" -ac 1 -ar 48000 \
  -c:a libopus -b:a 64k -vbr on -compression_level 5 -application voip \
  "$out"

if [[ ! -s "$out" ]]; then
  echo "ERROR: failed to create audio at $out" >&2
  exit 1
fi

chmod 644 "$out" 2>/dev/null || true

# IMPORTANT: use absolute file URL so the channel worker CWD doesn't matter
abs="$(cd "$(dirname "$out")" && pwd -P)/$(basename "$out")"

media="MEDIA:file://$abs"
channel="$(printf '%s' "$TTS_CHANNEL" | tr '[:upper:]' '[:lower:]')"
if [[ "$channel" == "telegram" && "$TTS_APPEND_VOICE_MARKER" == "1" ]]; then
  # Some OpenClaw builds support this marker; default off for compatibility.
  media+="[[audio_as_voice]]"
fi
echo "$media"

nano ~/.openclaw/skills/fast-tts/SKILL.md

---
name: fast-tts
description: Ultra-fast local TTS (espeak-ng + ffmpeg) for OpenClaw chat channels. Use when you want audio-only replies (prefer no written text) in WhatsApp/Telegram. Includes a minimal plugin skeleton for OpenClaw voice-call telephony TTS with local espeak-ng.
metadata: {"openclaw":{"requires":{"bins":["espeak-ng","ffmpeg"]}}}
---

When the user wants an audio-only reply in chat channels:

1) Put the full reply text into env var `TTS_TEXT` (do NOT put the text on the shell command line).
2) Call the exec tool with:
   - command: "{baseDir}/bin/fast-tts"
   - env: { "TTS_TEXT": "<your reply text>", "TTS_CHANNEL": "<channel>" }
   - Set `TTS_CHANNEL` from message context. Supported values: `whatsapp`, `telegram`. Defaults to `whatsapp`.
3) The command prints a single `MEDIA:` line.
4) Respond with exactly that `MEDIA:` line and nothing else.

Notes:
- The script emits OGG/Opus at 48kHz mono and appends `[[audio_as_voice]]` automatically for Telegram voice bubbles.
- Optional env vars: `TTS_SPEED` (default `185`), `TTS_VOICE` (espeak voice id), `OUT_DIR` (output directory).
- Use `assets/openclaw-espeak-telephony-plugin/` as the minimal starting point for local `espeak-ng` telephony TTS in the OpenClaw voice-call path.
- Integration notes for the voice-call fork are in `references/voice-call-provider-skeleton.md`.
- Config guidance for audio-only chat behavior is in `references/openclaw-config-for-audio-only.md`.

nano ~/.openclaw/openclaw.json

 skills: {
   entries: {
     "fast-tts": { enabled: true }
   }
 }

  "skills": {
    "install": {
      "nodeManager": "npm"
    },
    "entries": {
      "fast-tts": {
        "enabled": true
      },
      "openai-whisper": {
        "enabled": false
      },
      "openai-whisper-api": {
        "enabled": false
      }
    }
  },

nano ~/.openclaw/workspace/SOUL.md

## Telegram/WhatsApp

When replying on Telegram/WhatsApp:

- Call exec exactly once per turn with:
  {"command":"/home/testtransip/.openclaw/skills/fast-tts/bin/fast-tts","env":{"TTS_CHANNEL":"telegram","OUT_DIR":"/home/<jegebruikersnaam>/.openclaw/media/outbound","TTS_APPEND_VOICE_MARKER":"0","TTS_TEXT":"<full reply text>"}}
- Never put reply text in the command string.
- Never output "Action:" or "Action Input:" to chat.
- call once per turn
- Assume your first call in a turn is successful.
- Never use tts
- Final output must be only the MEDIA: line returned by the tool.
- If exec or fast-tts fails once in a turn, do not retry again in that same turn.

Herstart je OpenClaw-gateway zodat skills herladen worden:

openclaw gateway restart

Potentiële bug

Er is een actief rapport waarin staat dat MEDIA: regels soms als platte tekst (zonder bijlage) worden weergegeven bij bepaalde model/provider-combinaties. Een tijdelijke oplossing is om in plaats daarvan audio via de berichtentool te verzenden. Als je dit probleem tegenkomt: probeer dan OpenClaw te updaten met openclaw update.