Skip to content

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 doctor y openclaw triage para hacer un chequeo y un diagnóstico con datos anonimizados

Tu situación actual ​

  • Terminaste de instalar con npm, ejecutas openclaw y sale command not found; pruebas a instalar con sudo y aparece un error de permisos
  • Por fin instalaste el Gateway, openclaw gateway status muestra 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:

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:

capaqué ocurreverificación rápidaerror típico
1. EntornoNode demasiado antiguo o no instalado; CLI no está en PATHnode -v / openclaw --versioncommand not found y node:sqlite truncates TEXT
2. Proceso del Gatewayno arranca, puerto ocupado, el servicio instalado no correopenclaw gateway statusEADDRINUSE y Gateway start blocked
3. Configuración y autenticaciónConfiguración mal escrita, token incorrectoopenclaw doctorInvalid config at ..., AUTH_TOKEN_MISSING
4. Conexión del clienteControl UI no conectacurl http://127.0.0.1:18789gateway 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.

bash
# 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 triage

Deberí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:

  1. Localizar en tres líneas:
bash
node -v           # Node 装了吗
npm prefix -g     # 全局包装在哪
echo "$PATH"      # 全局 bin 目录在 PATH 里吗
  1. 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):
bash
export PATH="$(npm prefix -g)/bin:$PATH"

Luego abre un terminal nuevo, o ejecuta rehash en zsh, hash -r en bash.

  1. 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:

bash
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:

bash
# npm 12 或 11.16+
npm install -g openclaw@latest --allow-scripts=openclaw
# npm 11.15 及更早:同命令去掉 --allow-scripts=openclaw

Node <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:

  1. Con node -v comprueba la versión; si es demasiado antigua, actualiza (Node 26 es la versión recomendada). En un terminal interactivo la CLI muestra Update 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.
  2. El instalador oficial instala Node automáticamente si falta: en macOS instala Node 26, en Linux Node 24 LTS.
  3. 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.
  4. 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:

bash
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
openclaw doctor --fix

Solo 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:

bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose

install.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):

  1. Establece gateway.mode="local" en la configuración;
  2. O vuelve a ejecutar openclaw onboard --mode local / openclaw setup para 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:

  1. openclaw gateway status --deep escanea servicios launchd / systemd / tareas programadas duplicados; presta atención a las indicaciones de limpieza de Other gateway-like services detected (best effort).
  2. 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.
  3. Caso especial de macOS: si ai.openclaw.gateway y ai.openclaw.node, los dos LaunchAgents, están activos a la vez, entran en un ciclo rápido de EADDRINUSE/respawn — si no necesitas la funcionalidad de node, ejecuta openclaw node uninstall.
  4. Tras limpiar, ejecuta openclaw gateway restart; status debería mostrar Runtime: 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:

  1. 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;
  2. 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:

  1. Localización y verificación:
bash
openclaw config file       # 配置文件在哪
openclaw config validate   # 哪一条不过
  1. Deja que doctor lo arregle: openclaw doctor --fix puede 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í.
  2. Si lo reparas a mano: conserva la estructura JSON5 completa, cambia solo las claves objetivo y, al terminar, verifica con openclaw config validate antes 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:

bash
openclaw doctor --fix      # 或 openclaw gateway install --force
openclaw gateway restart

Control 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:

bash
openclaw gateway restart
lsof -i :18789
curl http://127.0.0.1:18789

curl 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:

  1. Obtén el token en el terminal interactivo de la máquina del Gateway:
bash
openclaw gateway auth-token --show
  1. 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 es gateway.auth.token (o la variable de entorno OPENCLAW_GATEWAY_TOKEN).
  2. Si sigue sin conectar, consulta la tabla oficial de códigos de error de autenticación:
Código de errorSignificadoSiguiente paso
AUTH_TOKEN_MISMATCHel shared token no coincidepermite un reintento de confianza con el token del dispositivo; si sigue fallando, sigue la lista oficial de deriva de tokens
AUTH_DEVICE_TOKEN_MISMATCHel token del dispositivo es demasiado antiguo o fue revocadorota / vuelve a aprobar con la CLI de devices
AUTH_SCOPE_MISMATCHel token del dispositivo no tiene permisos suficientesvuelve a emparejar o aprueba los scopes solicitados; no cambies el shared token
PAIRING_REQUIREDidentidad del dispositivo pendiente de aprobaciónopenclaw 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:

bash
openclaw gateway restart
openclaw status
openclaw models status
openclaw logs --follow

Si 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:

  1. El directorio te pertenece → corrígelo con el comando chmod u+rwx indicado en el error;
  2. El directorio pertenece al administrador → que una cuenta con permisos ejecute la actualización, o que te otorgue permisos;
  3. 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:

bash
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:

  1. Con openclaw gateway status --deep (o openclaw doctor --deep) localiza el PID del cliente stale y detenlo;
  2. Reinicia lo que tenga embebido OpenClaw: el dashboard local, el editor, el helper de app-server, el shell persistente con openclaw logs --follow montado;
  3. Ejecuta de nuevo --deep para 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:

bash
openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart

doctor --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):

ComandoQué se puede ver
openclaw statusSalud del Gateway / agent + instantánea de configuración básica
openclaw status --allDiagnóstico completo de solo lectura, listo para pegar
openclaw models statusAutenticación del provider + disponibilidad de modelos
openclaw doctorVerifica y repara problemas comunes de configuración / estado
openclaw logs --followCola de logs en tiempo real
openclaw gateway status --deepChequeo profundo del Gateway / configuración / plugins
openclaw health --verboseInforme 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:

CanalPara qué sirve
community.openclaw.aiSitio de soporte oficial: problemas de configuración y entorno empieza aquí
GitHub issue chooserDefectos del producto reproducibles / bugs de documentación, con pasos de reproducción y evidencia
Documentación oficial de resolución de problemasEntrada 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 --version imprime el número de versión, command not found ya está corregido
  • node -v está en el rango 24.16.0+ (24.x) o 26.1.0+
  • openclaw gateway status muestra Runtime: 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 errorCapaPrimer paso
openclaw: command not foundEntornonpm prefix -g → completar el PATH
node:sqlite truncates TEXT ...EntornoActualizar Node a 24.16+/26.1+
blocked ... allowScriptsEntorno--allow-scripts=openclaw → Reinstalar
Gateway start blocked: set gateway.mode=localGatewaySobrescribir gateway.mode=local
EADDRINUSEGatewaystatus --deep Buscar servicios duplicados
Invalid config at ...Configuracióndoctor --fix + config validate
AUTH_TOKEN_MISSINGAutenticacióngateway auth-token --show
managed-service-handoff-failedActualizaciónPoner consoleLevel en info
protocol mismatchActualizació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ón
  • openclaw models Familia de comandos: list / set / status
  • Matriz completa de modelos nacionales: DeepSeek, Qianwen, GLM, Kimi, MiniMax, Doubao… una página por cada proveedor

Tutoriales relacionados ​

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.