Solución de problemas

Síntoma	Qué revisar
La CLI no encuentra el workspace	Corre desde el directorio que contiene vatio.yml o debajo de él; inspecciona con vatio doctor
La autenticación de la CLI falla	Corre vatio login; verifica el host con vatio doctor
La validación del manifiesto o de una herramienta falla	Corre vatio tools check y arregla el archivo que reporta; las claves raíz desconocidas y la falta de instructions son errores
El agente nunca llama a una herramienta	Agrega su clave a agent.tools, describe cuándo usarla, pushea y empieza un chat de prueba nuevo
Faltan respuestas de conocimiento	Revisa vatio kb show BASE, las referencias en knowledge y la asignación de la herramienta knowledge_lookup
El agente no puede compartir una URL	Revisa que esté escrita literalmente en links, en instructions o en un resultado de herramienta — una URL armada o editada se elimina
El widget no aparece	Revisa vatio widget, el entorno del token, que haya un agente desplegado y el origen permitido exacto del sitio
Un visitante con sesión aparece como anónimo	Revisa que auth.public_key coincida con la clave con que firmas, y la firma, el exp y el aud del JWT (el slug del workspace)
WhatsApp o Instagram está conectado pero en silencio	Corre el check del canal; confirma la recepción del webhook y un agente en vivo; WhatsApp además debe estar activado
El agente dejó de responder en un chat	Revisa si hay traspaso a humano en la bandeja y libéralo cuando corresponda

Reportes

Envía un reporte de error o una solicitud de funcionalidad desde la CLI:

vatio issue "Describe what happened and what you expected"
vatio issue --template > issue.md
vatio issue --file issue.md
vatio issue list
vatio issue show 42
vatio issue comment 42 "Additional details"
vatio issue "Push is rejected" --no-source

Corrido desde un workspace, vatio issue adjunta el directorio — los mismos archivos que envía vatio push. Vatio conserva vatio.yml y todo lo que esté bajo tools/, lista el resto por nombre, y registra qué opinaron sus propias validaciones, así que un reporte sobre una herramienta llega con la herramienta. Cualquier archivo del que una validación se haya quejado también se conserva. El comando imprime qué va a adjuntar antes de enviar; --no-source manda el reporte solo. Los archivos ocultos nunca se incluyen, así que .env y .git/ se quedan en tu máquina.

Los comandos de issue y comment envían de inmediato. Revisa el texto antes de correrlos. Incluye el comando que falló, el error observado y un request_id cuando esté disponible. La CLI incluye su versión y el contexto del workspace; no adjunta la salida de tu comando anterior. Quita credenciales y datos de clientes de cualquier reporte. Haz seguimiento en el hilo existente para que el contexto se mantenga junto.