Doctor

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

Inicio rápido

openclaw doctor

Modo headless / automatización

openclaw doctor --yes

Acepta valores por defecto sin preguntar (incluyendo pasos de reinicio/servicio/sandbox cuando aplique).

openclaw doctor --repair

Aplica reparaciones recomendadas sin preguntar (reparaciones + reinicios cuando es seguro).

openclaw doctor --repair --force

Aplica reparaciones agresivas también (sobrescribe configuraciones de supervisor personalizadas).

openclaw doctor --non-interactive

Ejecuta sin prompts y solo aplica migraciones seguras (normalización de configuración + movimientos de estado en disco). Omite acciones de reinicio/servicio/sandbox que requieren confirmación humana. Las migraciones de estado legacy se ejecutan automáticamente cuando se detectan.

openclaw doctor --deep

Escanea servicios del sistema en busca de instalaciones extra del gateway (launchd/systemd/schtasks).

Si quieres revisar los cambios antes de escribir, abre primero el archivo de configuración:

cat ~/.openclaw/openclaw.json

Qué hace (resumen)

Actualización pre-vuelo opcional para instalaciones git (solo interactivo).
Verificación de frescura del protocolo de UI (reconstruye el Control UI cuando el esquema del protocolo es más nuevo).
Verificación de salud + prompt de reinicio.
Resumen de estado de skills (elegibles/faltantes/bloqueadas).
Normalización de configuración para valores legacy.
Advertencias de sustitución de proveedor OpenCode (models.providers.opencode / models.providers.opencode-go).
Migración de estado legacy en disco (sesiones/directorio de agente/auth de WhatsApp).
Migración de almacén cron legacy (jobId, schedule.cron, campos de entrega/payload de nivel superior, payload provider, trabajos de respaldo webhook simples con notify: true).
Verificaciones de integridad de estado y permisos (sesiones, transcripciones, directorio de estado).
Verificaciones de permisos del archivo de configuración (chmod 600) cuando se ejecuta localmente.
Salud de autenticación de modelos: verifica expiración de OAuth, puede refrescar tokens que expiran, y reporta estados de enfriamiento/deshabilitación de perfiles de autenticación.
Detección de directorio de workspace extra (~/openclaw).
Reparación de imagen de sandbox cuando el sandboxing está habilitado.
Migración de servicio legacy y detección de gateway extra.
Verificaciones de runtime del Gateway (servicio instalado pero no ejecutándose; etiqueta launchd en caché).
Advertencias de estado de canales (probadas desde el gateway en ejecución).
Auditoría de configuración del supervisor (launchd/systemd/schtasks) con reparación opcional.
Verificaciones de mejores prácticas del runtime del Gateway (Node vs Bun, rutas de gestores de versiones).
Diagnósticos de colisión de puerto del Gateway (por defecto 18789).
Advertencias de seguridad para políticas de DM abiertas.
Verificaciones de autenticación del Gateway para modo de token local (ofrece generación de token cuando no existe fuente de token; no sobrescribe configuraciones de token SecretRef).
Verificación de linger de systemd en Linux.
Verificaciones de instalación desde fuente (desajuste de workspace pnpm, assets de UI faltantes, binario tsx faltante).
Escribe configuración actualizada + metadatos del asistente.

Comportamiento detallado y justificación

0) Actualización opcional (instalaciones git)

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

1) Normalización de configuración

Si la configuración contiene formas de valores legacy (por ejemplo messages.ackReaction sin una sustitución específica del canal), doctor los normaliza en el esquema actual.

2) Migraciones de claves de configuración legacy

Cuando la configuración contiene claves obsoletas, otros comandos se niegan a ejecutar y piden que ejecutes openclaw doctor.

Doctor:

Explica qué claves legacy se encontraron.
Muestra la migración que aplicó.
Reescribe ~/.openclaw/openclaw.json con el esquema actualizado.

El Gateway también auto-ejecuta migraciones de doctor al inicio cuando detecta un formato de configuración legacy, para que las configuraciones obsoletas se reparen sin intervención manual.

Migraciones actuales:

routing.allowFrom → channels.whatsapp.allowFrom
routing.groupChat.requireMention → channels.whatsapp/telegram/imessage.groups."*".requireMention
routing.groupChat.historyLimit → messages.groupChat.historyLimit
routing.groupChat.mentionPatterns → messages.groupChat.mentionPatterns
routing.queue → messages.queue
routing.bindings → bindings de nivel superior
routing.agents/routing.defaultAgentId → agents.list + agents.list[].default
routing.agentToAgent → tools.agentToAgent
routing.transcribeAudio → tools.media.audio.models
bindings[].match.accountID → bindings[].match.accountId
Para canales con accounts nombradas pero sin accounts.default, mover valores de canal de cuenta única de nivel superior con alcance de cuenta a channels.<channel>.accounts.default cuando estén presentes
identity → agents.list[].identity
agent.* → agents.defaults + tools.* (tools/elevated/exec/sandbox/subagents)
agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks → agents.defaults.models + agents.defaults.model.primary/fallbacks + agents.defaults.imageModel.primary/fallbacks
browser.ssrfPolicy.allowPrivateNetwork → browser.ssrfPolicy.dangerouslyAllowPrivateNetwork

Las advertencias de doctor también incluyen orientación de cuenta por defecto para canales multi-cuenta:

Si se configuran dos o más entradas channels.<channel>.accounts sin channels.<channel>.defaultAccount o accounts.default, doctor advierte que el enrutamiento de respaldo puede elegir una cuenta inesperada.
Si channels.<channel>.defaultAccount está configurado con un ID de cuenta desconocido, doctor advierte y lista los IDs de cuenta configurados.

2b) Sustituciones de proveedor OpenCode

Si agregaste models.providers.opencode, opencode-zen u opencode-go manualmente, sobrescribe el catálogo OpenCode integrado de @mariozechner/pi-ai. Eso puede forzar modelos a la API incorrecta o poner costos en cero. Doctor advierte para que puedas eliminar la sustitución y restaurar el enrutamiento de API + costos por modelo.

3) Migraciones de estado legacy (estructura de disco)

Doctor puede migrar estructuras de disco antiguas a la estructura actual:

Almacén de sesiones + transcripciones:
- de ~/.openclaw/sessions/ a ~/.openclaw/agents/<agentId>/sessions/
Directorio de agente:
- de ~/.openclaw/agent/ a ~/.openclaw/agents/<agentId>/agent/
Estado de autenticación de WhatsApp (Baileys):
- de ~/.openclaw/credentials/*.json legacy (excepto oauth.json)
- a ~/.openclaw/credentials/whatsapp/<accountId>/... (id de cuenta por defecto: default)

Estas migraciones son de mejor esfuerzo e idempotentes; doctor emitirá advertencias cuando deje carpetas legacy como respaldos. El Gateway/CLI también auto-migra las sesiones legacy + directorio de agente al inicio para que el historial/auth/modelos lleguen a la ruta por agente sin una ejecución manual de doctor. La autenticación de WhatsApp se migra intencionalmente solo vía openclaw doctor.

3b) Migraciones del almacén cron legacy

Doctor también verifica el almacén de trabajos cron (~/.openclaw/cron/jobs.json por defecto, o cron.store cuando se sobrescribe) en busca de formas de trabajo antiguas que el scheduler aún acepta por compatibilidad.

Las limpiezas cron actuales incluyen:

jobId → id
schedule.cron → schedule.expr
campos de payload de nivel superior (message, model, thinking, …) → payload
campos de entrega de nivel superior (deliver, channel, to, provider, …) → delivery
alias de entrega de payload provider → delivery.channel explícito
trabajos de respaldo webhook simples legacy notify: true → delivery.mode="webhook" explícito con delivery.to=cron.webhook

Doctor solo auto-migra trabajos notify: true cuando puede hacerlo sin cambiar el comportamiento. Si un trabajo combina respaldo notify legacy con un modo de entrega no webhook existente, doctor advierte y deja ese trabajo para revisión manual.

4) Verificaciones de integridad de estado (persistencia de sesión, enrutamiento y seguridad)

El directorio de estado es el tronco operativo. Si desaparece, pierdes sesiones, credenciales, logs y configuración (a menos que tengas respaldos en otro lugar).

Doctor verifica:

Directorio de estado faltante: advierte sobre pérdida catastrófica de estado, solicita recrear el directorio, y recuerda que no puede recuperar datos faltantes.
Permisos del directorio de estado: verifica que sea escribible; ofrece reparar permisos (y emite una indicación chown cuando se detecta desajuste de propietario/grupo).
Directorio de estado en nube macOS: advierte cuando el estado resuelve bajo iCloud Drive (~/Library/Mobile Documents/com~apple~CloudDocs/...) o ~/Library/CloudStorage/... porque las rutas respaldadas por sincronización pueden causar I/O más lento y conflictos de bloqueo/sincronización.
Directorio de estado en SD o eMMC Linux: advierte cuando el estado resuelve a una fuente de montaje mmcblk*, porque I/O aleatorio en SD o eMMC puede ser más lento y desgastarse más rápido bajo escrituras de sesión y credenciales.
Directorios de sesión faltantes: sessions/ y el directorio del almacén de sesiones son necesarios para persistir historial y evitar crashes ENOENT.
Desajuste de transcripciones: advierte cuando entradas de sesión recientes tienen archivos de transcripción faltantes.
Sesión principal “JSONL de 1 línea”: señala cuando la transcripción principal tiene solo una línea (el historial no se está acumulando).
Múltiples directorios de estado: advierte cuando existen múltiples carpetas ~/.openclaw entre directorios home o cuando OPENCLAW_STATE_DIR apunta a otro lugar (el historial puede dividirse entre instalaciones).
Recordatorio de modo remoto: si gateway.mode=remote, doctor recuerda ejecutarlo en el host remoto (el estado vive allí).
Permisos del archivo de configuración: advierte si ~/.openclaw/openclaw.json es legible por grupo/todos y ofrece restringir a 600.

5) Salud de autenticación de modelos (expiración OAuth)

Doctor inspecciona perfiles OAuth en el almacén de autenticación, advierte cuando los tokens están por expirar/expirados, y puede refrescarlos cuando es seguro. Si el perfil de Claude Code de Anthropic está obsoleto, sugiere ejecutar claude setup-token (o pegar un setup-token). Los prompts de refresco solo aparecen cuando se ejecuta interactivamente (TTY); --non-interactive omite intentos de refresco.

Doctor también reporta perfiles de autenticación que están temporalmente inutilizables debido a:

enfriamientos cortos (límites de tasa/timeouts/fallos de autenticación)
deshabilitaciones más largas (fallos de facturación/crédito)

6) Validación de modelo de Hooks

Si hooks.gmail.model está configurado, doctor valida la referencia del modelo contra el catálogo y la lista de permitidos y advierte cuando no resolverá o está prohibido.

7) Reparación de imagen de sandbox

Cuando el sandboxing está habilitado, doctor verifica las imágenes Docker y ofrece construir o cambiar a nombres legacy si la imagen actual falta.

8) Migraciones de servicio Gateway y consejos de limpieza

Doctor detecta servicios gateway legacy (launchd/systemd/schtasks) y ofrece eliminarlos e instalar el servicio OpenClaw usando el puerto de gateway actual. También puede escanear servicios extra tipo gateway e imprimir consejos de limpieza. Los servicios gateway OpenClaw nombrados por perfil se consideran de primera clase y no se señalan como “extra”.

9) Advertencias de seguridad

Doctor emite advertencias cuando un proveedor está abierto a DMs sin lista de permitidos, o cuando una política está configurada de forma peligrosa.

10) Linger de systemd (Linux)

Si se ejecuta como servicio de usuario systemd, doctor asegura que el lingering esté habilitado para que el gateway se mantenga activo después de cerrar sesión.

11) Estado de skills

Doctor imprime un resumen rápido de skills elegibles/faltantes/bloqueadas para el workspace actual.

12) Verificaciones de autenticación del Gateway (token local)

Doctor verifica la preparación de autenticación por token local del gateway.

Si el modo token necesita un token y no existe fuente de token, doctor ofrece generar uno.
Si gateway.auth.token está gestionado por SecretRef pero no disponible, doctor advierte y no lo sobrescribe con texto plano.
openclaw doctor --generate-gateway-token fuerza la generación solo cuando no hay SecretRef de token configurado.

12b) Reparaciones conscientes de SecretRef de solo lectura

Algunos flujos de reparación necesitan inspeccionar credenciales configuradas sin debilitar el comportamiento fail-fast del runtime.

openclaw doctor --fix ahora usa el mismo modelo de resumen de SecretRef de solo lectura que los comandos de la familia status para reparaciones de configuración específicas.
Ejemplo: la reparación de allowFrom / groupAllowFrom de Telegram con @username intenta usar credenciales de bot configuradas cuando están disponibles.
Si el token del bot de Telegram está configurado vía SecretRef pero no disponible en la ruta del comando actual, doctor reporta que la credencial está configurada-pero-no-disponible y omite la auto-resolución en lugar de crashear o reportar incorrectamente el token como faltante.

13) Verificación de salud del Gateway + reinicio

Doctor ejecuta una verificación de salud y ofrece reiniciar el gateway cuando parece no saludable.

14) Advertencias de estado de canales

Si el gateway está saludable, doctor ejecuta una prueba de estado de canales y reporta advertencias con correcciones sugeridas.

15) Auditoría de configuración del supervisor + reparación

Doctor verifica la configuración instalada del supervisor (launchd/systemd/schtasks) para valores por defecto faltantes u obsoletos (por ejemplo, dependencias de network-online de systemd y retraso de reinicio). Cuando encuentra un desajuste, recomienda una actualización y puede reescribir el archivo/tarea del servicio a los valores por defecto actuales.

Notas:

openclaw doctor pregunta antes de reescribir la configuración del supervisor.
openclaw doctor --yes acepta los prompts de reparación por defecto.
openclaw doctor --repair aplica correcciones recomendadas sin prompts.
openclaw doctor --repair --force sobrescribe configuraciones de supervisor personalizadas.
Si la autenticación por token requiere un token y gateway.auth.token está gestionado por SecretRef, la instalación/reparación del servicio de doctor valida el SecretRef pero no persiste valores de token resueltos en texto plano en los metadatos de entorno del servicio supervisor.
Si la autenticación por token requiere un token y el SecretRef de token configurado no está resuelto, doctor bloquea la ruta de instalación/reparación con orientación accionable.
Si tanto gateway.auth.token como gateway.auth.password están configurados y gateway.auth.mode no está establecido, doctor bloquea la instalación/reparación hasta que el modo se establezca explícitamente.
Para unidades user-systemd de Linux, las verificaciones de deriva de token de doctor ahora incluyen fuentes Environment= y EnvironmentFile= al comparar metadatos de autenticación del servicio.
Siempre puedes forzar una reescritura completa vía openclaw gateway install --force.

16) Runtime del Gateway + diagnósticos de puerto

Doctor inspecciona el runtime del servicio (PID, último estado de salida) y advierte cuando el servicio está instalado pero no se está ejecutando realmente. También verifica colisiones de puerto en el puerto del gateway (por defecto 18789) y reporta causas probables (gateway ya ejecutándose, túnel SSH).

17) Mejores prácticas del runtime del Gateway

Doctor advierte cuando el servicio gateway se ejecuta en Bun o una ruta Node gestionada por versiones (nvm, fnm, volta, asdf, etc.). Los canales WhatsApp + Telegram requieren Node, y las rutas de gestores de versiones pueden romperse después de actualizaciones porque el servicio no carga tu inicialización de shell. Doctor ofrece migrar a una instalación de Node del sistema cuando esté disponible (Homebrew/apt/choco).

18) Escritura de configuración + metadatos del asistente

Doctor persiste cualquier cambio de configuración y estampa metadatos del asistente para registrar la ejecución de doctor.

19) Consejos de workspace (respaldo + sistema de memoria)

Doctor sugiere un sistema de memoria del workspace cuando falta e imprime un consejo de respaldo si el workspace no está ya bajo git.

Consulta /concepts/agent-workspace para una guía completa sobre estructura del workspace y respaldo git (se recomienda GitHub o GitLab privado).