Guía técnica de implantación, respuestas Audio+Texto y reconocimiento de voz en OpenClaw

Actualización operativa, Transcripción de Audio, STT en OpenClaw vía Telegram

Arquitectura

Telegram (audio .oga) → OpenClaw Gateway → transcribe_audio.py → faster-whisper → texto

1. Dependencias del servidor

# FFmpeg (convertir .oga → .wav)
sudo apt install -y ffmpeg

# faster-whisper (motor STT)
pip3 install --user faster-whisper

2. Script de transcripción

Ubicación:

~/.openclaw/scripts/transcribe_audio.py

#!/usr/bin/env python3
import sys, subprocess, tempfile, os
from faster_whisper import WhisperModel

audio_path = sys.argv[1]

# Convertir a WAV 16kHz mono (formato óptimo para Whisper)
with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
    wav_path = tmp.name

subprocess.run([
    "ffmpeg", "-y", "-i", audio_path,
    "-ar", "16000", "-ac", "1", "-f", "wav", wav_path
], capture_output=True)

# Transcribir con faster-whisper
model = WhisperModel("small", device="cpu", compute_type="int8")
segments, info = model.transcribe(wav_path, language="es", vad_filter=True)

text = " ".join(seg.text.strip() for seg in segments)
print(text)

os.unlink(wav_path)

Permisos:

chmod +x ~/.openclaw/scripts/transcribe_audio.py

3. Configuración en openclaw.json

En ~/.openclaw/openclaw.json, dentro del bloque tools.media:

{
  "tools": {
    "media": {
      "audio": {
        "command": "python3 ~/.openclaw/scripts/transcribe_audio.py {{MediaPath}}",
        "timeout": 120
      }
    }
  }
}

4. Reiniciar el servicio

# silvio-server (systemd user)
systemctl --user restart openclaw-gateway.service

# Hetzner (systemd system)
sudo systemctl restart openclaw.service

5. Parámetros clave y por qué

• Modelo: small, equilibrio precisión/velocidad en CPU
• Idioma: es, forzar español evita alucinaciones por autodetección
• compute_type: int8, reduce RAM y acelera en CPU
• vad_filter: True, ignora silencios y mejora precisión
• Formato: WAV 16kHz mono, estándar Whisper y evita artefactos de .oga
• Timeout: 120s, útil para audios largos de Telegram

6. Verificación

Enviar un audio por Telegram al bot. En logs debería verse la transcripción.

journalctl --user -u openclaw-gateway.service -f

Buscar trazas relacionadas con la transcripción del audio.

7. Solución de problemas

• Sin transcripción: script no encontrado, verificar ruta en openclaw.json
• Texto en inglés: idioma no forzado, añadir language="es"
• Alucinaciones: modelo demasiado pequeño o sin VAD, usar small + vad_filter=True
• Timeout: audio largo o CPU lenta, subir timeout o usar un modelo más ligero
• Error ffmpeg: instalar ffmpeg

1. Propósito

Este documento describe una implantación reutilizable para OpenClaw con dos capacidades coordinadas:

• TTS de salida para que el asistente responda con texto + audio.
• STT de entrada para que las notas de voz del usuario se conviertan en texto utilizable por el agente.

La guía está pensada para una instalación operativa en servidor o estación Linux con OpenClaw ya desplegado.

2. Alcance

Esta implantación cubre:

• configuración de TTS automático para respuestas finales
• selección de voz femenina en español
• transcripción local de audios mediante faster-whisper
• validación funcional extremo a extremo
• diagnóstico básico y rollback

No cubre:

• instalación inicial completa de OpenClaw
• hardening del host
• telephony / voice-call
• alta disponibilidad

3. Resultado esperado

Tras aplicar este procedimiento, el sistema debe cumplir lo siguiente:

1. El asistente responde en texto.
2. Cada respuesta final se entrega también como audio TTS.
3. Los audios recibidos del usuario se transcriben localmente.
4. La voz configurada para TTS queda en es-ES-XimenaNeural.
5. El reconocimiento de voz en español mejora respecto a la configuración base, usando un modelo small con parámetros más robustos.

4. Arquitectura de la solución

La solución queda dividida en dos flujos:

4.1 Flujo de entrada, STT

1. El usuario envía una nota de voz.
2. OpenClaw descarga el archivo de audio.
3. OpenClaw ejecuta un modelo de audio tipo cli.
4. Ese modelo llama a python3 /home/kevin/.openclaw/scripts/transcribe_audio.py {{MediaPath}}.
5. El script usa faster-whisper para transcribir en español.
6. La transcripción se incorpora al contexto del agente.

4.2 Flujo de salida, TTS

1. El agente genera una respuesta final en texto.
2. OpenClaw aplica la política messages.tts.
3. Se sintetiza audio usando el proveedor microsoft.
4. La voz seleccionada es es-ES-XimenaNeural.
5. El usuario recibe respuesta en texto y audio.

5. Prerrequisitos

5.1 Requisitos funcionales

• OpenClaw instalado y operativo.
• Acceso al host donde corre el gateway.
• Capacidad para reiniciar el gateway tras cambios de configuración.
• Python 3 disponible en el sistema.
• Dependencias de faster-whisper instaladas.
• edge-tts disponible si se va a validar inventario de voces locales.

5.2 Comprobaciones recomendadas

python3 --version
edge-tts --list-voices | grep Ximena
openclaw status --deep

5.3 Condiciones operativas

• El host debe poder ejecutar procesos Python locales.
• El usuario debe aceptar que un reinicio del gateway puede interrumpir momentáneamente la sesión activa.

6. Componentes implantados

6.1 Script de transcripción STT

Ruta recomendada de producción:

/home/kevin/.openclaw/scripts/transcribe_audio.py

No depender de una ruta relativa dentro del workspace para el gateway.

Código implantado:

import sys
from functools import lru_cache
from faster_whisper import WhisperModel


@lru_cache(maxsize=1)
def get_model():
    model_size = "small"
    return WhisperModel(model_size, device="cpu", compute_type="int8")


def transcribe_audio_file(audio_file_path):
    model = get_model()
    segments, info = model.transcribe(
        audio_file_path,
        beam_size=5,
        language="es",
        vad_filter=True,
        condition_on_previous_text=False,
        temperature=0,
    )

    transcription = " ".join(segment.text.strip() for segment in segments).strip()
    print(transcription)


if __name__ == "__main__":
    if len(sys.argv) > 1:
        audio_path = sys.argv[1]
        transcribe_audio_file(audio_path)
    else:
        print("Usage: python3 transcribe_audio.py <audio_file_path>")

6.2 Justificación técnica del ajuste STT

Se sustituyó una configuración menos precisa por una más robusta para español:

• model_size = "small" en lugar de base
• vad_filter=True para recortar silencios y mejorar segmentación
• condition_on_previous_text=False para evitar arrastre de contexto erróneo
• temperature=0 para reducir variabilidad en la decodificación

Este ajuste resolvió errores observados en pruebas reales de voz, especialmente en frases como:

• “¿Cómo te llamas?”
• “Dime qué día es hoy.”
• “Dime cuál es tu nombre.”

7. Implantación de STT en OpenClaw

7.1 Configuración requerida

Aplicar:

openclaw config set tools.media.audio.models.0.type cli
openclaw config set tools.media.audio.models.0.command python3
openclaw config set tools.media.audio.models.0.timeoutSeconds 120
openclaw config set tools.media.audio.models.0.args '["/home/kevin/.openclaw/scripts/transcribe_audio.py", "{{MediaPath}}"]' --strict-json

7.2 Estado objetivo

La sección efectiva debe equivaler a:

{
  "tools": {
    "media": {
      "audio": {
        "models": [
          {
            "type": "cli",
            "command": "python3",
            "timeoutSeconds": 120,
            "args": ["/home/kevin/.openclaw/scripts/transcribe_audio.py", "{{MediaPath}}"]
          }
        ]
      }
    }
  }
}

7.3 Verificación puntual del script

Se puede probar sin pasar por OpenClaw:

python3 /home/kevin/.openclaw/scripts/transcribe_audio.py /ruta/al/audio.ogg

8. Implantación de TTS automático, Audio+Texto

8.1 Objetivo funcional

La respuesta del asistente debe entregarse siempre en dos formatos:

• texto visible
• audio TTS de la respuesta final

8.2 Configuración requerida

Aplicar:

openclaw config set messages.tts.enabled true
openclaw config set messages.tts.auto always
openclaw config set messages.tts.mode final
openclaw config set messages.tts.provider microsoft
openclaw config set messages.tts.providers.microsoft.enabled true
openclaw config set messages.tts.providers.microsoft.lang es-ES
openclaw config set messages.tts.providers.microsoft.voice es-ES-XimenaNeural

8.3 Estado objetivo

La configuración efectiva debe quedar equivalente a:

{
  "messages": {
    "tts": {
      "enabled": true,
      "auto": "always",
      "mode": "final",
      "provider": "microsoft",
      "prefsPath": "~/.openclaw/settings/tts.json",
      "providers": {
        "microsoft": {
          "enabled": true,
          "voice": "es-ES-XimenaNeural",
          "lang": "es-ES"
        }
      }
    }
  }
}

8.4 Consideraciones operativas

• auto: always fuerza intento de audio en todas las respuestas.
• mode: final evita sintetizar texto intermedio o commentary.
• provider: microsoft activa la ruta de síntesis compatible con la voz seleccionada.
• La voz seleccionada en esta implantación es es-ES-XimenaNeural.

9. Inventario de voces femeninas en español

Voces útiles detectadas para pruebas:

• es-ES-ElviraNeural
• es-ES-XimenaNeural
• es-MX-DaliaNeural
• es-AR-ElenaNeural
• es-CO-SalomeNeural

9.1 Cambio de voz

Ejemplo:

openclaw config set messages.tts.providers.microsoft.voice es-MX-DaliaNeural
openclaw gateway restart

10. Aplicación de cambios

Tras modificar configuración, reiniciar el gateway:

openclaw gateway restart

En despliegues con systemd --user, también puede utilizarse:

systemctl --user restart openclaw-gateway.service

10.1 Nota de operación

Un reinicio del gateway puede cortar la ejecución de la sesión actual. Esto es esperable. La validación debe realizarse con el siguiente mensaje entrante.

11. Procedimiento de validación

11.1 Validación de STT

Enviar varias notas de voz cortas en español y confirmar transcripción correcta.

Casos recomendados:

• “¿Cómo te llamas?”
• “Dime qué día es hoy.”
• “Dime cuál es tu nombre.”

Criterio de aceptación:

• la frase reconocida coincide de forma fiable con el audio real
• no aparecen sustituciones sistemáticas graves

11.2 Validación de TTS

Enviar mensajes normales al asistente y comprobar:

1. hay respuesta textual
2. hay audio adjunto
3. la voz es Ximena
4. el audio corresponde a la respuesta final

11.3 Validación extremo a extremo

Secuencia mínima:

1. enviar audio del usuario
2. verificar que el sistema lo entiende correctamente
3. solicitar una respuesta del asistente
4. verificar que vuelve texto + audio

12. Diagnóstico y troubleshooting

12.1 Síntoma, STT falla o devuelve transcripciones ajenas al audio real

Posibles causas:

• la ruta configurada del script STT no existe realmente para el gateway
• OpenClaw no está ejecutando el script esperado
• se está usando una ruta relativa no fiable en vez de una ruta absoluta estable
• modelo demasiado pequeño o segmentación débil

Acción correctiva recomendada:

• mover el script a /home/kevin/.openclaw/scripts/transcribe_audio.py
• configurar tools.media.audio.models.0.args con ruta absoluta
• ampliar timeoutSeconds a 120
• reiniciar el gateway
• dentro del script usar small, vad_filter=True, condition_on_previous_text=False, temperature=0, beam_size=5

Nota importante:

En esta implantación, la causa raíz real no fue solo la precisión del modelo, sino que OpenClaw no estaba usando de forma fiable el script outbox/transcribe_audio.py. Al fijar una ruta absoluta estable dentro de ~/.openclaw/scripts/, las pruebas reales de audio empezaron a comportarse correctamente.

12.2 Síntoma, aparece texto pero no audio

Comprobar:

openclaw config get messages.tts.enabled
openclaw config get messages.tts.auto
openclaw config get messages.tts.provider
openclaw config get messages.tts.providers.microsoft.voice

Valores esperados:

• true
• always
• microsoft
• es-ES-XimenaNeural

Si los valores son correctos, reiniciar gateway.

12.3 Síntoma, se sintetiza contenido no deseado

Comprobar que messages.tts.mode sea:

final

Esto limita la síntesis a la respuesta final.

12.4 Síntoma, el reinicio interrumpe la prueba

Comportamiento esperado. Reanudar validación tras reconexión y enviar un mensaje nuevo.

13. Rollback

Si se necesita volver a una configuración anterior:

13.1 Desactivar TTS automático

openclaw config set messages.tts.enabled false
openclaw gateway restart

13.2 Volver a otra voz

openclaw config set messages.tts.providers.microsoft.voice es-ES-ElviraNeural
openclaw gateway restart

13.3 Retirar el STT basado en script

Reconfigurar tools.media.audio.models al proveedor o comando anterior, o eliminar la entrada activa.

14. Configuración final validada en esta implantación

14.1 TTS

{
  "auto": "always",
  "provider": "microsoft",
  "prefsPath": "~/.openclaw/settings/tts.json",
  "providers": {
    "edge": {
      "enabled": true,
      "voice": "es-ES-AlvaroNeural",
      "lang": "es-ES"
    },
    "microsoft": {
      "enabled": true,
      "voice": "es-ES-XimenaNeural",
      "lang": "es-ES"
    }
  },
  "enabled": true,
  "mode": "final"
}

14.2 STT

{
  "models": [
    {
      "command": "python3",
      "type": "cli",
      "timeoutSeconds": 60,
      "args": ["outbox/transcribe_audio.py", "{{MediaPath}}"]
    }
  ]
}

15. Evidencia de cambio

15.1 Mejora de STT

Commit asociado:

• 93c8598 - Improve Spanish STT accuracy for voice notes

15.2 Documento de implantación

Commit asociado:

• dc0d95e - Add deployment manual for audio text and STT setup

16. Recomendación de uso en nuevas instalaciones

Para replicar esta solución en otro entorno:

1. verificar dependencias
2. desplegar el script outbox/transcribe_audio.py
3. configurar tools.media.audio.models
4. configurar messages.tts
5. reiniciar gateway
6. ejecutar validación con audios reales y respuestas reales
7. fijar la voz elegida según preferencia del usuario

17. Resumen ejecutivo

Esta implantación convierte OpenClaw en un asistente conversacional con entrada y salida por voz en español:

• entrada: STT local con Faster-Whisper ajustado para mejor precisión
• salida: TTS automático en todas las respuestas finales
• voz activa: es-ES-XimenaNeural
• modo de entrega: texto + audio

La solución ha sido validada con pruebas reales y deja una base reutilizable para futuras instalaciones.