Tu propio servidor
Cómo correr xiaozhi-esp32-server de xinnan-tech en modo mínimo con Docker en tu PC, solo en la red local: su configuración, sus puertos y cómo lo encuentra la panza.
Qué hace
Xiaozhi en la panza no entiende la voz ni piensa. Graba, comprime y reproduce. Escuchar, pensar y hablar ocurre en un servidor: por defecto el oficial en xiaozhi.me, y en este bot, un servidor en tu propio PC.
Ese servidor es xinnan-tech/xiaozhi-esp32-server, el servidor en Python que el README de Xiaozhi lista primero para desplegar en ordenadores personales. En cada conversación:
- Recibe el audio de la panza por WebSocket.
- Detecta dónde empiezas y dónde terminas de hablar (detección de actividad de voz).
- Convierte tu voz en texto (reconocimiento de voz, ASR).
- Envía el texto a un modelo de lenguaje (LLM). En este bot, Claude, desde la guía 5.
- Convierte la respuesta en voz (síntesis, TTS) y la envía de vuelta.
También responde a la petición OTA de la panza, que es como la panza sabe dónde está el WebSocket (guía 3).
El bot lo corre en el modo mínimo del proyecto, que el README en inglés llama “Simplified Installation” (instalación simplificada): un agente, datos guardados en archivos de configuración, sin base de datos y sin consola web. Corre en Docker en el PC en el que trabajas, y solo se puede llegar a él desde tu red local.
Cómo funciona por dentro
Por qué solo en tu red local
El README del proyecto es directo sobre su madurez. Su traducción al inglés dice que el proyecto “has not passed network security assessment” (no ha superado una evaluación de seguridad de red), pide no usarlo en producción y pide medidas de protección si lo despliegas en una red pública para aprender. El original en chino dice lo mismo: “未通过网络安全测评”.
El bot toma la lectura segura: el servidor nunca da a internet. No se redirige ningún puerto en el router, y solo los dispositivos de tu red pueden llegar a él. La configuración por defecto encaja con ese uso: la autenticación está desactivada (server.auth.enabled: false), lo que es aceptable en una red doméstica y no en internet.
Módulos: qué usa cada paso
main/xiaozhi-server/config.yaml elige un proveedor por paso en selected_module. Los valores por defecto:
| Paso | Clave | Por defecto | Notas de config.yaml |
|---|---|---|---|
| Actividad de voz | VAD |
SileroVAD |
Modelo local |
| Reconocimiento de voz | ASR |
FunASR |
Local, sin conexión, modelo SenseVoiceSmall |
| Modelo de lenguaje | LLM |
ChatGLMLLM |
Necesita clave; la guía 5 lo sustituye por Claude |
| Modelo de visión | VLLM |
ChatGLMVLLM |
El bot no lo usa |
| Síntesis de voz | TTS |
EdgeTTS |
Voz zh-CN-XiaoxiaoNeural por defecto |
| Memoria | Memory |
nomem |
Sin memoria entre conversaciones |
| Intención | Intent |
function_call |
El modelo llama a las herramientas directamente |
Cada nombre apunta a un bloque del mismo nombre más abajo en el archivo (ASR.FunASR, TTS.EdgeTTS y así sucesivamente) con los ajustes de ese proveedor.
config.yaml y data/.config.yaml
Los comentarios del principio de config.yaml dan la regla: crea data/.config.yaml y pon ahí tus cambios, no en config.yaml. El servidor lee primero data/.config.yaml y toma de config.yaml todo lo que falte. La guía de despliegue lo llama la forma más concisa, y el comentario añade por qué importa: mantiene tus claves fuera del propio archivo del proyecto.
Para el bot esto significa que data/.config.yaml contiene solo lo que difiere de los valores por defecto: la dirección del WebSocket, la zona horaria, los proveedores elegidos y sus claves. Vive en tu PC, fuera de cualquier repositorio.
Puertos
El docker-compose.yml del proyecto publica dos puertos:
| Puerto | Ajuste | Qué sirve |
|---|---|---|
| 8000 | server.port |
El WebSocket con el que habla la panza, en /xiaozhi/v1/ |
| 8003 | server.http_port |
HTTP: la interfaz OTA sencilla en /xiaozhi/ota/, y el análisis de visión |
El servidor escucha en 0.0.0.0 (server.ip), es decir, en todas las interfaces de red del contenedor. Docker publica esos puertos en el PC.
Cómo lo encuentra la panza
Importan dos direcciones, las dos construidas a partir de la dirección de tu PC en la red local (aquí la inventada 192.168.1.50):
- URL OTA:
http://192.168.1.50:8003/xiaozhi/ota/. La escribes una vez en la panza, en la pestaña Advanced del portal Wi-Fi (guía 3). - URL del WebSocket:
ws://192.168.1.50:8000/xiaozhi/v1/. El servidor se la envía a la panza en su respuesta OTA.
La segunda necesita cuidado en Docker. El servidor construye la dirección del WebSocket por sí mismo solo mientras server.websocket conserva el marcador de config.yaml (ws://你的ip或者域名:端口号/xiaozhi/v1/, “tu IP o dominio : puerto”). Dentro de un contenedor, la dirección que ve es la del contenedor, no la de tu PC. La guía de despliegue advierte que con Docker las direcciones del log de arranque no son las reales, y que el método correcto es usar la dirección LAN del PC. Así que el bot fija server.websocket de forma explícita, y el manejador OTA envía entonces exactamente ese valor. Como no hay ningún mqtt_gateway configurado, envía un objeto websocket, que es lo que selecciona WebSocket en la panza.
Va un ajuste más con él: server.timezone_offset, la zona horaria que la respuesta OTA comunica a la panza. El valor por defecto +8 es la hora de China; pon la tuya.
Local o API: elegir el reconocimiento y la síntesis de voz
Cada paso puede correr en tu PC o llamar a una API en la nube. config.yaml documenta los dos tipos:
| Tipo | Reconocimiento de voz (ASR) | Síntesis de voz (TTS) |
|---|---|---|
| Local | FunASR (por defecto), SherpaASR, VoskASR (sin conexión) |
FishSpeech, PaddleSpeechTTS, IndexStreamTTS, GPT_SOVITS_V2 (cada uno necesita su propio despliegue) |
| API | OpenaiASR, GroqASR, AliyunASR, DoubaoASR y otros |
OpenAITTS, AliyunTTS, DoubaoTTS y otros |
Las ventajas y desventajas:
- Lo local mantiene tu voz en casa y no cuesta nada por uso, pero usa la memoria y la CPU de tu PC. El README indica que correr
FunASRen local consume más memoria, y que usar APIs para todo mantiene bajo el consumo de recursos. - El idioma importa. Narsil habla español. El comentario del bloque
FunASRlista las etiquetas de idioma que admite SenseVoice como zh, en, ja, ko y yue, así que para español el bot usa otro reconocedor.OpenaiASR(modelogpt-4o-mini-transcribepor defecto) yGroqASR(whisper-large-v3-turbo) son APIs multilingües;VoskASRfunciona sin conexión y admite varios idiomas con un modelo descargado. - Una API envía tu audio fuera de tu red y necesita una clave. La guía 12 lista lo que sale de la red y por qué.
El bot usa OpenaiASR para el reconocimiento y mantiene EdgeTTS para la síntesis, que no necesita clave en config.yaml. La voz de Narsil en sí, y el ajuste voice, son la guía 6.
Sin el servidor, solo se para la voz
El servidor hace un único trabajo: la voz. La panza se conecta a ntfy y a GitHub por su cuenta (guías 7 y 8), y la cabeza dibuja lo que la panza le envíe. Si tu PC está apagado, o Docker está parado, los avisos de Narsil, tus pull requests y su cara siguen funcionando. Solo la palabra de activación no lleva a ninguna parte hasta que el servidor vuelve.
Cómo se le pidió a la IA
La decisión de correr un servidor llegó en la guía 3: quien creó Narsil eligió “servidor propio” en lugar de xiaozhi.me. La IA propuso entonces este servidor en modo mínimo, con Docker, solo en la red local, y volvió a preguntar antes de seguir. La confirmación fue:
vamos con el propio de una
La siguiente pregunta fue dónde correría: en el PC, o en otra máquina de casa. La respuesta:
en el pc, igual la idea es usarlo para trabajar con claude
Esa segunda respuesta explica dos cosas de esta guía. El servidor corre en Docker en el PC en el que ya trabaja quien creó Narsil, así que no hay nada nuevo que tenga que quedarse encendido. Y Claude es el cerebro: la siguiente decisión, registrada como la especificación S5, eligió la opción “1”, un proveedor nativo de Anthropic escrito en Python con el Anthropic SDK en lugar de un endpoint compatible con OpenAI. La guía 5 lo construye.
Un prompt que puedes usar
El siguiente prompt se escribió para esta guía como sugerencia. No es la conversación con la que se preparó el bot.
Quiero correr xinnan-tech/xiaozhi-esp32-server en su modo mínimo con Docker en mi PC con Windows, accesible solo desde mi red local, para un dispositivo Xiaozhi. Lee el README del proyecto,
docs/Deployment.md,main/xiaozhi-server/config.yamlydocker-compose.yml, y después dame: la estructura de carpetas, undata/.config.yamlque sobrescriba solo lo que necesito (dirección del WebSocket con mi IP de la LAN, zona horaria, un reconocedor de voz que entienda español), los comandos para arrancarlo y leer sus logs, y la URL OTA que tengo que darle al dispositivo. Cita el aviso de seguridad del proyecto y dime qué puertos abre.
El código mínimo
La carpeta en el PC, según la guía de despliegue:
xiaozhi-server
├─ docker-compose.yml
├─ data
│ └─ .config.yaml
└─ models
└─ SenseVoiceSmall
└─ model.pt
docker-compose.yml es el propio archivo del proyecto, descargado de main/xiaozhi-server/. El archivo compose monta models/SenseVoiceSmall/model.pt en el contenedor, así que la guía de despliegue te hace descargar ese modelo (desde ModelScope o Baidu) aunque el bot reconozca la voz mediante una API.
data/.config.yaml, con una dirección y una clave inventadas:
server:
websocket: ws://192.168.1.50:8000/xiaozhi/v1/
timezone_offset: -5
selected_module:
ASR: OpenaiASR
TTS: EdgeTTS
ASR:
OpenaiASR:
api_key: sk-EXAMPLE-not-a-real-key
Solo se fija api_key dentro de OpenaiASR; el resto de ese bloque (type, base_url, model_name) viene de config.yaml. Usa el desplazamiento de tu propia zona horaria. La sección LLM llega en la guía 5; hasta entonces el servidor sigue seleccionando el ChatGLMLLM por defecto, que según la guía de despliegue necesita su clave para arrancar.
Arráncalo desde la carpeta xiaozhi-server y sigue su log:
docker compose up -d
docker logs -f xiaozhi-esp32-server
La imagen es ghcr.nju.edu.cn/xinnan-tech/xiaozhi-esp32-server:server_latest, el contenedor se llama xiaozhi-esp32-server, y restart: always lo vuelve a levantar después de un reinicio de Docker.
Errores comunes y cómo probarlo
- Editar
config.yamlen lugar dedata/.config.yaml. Tus cambios se mezclan con el archivo del proyecto y se pierden en la siguiente descarga. Ponlos endata/.config.yaml. - Fiarse de las direcciones del log de Docker. Son las del contenedor. Usa la dirección LAN de tu PC en
server.websockety en la URL OTA de la panza. - Redirigir el 8000 o el 8003 en el router. El proyecto no tiene evaluación de seguridad y la autenticación está desactivada por defecto. Mantenlo en tu red.
- El cortafuegos del PC. Si la panza no llega al servidor pero el propio navegador del PC sí, permite las conexiones entrantes en el 8000 y el 8003 desde tu red privada.
- Una dirección del PC que cambia. Si el router le da al PC una dirección nueva, la URL OTA de la panza y
server.websocketquedan desfasadas. Una reserva DHCP en el router mantiene fija la dirección. - Actualizar sobrescribiendo
.config.yaml. Los pasos de actualización de la guía de despliegue dicen que hagas una copia de seguridad y copies tus claves una a una en el nuevo, porque unconfig.yamlnuevo puede traer ajustes nuevos.
Para probarlo, abre la URL OTA en un navegador del PC, por ejemplo http://192.168.1.50:8003/xiaozhi/ota/. La guía de firmware de xinnan-tech dice que un servidor que funciona responde “OTA接口运行正常” (“la interfaz OTA funciona con normalidad”) seguido de la dirección del WebSocket que envía a los dispositivos. Si esa dirección muestra tu IP de la LAN y el puerto 8000, la panza lo encontrará. Después di la palabra de activación y mira docker logs -f xiaozhi-esp32-server: deberías ver cómo se conecta la panza y el texto que oyó.
Para ir más lejos
- La instalación completa con módulos añade una base de datos, varios usuarios y agentes, y una consola web. El bot no la necesita, y su dirección OTA es distinta (la guía de firmware usa el puerto 8002 para ella).
- El servidor puede servir actualizaciones de firmware para la panza desde su carpeta
data/bin, como describe la guía de actualización OTA del proyecto (docs/ota-upgrade-guide.md). server.authpuede exigir un token, conallowed_deviceslistando las direcciones MAC que se saltan la comprobación. Es una capa útil incluso en una red doméstica.- La mayoría de los bloques de proveedor de
config.yamlllevan comentarios, en chino, sobre dónde conseguir la clave y, en algunos, cuánto cuesta; lee el del que elijas antes de comprometerte con él. - La guía 5 añade el
LLMque hace pensar a Narsil con Claude, y la guía 6 le da una voz y una personalidad.
¿Te ha servido esta guía?
Todas las guías son gratuitas. Si esta te ha ahorrado tiempo, puedes invitarme un café.
Invítame un café