Doctor

• Actualización previa opcional para instalaciones git (solo interactivo).
• Comprobación de frescura del protocolo de UI (recompila Control UI cuando el esquema de protocolo es más reciente).
• Comprobación de salud + solicitud de reinicio.
• Resumen de estado de Skills (aptas/faltantes/bloqueadas) y estado de plugins.

• Normalización de configuración para valores heredados.
• Migración de configuración de Talk desde campos planos heredados talk.* a talk.provider + talk.providers.<provider>.
• Comprobaciones de migración de navegador para configuraciones heredadas de la extensión de Chrome y preparación de Chrome MCP.
• Advertencias de anulación del proveedor OpenCode (models.providers.opencode / models.providers.opencode-go).
• Migración de proveedor/perfil heredado de OpenAI Codex (openai-codex → openai) y advertencias de sombreado para models.providers.openai-codex obsoleto.
• Comprobación de requisitos previos de TLS de OAuth para perfiles OAuth de OpenAI Codex.
• Advertencias de lista de permitidos de Plugin/herramientas cuando plugins.allow es restrictivo pero la política de herramientas aún pide comodín o herramientas propiedad de plugins.
• Migración de estado heredado en disco (sesiones/directorio de agente/autenticación de WhatsApp).
• Migración de claves heredadas del contrato de manifiesto de plugin (speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders → contracts).
• Migración del almacén Cron heredado (jobId, schedule.cron, campos de entrega/carga útil de nivel superior, provider de carga útil, trabajos de respaldo de webhook notify: true).
• Limpieza de política de runtime heredada de agente completo; la política de runtime de proveedor/modelo es el selector de ruta activo.
• Limpieza de configuración obsoleta de plugins cuando los plugins están habilitados; cuando plugins.enabled=false, las referencias obsoletas de plugins se tratan como configuración de contención inerte y se conservan.

• Inspección de archivos de bloqueo de sesión y limpieza de bloqueos obsoletos.
• Reparación de transcripciones de sesión para ramas duplicadas de reescritura de prompts creadas por compilaciones afectadas de 2026.4.24.
• Detección de lápidas de recuperación por reinicio de subagentes bloqueados, con soporte de --fix para limpiar marcas de recuperación abortada obsoletas de modo que el arranque no siga tratando al proceso hijo como abortado por reinicio.
• Comprobaciones de integridad de estado y permisos (sesiones, transcripciones, directorio de estado).
• Comprobaciones de permisos del archivo de configuración (chmod 600) al ejecutarse localmente.
• Salud de autenticación del modelo: comprueba la expiración de OAuth, puede actualizar tokens próximos a expirar e informa estados de enfriamiento/deshabilitación de perfiles de autenticación.

• Reparación de imagen sandbox cuando el sandboxing está habilitado.
• Migración de servicio heredado y detección de gateways adicionales.
• Migración de estado heredado del canal Matrix (en modo --fix / --repair).
• Comprobaciones de runtime del Gateway (servicio instalado pero no en ejecución; etiqueta launchd en caché).
• Advertencias de estado de canales (sondeadas desde el gateway en ejecución).
• Las comprobaciones de permisos específicas de canal viven bajo openclaw channels capabilities; por ejemplo, los permisos de canal de voz de Discord se auditan con openclaw channels capabilities --channel discord --target channel:<channel-id>.
• Comprobaciones de capacidad de respuesta de WhatsApp para salud degradada del bucle de eventos del Gateway con clientes TUI locales aún en ejecución; --fix detiene solo clientes TUI locales verificados.
• Reparación de rutas de Codex para refs de modelo heredadas openai-codex/* en modelos primarios, respaldos, modelos de generación de imagen/video, anulaciones de heartbeat/subagente/compaction, hooks, anulaciones de modelo por canal y fijaciones de ruta de sesión; --fix las reescribe a openai/*, migra perfiles/orden de autenticación openai-codex:* a openai:*, elimina fijaciones obsoletas de runtime de sesión/agente completo y deja refs canónicas de agentes OpenAI en el harness Codex predeterminado.
• Auditoría de configuración de supervisor (launchd/systemd/schtasks) con reparación opcional.
• Limpieza del entorno de proxy embebido para servicios de gateway que capturaron valores de shell HTTP_PROXY / HTTPS_PROXY / NO_PROXY durante la instalación o actualización.
• Comprobaciones de mejores prácticas del runtime del Gateway (Node frente a Bun, rutas de gestores de versión).
• Diagnósticos de colisión de puerto del Gateway (predeterminado 18789).

• Advertencias de seguridad para políticas de DM abiertas.
• Comprobaciones de autenticación del Gateway para modo de token local (ofrece generación de token cuando no existe una fuente de token; no sobrescribe configuraciones SecretRef de token).
• Detección de problemas de emparejamiento de dispositivo (solicitudes pendientes de primer emparejamiento, actualizaciones pendientes de rol/alcance, deriva obsoleta de caché local de token de dispositivo y deriva de autenticación de registros emparejados).

• Comprobación de linger de systemd en Linux.
• Comprobación de tamaño de archivo de bootstrap del workspace (advertencias de truncamiento/cercanía al límite para archivos de contexto).
• Comprobación de preparación de Skills para el agente predeterminado; informa skills permitidas con requisitos faltantes de binarios, entorno, configuración o sistema operativo, y --fix puede deshabilitar skills no disponibles en skills.entries.
• Comprobación de estado de autocompletado de shell e instalación/actualización automática.
• Comprobación de preparación del proveedor de embeddings de búsqueda de memoria (modelo local, clave API remota o binario QMD).
• Comprobaciones de instalación desde código fuente (desajuste de workspace pnpm, recursos de UI faltantes, binario tsx faltante).
• Escribe configuración actualizada + metadatos del asistente.

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

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

Eso incluye campos planos heredados de Talk. La configuración pública actual de voz de Talk es talk.provider + talk.providers.<provider>, y la configuración de voz en tiempo real es talk.realtime.*. Doctor reescribe formas antiguas talk.voiceId / talk.voiceAliases / talk.modelId / talk.outputFormat / talk.apiKey en el mapa de proveedores, y reescribe selectores heredados de tiempo real de nivel superior (talk.mode, talk.transport, talk.brain, talk.model, talk.voice) en talk.realtime.

Doctor también advierte cuando plugins.allow no está vacío y la política de herramientas usa comodines o entradas de herramientas propiedad de plugins. tools.allow: ["*"] solo coincide con herramientas de plugins que realmente se cargan; no omite la lista de permitidos exclusiva de plugins.

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

Doctor hará lo siguiente:

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

El inicio de Gateway rechaza formatos de configuración heredados y te pide que ejecutes openclaw doctor --fix; no reescribe openclaw.json al iniciar. Las migraciones del almacén de trabajos Cron también las gestiona 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
• channels.telegram.requireMention → channels.telegram.groups."*".requireMention
• eliminar los channels.webchat y gateway.webchat retirados
• 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>
• selectores Talk en tiempo real heredados de nivel superior (talk.mode/talk.transport/talk.brain/talk.model/talk.voice) + talk.provider/talk.providers → talk.realtime
• routing.agentToAgent → tools.agentToAgent
• routing.transcribeAudio → tools.media.audio.models
• messages.tts.<provider> (openai/elevenlabs/microsoft/edge) → messages.tts.providers.<provider>
• messages.tts.provider: "edge" y messages.tts.providers.edge → messages.tts.provider: "microsoft" y messages.tts.providers.microsoft
• campos de selección de hablante TTS (voice/voiceName/voiceId) → speakerVoice/speakerVoiceId
• 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.tts.provider: "edge" y plugins.entries.voice-call.config.tts.providers.edge → provider: "microsoft" y providers.microsoft
• 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 con nombre pero valores de canal de nivel superior de cuenta única aún presentes, mover esos valores con ámbito de cuenta a la cuenta promovida elegida para ese canal (accounts.default para la mayoría de los canales; Matrix puede conservar un destino existente con nombre/predeterminado que coincida)
• 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
• eliminar agents.defaults.llm; usa models.providers.<id>.timeoutSeconds para tiempos de espera de proveedor/modelo lentos, y mantén el tiempo de espera del agente/ejecución por encima de ese valor cuando toda la ejecución deba durar más
• browser.ssrfPolicy.allowPrivateNetwork → browser.ssrfPolicy.dangerouslyAllowPrivateNetwork
• browser.profiles.*.driver: "extension" → "existing-session"
• eliminar browser.relayBindHost (ajuste heredado del relé de la extensión)
• models.providers.*.api: "openai" heredado → "openai-completions" (el inicio de Gateway también omite proveedores cuyo api esté configurado con un valor enum futuro o desconocido en lugar de fallar cerrado)
• eliminar plugins.entries.codex.config.codexDynamicToolsProfile; el servidor de aplicación Codex siempre mantiene nativas las herramientas de espacio de trabajo nativas de Codex

Las advertencias de Doctor también incluyen orientación de cuenta predeterminada para canales con varias cuentas:

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

Si agregaste models.providers.opencode, opencode-zen u opencode-go manualmente, eso sobrescribe el catálogo OpenCode integrado de openclaw/plugin-sdk/llm. Eso puede forzar modelos a la API incorrecta o reducir los costos a cero. Doctor advierte para que puedas eliminar la sobrescritura y restaurar el enrutamiento de API por modelo + costos.

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

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

Doctor también audita la ruta Chrome MCP local al host cuando usas defaultProfile: "user" o un perfil existing-session configurado:

• comprueba si Google Chrome está instalado en el mismo host para perfiles predeterminados de conexión automática
• comprueba la versión detectada de Chrome y advierte cuando es inferior a Chrome 144
• 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)

Doctor no puede habilitar por ti el ajuste del lado de Chrome. Chrome MCP local al host aún requiere:

• un navegador basado en Chromium 144+ en el host de gateway/nodo
• el navegador ejecutándose localmente
• depuración remota habilitada en ese navegador
• aprobar el primer aviso de consentimiento de conexión en el navegador

La preparación aquí se refiere únicamente a los prerrequisitos de conexión local. Existing-session conserva los límites actuales de rutas de Chrome MCP; las rutas avanzadas como responsebody, exportación de PDF, interceptación de descargas y acciones por lotes aún requieren un navegador administrado o un perfil CDP sin procesar.

Esta comprobación no se aplica a Docker, sandbox, remote-browser u otros flujos headless. Esos siguen usando CDP sin procesar.

Cuando se configura un perfil OAuth de OpenAI Codex, doctor sondea el endpoint de autorización de OpenAI para verificar que la pila TLS local de Node/OpenSSL 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), doctor imprime orientación de corrección específica de la plataforma. En macOS con un Node de Homebrew, la corrección suele ser brew postinstall ca-certificates. Con --deep, el sondeo se ejecuta incluso si el gateway está sano.

Si antes agregaste ajustes heredados de transporte de OpenAI bajo models.providers.openai-codex, pueden ocultar la ruta integrada de proveedor OAuth de Codex que las versiones más nuevas usan automáticamente. Doctor advierte cuando ve esos ajustes de transporte antiguos junto con Codex OAuth para que puedas eliminar o reescribir la sobrescritura de transporte obsoleta y recuperar el comportamiento integrado de enrutamiento/reserva. Los proxies personalizados y las sobrescrituras solo de encabezados siguen siendo compatibles y no activan esta advertencia.

Doctor comprueba referencias de modelo openai-codex/* heredadas. El enrutamiento nativo del arnés Codex usa referencias de modelo canónicas openai/*; los turnos de agentes de OpenAI pasan por el arnés del servidor de aplicación Codex en lugar de la ruta del proveedor OpenAI de OpenClaw.

En modo --fix / --repair, doctor reescribe las referencias afectadas del agente predeterminado y por agente, incluidos modelos principales, reservas, modelos de generación de imágenes/video, sobrescrituras de Heartbeat/subagente/Compaction, hooks, sobrescrituras de modelo de canal y estado persistido obsoleto de ruta de sesión:

• openai-codex/gpt-* se convierte en openai/gpt-*.
• La intención de Codex se mueve a entradas agentRuntime.id: "codex" con ámbito de proveedor/modelo para referencias de modelo de agente reparadas.
• La configuración obsoleta de runtime de agente completo y los anclajes persistidos de runtime de sesión se eliminan porque la selección de runtime tiene ámbito de proveedor/modelo.
• La política existente de runtime de proveedor/modelo se conserva, salvo que la referencia de modelo heredada reparada necesite enrutamiento de Codex para mantener la antigua ruta de autenticación.
• Las listas existentes de modelos de reserva se conservan con sus entradas heredadas reescritas; los ajustes copiados por modelo se mueven de la clave heredada a la clave canónica openai/*.
• modelProvider/providerOverride, model/modelOverride, avisos de reserva y anclajes de perfil de autenticación de sesiones persistidas se reparan en todos los almacenes de sesiones de agente descubiertos.
• /codex ... significa "controlar o vincular una conversación nativa de Codex desde el chat".
• /acp ... o runtime: "acp" significa "usar el adaptador ACP/acpx externo".

Doctor también analiza los almacenes de sesiones de agente descubiertos en busca de estado de ruta obsoleto creado automáticamente después de mover modelos configurados o runtime fuera de una ruta propiedad de un Plugin como Codex.

openclaw doctor --fix puede borrar estado obsoleto creado automáticamente, como anclajes de modelo modelOverrideSource: "auto", metadatos de modelo de runtime, IDs de arnés anclados, enlaces de sesión CLI y sobrescrituras automáticas de perfil de autenticación cuando su ruta propietaria ya no está configurada. Las elecciones explícitas de usuario o de modelos de sesión heredados se informan para revisión manual y se dejan intactas; cámbialas con /model ..., /new o restablece la sesión cuando esa ruta ya no sea la prevista.

Doctor puede migrar diseños antiguos en disco 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 heredado (excepto oauth.json)
  • a ~/.openclaw/credentials/whatsapp/<accountId>/... (ID de cuenta predeterminado: default)

Estas migraciones son de mejor esfuerzo e idempotentes; doctor emitirá advertencias cuando deje carpetas heredadas como respaldos. Gateway/CLI también migra automáticamente el almacén de sesiones heredado + directorio de agente al iniciar para que historial/autenticación/modelos terminen en la ruta por agente sin ejecutar doctor manualmente. La autenticación de WhatsApp se migra intencionalmente solo mediante openclaw doctor. La normalización de proveedor/mapa de proveedores de Talk ahora compara por igualdad estructural, por lo que las diferencias solo de orden de claves ya no activan cambios no operativos repetidos de doctor --fix.

Doctor analiza 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 el mismo lugar. Esta migración es idempotente; si la clave contracts ya tiene los mismos valores, la clave heredada se elimina sin duplicar los datos.

Doctor también comprueba el almacén de trabajos de Cron (~/.openclaw/cron/jobs.json de forma predeterminada, o cron.store cuando se sobrescribe) en busca de formas de trabajos antiguas que el planificador aún acepta por compatibilidad.

Las limpiezas actuales de Cron incluyen:

• jobId → id
• schedule.cron → schedule.expr
• campos payload de nivel superior (message, model, thinking, ...) → payload
• campos de entrega de nivel superior (deliver, channel, to, provider, ...) → delivery
• alias de entrega provider de payload → delivery.channel explícito
• trabajos de fallback Webhook heredados notify: true → entrega Webhook explícita desde cron.webhook cuando está configurado; los trabajos de anuncio conservan su entrega de chat y obtienen delivery.completionDestination. Cuando cron.webhook no está configurado, el marcador inerte de nivel superior notify se elimina para los trabajos sin destino (se conserva la entrega existente, incluida la de anuncio), ya que la entrega en tiempo de ejecución nunca lo lee

El Gateway también sanea las filas de Cron malformadas en el momento de la carga para que los trabajos válidos sigan ejecutándose. Las filas sin procesar malformadas se copian en jobs-quarantine.json junto al almacén activo antes de eliminarse de jobs.json; doctor informa las filas en cuarentena para que puedas revisarlas o repararlas manualmente.

El inicio del Gateway normaliza la proyección de tiempo de ejecución e ignora el marcador de nivel superior notify, pero deja la configuración persistida de Cron para la reparación de doctor. Cuando cron.webhook no está configurado, doctor elimina el marcador inerte para trabajos sin destino de migración (delivery.mode ninguno/ausente, un destino Webhook inutilizable o una entrega existente de anuncio/chat), dejando intacta la entrega existente, por lo que las ejecuciones repetidas de doctor --fix ya no vuelven a advertir sobre el mismo trabajo. Si cron.webhook está configurado pero no es una URL HTTP(S) válida, doctor sigue advirtiendo y deja el marcador para que puedas corregir la URL.

En Linux, doctor también advierte cuando el crontab del usuario todavía invoca el ~/.openclaw/bin/ensure-whatsapp.sh heredado. Ese script local del host no está mantenido por el OpenClaw actual y puede escribir mensajes falsos de Gateway inactive en ~/.openclaw/logs/whatsapp-health.log cuando Cron no puede alcanzar el bus de usuario de systemd. Elimina la entrada obsoleta del crontab con crontab -e; usa openclaw channels status --probe, openclaw doctor y openclaw gateway status para las comprobaciones de estado actuales.

Doctor analiza cada directorio de sesión de agente en busca de archivos de bloqueo de escritura obsoletos: archivos que quedaron atrás cuando una sesión terminó de forma anómala. Por cada archivo de bloqueo encontrado, informa: la ruta, el PID, si el PID sigue activo, la antigüedad del bloqueo y si se considera obsoleto (PID muerto, metadatos de propietario malformados, más de 30 minutos de antigüedad o un PID activo que puede demostrarse que pertenece a un proceso que no es de OpenClaw). En modo --fix / --repair, elimina automáticamente los bloqueos con propietarios muertos, huérfanos, reciclados, malformados-antiguos o que no son de OpenClaw. Los bloqueos antiguos que aún pertenecen a un proceso de OpenClaw activo se informan, pero se dejan en su lugar para que doctor no interrumpa un escritor de transcripciones activo.

Doctor analiza los archivos JSONL de sesión de agente en busca de la forma de rama duplicada creada por el error de reescritura de transcripciones de prompts de 2026.4.24: un turno de usuario abandonado con contexto de tiempo de ejecución interno de OpenClaw más un hermano activo que contiene el mismo prompt visible del usuario. En modo --fix / --repair, doctor hace una copia de seguridad de cada archivo afectado junto al original y reescribe la transcripción a la rama activa para que el historial del Gateway y los lectores de memoria ya no vean turnos duplicados.

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).

Doctor comprueba:

• Falta el directorio de estado: advierte sobre pérdida catastrófica de estado, solicita recrear el directorio y recuerda que no puede recuperar los datos faltantes.
• Permisos del directorio de estado: verifica la capacidad de escritura; ofrece reparar permisos (y emite una sugerencia de chown cuando se detecta una discrepancia de propietario/grupo).
• Directorio de estado sincronizado con la nube en 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 E/S más lenta y carreras de bloqueo/sincronización.
• Directorio de estado en SD o eMMC en Linux: advierte cuando el estado se resuelve a un origen de montaje mmcblk*, porque la E/S aleatoria respaldada por SD o eMMC puede ser más lenta y desgastarse más rápido con escrituras de sesión y credenciales.
• Directorio de estado volátil en Linux: advierte cuando el estado se resuelve a tmpfs o ramfs, porque las sesiones, credenciales, configuración y el estado de SQLite con sus archivos acompañantes WAL/journal desaparecerán al reiniciar. Los montajes overlay de Docker no se marcan intencionalmente porque sus capas escribibles persisten entre reinicios del host mientras el contenedor permanece.
• Faltan directorios de sesión: sessions/ y el directorio del almacén de sesiones son necesarios para persistir el historial y evitar bloqueos ENOENT.
• Discordancia de transcripción: advierte cuando entradas de sesión recientes tienen archivos de transcripción faltantes.
• Sesión principal "JSONL de 1 línea": marca cuando la transcripción principal tiene solo una línea (el historial no se está acumulando).
• Múltiples directorios de estado: advierte cuando existen varias carpetas ~/.openclaw entre directorios de inicio o cuando OPENCLAW_STATE_DIR apunta a otro lugar (el historial puede dividirse entre instalaciones).
• Recordatorio de modo remoto: si gateway.mode=remote, doctor te 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/todo el mundo y ofrece restringirlo a 600.

Doctor inspecciona los perfiles de OAuth en el almacén de autenticación, advierte cuando los tokens están por caducar o han caducado, y puede actualizarlos cuando es seguro. Si el perfil OAuth/token de Anthropic está obsoleto, sugiere una clave de API de Anthropic o la ruta de token de configuración de Anthropic. Los prompts 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 indica iniciar sesión de nuevo), doctor informa que se requiere volver a autenticarse e imprime el comando exacto openclaw models auth login --provider ... que se debe ejecutar.

Doctor también informa perfiles de autenticación que son temporalmente inutilizables debido a:

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

Los perfiles OAuth heredados de Codex cuyos tokens viven en macOS Keychain (onboarding más antiguo anterior al diseño de archivo acompañante) solo son reparados por doctor. Ejecuta openclaw doctor --fix una vez desde un terminal interactivo para migrar los tokens heredados respaldados por Keychain en línea a auth-profiles.json; después de eso, los turnos embebidos (Telegram, Cron, despacho de subagentes) los resuelven como perfiles OAuth canónicos de OpenAI.

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

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

Doctor elimina el estado de preparación de dependencias de plugins generado por OpenClaw heredado en modo openclaw doctor --fix / openclaw doctor --repair. Esto cubre raíces de dependencias generadas obsoletas, directorios antiguos de etapa de instalación, residuos locales de paquete de código anterior de reparación de dependencias de plugins incluidos, y copias npm gestionadas huérfanas o recuperadas de plugins @openclaw/* incluidos que pueden ocultar el manifiesto incluido actual. Doctor también vuelve a enlazar el paquete openclaw del host en plugins npm gestionados que declaran peerDependencies.openclaw, para que las importaciones de tiempo de ejecución locales al paquete como openclaw/plugin-sdk/* sigan resolviéndose después de actualizaciones o reparaciones npm.

Doctor también puede reinstalar plugins descargables faltantes cuando la configuración los referencia pero el registro local de plugins no puede encontrarlos. Entre los ejemplos se incluyen plugins.entries materiales, ajustes configurados de canal/proveedor/búsqueda y runtimes de agente configurados. Durante actualizaciones de paquete, doctor evita ejecutar la reparación de plugins del gestor de paquetes mientras se intercambia el paquete core; ejecuta openclaw doctor --fix de nuevo después de la actualización si un plugin configurado aún necesita recuperación. El inicio del Gateway y la recarga de configuración no ejecutan gestores de paquetes; las instalaciones de plugins siguen siendo trabajo explícito de doctor/install/update.

Doctor detecta servicios de Gateway heredados (launchd/systemd/schtasks) y ofrece eliminarlos e instalar el servicio de OpenClaw usando el puerto actual del Gateway. También puede buscar servicios adicionales similares al Gateway e imprimir sugerencias de limpieza. Los servicios de Gateway de OpenClaw con nombre de perfil se consideran de primera clase y no se marcan como "extra".

En Linux, si falta el servicio de Gateway a nivel de usuario pero existe un servicio de Gateway de OpenClaw a nivel de sistema, doctor no instala automáticamente un segundo servicio a nivel de usuario. Inspecciona con openclaw gateway status --deep o openclaw doctor --deep, luego elimina el duplicado o configura OPENCLAW_SERVICE_REPAIR_POLICY=external cuando un supervisor del sistema sea propietario del ciclo de vida del Gateway.

Cuando una cuenta de canal de Matrix tiene una migración de estado heredado pendiente o accionable, 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 heredado de Matrix 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 comprobación se omite por completo.

Doctor ahora inspecciona el estado de emparejamiento de dispositivos como parte del pase de salud normal.

Lo que informa:

• solicitudes pendientes de emparejamiento por primera vez
• actualizaciones de rol pendientes para dispositivos ya emparejados
• actualizaciones de alcance pendientes para dispositivos ya emparejados
• reparaciones de discordancia de clave pública donde el id del dispositivo aún coincide pero la identidad del dispositivo ya no coincide con el registro aprobado
• registros emparejados a los que les falta un token activo para un rol aprobado
• tokens emparejados cuyos alcances se desvían fuera de la línea base de emparejamiento aprobada
• entradas locales en caché de token de dispositivo para la máquina actual que son anteriores a una rotación de token del lado del Gateway o llevan metadatos de alcance obsoletos

Doctor no aprueba automáticamente solicitudes de emparejamiento ni rota automáticamente tokens de dispositivo. En su lugar, imprime los próximos pasos exactos:

• inspecciona solicitudes pendientes con openclaw devices list
• aprueba la solicitud exacta con openclaw devices approve <requestId>
• rota un token nuevo con openclaw devices rotate --device <deviceId> --role <role>
• elimina y vuelve a aprobar un registro obsoleto con openclaw devices remove <deviceId>

Esto cierra el vacío común de "ya emparejado pero todavía recibe emparejamiento requerido": doctor ahora distingue el emparejamiento por primera vez de las actualizaciones pendientes de rol/alcance y de la deriva de token/identidad de dispositivo obsoleta.

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

Si se ejecuta como un servicio de usuario de systemd, doctor garantiza que linger esté habilitado para que el gateway siga activo después de cerrar sesión.

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

• Estado de Skills: cuenta Skills elegibles, con requisitos faltantes y bloqueadas por lista de permitidos.
• Estado de Plugin: cuenta plugins habilitados/deshabilitados/con errores; lista los ID de Plugin para cualquier error; informa las capacidades de Plugin del paquete.
• Advertencias de compatibilidad de Plugin: marca plugins que tienen problemas de compatibilidad con el runtime actual.
• Diagnósticos de Plugin: muestra cualquier advertencia o error en tiempo de carga emitido por el registro de Plugin.
• Recuperación de TaskFlow: muestra TaskFlows administrados sospechosos que requieren inspección manual o cancelación.

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, por archivo, los recuentos de caracteres sin procesar frente a inyectados, el porcentaje de truncamiento, la causa del truncamiento (max/file o max/total) y el total de caracteres inyectados como fracción del presupuesto total. Cuando los archivos están truncados o cerca del límite, doctor imprime consejos para ajustar agents.defaults.bootstrapMaxChars y agents.defaults.bootstrapTotalMaxChars.

Cuando openclaw doctor --fix elimina un plugin de canal faltante, también elimina la configuración colgante con alcance de canal que hacía referencia a ese plugin: entradas channels.<id>, objetivos de Heartbeat que nombraban el canal y sobrescrituras agents.*.models["<channel>/*"]. Esto evita bucles de arranque del Gateway donde el runtime del canal ya no existe, pero la configuración todavía pide al gateway que se enlace a él.

Doctor comprueba si el autocompletado con tabulador está instalado para el shell actual (zsh, bash, fish o PowerShell):

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

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

Doctor comprueba la preparación de autenticación con token del gateway local.

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

Algunos flujos de reparación necesitan inspeccionar credenciales configuradas sin debilitar el comportamiento de fallo rápido del runtime.

• 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 dirigidas.
• Ejemplo: la reparación de Telegram allowFrom / groupAllowFrom @username intenta usar las credenciales de bot configuradas cuando están disponibles.
• Si el token del bot de Telegram está configurado mediante SecretRef pero no está disponible en la ruta del comando actual, doctor informa que la credencial está configurada pero no disponible y omite la resolución automática en lugar de fallar o informar erróneamente que falta el token.

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

Doctor comprueba si el proveedor configurado de embeddings de búsqueda en memoria está listo para el agente predeterminado. El comportamiento depende del backend y del proveedor configurados:

• Backend QMD: sondea si el binario qmd está disponible y se puede iniciar. Si no, imprime orientación de corrección que incluye el paquete npm y una opción de ruta manual al binario.
• Proveedor local explícito: comprueba si existe un archivo de modelo local o una URL de modelo remoto/descargable reconocida. Si falta, sugiere cambiar a un proveedor remoto.
• Proveedor remoto explícito (openai, voyage, etc.): verifica que haya una clave de API presente en el entorno o en el almacén de autenticación. Imprime indicaciones de corrección accionables si falta.
• Proveedor automático heredado: trata memorySearch.provider: "auto" como OpenAI, comprueba la preparación de OpenAI, y doctor --fix lo reescribe como provider: "openai".

Cuando hay disponible un resultado de sondeo del gateway en caché (el gateway estaba saludable en el momento de la comprobación), doctor cruza su resultado con la configuración visible para la CLI y señala cualquier discrepancia. Doctor no inicia un ping de embedding nuevo en la ruta predeterminada; usa el comando de estado profundo de memoria cuando quieras una comprobación en vivo del proveedor.

Usa openclaw memory status --deep para verificar la preparación de embeddings en runtime.

Si el gateway está saludable, doctor ejecuta un sondeo de estado de canal e informa advertencias con correcciones sugeridas.

Doctor comprueba la configuración instalada del supervisor (launchd/systemd/schtasks) para detectar valores predeterminados faltantes u obsoletos (por ejemplo, dependencias de systemd network-online y demora de reinicio). Cuando encuentra una discrepancia, recomienda una actualización y puede reescribir el archivo de servicio/tarea con 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 --fix aplica las correcciones recomendadas sin avisos (--repair es un alias).
• openclaw doctor --fix --force sobrescribe configuraciones personalizadas del supervisor.
• OPENCLAW_SERVICE_REPAIR_POLICY=external mantiene doctor en modo de solo lectura para el ciclo de vida del servicio del gateway. Todavía informa la salud del servicio y ejecuta reparaciones que no son de servicio, pero omite la instalación/inicio/reinicio/arranque del servicio, las reescrituras de configuración del supervisor y la limpieza de servicios heredados porque un supervisor externo es propietario de ese ciclo de vida.
• En Linux, doctor no reescribe metadatos de comando/punto de entrada mientras la unidad systemd del gateway correspondiente está activa. También ignora unidades adicionales inactivas no heredadas parecidas a gateway durante el escaneo de servicios duplicados para que los archivos de servicios complementarios no generen ruido de limpieza.
• Si la autenticación con token requiere un token y gateway.auth.token está administrado por SecretRef, la instalación/reparación del servicio de doctor valida el SecretRef pero no persiste valores de token resueltos en texto sin formato en los metadatos de entorno del servicio del supervisor.
• Doctor detecta valores de entorno de servicio administrados respaldados por .env/SecretRef que instalaciones antiguas de LaunchAgent, systemd o Windows Scheduled Task incrustaron en línea, y reescribe los metadatos del servicio para que esos valores se carguen desde la fuente de runtime en lugar de la definición del supervisor.
• Doctor detecta cuando el comando del servicio todavía fija un --port antiguo después de cambios en gateway.port y reescribe los metadatos del servicio al puerto actual.
• Si la autenticación con token requiere un token y el SecretRef de token configurado no se resuelve, 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 comprobaciones de deriva de token de doctor ahora incluyen tanto fuentes Environment= como EnvironmentFile= al comparar metadatos de autenticación del servicio.
• Las reparaciones de servicio de doctor se niegan a reescribir, detener o reiniciar un servicio de gateway desde un binario de OpenClaw anterior cuando la configuración fue escrita por última vez por una versión más reciente. Consulta Solución de problemas del Gateway.
• Siempre puedes forzar una reescritura completa mediante openclaw gateway install --force.

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 comprueba colisiones de puerto en el puerto del gateway (predeterminado 18789) e informa causas probables (gateway ya en ejecución, túnel SSH).

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

Los LaunchAgents de macOS recién instalados o reparados usan un PATH de sistema canónico (/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin) en lugar de copiar el PATH del shell interactivo, por lo que los binarios de sistema administrados por Homebrew siguen disponibles mientras Volta, asdf, fnm, pnpm y otros directorios de gestores de versiones no cambian qué procesos hijo de Node se resuelven. Los servicios de Linux todavía conservan raíces de entorno explícitas (NVM_DIR, FNM_DIR, VOLTA_HOME, ASDF_DATA_DIR, BUN_INSTALL, PNPM_HOME) y directorios user-bin estables, pero los directorios de respaldo inferidos de gestores de versiones solo se escriben en el PATH del servicio cuando esos directorios existen en disco.

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

Doctor sugiere un sistema de memoria del 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 una guía completa de la estructura del espacio de trabajo y copia de seguridad con git (se recomienda GitHub o GitLab privado).