Solución general de problemas

Solución de problemas

Si solo tiene 2 minutos, use esta página como puerta de entrada de triaje.

Primeros 60 segundos

Ejecute esta siguiente escalera exacta en orden:

openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow

Buena salida en una línea:

openclaw status → muestra los canales configurados y no hay errores de autenticación obvios.
openclaw status --all → el informe completo está presente y se puede compartir.
openclaw gateway probe → el objetivo de puerta de enlace esperado es alcanzable (Reachable: yes). RPC: limited - missing scope: operator.read son diagnósticos degradados, no un fallo de conexión.
openclaw gateway status → Runtime: running y RPC probe: ok.
openclaw doctor → sin errores de configuración/servicio que bloqueen.
openclaw channels status --probe → los canales reportan connected o ready.
openclaw logs --follow → actividad constante, sin errores fatales repetitivos.

Contexto largo de Anthropic 429

Si ves: HTTP 429: rate_limit_error: Extra usage is required for long context requests, ve a /gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context.

La instalación del complemento falla con extensiones de openclaw faltantes

Si la instalación falla con package.json missing openclaw.extensions, el paquete del complemento está usando una forma antigua que OpenClaw ya no acepta.

Solución en el paquete del complemento:

Añade openclaw.extensions a package.json.
Apunta las entradas a los archivos de tiempo de ejecución compilados (generalmente ./dist/index.js).
Republica el complemento y ejecuta openclaw plugins install <package> de nuevo.

Ejemplo:

{
  "name": "@openclaw/my-plugin",
  "version": "1.2.3",
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}

Referencia: Arquitectura del complemento

Árbol de decisiones

flowchart TD
  A[OpenClaw is not working] --> B{What breaks first}
  B --> C[No replies]
  B --> D[Dashboard or Control UI will not connect]
  B --> E[Gateway will not start or service not running]
  B --> F[Channel connects but messages do not flow]
  B --> G[Cron or heartbeat did not fire or did not deliver]
  B --> H[Node is paired but camera canvas screen exec fails]
  B --> I[Browser tool fails]

  C --> C1[/No replies section/]
  D --> D1[/Control UI section/]
  E --> E1[/Gateway section/]
  F --> F1[/Channel flow section/]
  G --> G1[/Automation section/]
  H --> H1[/Node tools section/]
  I --> I1[/Browser section/]

Sin respuestas

openclaw status
openclaw gateway status
openclaw channels status --probe
openclaw pairing list --channel

[—account

] openclaw logs —follow ```

El resultado correcto se ve así:

- `Runtime: running`
- `RPC probe: ok`
- Tu canal muestra conectado/listo en `channels status --probe`
- El remitente aparece aprobado (o la política de MD está abierta/en lista de permitidos)

Firmas de registro comunes:

- `drop guild message (mention required` → el bloqueo de mención bloqueó el mensaje en Discord.
- `pairing request` → el remitente no está aprobado y está esperando la aprobación de emparejamiento por DM.
- `blocked` / `allowlist` en los registros del canal → el remitente, la sala o el grupo está filtrado.

Páginas profundas:

- [/gateway/troubleshooting#no-replies](/en/gateway/troubleshooting#no-replies)
- [/channels/troubleshooting](/en/channels/troubleshooting)
- [/channels/pairing](/en/channels/pairing)

El Panel de Control o la Interfaz de Control no se conectan

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

El resultado correcto se ve así:

Dashboard: http://... se muestra en openclaw gateway status
RPC probe: ok
Sin bucle de autenticación en los registros

Firmas de registro comunes:

device identity required → el contexto HTTP/no seguro no puede completar la autenticación del dispositivo.
AUTH_TOKEN_MISMATCH con sugerencias de reintento (canRetryWithDeviceToken=true) → puede producirse automáticamente un reintento de token de dispositivo de confianza.
unauthorized repetido después de ese reintento → token/contraseña incorrecta, discrepancia del modo de autenticación o token de dispositivo emparejado obsoleto.
gateway connect failed: → la Interfaz de Control está apuntando a la URL/puerto incorrecto o a una puerta de enlace inalcanzable.

Páginas profundas:

La puerta de enlace no se inicia o el servicio está instalado pero no se está ejecutando

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

El resultado correcto se ve así:

Service: ... (loaded)
Runtime: running
RPC probe: ok

Firmas de registro comunes:

Gateway start blocked: set gateway.mode=local → el modo de puerta de enlace no está establecido/es remoto.
refusing to bind gateway ... without auth → enlace que no es de bucle invertido sin token/contraseña.
another gateway instance is already listening o EADDRINUSE → puerto ya ocupado.

Páginas profundas:

El canal se conecta pero los mensajes no fluyen

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

El resultado correcto se ve así:

El transporte del canal está conectado.
Las verificaciones de emparejamiento/lista blanca pasan.
Las menciones se detectan donde se requieren.

Firmas de registro comunes:

mention required → el filtrado de menciones de grupo bloqueó el procesamiento.
pairing / pending → el remitente del MD aún no está aprobado.
not_in_channel, missing_scope, Forbidden, 401/403 → problema con el token de permisos del canal.

Páginas profundas:

Cron o latido no se disparó o no se entregó

openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id

—limit 20 openclaw logs —follow

Una buena salida se ve así:

- `cron.status` muestra habilitado con un próximo despertar.
- `cron runs` muestra entradas `ok` recientes.
- El latido está habilitado y no está fuera del horario activo.

Firmas de registro comunes:

- `cron: scheduler disabled; jobs will not run automatically` → cron está deshabilitado.
- `heartbeat skipped` con `reason=quiet-hours` → fuera del horario activo configurado.
- `requests-in-flight` → carril principal ocupado; el despertar del latido se aplazó.
- `unknown accountId` → la cuenta de destino de entrega del latido no existe.

Páginas profundas:

- [/gateway/troubleshooting#cron-and-heartbeat-delivery](/en/gateway/troubleshooting#cron-and-heartbeat-delivery)
- [/automation/troubleshooting](/en/automation/troubleshooting)
- [/gateway/heartbeat](/en/gateway/heartbeat)

El nodo está emparejado pero la herramienta falla cámara lienzo pantalla exec

openclaw status
openclaw gateway status
openclaw nodes status
openclaw nodes describe --node

openclaw logs —follow

Una buena salida se ve así:

- El nodo figura como conectado y emparejado para el rol `node`.
- Existe la capacidad para el comando que estás invocando.
- El estado de permiso está concedido para la herramienta.

Firmas de registro comunes:

- `NODE_BACKGROUND_UNAVAILABLE` → traer la aplicación del nodo al primer plano.
- `*_PERMISSION_REQUIRED` → el permiso del sistema operativo fue denegado o falta.
- `SYSTEM_RUN_DENIED: approval required` → la aprobación de ejecución está pendiente.
- `SYSTEM_RUN_DENIED: allowlist miss` → comando no en la lista de permitidos de ejecución.

Páginas profundas:

- [/gateway/troubleshooting#node-paired-tool-fails](/en/gateway/troubleshooting#node-paired-tool-fails)
- [/nodes/troubleshooting](/en/nodes/troubleshooting)
- [/tools/exec-approvals](/en/tools/exec-approvals)

Exec de repente solicita aprobación

openclaw config get tools.exec.host
openclaw config get tools.exec.security
openclaw config get tools.exec.ask
openclaw gateway restart

Lo que cambió:

Si tools.exec.host no está establecido, el valor predeterminado es auto.
host=auto se resuelve en sandbox cuando un entorno de ejecución de sandbox está activo, gateway en caso contrario.
En gateway y node, el valor no establecido de tools.exec.security es allowlist de forma predeterminada.
El valor no establecido de tools.exec.ask es on-miss de forma predeterminada.
Resultado: los comandos ordinarios del host ahora pueden pausarse con Approval required en lugar de ejecutarse inmediatamente.

Restaurar el comportamiento antiguo de pasarela sin aprobación:

openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
openclaw gateway restart

Alternativas más seguras:

Establezca solo tools.exec.host=gateway si solo desea un enrutamiento estable del host y aún desea aprobaciones.
Mantenga security=allowlist con ask=on-miss si desea exec del host pero aún desea revisiones por errores en la lista de permitidos.
Habilite el modo sandbox si desea que host=auto se resuelva nuevamente a sandbox.

Firmas de registro comunes:

Approval required. → el comando está esperando en /approve ....
SYSTEM_RUN_DENIED: approval required → la aprobación de exec del nodo-host está pendiente.
exec host=sandbox requires a sandbox runtime for this session → selección de sandbox implícita/explícita pero el modo sandbox está desactivado.

Páginas en profundidad:

Herramienta del navegador falla

openclaw status
openclaw gateway status
openclaw browser status
openclaw logs --follow
openclaw doctor

El resultado correcto se ve así:

El estado del navegador muestra running: true y un navegador/perfil elegido.
openclaw se inicia, o user puede ver las pestañas locales de Chrome.

Firmas de registro comunes:

unknown command "browser" o unknown command 'browser' → plugins.allow está configurado y no incluye browser.
Failed to start Chrome CDP on port → falló el inicio del navegador local.
browser.executablePath not found → la ruta binaria configurada es incorrecta.
No Chrome tabs found for profile="user" → el perfil de conexión de Chrome MCP no tiene pestañas locales de Chrome abiertas.
Browser attachOnly is enabled ... not reachable → el perfil de solo conexión no tiene un objetivo CDP activo.

Páginas en profundidad:

Relacionado

Preguntas frecuentes — preguntas frecuentes
Solución de problemas de la puerta de enlace — problemas específicos de la puerta de enlace
Doctor — comprobaciones y reparaciones automatizadas del estado de salud
Solución de problemas de canal — problemas de conectividad del canal
Solución de problemas de automatización — problemas de cron y latidos