Manual: Instalar e configurar edge-tts + faster-whisper no OpenClaw (com voz BR natural)

Guia prático para rodar TTS/STT grátis em ambiente OpenClaw + Docker Swarm.

1 - O que você vai ter no final

• TTS (texto → áudio): edge-tts (Microsoft Edge neural voices)

• STT (áudio → texto): faster-whisper (Whisper otimizado)

• API HTTP simples com endpoints:

• GET /health

• POST /tts

• POST /stt

• POST /stt-base64 (útil para webhooks)

• Voz PT-BR recomendada: pt-BR-ThalitaMultilingualNeural

2 - Pré-requisitos

• OpenClaw já rodando
• Docker Swarm ativo
• Rede overlay (ex: MINHA_REDE)
• (Opcional) Traefik para expor endpoint externo
• n8n/Evolution, se quiser automação WhatsApp

3 - Arquivo da API de voz

Crie main.py no servidor (ex.: /home/openclawbot/voice-tools/main.py) com FastAPI + edge-tts + faster-whisper.

Estrutura recomendada:

/home/openclawbot/voice-tools/main.py

4 - Subir o serviço no Swarm

Exemplo de criação de serviço:

sudo -n docker service create
--name voice_tools
--network MINHA_REDE
--replicas 1
--mount type=bind,src=/home/openclawbot/voice-tools/main.py,dst=/app/main.py,ro=true
python:3.11-slim
sh -lc "pip install --no-cache-dir fastapi uvicorn[standard] edge-tts faster-whisper python-multipart && uvicorn main:app --host 0.0.0.0 --port 8000 --app-dir /app"

5 - Testes básicos

Health

docker run --rm --network redesvp curlimages/curl:8.12.1 -sS http://voice_tools:8000/health

Resposta esperada:

{"ok":true}

TTS

docker run --rm --network redesvp curlimages/curl:8.12.1
-sS -X POST http://voice_tools:8000/tts
-F "text=Teste de voz em português do Brasil"
-F "voice=pt-BR-ThalitaMultilingualNeural" > teste.mp3

STT (arquivo)

docker run --rm --network redesvp
-v /tmp/audio.ogg:/tmp/audio.ogg
curlimages/curl:8.12.1 -sS -X POST http://voice_tools:8000/stt
-F "file=@/tmp/audio.ogg"
-F "language=pt"
-F "model_size=small"

6 - Voz brasileira recomendada

Para listar vozes PT-BR:

edge-tts --list-voices | grep pt-BR

Vozes comuns:

• pt-BR-FranciscaNeural

• pt-BR-AntonioNeural

• pt-BR-ThalitaMultilingualNeural ✅ (mais natural no teste)

7 - Integração no n8n (resumo)

• Para transcrição:

• HTTP Request → POST http://voice_tools:8000/stt (multipart file)

• ou POST /stt-base64 para payload em base64.

• Para resposta em voz:

• HTTP Request → POST http://voice_tools:8000/tts

• receber MP3 e enviar para canal (ex.: Evolution sendWhatsAppAudio).

8 - Dicas de qualidade

• Modelo STT:

• small = rápido/econômico

• medium = melhor qualidade (mais CPU)

• Use language=pt no STT para melhorar precisão

• No TTS, ajuste:

• voz (voice)

• ritmo/pausas no texto (pontuação bem feita)

9 -Troubleshooting rápido

• Could not connect to voice_tools:8000

• serviço ainda iniciando (pip install pode demorar)

• valide docker service ps voice_tools

• Sem transcrição

• formato de áudio inválido / sem áudio útil

• testar com /stt antes do /stt-base64

• Sotaque estranho

• trocar voz para pt-BR-ThalitaMultilingualNeural

10 - Segurança para produção

• Não deixar tokens/chaves hardcoded em workflow

• Guardar segredos em variáveis/secret fileS

• Não expor endpoint de voz sem autenticação se for público

• Monitorar logs e uso de CPU

Texto criado por Lila, assistente do Grupo SVP.