Repara OpenClaw: Diagnóstico y optimización en segundos

Descripción general de Doctor

La herramienta Doctor es el asistente esencial de OpenClaw diseñado para diagnosticar y solucionar problemas comunes en tu entorno. Esta utilidad se encarga de reparar configuraciones obsoletas, verificar el estado de salud de tu Gateway y ofrecerte pasos claros para corregir cualquier inconsistencia en tu API.

1. Ejecuta el comando openclaw doctor en tu terminal para iniciar el análisis automático de tu configuración actual.
2. La herramienta escaneará tus archivos de estado y comparará la versión instalada de Node.js con los requisitos mínimos del sistema.
3. Si se detecta algún problema, el CLI te mostrará un informe detallado con las acciones recomendadas para restaurar el funcionamiento correcto.

openclaw doctor

Verificación de salud del sistema

Esta sección se enfoca en asegurar que todos los componentes críticos de tu infraestructura estén operativos y bien configurados. Al ejecutar este proceso, OpenClaw valida la conectividad con tu Gateway y confirma que los permisos de los archivos sean los adecuados para evitar errores de ejecución.

1. Utiliza el comando con el flag de verificación para realizar un chequeo profundo de los servicios activos.
2. El sistema validará que tu JSON de configuración esté correctamente estructurado y no contenga valores nulos en campos obligatorios.
3. Si el diagnóstico encuentra una discrepancia, el sistema te sugerirá ejecutar un comando de reparación específico.

openclaw doctor --check

Migración y reparación automática

Cuando detectas que tu entorno de OpenClaw ha quedado desactualizado tras una actualización de npm o pnpm, esta función es tu mejor aliada. El proceso de reparación ajusta automáticamente los esquemas de datos y sincroniza los cambios necesarios para que tu webhook siga funcionando sin interrupciones.

1. Para aplicar las correcciones automáticamente, utiliza el flag de reparación junto al comando principal.
2. El CLI realizará una copia de seguridad de tus archivos actuales antes de aplicar cualquier cambio estructural.
3. Una vez completado, el sistema te notificará si es necesario reiniciar los servicios de Docker para aplicar las nuevas configuraciones.

openclaw doctor --fix

Diagnóstico de conectividad

Si experimentas problemas al conectar tu API con servicios externos, esta herramienta te ayuda a identificar bloqueos en la red o configuraciones erróneas en el Gateway. Es la forma más rápida de descartar fallos de red antes de revisar el código fuente en GitHub.

1. Ejecuta el comando de diagnóstico para probar la latencia y la respuesta de los endpoints configurados.
2. La herramienta intentará realizar una petición de prueba para verificar que el webhook esté recibiendo y enviando datos correctamente.
3. Revisa el resumen final en la consola para ver si el problema reside en tu red local o en la configuración del servicio remoto.

openclaw doctor --network

AI Setup Assistant

Inicio rápido

Para comenzar a utilizar OpenClaw y verificar el estado de tu entorno, ejecuta el siguiente comando en tu terminal. Esta herramienta te ayudará a diagnosticar cualquier problema con tu API o configuración de Node.js.

openclaw doctor

Automatización y modo headless

Si necesitas integrar OpenClaw en tus flujos de trabajo automatizados o entornos de integración continua, puedes utilizar los siguientes comandos para evitar interacciones manuales. Esto es ideal para gestionar tu Gateway sin intervención humana.

1. Acepta los valores predeterminados sin solicitar confirmación (incluyendo pasos de reinicio, servicio o reparación de sandbox cuando sea necesario).

openclaw doctor --yes

2. Aplica las reparaciones recomendadas sin preguntar (incluye reparaciones y reinicios cuando el sistema lo considera seguro).

openclaw doctor --repair

3. Aplica reparaciones agresivas, lo cual sobrescribirá tus configuraciones personalizadas de supervisor.

openclaw doctor --repair --force

4. Ejecuta el proceso sin prompts y aplica únicamente migraciones seguras, como la normalización de configuración o movimientos de estado en disco. Este comando omite acciones de reinicio, servicio o sandbox que requieran confirmación humana, aunque las migraciones de estado heredado se ejecutan automáticamente al detectarse.

openclaw doctor --non-interactive

5. Escanea los servicios del sistema en busca de instalaciones adicionales de Gateway (como launchd, systemd o schtasks).

openclaw doctor --deep

Si prefieres revisar los cambios en tu configuración antes de realizar cualquier escritura, puedes consultar el archivo JSON directamente:

cat ~/.openclaw/openclaw.json

Resumen de funciones de OpenClaw

OpenClaw realiza una serie de comprobaciones y migraciones automáticas para asegurar que tu entorno esté siempre actualizado y configurado correctamente. Estas tareas garantizan que tu API, Node.js y Gateway funcionen sin errores de compatibilidad.

1. Actualización opcional previa al vuelo para instalaciones de git (solo interactivo).
2. Verificación de frescura del protocolo de la interfaz de usuario (reconstruye la Control UI cuando el esquema del protocolo es más reciente).
3. Verificación de estado y aviso de reinicio.
4. Resumen del estado de las habilidades (elegibles/faltantes/bloqueadas) y estado de los plugins.
5. Normalización de configuración para valores heredados.
6. Migración de la configuración de chat desde campos planos antiguos talk.* a talk.provider + talk.providers.<provider>.
7. Verificaciones de migración del navegador para configuraciones antiguas de la extensión de Chrome y preparación para Chrome MCP.
8. Advertencias de anulación del proveedor OpenCode (models.providers.opencode / models.providers.opencode-go).
9. Advertencias de ocultamiento de OAuth de Codex (models.providers.openai-codex).
10. Verificación de requisitos previos de TLS de OAuth para perfiles de OpenAI Codex OAuth.
11. Migración del estado antiguo en disco (sesiones/directorio de agentes/autenticación de WhatsApp).
12. Migración de claves de contrato de manifiesto de plugin heredado (speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders → contracts).
13. Migración del almacén cron heredado (jobId, schedule.cron, campos de entrega/carga de nivel superior, carga provider, trabajos de respaldo de webhook simples notify: true).
14. Inspección de archivos de bloqueo de sesión y limpieza de bloqueos obsoletos.
15. Verificaciones de integridad de estado y permisos (sesiones, transcripciones, directorio de estado).
16. Verificaciones de permisos de archivos de configuración (chmod 600) al ejecutar localmente.
17. Estado de autenticación del modelo: verifica la caducidad de OAuth, puede actualizar tokens que caducan e informa estados de enfriamiento/deshabilitado del perfil de autenticación.
18. Detección de directorio de espacio de trabajo adicional (~/openclaw).
19. Reparación de imágenes de sandbox cuando el sandboxing está habilitado.
20. Migración de servicios heredados y detección de Gateway adicional.
21. Migración de estado heredado del canal Matrix (en modo --fix / --repair).
22. Verificaciones de tiempo de ejecución del Gateway (servicio instalado pero no ejecutándose; etiqueta de launchd en caché).
23. Advertencias de estado del canal (sondeadas desde el Gateway en ejecución).
24. Auditoría de configuración del supervisor (launchd/systemd/schtasks) con reparación opcional.
25. Verificaciones de mejores prácticas de tiempo de ejecución del Gateway (Node vs Bun, rutas del gestor de versiones).
26. Diagnóstico de colisión de puertos del Gateway (predeterminado 18789).
27. Advertencias de seguridad para políticas de mensajes directos abiertos.
28. Verificaciones de autenticación del Gateway para el modo de token local (ofrece generación de tokens cuando no existe una fuente de tokens; no sobrescribe las configuraciones de SecretRef de tokens).
29. Detección de problemas de emparejamiento de dispositivos (solicitudes de emparejamiento por primera vez pendientes, actualizaciones de rol/alcance pendientes, deriva de caché de token de dispositivo local obsoleto y deriva de autenticación de registro emparejado).
30. Verificación de persistencia de systemd en Linux.
31. Verificación del tamaño del archivo de arranque del espacio de trabajo (advertencias de truncamiento/cerca del límite para archivos de contexto).
32. Verificación del estado de finalización del shell e instalación/actualización automática.
33. Verificación de preparación del proveedor de incrustación de búsqueda de memoria (modelo local, clave de API remota o binario QMD).
34. Verificaciones de instalación de origen (desajuste del espacio de trabajo de pnpm, activos de interfaz de usuario faltantes, binario tsx faltante).
35. Escribe la configuración actualizada + metadatos del asistente.

AI Setup Assistant

Backfill y reset de la Dreams UI

La escena Dreams de la Control UI incluye acciones de Backfill, Reset y Clear Grounded para el flujo de trabajo de sueños fundamentados. Estas acciones utilizan métodos RPC al estilo doctor del Gateway, pero no forman parte de la reparación o migración de la CLI de openclaw doctor.

Lo que hacen estas acciones:

1. Backfill: escanea los archivos históricos memory/YYYY-MM-DD.md en el espacio de trabajo activo, ejecuta el paso de diario REM fundamentado y escribe entradas de Backfill reversibles en DREAMS.md.
2. Reset: elimina únicamente las entradas de diario marcadas como Backfill de DREAMS.md.
3. Clear Grounded: elimina solo las entradas a corto plazo fundamentadas que fueron puestas en escena desde la reproducción histórica y que aún no han acumulado recuerdo en vivo o soporte diario.

Lo que no hacen por sí mismas:

1. No editan MEMORY.md.
2. No ejecutan migraciones completas de doctor.
3. No ponen en escena automáticamente candidatos fundamentados en el almacén de promoción a corto plazo en vivo, a menos que ejecutes explícitamente la ruta de la CLI puesta en escena primero.

Si deseas que la reproducción histórica fundamentada influya en el carril de promoción profunda normal, utiliza el flujo de la CLI en su lugar:

openclaw memory rem-backfill --path ./memory --stage-short-term

Esto coloca a los candidatos duraderos fundamentados en el almacén de sueños a corto plazo mientras mantienes DREAMS.md como la superficie de revisión.

Comportamiento detallado y justificación

0) Actualización opcional (instalaciones git)

Si esto es un checkout de git y el doctor se está ejecutando de forma interactiva, te ofrecerá actualizar (hacer fetch/rebase/build) antes de ejecutar el diagnóstico.

1) Normalización de la configuración

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

Esto incluye campos planos heredados de Talk. La configuración pública actual de Talk es talk.provider + talk.providers.<provider>. El doctor reescribe las formas antiguas de talk.voiceId / talk.voiceAliases / talk.modelId / talk.outputFormat / talk.apiKey en el mapa del proveedor.

2) Migraciones de claves de configuración heredadas

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

El doctor hará lo siguiente:

1. Explicar qué claves heredadas se encontraron.
2. Mostrar la migración que aplicó.
3. Reescribir ~/.openclaw/openclaw.json con el esquema actualizado.

El Gateway también ejecuta automáticamente las migraciones del doctor al iniciar cuando detecta un formato de configuración heredado, por lo que las configuraciones obsoletas se reparan sin intervención manual. Las migraciones del almacén de tareas cron se gestionan mediante openclaw doctor --fix.

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
• talk.voiceId/talk.voiceAliases/talk.modelId/talk.outputFormat/talk.apiKey heredados → talk.provider + talk.providers.<provider>
• routing.agentToAgent → tools.agentToAgent
• routing.transcribeAudio → tools.media.audio.models
• messages.tts.<provider> (openai/elevenlabs/microsoft/edge) → messages.tts.providers.<provider>
• channels.discord.voice.tts.<provider> (openai/elevenlabs/microsoft/edge) → channels.discord.voice.tts.providers.<provider>
• channels.discord.accounts.<id>.voice.tts.<provider> (openai/elevenlabs/microsoft/edge) → channels.discord.accounts.<id>.voice.tts.providers.<provider>
• plugins.entries.voice-call.config.tts.<provider> (openai/elevenlabs/microsoft/edge) → plugins.entries.voice-call.config.tts.providers.<provider>
• plugins.entries.voice-call.config.provider: "log" → "mock"
• plugins.entries.voice-call.config.twilio.from → plugins.entries.voice-call.config.fromNumber
• plugins.entries.voice-call.config.streaming.sttProvider → plugins.entries.voice-call.config.streaming.provider
• plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold → plugins.entries.voice-call.config.streaming.providers.openai.*
• bindings[].match.accountID → bindings[].match.accountId
• Para canales con accounts nombradas pero con valores de canal de nivel superior de cuenta única persistentes, mueve esos valores con alcance de cuenta a la cuenta promocionada elegida para ese canal (accounts.default para la mayoría de los canales; Matrix puede preservar un destino coincidente existente nombrado/predeterminado)
• 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
• browser.profiles.*.driver: "extension" → "existing-session"
• eliminar browser.relayBindHost (configuración de relé de extensión heredada)

Las advertencias del doctor también incluyen orientación sobre cuentas predeterminadas para canales con múltiples cuentas:

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

2b) Anulaciones del proveedor OpenCode

Si has añadido models.providers.opencode, opencode-zen o opencode-go manualmente, esto anula el catálogo integrado de OpenCode de @mariozechner/pi-ai. Eso puede forzar a los modelos a usar la API incorrecta o eliminar los costos. El doctor advierte para que puedas eliminar la anulación y restaurar el enrutamiento de API por modelo + costos.

2c) Migración del navegador y preparación para Chrome MCP

Si tu configuración del navegador aún apunta a la ruta de la extensión de Chrome eliminada, el doctor la normaliza al modelo de conexión Chrome MCP local del host actual:

1. browser.profiles.*.driver: "extension" se convierte en "existing-session"
2. Se elimina browser.relayBindHost

El doctor también audita la ruta de Chrome MCP local del host cuando usas defaultProfile: "user" o un perfil de existing-session configurado:

1. Comprueba si Google Chrome está instalado en el mismo host para los perfiles de conexión automática predeterminados.
2. Comprueba la versión de Chrome detectada y advierte cuando es inferior a Chrome 144.
3. Te recuerda habilitar la depuración remota en la página de inspección del navegador (por ejemplo, chrome://inspect/#remote-debugging, brave://inspect/#remote-debugging o edge://inspect/#remote-debugging).

El doctor no puede habilitar la configuración del lado de Chrome por ti. Chrome MCP local del host aún requiere:

1. Un navegador basado en Chromium 144+ en el host del Gateway/Node.
2. El navegador ejecutándose localmente.
3. Depuración remota habilitada en ese navegador.
4. Aprobar el primer aviso de consentimiento de conexión en el navegador.

La preparación aquí es solo sobre los requisitos previos de conexión local. existing-session mantiene los límites de ruta actuales de Chrome MCP; las rutas avanzadas como responsebody, exportación a PDF, interceptación de descargas y acciones por lotes aún requieren un navegador gestionado o un perfil CDP sin procesar.

Esta verificación no se aplica a Docker, sandbox, navegador remoto u otros flujos headless. Esos continúan usando CDP sin procesar.

2d) Requisitos previos de OAuth TLS

Cuando se configura un perfil de OAuth de OpenAI Codex, el doctor sondea el punto final de autorización de OpenAI para verificar que la pila TLS de Node.js/OpenSSL local pueda validar la cadena de certificados. Si el sondeo falla con un error de certificado (por ejemplo, UNABLE_TO_GET_ISSUER_CERT_LOCALLY, certificado caducado o certificado autofirmado), el doctor imprime una guía de solución específica para la plataforma. En macOS con un Node.js de Homebrew, la solución suele ser brew postinstall ca-certificates. Con --deep, el sondeo se ejecuta incluso si el Gateway está saludable.

2c) Anulaciones del proveedor Codex OAuth

Si anteriormente añadiste configuraciones de transporte de OpenAI heredadas en models.providers.openai-codex, pueden ocultar la ruta del proveedor OAuth de Codex integrada que las versiones más nuevas usan automáticamente. El doctor advierte cuando ve esas configuraciones de transporte antiguas junto con Codex OAuth para que puedas eliminar o reescribir la anulación de transporte obsoleta y recuperar el comportamiento de enrutamiento/respaldo integrado. Los proxies personalizados y las anulaciones solo de encabezado aún son compatibles y no activan esta advertencia.

3) Migraciones de estado heredadas (diseño del disco)

El doctor puede migrar diseños antiguos en disco a la estructura actual:

1. Almacén de sesiones + transcripciones:
   • de ~/.openclaw/sessions/ a ~/.openclaw/agents/<agentId>/sessions/
2. Directorio del agente:
   • de ~/.openclaw/agent/ a ~/.openclaw/agents/<agentId>/agent/
3. Estado de autenticación de WhatsApp (Baileys):
   • de ~/.openclaw/credentials/*.json heredado (excepto oauth.json)
   • a ~/.openclaw/credentials/whatsapp/<accountId>/... (id de cuenta predeterminado: default)

Estas migraciones son de mejor esfuerzo e idempotentes; el doctor emitirá advertencias cuando deje carpetas heredadas como copias de seguridad. El Gateway/CLI también migra automáticamente las sesiones heredadas + el directorio del agente al iniciar, por lo que el historial/autenticación/modelos aterrizan en la ruta por agente sin una ejecución manual del doctor. La autenticación de WhatsApp se migra intencionalmente solo a través de openclaw doctor. La normalización del mapa de proveedores de Talk ahora compara por igualdad estructural, por lo que las diferencias solo de orden de claves ya no activan cambios repetidos de doctor --fix sin efecto.

3a) Migraciones de manifiesto de plugin heredadas

El doctor escanea todos los manifiestos de plugins instalados en busca de claves de capacidad de nivel superior obsoletas (speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders). Cuando las encuentra, ofrece moverlas al objeto contracts y reescribir el archivo de manifiesto en su lugar. Esta migración es idempotente; si la clave contracts ya tiene los mismos valores, la clave heredada se elimina sin duplicar los datos.

3b) Migraciones del almacén cron heredadas

El doctor también comprueba el almacén de tareas cron (~/.openclaw/cron/jobs.json por defecto, o cron.store cuando se anula) en busca de formas de trabajo antiguas que el programador aún acepta por compatibilidad.

Las limpiezas de cron actuales incluyen:

1. jobId → id
2. schedule.cron → schedule.expr
3. Campos de carga útil de nivel superior (message, model, thinking, …) → payload
4. Campos de entrega de nivel superior (deliver, channel, to, provider, …) → delivery
5. Alias de entrega de provider en payload → delivery.channel explícito
6. Trabajos de respaldo de webhook simples heredados notify: true → delivery.mode="webhook" explícito con delivery.to=cron.webhook

El doctor solo migra automáticamente los trabajos notify: true cuando puede hacerlo sin cambiar el comportamiento. Si un trabajo combina un respaldo de notificación heredado con un modo de entrega que no es webhook, el doctor advierte y deja ese trabajo para revisión manual.

3c) Limpieza de bloqueo de sesión

El doctor escanea cada directorio de sesión de agente en busca de archivos de bloqueo de escritura obsoletos (archivos dejados atrás cuando una sesión terminó de forma anormal). Para cada archivo de bloqueo encontrado, informa: la ruta, el PID, si el PID sigue vivo, la antigüedad del bloqueo y si se considera obsoleto (PID muerto o más antiguo de 30 minutos). En el modo --fix / --repair, elimina los archivos de bloqueo obsoletos automáticamente; de lo contrario, imprime una nota y te indica que vuelvas a ejecutar con --fix.

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

El directorio de estado es el tronco encefálico operativo. Si desaparece, pierdes sesiones, credenciales, registros y configuración (a menos que tengas copias de seguridad en otro lugar).

El doctor comprueba:

1. Directorio de estado faltante: advierte sobre la pérdida catastrófica de estado, solicita recrear el directorio y te recuerda que no puede recuperar datos faltantes.
2. Permisos del directorio de estado: verifica la capacidad de escritura; ofrece reparar los permisos (y emite una sugerencia de chown cuando se detecta una falta de coincidencia de propietario/grupo).
3. Directorio de estado sincronizado en la nube de macOS: advierte cuando el estado se resuelve bajo iCloud Drive (~/Library/Mobile Documents/com~apple~CloudDocs/...) o ~/Library/CloudStorage/... porque las rutas respaldadas por sincronización pueden causar una E/S más lenta y carreras de bloqueo/sincronización.
4. Directorio de estado en SD o eMMC de Linux: advierte cuando el estado se resuelve en una fuente de montaje mmcblk*, porque la E/S aleatoria respaldada por SD o eMMC puede ser más lenta y desgastarse más rápido bajo escrituras de sesión y credenciales.
5. Directorios de sesión faltantes: sessions/ y el directorio del almacén de sesiones son necesarios para persistir el historial y evitar bloqueos ENOENT.
6. Falta de coincidencia de transcripción: advierte cuando las entradas de sesión recientes tienen archivos de transcripción faltantes.
7. Sesión principal “1-line JSONL”: marca cuando la transcripción principal tiene solo una línea (el historial no se está acumulando).
8. Múltiples directorios de estado: advierte cuando existen múltiples carpetas ~/.openclaw en directorios de inicio o cuando OPENCLAW_STATE_DIR apunta a otro lugar (el historial puede dividirse entre instalaciones).
9. Recordatorio de modo remoto: si gateway.mode=remote, el doctor te recuerda ejecutarlo en el host remoto (el estado vive allí).
10. Permisos del archivo de configuración: advierte si ~/.openclaw/openclaw.json es legible por el grupo/mundo y ofrece ajustarlo a 600.

5) Salud de autenticación del modelo (caducidad de OAuth)

El doctor inspecciona los perfiles de OAuth en el almacén de autenticación, advierte cuando los tokens están caducando/caducados y puede actualizarlos cuando sea seguro. Si el perfil de OAuth/token de Anthropic está obsoleto, sugiere una API key de Anthropic o la ruta del token de configuración de Anthropic. Los avisos de actualización solo aparecen cuando se ejecuta de forma interactiva (TTY); --non-interactive omite los intentos de actualización.

Cuando una actualización de OAuth falla permanentemente (por ejemplo, refresh_token_reused, invalid_grant o un proveedor que te dice que inicies sesión de nuevo), el doctor informa que se requiere re-autenticación e imprime el comando exacto openclaw models auth login --provider ... a ejecutar.

El doctor también informa perfiles de autenticación que están temporalmente inutilizables debido a:

1. Enfriamientos cortos (límites de tasa/tiempos de espera/fallos de autenticación)
2. Deshabilitaciones más largas (fallos de facturación/crédito)

6) Validación del modelo de Hooks

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

7) Reparación de imágenes de Sandbox

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

7b) Dependencias de tiempo de ejecución de plugins incluidos

El doctor verifica las dependencias de tiempo de ejecución solo para los plugins incluidos que están activos en la configuración actual o habilitados por su manifiesto predeterminado, por ejemplo plugins.entries.discord.enabled: true, channels.discord.enabled: true heredado, o un proveedor incluido habilitado por defecto. Si falta alguno, el doctor informa los paquetes y los instala en el modo openclaw doctor --fix / openclaw doctor --repair. Los plugins externos siguen usando openclaw plugins install / openclaw plugins update; el doctor no instala dependencias para rutas de plugins arbitrarias.

8) Migraciones de servicio de Gateway y sugerencias de limpieza

El doctor detecta servicios de Gateway heredados (launchd/systemd/schtasks) y ofrece eliminarlos e instalar el servicio de OpenClaw usando el puerto de Gateway actual. También puede escanear en busca de servicios adicionales tipo Gateway e imprimir sugerencias de limpieza. Los servicios de Gateway de OpenClaw nombrados por perfil se consideran de primera clase y no se marcan como “adicionales”.

8b) Migración de inicio de Matrix

Cuando una cuenta de canal de Matrix tiene una migración de estado heredada pendiente o accionable, el doctor (en modo --fix / --repair) crea una instantánea previa a la migración y luego ejecuta los pasos de migración de mejor esfuerzo: migración de estado de Matrix heredado y preparación de estado cifrado heredado. Ambos pasos no son fatales; los errores se registran y el inicio continúa. En modo de solo lectura (openclaw doctor sin --fix), esta verificación se omite por completo.

8c) Emparejamiento de dispositivos y deriva de autenticación

El doctor ahora inspecciona el estado de emparejamiento de dispositivos como parte de la verificación de salud normal.

Lo que informa:

1. Solicitudes de emparejamiento por primera vez pendientes.
2. Actualizaciones de rol pendientes para dispositivos ya emparejados.
3. Actualizaciones de alcance pendientes para dispositivos ya emparejados.
4. Reparaciones de falta de coincidencia de clave pública donde el ID del dispositivo sigue coincidiendo pero la identidad del dispositivo ya no coincide con el registro aprobado.
5. Registros emparejados a los que les falta un token activo para un rol aprobado.
6. Tokens emparejados cuyos alcances se desvían fuera de la línea base de emparejamiento aprobada.
7. Entradas de token de dispositivo almacenadas en caché local para la máquina actual que son anteriores a una rotación de token del lado del Gateway o contienen metadatos de alcance obsoletos.

El doctor no aprueba automáticamente las solicitudes de emparejamiento ni rota automáticamente los tokens de dispositivo. Imprime los siguientes pasos exactos:

1. Inspeccionar solicitudes pendientes con openclaw devices list
2. Aprobar la solicitud exacta con openclaw devices approve <requestId>
3. Rotar un token nuevo con openclaw devices rotate --device <deviceId> --role <role>
4. Eliminar y volver a aprobar un registro obsoleto con openclaw devices remove <deviceId>

Esto cierra el problema común de “ya emparejado pero aún recibiendo emparejamiento requerido”: el doctor ahora distingue el emparejamiento por primera vez de las actualizaciones de rol/alcance pendientes y de la deriva de token/identidad de dispositivo obsoleta.

9) Advertencias de seguridad

El doctor emite advertencias cuando un proveedor está abierto a mensajes directos (DM) sin una lista de permitidos, o cuando una política está configurada de una manera peligrosa.

10) systemd linger (Linux)

Si se ejecuta como un servicio de usuario de systemd, el doctor asegura que el “lingering” esté habilitado para que el Gateway permanezca activo después de cerrar sesión.

11) Estado del espacio de trabajo (habilidades, plugins y directorios heredados)

El doctor imprime un resumen del estado del espacio de trabajo para el agente predeterminado:

1. Estado de las habilidades: cuenta las habilidades elegibles, las que faltan requisitos y las bloqueadas por la lista de permitidos.
2. Directorios de espacio de trabajo heredados: advierte cuando existen ~/openclaw u otros directorios de espacio de trabajo heredados junto al espacio de trabajo actual.
3. Estado de los plugins: cuenta los plugins cargados/deshabilitados/con errores; enumera los IDs de plugin para cualquier error; informa las capacidades de los plugins incluidos.
4. Advertencias de compatibilidad de plugins: marca los plugins que tienen problemas de compatibilidad con el tiempo de ejecución actual.
5. Diagnóstico de plugins: muestra cualquier advertencia o error de tiempo de carga emitido por el registro de plugins.

11b) Tamaño del archivo de arranque

El doctor comprueba si los archivos de arranque del espacio de trabajo (por ejemplo, AGENTS.md, CLAUDE.md u otros archivos de contexto inyectados) están cerca o por encima del presupuesto de caracteres configurado. Informa los recuentos de caracteres sin procesar frente a los inyectados por archivo, el porcentaje de truncamiento, la causa del truncamiento (max/file o max/total) y el total de caracteres inyectados como una fracción del presupuesto total. Cuando los archivos están truncados o cerca del límite, el doctor imprime consejos para ajustar agents.defaults.bootstrapMaxChars y agents.defaults.bootstrapTotalMaxChars.

11c) Autocompletado de shell

El doctor comprueba si el autocompletado con tabulación está instalado para el shell actual (zsh, bash, fish o PowerShell):

1. Si el perfil del shell usa un patrón de autocompletado dinámico lento (source <(openclaw completion ...)), el doctor lo actualiza a la variante de archivo en caché más rápida.
2. Si el autocompletado está configurado en el perfil pero falta el archivo de caché, el doctor regenera la caché automáticamente.
3. Si no hay autocompletado configurado en absoluto, el doctor solicita instalarlo (solo modo interactivo; omitido con --non-interactive).

Ejecuta openclaw completion --write-state para regenerar la caché manualmente.

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

El doctor comprueba la preparación de la autenticación del token del Gateway local.

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

12b) Reparaciones conscientes de SecretRef de solo lectura

Algunos flujos de reparación necesitan inspeccionar las credenciales configuradas sin debilitar el comportamiento de fallo rápido en tiempo de ejecución.

1. openclaw doctor --fix ahora usa el mismo modelo de resumen de SecretRef de solo lectura que los comandos de la familia de estado para reparaciones de configuración específicas.
2. Ejemplo: la reparación de allowFrom / groupAllowFrom @username de Telegram intenta usar las credenciales de bot configuradas cuando están disponibles.
3. Si el token de bot de Telegram está configurado a través de SecretRef pero no está disponible en la ruta del comando actual, el doctor informa que la credencial está configurada pero no disponible y omite la resolución automática en lugar de bloquearse o informar erróneamente que el token falta.

13) Verificación de salud del Gateway + reinicio

El doctor ejecuta una verificación de salud y ofrece reiniciar el Gateway cuando parece poco saludable.

13b) Preparación de búsqueda de memoria

El doctor comprueba si el proveedor de incrustación de búsqueda de memoria configurado está listo para el agente predeterminado. El comportamiento depende del backend y el proveedor configurados:

1. Backend QMD: sondea si el binario qmd está disponible y se puede iniciar. Si no, imprime una guía de solución que incluye el paquete npm y una opción de ruta binaria manual.
2. Proveedor local explícito: comprueba si hay un archivo de modelo local o una URL de modelo remota/descargable reconocida. Si falta, sugiere cambiar a un proveedor remoto.
3. Proveedor remoto explícito (openai, voyage, etc.): verifica que haya una API key presente en el entorno o en el almacén de autenticación. Imprime sugerencias de solución accionables si falta.
4. Proveedor automático: comprueba primero la disponibilidad del modelo local, luego intenta cada proveedor remoto en orden de selección automática.

Cuando hay un resultado de sondeo del Gateway disponible (el Gateway estaba saludable en el momento de la verificación), el doctor hace referencia cruzada de su resultado con la configuración visible en la CLI y anota cualquier discrepancia.

Usa openclaw memory status --deep para verificar la preparación de la incrustación en tiempo de ejecución.

14) Advertencias de estado del canal

Si el Gateway está saludable, el doctor ejecuta un sondeo de estado del canal e informa advertencias con soluciones sugeridas.

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

El doctor comprueba la configuración del supervisor instalada (launchd/systemd/schtasks) en busca de valores predeterminados faltantes o obsoletos (por ejemplo, dependencias de red en línea de systemd y retraso de reinicio). Cuando encuentra una falta de coincidencia, recomienda una actualización y puede reescribir el archivo de servicio/tarea a los valores predeterminados actuales.

Notas:

• openclaw doctor solicita confirmación antes de reescribir la configuración del supervisor.
• openclaw doctor --yes acepta los avisos de reparación predeterminados.
• openclaw doctor --repair aplica las correcciones recomendadas sin avisos.
• openclaw doctor --repair --force sobrescribe las configuraciones de supervisor personalizadas.
• Si la autenticación de token requiere un token y gateway.auth.token es gestionado por SecretRef, la instalación/reparación del servicio del doctor valida el SecretRef pero no persiste los valores de token en texto plano resueltos en los metadatos del entorno del servicio del supervisor.
• Si la autenticación de token requiere un token y el SecretRef de token configurado no está resuelto, el 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, el doctor bloquea la instalación/reparación hasta que el modo se establezca explícitamente.
• Para unidades de systemd de usuario de Linux, las verificaciones de deriva de token del doctor ahora incluyen fuentes Environment= y EnvironmentFile= al comparar metadatos de autenticación de servicio.
• Siempre puedes forzar una reescritura completa mediante openclaw gateway install --force.

16) Diagnóstico de tiempo de ejecución + puerto del Gateway

El doctor inspecciona el tiempo de ejecución del servicio (PID, último estado de salida) y advierte cuando el servicio está instalado pero no se está ejecutando realmente. También comprueba si hay colisiones de puertos en el puerto del Gateway (predeterminado 18789) e informa las causas probables (Gateway ya ejecutándose, túnel SSH).

17) Mejores prácticas de tiempo de ejecución del Gateway

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

18) Escritura de configuración + metadatos del asistente

El doctor persiste cualquier cambio de configuración y sella los metadatos del asistente para registrar la ejecución del doctor.

19) Consejos para el espacio de trabajo (copia de seguridad + sistema de memoria)

El doctor sugiere un sistema de memoria de espacio de trabajo cuando falta e imprime un consejo de copia de seguridad si el espacio de trabajo aún no está bajo git.

Consulta /concepts/agent-workspace para obtener una guía completa sobre la estructura del espacio de trabajo y la copia de seguridad en git (se recomienda GitHub o GitLab privado).

AI Setup Assistant