Solución de problemas

Este es el manual operativo detallado. Empiece primero por /help/troubleshooting para seguir el flujo de triaje rápido.

Secuencia de comandos

Ejecútelos en este orden:

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Indicadores de funcionamiento correcto:

• openclaw gateway status muestra Runtime: running, Connectivity probe: ok y una línea Capability: ....
• openclaw doctor no informa de problemas de configuración o servicio que impidan continuar.
• openclaw channels status --probe muestra el estado activo del transporte por cuenta y, cuando se admite, works o audit ok.

Después de una actualización

Utilice esta sección cuando finalice una actualización, pero el Gateway esté inactivo, los canales estén vacíos o las llamadas a modelos fallen con errores 401.

openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw gateway restart

Compruebe lo siguiente:

• Update restart en openclaw status / openclaw status --all. Las transferencias pendientes o fallidas incluyen el siguiente comando que debe ejecutarse.
• plugin load failed: dependency tree corrupted; run openclaw doctor --fix en Canales: la configuración del canal todavía existe, pero el registro del plugin falló antes de que pudiera cargarse el canal.
• Errores 401 del proveedor después de volver a autenticarse: openclaw doctor --fix busca copias obsoletas de autenticación OAuth por agente y elimina las antiguas para que todos los agentes resuelvan el perfil compartido actual.

Instalaciones divergentes y protección frente a configuraciones más recientes

Utilice esta sección cuando un servicio del Gateway se detenga inesperadamente después de una actualización o cuando los registros indiquen que un binario openclaw es anterior a la versión que escribió por última vez openclaw.json.

OpenClaw marca las escrituras de configuración con meta.lastTouchedVersion. Los comandos de solo lectura pueden inspeccionar una configuración escrita por una versión más reciente de OpenClaw, pero las mutaciones de procesos y servicios se niegan a ejecutarse desde un binario anterior. Acciones bloqueadas: iniciar, detener, reiniciar o desinstalar el servicio del Gateway; forzar la reinstalación del servicio; iniciar el Gateway en modo de servicio; y limpiar el puerto gateway --force.

which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion

openclaw gateway install --forceopenclaw gateway restart

Incompatibilidad de protocolo después de una reversión

Utilice esta sección cuando los registros sigan mostrando protocol mismatch después de una degradación o reversión. Se está ejecutando un Gateway anterior, pero un proceso cliente local más reciente sigue intentando reconectarse con un intervalo de protocolo que el Gateway anterior no admite.

openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw logs --follow

Compruebe lo siguiente:

• protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> en los registros del Gateway.
• Established clients: en openclaw gateway status --deep o Gateway clients en openclaw doctor --deep: clientes TCP activos conectados al puerto del Gateway, con PID y líneas de comandos cuando el sistema operativo lo permita.
• Un proceso cliente cuya línea de comandos apunte a la instalación o al envoltorio más reciente de OpenClaw desde el que se realizó la reversión.

Solución:

1. Detenga o reinicie el proceso cliente obsoleto de OpenClaw que muestra gateway status --deep.
2. Reinicie las aplicaciones o los envoltorios que incorporan OpenClaw: paneles locales, editores, asistentes de servidores de aplicaciones o shells openclaw logs --follow de larga duración.
3. Vuelva a ejecutar openclaw gateway status --deep o openclaw doctor --deep y confirme que el PID del cliente obsoleto ha desaparecido.

No haga que un Gateway anterior acepte un protocolo más reciente e incompatible. Los incrementos de versión del protocolo protegen el contrato de comunicación; la recuperación tras una reversión es un problema de limpieza de procesos y versiones.

Enlace simbólico de una Skill omitido por escapar de la ruta

Utilice esta sección cuando los registros incluyan:

Se omite la ruta de la skill que escapa de su raíz configurada: ... reason=symlink-escape

Cada raíz de Skills constituye un límite de contención. Un enlace simbólico en ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills o ~/.openclaw/skills se omite cuando su destino real se resuelve fuera de esa raíz, salvo que el destino sea explícitamente de confianza.

Inspeccione el enlace:

ls -l ~/.agents/skills/<name>realpath ~/.agents/skills/<name>openclaw config get skills.load

Si el destino es intencionado, configure tanto la raíz directa de la Skill como el destino permitido del enlace simbólico:

{  skills: {    load: {      extraDirs: ["~/Projects/manager/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },  },}

Después, inicie una sesión nueva o espere a que se actualice el observador de Skills. Reinicie el Gateway si el proceso en ejecución es anterior al cambio de configuración.

No utilice destinos amplios como ~, / o una carpeta completa de proyecto sincronizada. Mantenga allowSymlinkTargets limitado a la raíz real de Skills que contiene directorios SKILL.md de confianza.

Si la aplicación de Skill Workshop también debe escribir a través de esas rutas de Skills del espacio de trabajo enlazadas simbólicamente y de confianza, habilite skills.workshop.allowSymlinkTargetWrites. Manténgalo deshabilitado para las raíces compartidas de Skills de solo lectura.

Relacionado:

• Configuración de Skills
• Ejemplos de configuración

Anthropic 429: se requiere uso adicional para contextos largos

Utilice esta sección cuando los registros o errores incluyan: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

openclaw logs --followopenclaw models statusopenclaw config get agents.defaults.models

Compruebe lo siguiente:

• El modelo de Anthropic seleccionado es un modelo Claude 4.x de 1M con disponibilidad general (Opus 4.6/4.7/4.8, Sonnet 4.6), o la configuración del modelo todavía contiene el valor heredado params.context1m: true.
• La credencial actual de Anthropic no cumple los requisitos para usar contextos largos.
• Las solicitudes solo fallan en sesiones o ejecuciones de modelos largas que requieren la ruta de contexto de 1M.

Opciones de solución:

Relacionado:

• Anthropic
• Uso y costes de tokens
• ¿Por qué aparece el error HTTP 429 de Anthropic?

Respuestas 403 bloqueadas en el servicio ascendente

Utilice esta sección cuando un proveedor de LLM ascendente devuelva un 403 genérico, como Your request was blocked.

No presuponga que esto siempre se debe a un problema de configuración de OpenClaw. La respuesta puede proceder de una capa de seguridad ascendente, como una CDN, un WAF, una regla de gestión de bots o un proxy inverso situado delante de un endpoint compatible con OpenAI.

openclaw statusopenclaw gateway statusopenclaw logs --follow

Compruebe lo siguiente:

• Varios modelos del mismo proveedor fallan de la misma manera.
• Aparece HTML o texto genérico de seguridad en lugar de un error normal de la API del proveedor.
• Hay eventos de seguridad del proveedor correspondientes a la misma hora de la solicitud.
• Una pequeña prueba directa con curl funciona, mientras que las solicitudes normales con la estructura del SDK fallan.

Corrija primero el filtrado del proveedor cuando las pruebas indiquen un bloqueo del WAF o la CDN. Es preferible utilizar una regla de permiso u omisión limitada específicamente a la ruta de la API que utiliza OpenClaw y evitar deshabilitar la protección de todo el sitio.

Relacionado:

• Endpoints compatibles con OpenAI
• Configuración de proveedores
• Registros

El backend local compatible con OpenAI supera las pruebas directas, pero las ejecuciones del agente fallan

Utilice esta sección cuando:

• curl ... /v1/models funciona.
• Las llamadas directas pequeñas con /v1/chat/completions funcionan.
• Las ejecuciones de modelos de OpenClaw solo fallan durante los turnos normales del agente.

curl http://127.0.0.1:1234/v1/modelscurl http://127.0.0.1:1234/v1/chat/completions \  -H 'content-type: application/json' \  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'openclaw infer model run --model <provider/model> --prompt "hi" --jsonopenclaw logs --follow

Compruebe lo siguiente:

• Las llamadas directas pequeñas funcionan, pero las ejecuciones de OpenClaw solo fallan con prompts más grandes.
• Aparecen errores model_not_found o 404, aunque una solicitud directa con /v1/chat/completions funciona con el mismo identificador de modelo sin prefijo.
• El backend genera errores que indican que messages[].content esperaba una cadena.
• Aparecen advertencias intermitentes incomplete turn detected ... stopReason=stop payloads=0 con un backend local compatible con OpenAI.
• El backend se bloquea únicamente con cantidades mayores de tokens del prompt o con los prompts completos del entorno de ejecución del agente.

Relacionado:

• Configuración
• Modelos locales
• Endpoints compatibles con OpenAI

Sin respuestas

Si los canales están activos pero nada responde, compruebe el enrutamiento y la política antes de volver a conectar nada.

openclaw statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw config get channelsopenclaw logs --follow

Busque:

• Emparejamiento pendiente para remitentes de mensajes directos.
• Restricción por mención en grupos (requireMention, mentionPatterns).
• Discrepancias en la lista de permitidos del canal/grupo.

Indicadores habituales:

• drop guild message (mention required → el mensaje del grupo se ignora hasta que haya una mención.
• pairing request → el remitente necesita aprobación.
• blocked / allowlist → la política filtró al remitente/canal.

Relacionado:

• Solución de problemas de canales
• Grupos
• Emparejamiento

Conectividad de la interfaz de control del panel

Cuando el panel o la interfaz de control no se conecten, valide la URL, el modo de autenticación y los supuestos del contexto seguro.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --json

Busque:

• URL de sondeo y URL del panel correctas.
• Discrepancia del modo de autenticación o del token entre el cliente y el gateway.
• Uso de HTTP cuando se requiere la identidad del dispositivo.

Si un navegador local no puede conectarse a 127.0.0.1:18789 después de una actualización, primero recupere el servicio Gateway local y confirme que está sirviendo el panel:

openclaw gateway restartlsof -i :18789curl http://127.0.0.1:18789

Si curl devuelve HTML de OpenClaw, el Gateway funciona y probablemente el problema restante sea la caché del navegador, un enlace profundo antiguo o el estado obsoleto de una pestaña. Abra http://127.0.0.1:18789 directamente y navegue desde el panel. Si el servicio no permanece en ejecución después de reiniciarlo, ejecute openclaw gateway start y vuelva a comprobar openclaw gateway status.

Mapa rápido de códigos de detalles de autenticación

Utilice error.details.code de la respuesta fallida de connect para elegir la siguiente acción:

Comprobación de migración de autenticación de dispositivos v2:

openclaw --versionopenclaw doctoropenclaw gateway status

Si los registros muestran errores de nonce o firma, actualice el cliente que se conecta y verifíquelo:

Si openclaw devices rotate / revoke / remove se deniega de forma inesperada:

• Las sesiones con token de dispositivo emparejado solo pueden gestionar su propio dispositivo, a menos que el llamador también tenga operator.admin.
• openclaw devices rotate --scope ... solo puede solicitar ámbitos de operador que la sesión del llamador ya posea.

Relacionado:

• Configuración (modos de autenticación del gateway)
• Interfaz de control
• Dispositivos
• Acceso remoto
• Autenticación mediante proxy de confianza

El servicio Gateway no se está ejecutando

Utilice esta sección cuando el servicio esté instalado, pero el proceso no permanezca activo.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # también analiza los servicios del sistema

Busque:

• Runtime: stopped con indicaciones de salida.
• Discrepancia en la configuración del servicio (Config (cli) frente a Config (service)).
• Conflictos de puerto o proceso de escucha.
• Instalaciones adicionales de launchd/systemd/schtasks cuando se utiliza --deep.
• Indicaciones de limpieza de Other gateway-like services detected (best effort).

Relacionado:

• Ejecución en segundo plano y herramienta de procesos
• Configuración
• Doctor

El gateway de macOS deja de responder silenciosamente y se reanuda al interactuar con el panel

Se utiliza cuando los canales (Telegram, WhatsApp, etc.) de un host macOS dejan de responder durante periodos de entre minutos y horas, y el Gateway parece volver a funcionar en cuanto se abre la interfaz de control, se accede por SSH o se interactúa de otro modo con el host. Normalmente no hay ningún síntoma evidente en openclaw status porque, para cuando se revisa, el Gateway ya vuelve a estar activo.

ls ~/.openclaw/logs/stability/ | tail -5openclaw gateway stability --bundle latestpmset -g log | grep -iE "sleep|wake|maintenance" | tail -50launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

Qué buscar:

• Uno o varios paquetes *-uncaught_exception.json en ~/.openclaw/logs/stability/ con error.code establecido en un código de red transitorio, como ENETDOWN, ENETUNREACH, EHOSTUNREACH o ECONNREFUSED.
• Líneas de pmset -g log como Entering Sleep state due to 'Maintenance Sleep' o en0 driver is slow (msg: WillChangeState to 0) que coincidan con las marcas de tiempo de los fallos. Power Nap / Maintenance Sleep pone brevemente el controlador Wi-Fi en el estado 0; cualquier connect() saliente que se produzca durante ese intervalo puede fallar con ENETDOWN, incluso en un host que, por lo demás, dispone de conectividad de red completa.
• Salida de launchctl print que muestre state = not running con varios runs recientes y un código de salida, especialmente cuando el intervalo entre el fallo y el siguiente inicio es de aproximadamente una hora en lugar de unos segundos. launchd de macOS aplica un mecanismo no documentado de protección contra reapariciones después de una ráfaga de fallos, que puede dejar de respetar KeepAlive=true hasta que un activador externo, como un inicio de sesión interactivo, una conexión al panel o launchctl kickstart, vuelva a habilitarlo.

Indicadores habituales:

• Un paquete de estabilidad cuyo error.code sea ENETDOWN o un código relacionado, con la pila de llamadas apuntando a net de Node, lookupAndConnect / Socket.connect. OpenClaw 2026.5.26 y las versiones posteriores clasifican estos errores como errores de red transitorios benignos, por lo que ya no se propagan al controlador superior de excepciones no capturadas; si se utiliza una versión anterior, se debe actualizar primero.
• Periodos prolongados de inactividad que terminan en cuanto se establece una conexión con la interfaz de control o se accede al host mediante SSH: la actividad visible para el usuario es lo que vuelve a habilitar el mecanismo de reaparición de launchd, no ninguna acción del panel sobre el Gateway.
• El recuento de runs aumenta a lo largo del día sin una línea received SIG*; shutting down correspondiente en ~/Library/Logs/openclaw/gateway.log: los cierres limpios registran una señal; los fallos transitorios no.

Qué hacer:

1. Actualizar el Gateway si se utiliza una versión anterior a 2026.5.26. Después de la actualización, los futuros errores ENETDOWN se registran como advertencias en lugar de finalizar el proceso.

2. Reducir la actividad de suspensión de mantenimiento en hosts Mac mini o de escritorio destinados a funcionar como servidores siempre activos:

   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0

   Esto reduce considerablemente, pero no elimina por completo, la inestabilidad subyacente del controlador. El sistema todavía puede realizar algunas suspensiones de mantenimiento para conservar conexiones TCP y mantener mDNS, independientemente de estas opciones.

3. Añadir un supervisor de actividad para detectar rápidamente cualquier futura ráfaga de fallos que launchd deje detenida:

   # Ejemplo de comprobación de actividad compatible con launchd, adecuada para un cron o LaunchAgent de 5 minutosstate=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')if [ "$state" != "running" ]; then  launchctl kickstart -k gui/$UID/ai.openclaw.gatewayfi

   El objetivo es volver a habilitar externamente el mecanismo de reaparición; KeepAlive=true por sí solo no es suficiente en macOS después de una ráfaga de fallos.

Relacionado:

• Notas de la plataforma macOS
• Registro
• Doctor

Bucle del supervisor launchd de macOS con LaunchAgents duplicados de Gateway/Node

Se utiliza cuando una instalación de macOS se reinicia continuamente cada pocos segundos, las comprobaciones de estado de openclaw alternan entre disponible y no disponible, y el envío a los canales se bloquea aunque el servicio parezca estar en ejecución.

Esto se observó en instalaciones antiguas en las que tanto ai.openclaw.gateway como ai.openclaw.node eran LaunchAgents activos y cada uno inyectaba OPENCLAW_LAUNCHD_LABEL. En ese estado, OpenClaw puede detectar la supervisión de launchd, intentar devolver el control del reinicio a launchd y caer en un bucle rápido de EADDRINUSE/reaparición en lugar de mantener un único proceso de Gateway estable.

for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done openclaw gateway status --deepopenclaw node statuslaunchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'tail -n 80 ~/Library/Logs/openclaw/gateway.log

Qué buscar:

• Más de un PID del Gateway durante la muestra de 30 segundos, en lugar de un único proceso estable.
• EADDRINUSE, another gateway instance is already listening o líneas repetidas de reinicio/transferencia en gateway.log.
• Tanto ~/Library/LaunchAgents/ai.openclaw.gateway.plist como ~/Library/LaunchAgents/ai.openclaw.node.plist cargados al mismo tiempo en un host que solo debería ejecutar un servicio de Gateway administrado.

Qué hacer:

1. Si este host solo debe ejecutar el servicio Gateway, se debe eliminar el servicio Node administrado mediante OpenClaw. Omitir este paso si se depende activamente del servicio Node para funciones de nodos remotos; al desinstalarlo, esas funciones dejan de estar disponibles en este host:

   openclaw node uninstall

2. Instalar un contenedor persistente para el Gateway que borre los indicadores heredados de launchd antes de iniciar OpenClaw. Se debe utilizar la opción --wrapper compatible; no se debe editar el archivo generado en ~/.openclaw/service-env/, ya que la reinstalación del servicio, las actualizaciones y las reparaciones de Doctor vuelven a generar ese archivo:

   mkdir -p ~/.local/bincat >~/.local/bin/openclaw-launchd-workaround <<'EOF'#!/bin/shset -euunset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || trueexec openclaw "$@"EOFchmod 700 ~/.local/bin/openclaw-launchd-workaround openclaw gateway install \  --wrapper ~/.local/bin/openclaw-launchd-workaround \  --force

   gateway install conserva la ruta del contenedor entre reinstalaciones forzadas, actualizaciones y reparaciones de Doctor.

3. Verificar que el Gateway sea estable y preste servicio RPC, no que simplemente esté escuchando:

   openclaw gateway status --deep --require-rpc for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done

   La muestra de PID debe mostrar un único proceso estable en lugar de un conjunto rotatorio de PID, y el envío entrante a los canales debe reanudarse.

4. Después de actualizar a una versión en la que se haya corregido el bucle subyacente de LaunchAgents duplicados, se debe eliminar la solución provisional y reinstalar el servicio administrado normal:

   OPENCLAW_WRAPPER= openclaw gateway install --forcerm ~/.local/bin/openclaw-launchd-workaround

Relacionado:

• Notas de la plataforma macOS
• Doctor
• CLI del Gateway

El Gateway se cierra durante un uso elevado de memoria

Se utiliza cuando el Gateway desaparece bajo carga, el supervisor informa de un reinicio similar a uno provocado por falta de memoria o los registros mencionan critical memory pressure bundle written.

openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw gateway diagnostics export

Qué buscar:

• Reason: diagnostic.memory.pressure.critical en el paquete de estabilidad más reciente.
• Memory pressure: con critical/rss_threshold, critical/heap_threshold o critical/rss_growth.
• Valores de V8 heap: cercanos al límite del montón.
• Entradas de Largest session files: como agents/<agent>/sessions/<session>.jsonl o sessions/<session>.jsonl.
• Contadores de memoria de cgroup de Linux cuando el Gateway se ejecuta dentro de un contenedor o un servicio con memoria limitada.

Indicadores habituales:

• critical memory pressure bundle written aparece poco antes del reinicio → OpenClaw capturó un paquete de estabilidad anterior al agotamiento de memoria. Se puede inspeccionar con openclaw gateway stability --bundle latest.
• memory pressure: level=critical aparece en los registros del Gateway → OpenClaw detectó una presión crítica de memoria y registró los datos disponibles sobre la memoria del proceso.
• Largest session files: apunta a una ruta de transcripción censurada muy grande → se debe reducir el historial conservado de la sesión, inspeccionar su crecimiento o mover las transcripciones antiguas fuera del almacén activo antes de reiniciar.
• Los bytes utilizados de V8 heap: están cerca del límite del montón → primero se debe reducir la presión de las indicaciones o sesiones, o disminuir el trabajo simultáneo. En un servicio administrado, se debe inspeccionar Gateway heap: en openclaw gateway status; si indica not set, se deben volver a generar los metadatos antiguos del servicio con openclaw gateway install --force. La variable NODE_OPTIONS del entorno del shell se ignora intencionadamente. Solo se debe utilizar una configuración explícita del límite del montón en el supervisor después de confirmar la carga de trabajo sostenida y reservar suficiente margen para la memoria nativa.
• Memory pressure: critical/rss_growth → la memoria creció rápidamente dentro de un único intervalo de muestreo. Se deben revisar los registros más recientes para detectar una importación grande, una salida descontrolada de herramientas, reintentos repetidos o un lote de trabajo de agentes en cola.
• Aparece una presión crítica de memoria en los registros, pero no existe ningún paquete → se debe capturar openclaw gateway diagnostics export después del suceso para obtener las pruebas operativas disponibles.

El paquete de estabilidad no contiene cargas útiles. Incluye pruebas operativas sobre la memoria y rutas de archivos relativas censuradas, pero no texto de mensajes, cuerpos de Webhook, credenciales, tokens, cookies ni identificadores de sesión sin procesar. Se debe adjuntar la exportación de diagnósticos a los informes de errores en lugar de copiar los registros sin procesar.

Relacionado:

• Estado del Gateway
• Exportación de diagnósticos
• Sesiones

El Gateway rechazó una configuración no válida

Se utiliza cuando el inicio del Gateway falla con Invalid config o cuando los registros de recarga en caliente indican que se omitió una edición no válida.

openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctor

Qué buscar:

• Invalid config at ...
• config reload skipped (invalid config): ...
• Config write rejected: ...
• Un archivo openclaw.json.rejected.* con marca de tiempo junto a la configuración activa.
• Un archivo openclaw.json.clobbered.* con marca de tiempo si doctor --fix reparó una edición directa defectuosa.
• OpenClaw conserva los 32 archivos .clobbered.* más recientes de cada ruta de configuración y rota los más antiguos.

CONFIG="$(openclaw config file)"ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | headdiff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"openclaw config validateopenclaw doctor

Relacionado:

• Configuración
• Configuración: recarga en caliente
• Configuración: validación estricta
• Doctor

Advertencias de la sonda del Gateway

Úselo cuando openclaw gateway probe llegue a algún destino, pero siga mostrando un bloque de advertencias.

openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --ssh user@gateway-host

Busque:

• warnings[].code y primaryTargetId en la salida JSON.
• Si la advertencia trata sobre la alternativa mediante SSH, varios gateways, ámbitos ausentes o referencias de autenticación sin resolver.

Indicadores comunes:

• SSH tunnel failed to start; falling back to direct probes. → la configuración de SSH falló, pero el comando aun así intentó usar los destinos directos configurados o de bucle invertido.
• multiple reachable gateway identities detected → respondieron gateways distintos, o OpenClaw no pudo demostrar que los destinos accesibles fueran el mismo gateway. Un túnel SSH, una URL de proxy o una URL remota configurada hacia el mismo gateway se consideran un único gateway con varios transportes, aunque los puertos de transporte sean diferentes.
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → la conexión funcionó, pero el RPC de detalles está limitado por el ámbito; empareje la identidad del dispositivo o use credenciales con operator.read.
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → la conexión funcionó, pero el conjunto completo de RPC de diagnóstico agotó el tiempo de espera o falló. Considérelo un Gateway accesible con diagnósticos degradados; compare connect.ok y connect.rpcOk en la salida de --json.
• Capability: pairing-pending o gateway closed (1008): pairing required → el gateway respondió, pero este cliente aún necesita emparejamiento o aprobación antes del acceso normal del operador.
• Texto de advertencia de SecretRef sin resolver para gateway.auth.* / gateway.remote.* → el material de autenticación no estaba disponible en esta ruta de comandos para el destino fallido.

Relacionado:

• Gateway
• Varios gateways en el mismo host
• Acceso remoto

Canal conectado, pero los mensajes no circulan

Si el estado del canal es conectado pero el flujo de mensajes está interrumpido, céntrese en la política, los permisos y las reglas de entrega específicas del canal.

openclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw status --deepopenclaw logs --followopenclaw config get channels

Busque:

• Política de mensajes directos (pairing, allowlist, open, disabled).
• Lista de permitidos de grupos y requisitos de mención.
• Permisos o ámbitos de API del canal ausentes.

Indicadores comunes:

• mention required → la política de menciones del grupo ignoró el mensaje.
• pairing / rastros de aprobación pendiente → el remitente no está aprobado.
• missing_scope, not_in_channel, Forbidden, 401/403 → problema de autenticación o permisos del canal.

Relacionado:

• Solución de problemas de canales
• Discord
• Telegram
• WhatsApp

Entrega de Cron y Heartbeat

Si Cron o Heartbeat no se ejecutaron o no realizaron la entrega, verifique primero el estado del planificador y después el destino de entrega.

openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --follow

Busque:

• Cron habilitado y la siguiente activación presente.
• Estado del historial de ejecución del trabajo (ok, skipped, error).
• Motivos por los que se omitió Heartbeat (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file).

Relacionado:

• Heartbeat
• Tareas programadas
• Tareas programadas: solución de problemas

Node emparejado, pero la herramienta falla

Si un Node está emparejado pero las herramientas fallan, aísle el estado de primer plano, permisos y aprobaciones.

openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>openclaw logs --followopenclaw status

Busque:

• Node en línea con las capacidades esperadas.
• Concesiones de permisos del sistema operativo para cámara, micrófono, ubicación y pantalla.
• Aprobaciones de ejecución y estado de la lista de permitidos.

Indicadores comunes:

• NODE_BACKGROUND_UNAVAILABLE → la aplicación del Node debe estar en primer plano.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → falta un permiso del sistema operativo.
• SYSTEM_RUN_DENIED: approval required → aprobación de ejecución pendiente.
• SYSTEM_RUN_DENIED: allowlist miss → comando bloqueado por la lista de permitidos.

Relacionado:

• Aprobaciones de ejecución
• Solución de problemas de Node
• Nodes

La herramienta de navegador falla

Úselo cuando las acciones de la herramienta de navegador fallen aunque el gateway esté en buen estado.

openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor

Busque:

• Si plugins.allow está establecido e incluye browser.
• Ruta válida al ejecutable del navegador.
• Accesibilidad del perfil CDP.
• Disponibilidad local de Chrome para los perfiles existing-session / user.

Relacionado:

• Navegador (administrado por OpenClaw)
• Solución de problemas del navegador

Si actualizó y algo dejó de funcionar de repente

La mayoría de los fallos posteriores a una actualización se deben a desviaciones en la configuración o a que ahora se aplican valores predeterminados más estrictos.

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

openclaw devices listopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --followopenclaw doctor

Si la configuración del servicio y el entorno de ejecución siguen sin coincidir después de las comprobaciones, reinstale los metadatos del servicio desde el mismo perfil o directorio de estado:

openclaw gateway install --forceopenclaw gateway restart

Contenido relacionado:

• Autenticación
• Ejecución en segundo plano y herramienta de procesos
• Emparejamiento de nodos

Contenido relacionado

• Doctor
• Preguntas frecuentes
• Guía operativa del Gateway