Solución de problemas en OpenClaw

Qué cubre este artículo sobre OpenClaw

Errores comunes después de la instalación.
Problemas con el gateway, proveedores y modelos.
Errores de conexión a Ollama y endpoints incorrectos.
Permisos, red y seguridad.
Herramientas como openclaw doctor y openclaw security audit.

Introducción: Solución de problemas en OpenClaw

OpenClaw es una herramienta potente que obtiene acceso profundo al sistema. Durante la instalación y operación pueden surgir varios problemas: claves API faltantes, endpoints incorrectos, errores de permisos o un gateway inaccesible. Conocer las fuentes de error más comunes permite identificarlas y resolverlas rápidamente.

Este artículo ofrece un enfoque sistemático para diagnosticar problemas en OpenClaw en Proxmox u otros sistemas Linux.

Procedimiento básico

Verifica la versión: openclaw --version
Ejecuta doctor: openclaw doctor
Revisa la configuración: openclaw config list
Lee los logs: ~/.openclaw/logs/ o stderr
Prueba mínima: Un modelo individual y un prompt simple.
Expande gradualmente: Proveedores, gateway, skills, herramientas.

Errores de instalación

La instalación se interrumpe

Verifica la versión de Node.js. OpenClaw requiere una versión reciente.
Usa el instalador oficial:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

Asegúrate de que npm y curl estén disponibles.
Verifica la conexión a Internet y la resolución DNS.

Comando no encontrado

Si openclaw no está disponible después de la instalación:

which openclaw
/usr/bin/openclaw

Si no está en el PATH:

export PATH="$PATH:/usr/bin"

Problemas de incorporación

El asistente no inicia

openclaw onboard --classic

Si faltan salidas interactivas, verifica el terminal y si stdin está disponible.

El proveedor no se reconoce

Es posible que se haya elegido Skip for now durante la incorporación. Vuelve a ejecutar el asistente o configura el proveedor manualmente:

openclaw config set models.providers.anthropic.apiKey "TU_ANTHROPIC_API_KEY"

Errores del gateway

El gateway no es accesible

openclaw gateway install
openclaw gateway status

Si el gateway no se ejecuta, verifica:

¿Se está ejecutando el proceso?
¿Está ocupado el puerto?
¿Se utilizó el parámetro bind correcto?

Se recomienda:

openclaw config set gateway.bind "127.0.0.1"

Gateway en interfaz pública

Esto representa un riesgo de seguridad. Ajusta la configuración:

openclaw config set gateway.bind "127.0.0.1"

Para acceso externo a través de Tailscale o túnel SSH, nunca uses bindeo a 0.0.0.0.

Errores de proveedor y modelo

El modelo no se encuentra

openclaw models list --provider anthropic
openclaw models list --provider ollama

Verifica que el proveedor correcto esté configurado.
Verifica que el modelo se haya descargado en Ollama.
Los nombres de modelo deben coincidir exactamente, incluida la etiqueta.

Clave API de Claude inválida

Asegúrate de que la clave tenga el formato correcto.
Verifica si se han agotado los créditos o límites.
Establece la clave nuevamente:

export ANTHROPIC_API_KEY="NUEVA_CLAVE"
openclaw config set models.providers.anthropic.apiKey "$ANTHROPIC_API_KEY"

Errores de conexión a Ollama

Endpoint incorrecto

OpenClaw utiliza el endpoint nativo de Ollama:

http://127.0.0.1:11434

No:

http://127.0.0.1:11434/v1

openclaw config set models.providers.ollama.baseUrl "http://127.0.0.1:11434"
openclaw config set models.providers.ollama.apiKey "ollama-local"

Ollama no es accesible

curl http://127.0.0.1:11434/api/tags

Si falla, verifica:

¿Se está ejecutando Ollama?
¿Es el puerto correcto?
¿Firewall o aislamiento de red lo bloquea?
En un LXC el dispositivo TUN no es necesario, pero Ollama debe estar iniciado.

El modelo no cabe en la memoria

Ollama se detiene o responde muy lentamente.
Verifica RAM/VRAM con free -h o nvidia-smi.
Elige un modelo más pequeño o una cuantización más agresiva.

Errores de permisos

OpenClaw se ejecuta como root

OpenClaw debe funcionar bajo un usuario dedicado:

useradd -m -s /bin/bash openclaw
mv /root/.openclaw /home/openclaw/.openclaw
chown -R openclaw:openclaw /home/openclaw/.openclaw

Archivos no legibles

ls -la /home/openclaw/.openclaw

Los permisos deben pertenecer al usuario OpenClaw.

Problemas de red y firewall

Sin acceso a Internet: Necesario para instalaciones y algunos skills.
Firewall de Proxmox bloquea puertos: Permite solo los puertos necesarios entre LXC.
Tailscale no es accesible: Verifica si el nodo está en línea.
Gateway no accesible externamente: Intencional si está vinculado al loopback.

Comprobaciones de seguridad

openclaw security audit --deep
openclaw doctor --fix

security audit muestra riesgos como permisos inseguros, gateways abiertos o componentes desactualizados. doctor verifica el estado de la instalación y puede reparar automáticamente algunos problemas.

Mensajes de error típicos

`ECONNREFUSED`

El servicio de destino no es accesible. Verifica host, puerto y firewall.

`Unauthorized`

Clave API faltante o inválida. Verifica la configuración del proveedor.

`Model not found`

Nombre de modelo incorrecto o modelo no instalado. Usa openclaw models list.

`Permission denied`

Problema de permisos en el sistema de archivos. Verifica usuario y derechos.

`Cannot find module`

Instalación posiblemente incompleta. Verifica reinstalación o openclaw doctor.

Enlaces e información adicional

FAQ: Solución de problemas en OpenClaw

¿Cómo reinicio OpenClaw? Detén el gateway y reinícialo, o reinicia todo el LXC.

¿Dónde están los logs de OpenClaw? Generalmente en ~/.openclaw/logs/, o en la salida del proceso.

¿Cómo verifico la configuración? Con openclaw config list o openclaw doctor.

¿Qué hago ante ECONNREFUSED? Verifica el host y puerto de destino, inicia el servicio, abre el firewall.

¿Debe OpenClaw ejecutarse como root? No, un usuario dedicado es más seguro.

Fuentes y lecturas adicionales

OpenClaw: https://openclaw.ai/
Ollama Docs: https://github.com/ollama/ollama/blob/main/docs/
Proxmox Troubleshooting: https://pve.proxmox.com/wiki/Troubleshooting

Resumen: Solución de problemas en OpenClaw

Los errores en OpenClaw suelen reducirse a problemas de instalación, configuración incorrecta de proveedores, errores de red o permisos. openclaw doctor y openclaw security audit ayudan en el diagnóstico. Es importante usar un usuario dedicado, vincular el gateway al loopback, usar el endpoint correcto de Ollama y realizar comprobaciones de seguridad periódicas. Quien proceda paso a paso y preste atención a los logs encontrará la mayoría de los problemas rápidamente.

Täglicher Artikel