No se instala o no funciona, ¿qué hacer: solución de problemas de instalación e inicio
Cuando OpenClaw no se instala o no funciona, lo más probable es que el problema esté en tres puntos: el entorno de Node no cumple los requisitos, el CLI no está en PATH, o el Gateway no arranca por su configuración. Esta página toma los errores comunes de la documentación oficial de solución de problemas y, agrupados por «texto del error», ofrece la causa y la solución de cada uno: primero la verificación rápida de 60 segundos, y luego localiza tu caso. Los textos de los errores están tomados de la documentación oficial y de la salida de diagnóstico del CLI, basados en v2026.10.9.
Qué podrás hacer al terminar
- Localizar en 60 segundos con 5 comandos de diagnóstico oficiales: en qué capa está el problema —entorno, CLI, Gateway o configuración
- Encasillar 21 errores comunes: texto del error → causa → comando de reparación
- Distinguir los límites de las cuatro capas de diagnóstico: entorno → proceso del Gateway → configuración y autenticación → conexión del cliente
- Saber qué tres comandos ejecutar primero para recuperarte de una actualización fallida, y dónde pedir ayuda
- Usar las dos herramientas oficiales
openclaw doctoryopenclaw triagepara hacer un chequeo y un diagnóstico con datos anonimizados
Tu situación actual
- Terminaste de instalar con npm, ejecutas
openclawy salecommand not found; pruebas a instalar consudoy aparece un error de permisos - Por fin instalaste el Gateway,
openclaw gateway statusmuestra stopped, y el log lanza una cadena de errores que nunca habías visto - Tras actualizar, ya no arranca: los canales están vacíos, las llamadas al modelo dan 401, y no sabes si la actualización rompió algo o fuiste tú al configurar
Cuándo usar esta técnica
Cuando necesitas:
- Reparar errores atascados en Instalación: puesta en marcha en 5 minutos o en métodos de instalación alternativos
- Reparar el Gateway que no arranca tras instalarse como servicio, o el Control UI que no conecta
- Recuperarte de una actualización fallida
Y además no quieres:
- Ir al foro a publicar y esperar sin hacer nada cada vez que hay un error: la verificación rápida de 60 segundos elimina la mayor parte de la espera
- Confundir «el entorno está roto» con «la configuración está rota» y cambiar cosas a ciegas en ambas
🎒 Preparativos antes de empezar
- Haber recorrido instalación, la ruta principal, o métodos de instalación alternativos —no importa en qué paso te hayas atascado, esta página es para desatascarte
- Poder ejecutar comandos en la terminal: en macOS / Linux / WSL2 usa Bash, en Windows usa PowerShell
- Acostumbrarte a copiar el texto del error completo —esta página agrupa por texto del error, y solo con la copia literal puedes encontrar tu caso
Idea central
Primero localiza la capa, luego mira el error. Desde que ejecutas el comando hasta que recibes la respuesta de la IA se atraviesan cuatro capas, y los errores de cada capa se ven distintos:
| capa | qué ocurre | verificación rápida | error típico |
|---|---|---|---|
| 1. Entorno | Node demasiado antiguo o no instalado; CLI no está en PATH | node -v / openclaw --version | command not found y node:sqlite truncates TEXT |
| 2. Proceso del Gateway | no arranca, puerto ocupado, el servicio instalado no corre | openclaw gateway status | EADDRINUSE y Gateway start blocked |
| 3. Configuración y autenticación | Configuración mal escrita, token incorrecto | openclaw doctor | Invalid config at ..., AUTH_TOKEN_MISSING |
| 4. Conexión del cliente | Control UI no conecta | curl http://127.0.0.1:18789 | gateway connect failed: |
Las dos herramientas oficiales de diagnóstico son lo más práctico. openclaw doctor hace una revisión y repara problemas comunes de configuración/servicios; openclaw triage genera un informe de diagnóstico con datos anonimizados (sin secrets, tokens, contenido original del chat ni logs originales), que puedes entregar directamente al agente de codificación de tu máquina para que continúe la reparación; si no respondes Yes dentro de 30 segundos cuando aparece la solicitud de confirmación, se omite el inicio y solo se imprime ese comando manual.
💡 Red de China continental
La documentación oficial no ofrece un espejo de npm ni una solución para acelerar la descarga, y este artículo no especula sobre direcciones de espejo. Si la descarga del script de instalación o de las dependencias expira, revisa primero el entorno de red y reintenta; no confíes en scripts de «espejo nacional» de origen desconocido.
Primera revisión: verificación rápida en 60 segundos
Ejecuta los cinco comandos en orden, verificando sucesivamente Node, la CLI, el Gateway y la configuración; cuando uno falle, repara desde esa capa.
# 1. Node 在支持范围吗?——要 24.16.0+(24.x)或 26.1.0+,建议 24.22.1+/26.12.1+
node -v
# 2. CLI 装上了吗?——应打印版本号(本页基准 v2026.10.9)
openclaw --version
# 3. Gateway 起来了吗?——应看到 Runtime: running、监听 18789
openclaw gateway status
# 4. 配置/服务有内伤吗?——应无 blocking 错误
openclaw doctor
# 5. 还是一头雾水?——一键生成脱敏诊断
openclaw triageDeberías ver: el 1 imprime v24.16.0+ o v26.1.0+; el 2 imprime el número de versión; el 3 Runtime: running; el 4 sin errores bloqueantes. Cuando uno falle, salta al grupo correspondiente más abajo.
Diagnóstico de problemas comunes
Instalación y entorno: no se instala
"openclaw: command not found"
Causa: palabras textuales de la documentación oficial: «casi siempre es un problema de PATH»—el directorio bin global de npm no está en el PATH de tu shell. Si usas un gestor de versiones como nvm / fnm pero no lo añadiste al archivo de inicio del shell, también te afecta. La variante en Windows es openclaw is not recognized.
Solución:
- Localizar en tres líneas:
node -v # Node 装了吗
npm prefix -g # 全局包装在哪
echo "$PATH" # 全局 bin 目录在 PATH 里吗- macOS / Linux: añade el bin global al PATH y escríbelo en el archivo de inicio del shell (en zsh es
${ZDOTDIR:-$HOME}/.zshrc, en bash es~/.bashrc):
export PATH="$(npm prefix -g)/bin:$PATH"Luego abre un terminal nuevo, o ejecuta rehash en zsh, hash -r en bash.
- Windows: añade al PATH del usuario el directorio de salida de
npm config get prefix(en la mayoría de sistemas es%AppData%\npm, sin añadir el sufijo\bin) y vuelve a abrir PowerShell.
Deberías ver: en el terminal nuevo, openclaw --version imprime el número de versión.
"npm error spawn git / git not found"
Causa: el instalador de Windows, al seguir la ruta de instalación por git, no encuentra Git—Git for Windows no está instalado, o está instalado pero no está en el PATH.
Solución: instala Git for Windows (recomendación de las preguntas frecuentes oficiales), confirma que git esté en el PATH → cierra por completo y vuelve a abrir PowerShell → vuelve a ejecutar el instalador.
"EACCES" (permiso denegado en npm install -g)
Causa: en Linux el directorio global de npm pertenece a root y el usuario actual no puede escribir en él.
Solución: cambia el prefix global de npm a un directorio escribible por el usuario:
mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"Escribe la línea export PATH=... en ~/.bashrc o ${ZDOTDIR:-$HOME}/.zshrc y reinstala OpenClaw.
"blocked because they are not covered by allowScripts"
Causa: npm 12 bloquea por defecto los scripts de ciclo de vida de paquetes no aprobados, y los preinstall / postinstall de OpenClaw quedan bloqueados. npm 11.16 solo advierte pero los deja pasar; npm 11.15 y anteriores no tienen esta política. Ojo con la trampa: el npm approve-scripts openclaw que sugiere npm 11.16 no funciona para instalaciones globales—devuelve ENOMATCH No installed packages match: openclaw.
Solución: pasa el parámetro correcto al instalar:
# npm 12 或 11.16+
npm install -g openclaw@latest --allow-scripts=openclaw
# npm 11.15 及更早:同命令去掉 --allow-scripts=openclawNode <v>: node:sqlite truncates TEXT at embedded NUL (nodejs/node#61954); use 24.16+/26.1+ or a build with the fix
Causa: requisitos estrictos de OpenClaw: Node 24.16.0+ (24.x) o 26.1.0+ (expresión engines >=24.16.0 <25 || >=26.1.0), y la biblioteca SQLite cargada debe superar la verificación de seguridad WAL (SQLite 3.51.3+, o en 3.50.x ≥ 3.50.7, en 3.44.x ≥ 3.44.6). Node 22, 23 y 25 no son compatibles en absoluto; oficialmente se recomienda encarecidamente 24.22.1+ / 26.12.1+ (correcciones de seguridad).
Solución:
- Con
node -vcomprueba la versión; si es demasiado antigua, actualiza (Node 26 es la versión recomendada). En un terminal interactivo la CLI muestraUpdate NodeJS: Y/N [N]:—pulsa Y para que descargue un runtime privado y verificado en~/.openclaw/tools/cli-node, sin tocar el Node del sistema. - El instalador oficial instala Node automáticamente si falta: en macOS instala Node 26, en Linux Node 24 LTS.
- Límites de plataforma: los binarios oficiales de Node 24+ para macOS se compilan para macOS 13.5+; 11–13.4 no se prueba ni se admite; Linux ARMv7 no tiene compilación oficial, es obligatorio usar un sistema de 64 bits.
- Distribuciones basadas en RPM (Fedora / RHEL): el Node de la distribución enlaza una SQLite del sistema insegura, y el instalador oficial cambia automáticamente a un runtime en modo usuario, sin que tengas que hacer nada.
Deberías ver: node -v imprime v24.16.0+ o v26.1.0+ y el error desaparece. El aviso oficial adicional: actualiza Node antes de actualizar OpenClaw, para evitar el truncamiento de TEXT en SQLite.
"blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)"
Causa: la imagen de Docker se ejecuta con el usuario node (uid 1000) y el propietario del directorio montado desde el host no coincide, por lo que la política de seguridad bloquea el plugin; suele ir seguido del mensaje plugin present but blocked.
Solución: cambia el propietario del directorio montado a 1000:
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
openclaw doctor --fixSolo si ejecutas OpenClaw a largo plazo como root, cambia /path/to/openclaw-config/npm a root:root. Para los detalles del despliegue con Docker, consulta Despliegue en servidor.
💡 ¿El instalador se queda colgado sin respuesta?
Vuelve a ejecutarlo añadiendo --verbose:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verboseinstall.ps1 no tiene un interruptor correspondiente; envuélvelo con Set-PSDebug -Trace 1 / -Trace 0.
Gateway: no arranca
Primero ejecuta openclaw gateway status (añade --deep para escanear también los servicios a nivel de sistema) y openclaw logs --follow para ver los registros, y luego compara con los errores de abajo.
"Gateway start blocked: set gateway.mode=local"
Causa: falta en la configuración el marcador de modo local de gateway.mode — el modo local no está activado, o el archivo de configuración se corrompió y perdió el campo (el registro también puede escribir existing config is missing gateway.mode). En despliegues con Podman, ten en cuenta que la ruta de configuración por defecto es ~/.openclaw/openclaw.json.
Solución (dos correcciones oficiales):
- Establece
gateway.mode="local"en la configuración; - O vuelve a ejecutar
openclaw onboard --mode local/openclaw setuppara regenerar una configuración de modo local.
"another gateway instance is already listening" / EADDRINUSE
Causa: el puerto por defecto 18789 está ocupado — normalmente porque se instalaron servicios Gateway duplicados, u otro proceso tomó el puerto.
Solución:
openclaw gateway status --deepescanea servicios launchd / systemd / tareas programadas duplicados; presta atención a las indicaciones de limpieza deOther gateway-like services detected (best effort).- La recomendación oficial es un Gateway por máquina en la mayoría de instalaciones; si de verdad necesitas ejecutar varios, debes aislar puertos + configuración + estado + espacio de trabajo.
- Caso especial de macOS: si
ai.openclaw.gatewayyai.openclaw.node, los dos LaunchAgents, están activos a la vez, entran en un ciclo rápido deEADDRINUSE/respawn — si no necesitas la funcionalidad de node, ejecutaopenclaw node uninstall. - Tras limpiar, ejecuta
openclaw gateway restart; status debería mostrarRuntime: running.
"refusing to bind gateway ... without auth"
Causa: por defecto, Gateway solo escucha en la dirección de loopback local + el puerto 18789. Quieres vincular a una dirección que no es loopback pero sin configurar autenticación — OpenClaw se niega a arrancar (fail closed; es un diseño de seguridad intencional).
Solución: elige una de dos opciones:
- Seguir escuchando solo en loopback y acceder en remoto mediante un túnel SSH (
ssh -N -L 18789:127.0.0.1:18789 user@gateway-host) o Tailscale; - Configurar autenticación para Gateway (token / password, o trusted-proxy); las reglas están en Endurecimiento de seguridad (1). ¿Todavía no has configurado un shared secret? Genera uno con
openclaw doctor --generate-gateway-token.
"Invalid config at ..."
Causa: el archivo de configuración no pasó la validación — se corrompió al editarlo a mano, la estructura es incorrecta, o se colaron claves desconocidas. Gateway se niega a arrancar; un Gateway en ejecución también omitirá las ediciones defectuosas en la recarga en caliente (el registro escribe config reload skipped (invalid config): ...).
Solución:
- Localización y verificación:
openclaw config file # 配置文件在哪
openclaw config validate # 哪一条不过- Deja que doctor lo arregle:
openclaw doctor --fixpuede reparar una configuración corrupta o restaurar la última conocida como buena; el contenido defectuoso rechazado se conserva en los archivos adyacentes.rejected.*/.clobbered.*(.clobbered.*conserva las últimas 32 copias por ruta de configuración); si quieres recuperar solo las claves que cambiaste, cópialas desde ahí. - Si lo reparas a mano: conserva la estructura JSON5 completa, cambia solo las claves objetivo y, al terminar, verifica con
openclaw config validateantes de reiniciar.
"Gateway service port does not match current gateway config"
Causa: el servicio en segundo plano ya instalado sigue con el viejo --port — habitual tras cambiar la configuración del puerto.
Solución:
openclaw doctor --fix # 或 openclaw gateway install --force
openclaw gateway restartControl UI: no conecta
¿Gateway está vivo pero el navegador no conecta? Los errores de este grupo ocurren todos en el último tramo de «cliente → Gateway».
"gateway connect failed:"
Causa: la URL / el puerto al que apunta Control UI son incorrectos, o Gateway simplemente no se está ejecutando.
Solución: triple verificación en la máquina local:
openclaw gateway restart
lsof -i :18789
curl http://127.0.0.1:18789curl recupera el HTML de OpenClaw → Gateway está bien; el problema está del lado del navegador: abre directamente http://127.0.0.1:18789, borra la caché y no uses enlaces profundos antiguos. Si tras un restart el servicio sigue sin levantarse, ejecuta openclaw gateway start y comprueba openclaw gateway status.
"AUTH_TOKEN_MISSING"
Causa: Gateway tiene configurada autenticación por token / password, pero el cliente no envió el shared token.
Solución:
- Obtén el token en el terminal interactivo de la máquina del Gateway:
openclaw gateway auth-token --show- Pega la salida en la configuración de Control UI y reintenta. ¿Todavía no has configurado un token? Genera uno con
openclaw doctor --generate-gateway-token; el origen del token esgateway.auth.token(o la variable de entornoOPENCLAW_GATEWAY_TOKEN). - Si sigue sin conectar, consulta la tabla oficial de códigos de error de autenticación:
| Código de error | Significado | Siguiente paso |
|---|---|---|
AUTH_TOKEN_MISMATCH | el shared token no coincide | permite un reintento de confianza con el token del dispositivo; si sigue fallando, sigue la lista oficial de deriva de tokens |
AUTH_DEVICE_TOKEN_MISMATCH | el token del dispositivo es demasiado antiguo o fue revocado | rota / vuelve a aprobar con la CLI de devices |
AUTH_SCOPE_MISMATCH | el token del dispositivo no tiene permisos suficientes | vuelve a emparejar o aprueba los scopes solicitados; no cambies el shared token |
PAIRING_REQUIRED | identidad del dispositivo pendiente de aprobación | openclaw devices approve <requestId> |
"device identity required" y "origin not allowed"
Causa: el primero — el cliente no envió la identidad del dispositivo (tampoco puede omitirse en modo token / password; el shared secret no la sustituye); el segundo — el Origin del navegador no está en la lista blanca; los despliegues en red pública o de origen cruzado requieren añadir entradas en gateway.controlUi.allowedOrigins (las redes locales privadas y las direcciones Tailscale no necesitan lista blanca).
Solución: para el primero, vuelve a completar el emparejamiento del dispositivo; para el segundo, añade el Origin del despliegue a gateway.controlUi.allowedOrigins y reconecta.
"too many failed authentication attempts (retry later)"
Causa: el mismo navegador Origin falló repetidamente en la autenticación y quedó bloqueado temporalmente. Los demás orígenes localhost usan contadores independientes y no se ven afectados.
Solución: deja de intentar y no sigas forzando el bloqueo; primero confirma según la entrada de AUTH_TOKEN_MISSING que las credenciales son correctas, y reintenta más tarde.
Atascado en "Wake up, my friend!" sin respuesta
Causa: la pantalla de incubación del onboarding depende de que el Gateway sea accesible y esté autenticado. Si se omitió la configuración de modelo / auth, el asistente mostrará Model auth missing y abrirá el TUI directamente sin enviar mensajes; si ves la frase de activación pero los tokens se quedan en 0, significa que el agent no llegó a ejecutarse.
Solución:
openclaw gateway restart
openclaw status
openclaw models status
openclaw logs --followSi aún no funciona, haz openclaw doctor. Si el provider del modelo o las credenciales no están bien configurados, ejecuta openclaw onboard para reconfigurar: es el único comando designado oficialmente para «cambiar el provider del modelo y la autenticación».
Fallo de actualización
La entrada de recuperación para fallos de actualización se fija en tres rutas: openclaw update status --json (ver el paso fallido registrado y el código de causa), openclaw triage (diagnóstico anonimizado), openclaw doctor --fix. En Settings → Updates de la Control UI se puede ver la hora del último intento, las versiones anterior y posterior, el paso fallido y el reason code.
"managed-service-handoff-failed"
Causa: cuando el nivel de log de la console es debug, la entrega de actualización de las versiones afectadas se rechaza. Versiones stable afectadas: 2026.9.6–2026.9.9 y 2026.10.1–2026.10.5.
Solución: pon logging.consoleLevel en "info", elimina OPENCLAW_LOG_LEVEL=debug del entorno del Gateway y del comando de actualización (el log de archivo puede mantenerse en debug), ejecuta openclaw update y, al terminar, restaura la configuración de log original.
"global-install-permission-denied"
Causa: el prefix global de npm no es escribible; es común con el Node de Homebrew, un prefix del sistema, o tras cambiar de gestor de versiones y apuntar a otro prefix.
Solución: revisa el directorio y el propietario mencionados en el error:
- El directorio te pertenece → corrígelo con el comando
chmod u+rwxindicado en el error; - El directorio pertenece al administrador → que una cuenta con permisos ejecute la actualización, o que te otorgue permisos;
- En una instalación personal se puede cambiar a un prefix escribible por el usuario (ver el truco de EACCES más arriba).
⚠️ No ejecutes todo el actualizador con sudo
La advertencia oficial es clara: ejecutar todo el actualizador con sudo puede seleccionar un home y una cuenta de servicio distintos. Tampoco cambies de forma recursiva el propietario de un prefix del sistema compartido.
"ETARGET" / "E404" / "EINTEGRITY"
Causa: npm falla al resolver o descargar paquetes; la versión objetivo no se encuentra en el registry, la caché está obsoleta, o hay problemas con la configuración del registry / espejo.
Solución:
npm cache verify
npm view <spec> version # 用报错里给出的 spec 验证Comprueba el registry o espejo que tengas configurado y reintenta. El actualizador vigente reintenta automáticamente una vez ante el fallo de una dependencia nombrada (npm usa --prefer-online, Bun usa --no-cache).
"protocol mismatch" (se repite sin parar tras un rollback)
Causa: tras revertir a un Gateway antiguo, aún hay procesos cliente más nuevos reconectando con un rango de protocolo que el Gateway antiguo no entiende. El log tiene la forma protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n>.
Solución:
- Con
openclaw gateway status --deep(oopenclaw doctor --deep) localiza el PID del cliente stale y detenlo; - Reinicia lo que tenga embebido OpenClaw: el dashboard local, el editor, el helper de app-server, el shell persistente con
openclaw logs --followmontado; - Ejecuta de nuevo
--deeppara confirmar que el PID antiguo desapareció. No fuerces al Gateway antiguo a aceptar el protocolo nuevo: la versión del protocolo protege el contrato de comunicación.
"plugin load failed: dependency tree corrupted; run openclaw doctor --fix"
Causa: la actualización acaba de terminar y la lista de canales está vacía o las llamadas al modelo devuelven 401; ambas apuntan a que el cierre de la actualización no se completó: el registro del plugin de canales falló (la configuración de canales sigue ahí, pero el plugin no se cargó); o el 401 del provider proviene de una sombra obsoleta de credenciales OAuth por agent.
Solución: la secuencia de recuperación genérica de cinco pasos tras actualizar:
openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restartdoctor --fix limpia las sombras OAuth obsoletas y repara el árbol de dependencias dañado. El recordatorio oficial: tras un fallo de actualización, no hagas rollback del estado de inmediato; primero conserva el estado actual y reinstala código que se sepa bueno, y solo restaura la copia de seguridad previa a la actualización si el código antiguo no puede leer la configuración / base de datos nuevas.
¿Sigue sin funcionar?
Reúne evidencia antes de preguntar. La tabla de comandos de diagnóstico de la guía oficial «I am stuck»: ejecútalos y adjunta la salida (anonimizada):
| Comando | Qué se puede ver |
|---|---|
openclaw status | Salud del Gateway / agent + instantánea de configuración básica |
openclaw status --all | Diagnóstico completo de solo lectura, listo para pegar |
openclaw models status | Autenticación del provider + disponibilidad de modelos |
openclaw doctor | Verifica y repara problemas comunes de configuración / estado |
openclaw logs --follow | Cola de logs en tiempo real |
openclaw gateway status --deep | Chequeo profundo del Gateway / configuración / plugins |
openclaw health --verbose | Informe de salud detallado |
Para fallos de tipo actualización, adjunta además la salida de openclaw update status --json. Un solo openclaw triage genera el diagnóstico anonimizado; revísalo antes de enviarlo y no adjuntes credenciales, configuración sin anonimizar ni salida de procesos sin tratar.
Dónde preguntar:
| Canal | Para qué sirve |
|---|---|
| community.openclaw.ai | Sitio de soporte oficial: problemas de configuración y entorno empieza aquí |
| GitHub issue chooser | Defectos del producto reproducibles / bugs de documentación, con pasos de reproducción y evidencia |
| Documentación oficial de resolución de problemas | Entrada oficial de resolución por síntomas; origen de muchos errores de esta página |
Punto de control ✅
- 60 segundos para comprobar con cinco comandos; sabes en qué capa estás atascado
openclaw --versionimprime el número de versión,command not foundya está corregidonode -vestá en el rango 24.16.0+ (24.x) o 26.1.0+openclaw gateway statusmuestraRuntime: running, escuchando en 18789- Al preguntar adjuntarás la salida de diagnóstico anonimizada, como
openclaw status --all
Preguntas frecuentes
OpenClaw ¿Qué significa?
OpenClaw es una herramienta de IA que se instala mediante npm, compuesta por la CLI de openclaw, el servicio Gateway residente y la Control UI del navegador, y sirve para conectar con los distintos proveedores de modelos y ejecutar agentes de IA. Esta página trata específicamente los errores de su fase de instalación e inicio; si no se instala o no arranca, consulta primero el «60 segundos de verificación rápida» de arriba.
OpenClaw ¿Cómo se usa? ¿Hay un tutorial detallado?
Para empezar, desde la instalación: sigue primero Instalación: 5 minutos para que funcione, o elige métodos de instalación alternativos. Una vez instalado, usa openclaw gateway status para confirmar Runtime: running y que escucha en 18789, luego completa la configuración de modelos y autenticación con openclaw onboard, y después abre http://127.0.0.1:18789 en el navegador para usar la Control UI.
Resumen de esta lección
✅ Para resolver problemas, primero determina la capa: entorno (Node / CLI) → proceso del Gateway → configuración y autenticación → conexión del cliente; cada capa tiene sus comandos de comprobación fijos.
✅ OpenClaw no se instala por tres causas principales (PATH, permisos de npm, versión de Node) y todas tienen solución fija: completar el PATH, cambiar a un prefix escribible por el usuario, actualizar a 24.16.0+/26.1.0+.
✅ Recuerda las dos herramientas oficiales: openclaw doctor hace chequeo y reparación, openclaw triage genera un diagnóstico anonimizado que puede entregarse directamente a un agente de codificación.
✅ Si la actualización falla, entra primero por la vía de recuperación: openclaw update status --json → openclaw triage → openclaw doctor --fix, y no te apresures a revertir el estado.
Consulta rápida de errores clave:
| Señal de error | Capa | Primer paso |
|---|---|---|
openclaw: command not found | Entorno | npm prefix -g → completar el PATH |
node:sqlite truncates TEXT ... | Entorno | Actualizar Node a 24.16+/26.1+ |
blocked ... allowScripts | Entorno | --allow-scripts=openclaw → Reinstalar |
Gateway start blocked: set gateway.mode=local | Gateway | Sobrescribir gateway.mode=local |
EADDRINUSE | Gateway | status --deep Buscar servicios duplicados |
Invalid config at ... | Configuración | doctor --fix + config validate |
AUTH_TOKEN_MISSING | Autenticación | gateway auth-token --show |
managed-service-handoff-failed | Actualización | Poner consoleLevel en info |
protocol mismatch | Actualización | --deep Buscar y detener procesos de clientes antiguos |
Para una consulta rápida completa de comandos y configuración, véase Referencia rápida de comandos y configuración de la CLI.
Avance de la próxima lección
Con el entorno estabilizado y el Gateway residente, el siguiente paso es conectar el «cerebro». Próxima lección: Panorama de conexión de modelos: sistema de providers y cambio de modelos.
Aprenderás:
provider/model— Cómo leer una referencia de modelo y por qué los plugins oficiales de provider no requieren escribir entradas de configuraciónopenclaw modelsFamilia de comandos: list / set / status- Matriz completa de modelos nacionales: DeepSeek, Qianwen, GLM, Kimi, MiniMax, Doubao… una página por cada proveedor