Doctor (Diagnósticos)

''openclaw doctor'' es la herramienta de reparación + migración de OpenClaw. Corrige configuración/estado obsoleto, verifica salud, y proporciona pasos de reparación accionables.

openclaw doctor

#

openclaw doctor --yes

Acepta predeterminados sin preguntar (incluyendo pasos de reparación restart/service/sandbox si aplican).

openclaw doctor --repair

Aplica reparaciones recomendadas sin preguntar (reparación + reinicio si es seguro).

openclaw doctor --repair --force

También aplica reparaciones agresivas (sobrescribe configuraciones de supervisor personalizadas).

openclaw doctor --non-interactive

Ejecuta sin preguntar, solo aplica migraciones seguras (normalización de config + movimientos de estado en disco). Omite operaciones restart/service/sandbox que requieren confirmación humana. Se ejecuta automáticamente cuando se detecta migración de estado legado.

openclaw doctor --deep

Escanea servicios del sistema para instalaciones gateway adicionales (launchd/systemd/schtasks).

Si quieres ver cambios antes de escribir, abre el archivo de config primero:

cat ~/.openclaw/openclaw.json

- Actualización opcional pre-ejecución para instalaciones git (solo interactivo).

- Verificación de frescura del protocolo UI (reconstruye UI de control cuando el esquema de protocolo es más nuevo).

- Verificación de salud + prompt de reinicio.

- Resumen de estado de habilidades (elegibles/faltantes/bloqueadas).

- Normalización de configuración de valores legados.

- Advertencia de override de proveedor OpenCode Zen ('<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'models.providers.opencode'</code>').

- Migración de estado de disco legado (sesiones/directorios de agente/auth de WhatsApp).

- Verificaciones de integridad de estado y permisos (sesiones, transcripciones, directorios de estado).

- Verificación de permisos de archivo de config de runtime local (chmod 600).

- Salud de auth de modelo: verifica expiraciones OAuth, puede refrescar tokens expirados, y reporta estado de cooldown/deshabilitado de perfiles de auth.

- Detección de directorio de espacio de trabajo extra ('<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/openclaw'</code>').

- Reparación de imagen de sandbox cuando sandbox está habilitado.

- Migración de servicio legado y detección de gateway extra.

- Verificación de runtime de Gateway (servicio instalado pero no ejecutándose; etiquetas launchd cacheadas).

- Advertencias de estado de canal (sondeadas desde gateway en ejecución).

- Auditoría de config de supervisor (launchd/systemd/schtasks) y reparación opcional.

- Verificación de mejores prácticas de runtime de Gateway (Node vs Bun, rutas de gestor de versiones).

- Diagnósticos de conflicto de puerto de Gateway (predeterminado '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'18789'</code>').

- Advertencia de seguridad para política DM abierta.

- Advertencia de auth de Gateway cuando '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'gateway.auth.token'</code>' no está establecido (modo local; ofrece generación de token).

- Verificación de systemd linger en Linux.

- Verificaciones de instalación desde fuente (mismatch de workspace pnpm, assets UI faltantes, binario tsx faltante).

- Escribe config actualizada + metadatos de wizard.

#

Si es un checkout git y doctor se ejecuta interactivamente, ofrece actualizar (fetch/rebase/build) antes de ejecutar doctor.

#

El modo "Remote via SSH" de la app macOS usa local port forwarding, así que el gateway remoto es accesible en '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'ws://127.0.0.1:&lt;port&gt;'</code>' (puede solo vincularse a loopback).

Equivalente CLI:

Opciones:

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'--ssh &lt;target&gt;'</code>': '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'user@host'</code>' o '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'user@host:port'</code>' (puerto predeterminado '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'22'</code>').

Ayudante RPC de bajo nivel.

ReferenceGatewayDoctorPage.step07.p2

ReferenceGatewayDoctorPage.step07.p3

ReferenceGatewayDoctorPage.step07.p4

ReferenceGatewayDoctorPage.step07.p5

ReferenceGatewayDoctorPage.step07.p6

ReferenceGatewayDoctorPage.step07.p7

ReferenceGatewayDoctorPage.step07.migration1

ReferenceGatewayDoctorPage.step07.migration2

ReferenceGatewayDoctorPage.step07.migration3

ReferenceGatewayDoctorPage.step07.migration4

ReferenceGatewayDoctorPage.step07.migration5

ReferenceGatewayDoctorPage.step07.migration6

ReferenceGatewayDoctorPage.step07.migration7

ReferenceGatewayDoctorPage.step07.migration8

ReferenceGatewayDoctorPage.step07.migration9

ReferenceGatewayDoctorPage.step07.migration10

ReferenceGatewayDoctorPage.step07.migration11

ReferenceGatewayDoctorPage.step07.migration12

ReferenceGatewayDoctorPage.step07.migration13

ReferenceGatewayDoctorPage.step07.p8

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'gateway install'</code>' soporta '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'--port'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'--runtime'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'--token'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'--force'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'--json'</code>'.

- Los comandos de ciclo de vida aceptan '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'--json'</code>' para scripting.

'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'gateway discover'</code>' escanea por beacons de gateway ('<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'_openclaw-gw._tcp'</code>').

- Multicast DNS-SD: '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'local.'</code>'

- Unicast DNS-SD (Wide-Area Bonjour): Elige un dominio (ej., '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw.internal.'</code>') y establece split DNS + servidor DNS; ver '<a href="/gateway/bonjour" className="text-emerald-400 hover:text-emerald-300 transition-colors">'/gateway/bonjour'</a>'

Solo gateways con Bonjour discovery habilitado (predeterminado) anuncian beacons.

Los registros de wide-area discovery incluyen (TXT):

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'role'</code>' (pista de rol de gateway)

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'transport'</code>' (pista de transporte, ej., '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'gateway'</code>')

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'gatewayPort'</code>' (puerto WebSocket, típicamente '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'18789'</code>')

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'sshPort'</code>' (puerto SSH; predeterminado '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'22'</code>' si ausente)

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'tailnetDns'</code>' (hostname MagicDNS, si disponible)

El directorio de estado es el tronco cerebral de las operaciones. Si desaparece, sesiones, credenciales, logs, y config se pierden (a menos que estén respaldados en otro lugar).

Doctor verifica:

- <strong>Directorio de estado faltante</strong>: advierte sobre pérdida catastrófica de estado, prompt para recrear directorio, recuerda que datos perdidos no pueden recuperarse.

- '<strong>'Permisos de directorio de estado'</strong>': verifica escribible, ofrece arreglar permisos (produce prompt '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'chown'</code>' si se detecta mismatch de propietario/grupo).

- '<strong>'Directorio de sesiones faltante'</strong>': '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'sessions/'</code>' y directorios de almacenamiento de sesiones contienen historial y se necesitan para evitar crashes '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'ENOENT'</code>'.

- <strong>Mismatches de transcripciones</strong>: advierte cuando entradas de sesión recientes carecen de archivos de transcripción.

- <strong>Sesión maestra "JSONL de 1 línea"</strong>: marca cuando el registro maestro tiene solo una línea (historial no acumulando).

- '<strong>'Múltiples directorios de estado'</strong>': advierte cuando múltiples carpetas '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw'</code>' existen en directorio primario, o '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'OPENCLAW_STATE_DIR'</code>' apunta a otro lugar (historial puede estar dividido entre instalaciones).

- '<strong>'Recordatorio de modo remoto'</strong>': si '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'gateway.mode=remote'</code>', doctor recuerda ejecutar en host remoto (el estado está allí).

- '<strong>'Permisos de archivo de config'</strong>': si '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/openclaw.json'</code>' existe y es legible por grupo/mundo, ofrece ajustar a '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'600'</code>'.

#

Doctor verifica perfiles OAuth en el almacén de auth, advierte cuando tokens están cerca/pasados de expiración, y puede refrescarlos cuando es seguro. Si el perfil de contraseña de Anthropic Claude está obsoleto, sugiere ejecutar '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'claude setup-token'</code>' (o pegar un token de configuración). Los prompts de refresco solo aparecen cuando se ejecuta interactivamente (TTY). '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'--non-interactive'</code>' omite intentos de refresco.

Doctor también reporta perfiles de auth que están temporalmente no disponibles debido a:

- Cooldown corto (fallo de límite de tasa/timeout/auth)

- Período largo deshabilitado (fallo de facturación/crédito)

#

Si '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'hooks.gmail.model'</code>' está establecido, doctor valida la referencia del modelo contra el catálogo de modelos y whitelist, advirtiendo si no puede resolverse o no está permitido.

#

Si sandbox está habilitado, doctor verifica la imagen Docker y ofrece construir o cambiar al nombre de imagen actual si no hay ninguna presente.

#

Doctor detecta servicios gateway legados (launchd/systemd/schtasks) y ofrece eliminarlos e instalar un servicio OpenClaw en el puerto gateway actual. También puede escanear servicios adicionales tipo gateway e imprimir prompts de limpieza. Servicios gateway OpenClaw nombrados en config se consideran first-class y no se marcan como "adicionales".

#

Doctor advierte si proveedores están abiertos a DMs sin una lista permitida, o si políticas están configuradas peligrosamente.

#

Si se ejecuta como servicio de usuario systemd, doctor verifica que linger está habilitado para que el gateway permanezca activo después de logout.

#

Doctor imprime un breve resumen de habilidades elegibles/faltantes/bloqueadas actuales en el espacio de trabajo.

#

Si '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'gateway.auth'</code>' falta en un gateway local, doctor advierte y ofrece generar un token. Usa '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor --generate-gateway-token'</code>' para forzar creación de token para automatización.

#

Doctor ejecuta una verificación de salud y si no está saludable, ofrece reiniciar el gateway después de las verificaciones.

#

Si el gateway está saludable, doctor ejecuta sondeos de estado de canal y reporta advertencias con correcciones sugeridas.

#

Doctor verifica configs de supervisor instalados (launchd/systemd/schtasks) para predeterminados faltantes o obsoletos (ej. dependencias network-online de systemd y delays de reinicio). Si encuentra mismatches, ofrece actualizar y puede reescribir archivos de servicio/tareas a predeterminados actuales.

Notas:

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor'</code>' pregunta antes de reescribir configs de supervisor.

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor --yes'</code>' acepta prompts de reparación predeterminados.

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor --repair'</code>' aplica reparaciones recomendadas sin preguntar.

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor --repair --force'</code>' sobrescribe configs de supervisor personalizados.

- Siempre puedes forzar una reescritura completa via '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw gateway install --force'</code>'.

#

Doctor verifica runtime de servicio (PID, último estado de salida) y advierte si el servicio está instalado pero no está realmente ejecutándose. También verifica conflictos de puerto en el puerto gateway (predeterminado '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'18789'</code>'), reportando posibles causas (gateway ya ejecutándose, túnel SSH).

#

Si el servicio de gateway se está ejecutando con Bun o una ruta de Node versionada, doctor advierte ('<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'nvm'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'fnm'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'volta'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'asdf'</code>', etc.). Los canales WhatsApp + Telegram requieren Node, y las rutas de gestores de versiones pueden romperse después de actualizaciones ya que los servicios no cargan inicialización de shell. Doctor ofrece migrar a una instalación de Node de sistema si está disponible (Homebrew/apt/choco).

#

Doctor persiste cambios de config y marca metadatos de wizard para registrar que doctor se ejecutó.

#

Doctor sugiere usar el sistema de memoria del espacio de trabajo si estás perdido, e imprime un prompt de backup si el espacio de trabajo no está ya bajo git.

Ver '<a href="/concepts/agent-workspace" className="text-emerald-400 hover:text-emerald-300 transition-colors">'/concepts/agent-workspace'</a>' para una guía completa sobre estructura de espacio de trabajo y backups git (GitHub privado o GitLab recomendado).