Solución de problemas

Modos de fallo comunes, en el orden en que es probable que los encuentres.

Primer paso para cualquier problema:

zeroclaw doctor

Ejecuta una serie de comprobaciones e imprime un resumen. La mayor parte de lo que sigue es la versión detallada de lo que indica doctor.

Durante la instalación

cargo no se encontró

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

O pasa --prebuilt a install.sh / setup.bat para omitir Rust por completo.

Faltan dependencias de compilación (Linux)

Instala la cadena de herramientas base para tu distribución y luego vuelve a ejecutar ./install.sh:

sudo apt install build-essential pkg-config

sudo dnf group install development-tools && sudo dnf install pkg-config

sudo pacman -S base-devel

Lista completa por distribución: Configuración → Linux.

Genera OOMs en hosts con poca memoria RAM

Compilar ZeroClaw desde el código fuente consume mucha memoria, principalmente durante el enlazado final. install.sh ya se adapta a esto automáticamente cuando compila desde el código fuente:

Cuando install.sh compila desde el código fuente en Linux, lee MemTotal de /proc/meminfo y, en hosts con menos de 12 GiB de RAM, exporta CARGO_PROFILE_RELEASE_LTO=thin antes de compilar. El LTO fat (el valor por defecto de [profile.release]) puede superar los 7 GB de RSS durante el paso de tipos entre crates y provocar un OOM en una placa con poca RAM; el LTO thin compensa un pequeño aumento del tamaño del binario con un pico de memoria mucho menor en tiempo de compilación.

El conmutador solo se aplica cuando aún no has fijado la variable. Anula cualquiera de las dos direcciones explícitamente:

# Forzar LTO completo incluso en un host con poca RAM (binario más pequeño, mayor RAM de compilación)
export CARGO_PROFILE_RELEASE_LTO=gordo

# Forzar LTO ligero (thin LTO) en un host con mucha RAM (menor consumo de RAM en la compilación)
export CARGO_PROFILE_RELEASE_LTO=thin

Si aún se queda sin memoria, o no está compilando a través de install.sh:

1. Usar una versión precompilada: ./install.sh --prebuilt omite la cadena de herramientas y descarga desde GitHub Releases.
2. Realiza la compilación cruzada en una máquina más potente y copia el binario.
3. Elige un perfil de compilación más ligero: cargo build --profile release-fast (mayor paralelismo de codegen, enlazado más ligero) o --profile ci (thin LTO, el más rápido y con menor consumo de memoria).
4. Serializa la compilación: CARGO_BUILD_JOBS=1 cargo build --release --locked.
5. Agregar swap (funciona para la RAM, consume disco, verifica que tienes ambos).

Para los detalles específicos de Raspberry Pi, consulte Configuración de Raspberry Pi → compilación.

La compilación es muy lenta.

La pila E2EE de Matrix (matrix-sdk, ruma, vodozemac) y las dependencias nativas de TLS/cifrado (aws-lc-sys, ring) son el principal costo. Desactívalas si no las necesitas:

cargo build --release --locked --no-default-features --features "lean-por-defecto"

O verifica qué está pasando:

cargo check --timings
# informe en target/cargo-timings/cargo-timing.html

zeroclaw: comando no encontrado después de la instalación

cargo install coloca los binarios en ~/.cargo/bin/. Añade a PATH:

export PATH="$HOME/.cargo/bin:$PATH"

Persiste en tu perfil de shell.

Inicio rápido

Quickstart no sobrescribirá una configuración existente

zeroclaw quickstart no tiene un flag --force, deja intencionalmente intacta una instalación existente. Para ejecutar un quickstart desde cero sobre una instalación obsoleta, elimina el directorio y comienza de nuevo:

rm -rf ~/.zeroclaw
zeroclaw quickstart

O bien, para editar un único campo desactualizado en lugar de borrar todo, usa zeroclaw config set <key> <value> directamente.

Instalación de Homebrew: discrepancia en la ruta de configuración

Las instalaciones de Homebrew prefieren $HOMEBREW_PREFIX/var/zeroclaw/ (para que brew services funcione) mientras que el directorio de configuración predeterminado es ~/.zeroclaw/. Establece ZEROCLAW_WORKSPACE con la ruta de Homebrew antes de ejecutar quickstart para que las dos rutas coincidan:

export ZEROCLAW_WORKSPACE="$HOMEBREW_PREFIX/var/zeroclaw"
zeroclaw quickstart

O crea un enlace simbólico manualmente una vez:

ln -s "$HOMEBREW_PREFIX/var/zeroclaw" ~/.zeroclaw

Tiempo de ejecución

La autenticación de la suscripción de OpenAI Codex advierte sobre la configuración o el streaming

Síntomas:

• El model_provider = "openai.<alias>" del agente apunta a una entrada de Codex, pero las ejecuciones siguen pareciendo mal configuradas
• La carga de configuración advierte sobre campos de nivel superior desconocidos como api_key / api_url (estos pertenecen a la entrada del proveedor, no a la raíz del archivo)
• El agente registra provider streaming failed, falling back to non-streaming chat

Comprobaciones (sustituye <alias> con el alias del agente configurado de [agents.<alias>]):

Para una suscripción de OpenAI Codex, establece requires_openai_auth = true en el alias del proveedor y deja api_key sin definir; el runtime utiliza el inicio de sesión de Codex almacenado. Obtén la credencial de suscripción desde el flujo de inicio de sesión propio del proveedor. Consulta Provider Configuration → OAuth and subscription auth para conocer el modelo completo de credenciales. Luego prueba:

zeroclaw agent -a <alias> -m "hola"

Notas:

• requires_openai_auth = true en el alias (con api_key sin establecer) selecciona la ruta de suscripción; rodéelo con el agente canónico + perfil de riesgo del Ejemplo mínimo funcional.
• Los campos api_key / uri en la entrada del alias solo son necesarios para gateways personalizados compatibles con OpenAI u otras sobrescrituras explícitas de endpoint.
• La advertencia de transmisión deshabilitada por sí sola no es un fallo de autenticación; ZeroClaw reintenta la solicitud en modo sin transmisión.

El demonio se inicia y luego sale inmediatamente

Comprueba el registro de journald o el registro de la plataforma (consulta Registros y observabilidad) para ver el error real. Causas comunes:

• Configuración no válida: zeroclaw config list para imprimir los valores resueltos, zeroclaw config schema para ver la estructura esperada
• Conflicto de puerto: otro proceso en 42617; cambie [gateway] port o libere el puerto
• Secretos faltantes: el almacén de secretos cifrados no puede descifrar porque el archivo de clave ya no existe; restaure desde una copia de seguridad o vuelva a ejecutar el proceso de incorporación

El demonio sigue reiniciándose

systemctl --user status zeroclaw muestra la última salida. Si se trata de un error de configuración, el servicio dejó de reiniciarse (salida 2) y es necesario corregir la configuración. Si se produce un pánico, la unidad se reintenta cada 10 s.

Habilitar el registro de depuración y capturar el próximo fallo:

zeroclaw service stop
RUST_LOG=depurar zeroclaw daemon

Puerta de enlace inalcanzable

curl -sv http://localhost:42617/health

Si la conexión es rechazada: el demonio no se está ejecutando o está vinculado a una interfaz diferente. Verifica el host / port de [gateway] en la configuración.

Si 403 / 401: el emparejamiento no se completó o el token ha expirado. Ejecute el flujo de emparejamiento nuevamente.

Canales

Telegram: terminado por otra solicitud getUpdates

Dos procesos están consultando el mismo token de bot. Telegram solo permite un consultor a la vez.

Corrección: detener todos los procesos zeroclaw daemon / zeroclaw channel start excepto uno, utilizando ese token.

Fallos de autenticación en Discord / Slack

Los tokens de Discord expiran si los regeneras en el Portal de Desarrolladores. Los tokens de bot de Slack no expiran, pero pueden ser revocados. Verifica que el bot siga instalado en el espacio de trabajo/guild de destino.

Para cualquiera de los dos:

zeroclaw channel doctor

El fan-in de SOP no está cubierto por channel doctor

zeroclaw channel doctor construye adaptadores de transporte sin el motor SOP activo ni los manejadores de auditoría del demonio. Puede comprobar los transportes de canal habituales, pero no demuestra que el despacho SOP de MQTT, el sistema de archivos o AMQP pueda iniciar una ejecución. Para esas fuentes, inicie zeroclaw daemon con el entorno de ejecución SOP habilitado (sop.sops_dir establecido en un valor no vacío; no establecido de forma predeterminada, lo que lo deshabilita; el valor documentado es shared/sops), y después inspeccione la conexión de origen y los eventos de registro de SOP ingress. Un canal AMQP que usa dispatch = "sop" o "sop_and_agent_loop" falla de forma segura durante el inicio del demonio cuando los manejadores SOP no están disponibles; en ese estado, se omite intencionadamente de la lista de trabajo de doctor.

Matrix: “dispositivo desconocido”

Si te volviste a registrar sin conservar las claves del dispositivo, el servidor de la casa ve un nuevo dispositivo que no ha sido verificado. Vuelve a verificar desde otro cliente conectado o restablece el almacén de claves:

rm -rf ~/.zeroclaw/workspace/matrix-crypto
# volver a ejecutar el flujo de emparejamiento en el próximo inicio de canal

La comprobación de IMAP se ha detenido

Lo más frecuente es un fallo de autenticación: el proveedor rotó la contraseña o la contraseña de aplicación expiró. Verifica:

journalctl --user -u zeroclaw -n 200 | grep -i imap

Proveedores

“Tiempo de conexión agotado” a Ollama

• El demonio de Ollama no se está ejecutando: systemctl status ollama (Linux), brew services list (macOS)
• URL incorrecta en la configuración: desde dentro de un contenedor, localhost:11434 no alcanza el host; usa host.docker.internal o la IP LAN del host
• Firewall bloqueando el puerto 11434, poco frecuente localmente, común en redes LAN compartidas

Anthropic / OpenAI 401

La clave de API no es válida o ha expirado. Regenera la clave en el panel de control del proveedor, actualízala en [providers.models.<name>] api_key y reinicia el servicio.

Si usas OAuth (sk-ant-oat*), es posible que el token de OAuth haya expirado. Los tokens emitidos por OAuth tienen una vida más larga, pero no infinita. Vuelve a autenticarte.

Herramientas

Comandos de shell “bloqueados por política”

Comportamiento esperado en la autonomía Supervised para comandos desconocidos. O bien:

• Aprobar en línea cuando se solicite
• Agregue el comando a [autonomy] allowed_commands
• Aumenta la autonomía a Full si confías en el contexto

Consulta Seguridad → Niveles de autonomía.

Las invocaciones de herramientas fallan dentro del entorno de contenedor de Docker

• La imagen del contenedor no está descargada, ejecuta docker pull <image> para la imagen que tengas configurada en [security.sandbox].image (por defecto: alpine:latest)
• No se puede acceder al daemon de Docker desde el usuario de ZeroClaw, verifica docker info
• La herramienta necesita un dispositivo que no está en passthrough, amplíe allow_devices

La herramienta del navegador se queda colgada en el primer uso

Playwright descarga Chromium (~150 MB) en el primer lanzamiento. Deja que termine. Si se queda colgado, verifica el espacio en disco y la configuración del proxy.

Modo de servicio

Servicio instalado pero muestra inactivo

zeroclaw service start
zeroclaw service status

Usa zeroclaw service logs para mostrar los logs del servicio instalado. Agrega --follow para transmitir entradas nuevas o --lines <count> para cambiar cuánto historial se muestra. Si el wrapper no está disponible o necesitas inspeccionar la plataforma directamente, usa:

• Linux: journalctl --user -u zeroclaw.service -f
• macOS: log stream --predicate 'process == "zeroclaw"'
• Si está ejecutando zeroclaw daemon directamente en una terminal, use esa salida en primer plano en lugar de los comandos de registro del servicio.

Si eso funciona de forma interactiva pero el servicio muere en segundo plano, casi siempre se trata de configuración o permisos, lee el journal:

journalctl --user -u zeroclaw --since "hace 5 minutos"

El servicio no puede encontrar la configuración

El servicio y la CLI pueden resolver la configuración de manera diferente si se ejecutan como distintos usuarios o con distintas variables de entorno. Imprime forzosamente la ruta que ve el daemon:

zeroclaw config list

Si las rutas difieren entre zeroclaw config list (como tú) y el servicio (como su usuario), puedes:

• Establece ZEROCLAW_CONFIG_DIR en Environment= de la unidad del servicio
• Ejecuta el servicio como tú (servicio de usuario habilitado para permanecer activo)
• Copia o enlaza simbólicamente la configuración a la ruta que espera el servicio

¿Sigues atascado?

Recolectar diagnósticos y abrir un problema:

zeroclaw --version
zeroclaw doctor
zeroclaw channel doctor
journalctl --user -u zeroclaw --since "hace 1 hora" > zeroclaw-log.txt

Sanea zeroclaw-log.txt (censura los tokens de canal si alguno se coló, no deberían) y adjúntalo al issue. Consulta Contributing → Communication para saber dónde.

Ver también

• Registros y observabilidad
• Servicio y demonio
• Configuración → Gestión de servicios
• Referencia → Config