--- read_when: - Agregar o modificar migraciones de doctor - Introducir cambios incompatibles en la configuración sidebarTitle: Doctor summary: 'Comando doctor: comprobaciones de estado, migraciones de configuración y pasos de reparación' title: Diagnóstico x-i18n: generated_at: "2026-05-12T08:45:34Z" model: gpt-5.5 provider: openai source_hash: 53d67fcc5ab4a356747bc4f4af0c5d42cbdae0c89a41616aaded7589e408a017 source_path: gateway/doctor.md workflow: 16 --- `openclaw doctor` es la herramienta de reparación y migración para OpenClaw. Corrige configuración/estado obsoletos, comprueba el estado y proporciona pasos de reparación accionables. ## Inicio rápido ```bash openclaw doctor ``` ### Modos sin interfaz y de automatización ```bash openclaw doctor --yes ``` Acepta los valores predeterminados sin preguntar (incluidos los pasos de reinicio/servicio/reparación de sandbox cuando corresponda). ```bash openclaw doctor --repair ``` Aplica las reparaciones recomendadas sin preguntar (reparaciones + reinicios cuando sea seguro). ```bash openclaw doctor --repair --force ``` Aplica también reparaciones agresivas (sobrescribe configuraciones personalizadas del supervisor). ```bash openclaw doctor --non-interactive ``` Se ejecuta sin avisos 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 heredado se ejecutan automáticamente cuando se detectan. ```bash openclaw doctor --deep ``` Escanea los servicios del sistema en busca de instalaciones adicionales del Gateway (launchd/systemd/schtasks). Si quieres revisar los cambios antes de escribir, abre primero el archivo de configuración: ```bash cat ~/.openclaw/openclaw.json ``` ## Qué hace (resumen) - Actualización previa opcional para instalaciones desde git (solo interactivo). - Comprobación de vigencia del protocolo de la IU (recompila la IU de Control cuando el esquema del protocolo es más reciente). - Comprobación de estado + aviso de reinicio. - Resumen del estado de Skills (elegibles/faltantes/bloqueadas) y estado de Plugin. - Normalización de configuración para valores heredados. - Migración de la configuración de Talk desde campos planos heredados `talk.*` a `talk.provider` + `talk.providers.`. - Comprobaciones de migración del navegador para configuraciones heredadas de la extensión de Chrome y preparación de Chrome MCP. - Advertencias de sobrescritura del proveedor OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). - Advertencias de sombreado de OAuth de Codex (`models.providers.openai-codex`). - Comprobación de prerrequisitos de TLS de OAuth para perfiles OAuth de OpenAI Codex. - Advertencias de allowlist de Plugin/herramienta cuando `plugins.allow` es restrictivo pero la política de herramientas sigue pidiendo comodines o herramientas propiedad de Plugin. - Migración de estado heredado en disco (sesiones/directorio de agente/autenticación de WhatsApp). - Migración de claves de contrato de manifiesto de Plugin heredadas (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). - Migración del almacén Cron heredado (`jobId`, `schedule.cron`, campos superiores de delivery/payload, payload `provider`, trabajos simples de Webhook de respaldo `notify: true`). - Limpieza de política de tiempo de ejecución heredada de agente completo; la política de tiempo de ejecución de proveedor/modelo es el selector de ruta activo. - Limpieza de configuración obsoleta de Plugin cuando los plugins están habilitados; cuando `plugins.enabled=false`, las referencias obsoletas a Plugin se tratan como configuración de contención inerte y se preservan. - 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 prompt creadas por compilaciones afectadas de 2026.4.24. - Detección de tombstones de recuperación por reinicio de subagentes bloqueados, con soporte de `--fix` para limpiar flags obsoletos de recuperación abortada de modo que el arranque no siga tratando al 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) cuando se ejecuta localmente. - Estado de autenticación de modelos: comprueba caducidad de OAuth, puede refrescar tokens próximos a caducar e informa estados de enfriamiento/deshabilitación de perfiles de autenticación. - Detección de directorio de workspace adicional (`~/openclaw`). - Reparación de imagen de 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 tiempo de ejecución del Gateway (servicio instalado pero no en ejecución; etiqueta launchd en caché). - Advertencias de estado de canal (sondeadas desde el Gateway en ejecución). - Las comprobaciones de permisos específicas de canal viven en `openclaw channels capabilities`; por ejemplo, los permisos de canal de voz de Discord se auditan con `openclaw channels capabilities --channel discord --target channel:`. - 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, fallbacks, sobrescrituras de heartbeat/subagente/compaction, hooks, sobrescrituras de modelo por canal y pines de ruta de sesión; `--fix` las reescribe a `openai/*`, elimina pines obsoletos de tiempo de ejecución de sesión/agente completo y deja refs canónicas de agente OpenAI en el arnés Codex predeterminado. - Auditoría de configuración de supervisores (launchd/systemd/schtasks) con reparación opcional. - Limpieza de 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 buenas prácticas de tiempo de ejecución del Gateway (Node frente a Bun, rutas de gestores de versiones). - 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 ninguna fuente de token; no sobrescribe configuraciones SecretRef de token). - Detección de problemas de emparejamiento de dispositivos (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 registro emparejado). - Comprobación de linger de systemd en Linux. - Comprobación de tamaño de archivo de arranque de workspace (advertencias de truncamiento/casi límite para archivos de contexto). - Comprobación de preparación de Skills para el agente predeterminado; informa skills permitidas con bins, env, configuración o requisitos de SO faltantes, 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 de API remota o binario QMD). - Comprobaciones de instalación desde código fuente (desajuste de workspace pnpm, assets de IU faltantes, binario tsx faltante). - Escribe configuración actualizada + metadatos del asistente. ## Relleno y restablecimiento de la IU Dreams La escena Dreams de la IU de Control incluye acciones **Rellenar**, **Restablecer** y **Borrar Grounded** para el flujo de trabajo de grounded dreaming. Estas acciones usan métodos RPC estilo doctor del Gateway, pero **no** forman parte de la reparación/migración de la CLI `openclaw doctor`. Qué hacen: - **Rellenar** escanea archivos históricos `memory/YYYY-MM-DD.md` en el workspace activo, ejecuta la pasada del diario REM grounded y escribe entradas de relleno reversibles en `DREAMS.md`. - **Restablecer** elimina solo esas entradas marcadas del diario de relleno de `DREAMS.md`. - **Borrar Grounded** elimina solo entradas staged grounded-only de corto plazo que vinieron de una reproducción histórica y todavía no han acumulado recuerdo en vivo ni soporte diario. Qué **no** hacen por sí mismas: - no editan `MEMORY.md` - no ejecutan migraciones completas de doctor - no preparan automáticamente candidatos grounded en el almacén de promoción de corto plazo en vivo a menos que ejecutes explícitamente primero la ruta staged de la CLI Si quieres que la reproducción histórica grounded influya en la ruta normal de promoción profunda, usa el flujo de la CLI en su lugar: ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` Eso prepara candidatos duraderos grounded en el almacén de dreaming de corto plazo mientras mantiene `DREAMS.md` como superficie de revisión. ## Comportamiento detallado y justificación Si esto es un checkout de 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 sobrescritura 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.`, y la configuración de voz en tiempo real es `talk.realtime.*`. Doctor reescribe las formas antiguas `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` en el mapa de proveedor, y reescribe selectores heredados superiores en tiempo real (`talk.mode`, `talk.transport`, `talk.brain`, `talk.model`, `talk.voice`) a `talk.realtime`. Doctor también advierte cuando `plugins.allow` no está vacío y la política de herramientas usa entradas de herramientas comodín o propiedad de Plugin. `tools.allow: ["*"]` solo coincide con herramientas de plugins que realmente se cargan; no omite la allowlist exclusiva de Plugin. Doctor escribe `plugins.bundledDiscovery: "compat"` para configuraciones heredadas migradas de allowlist para preservar el comportamiento existente de proveedores empaquetados, y luego apunta a la configuración más estricta `"allowlist"`. 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 arranque del Gateway rechaza formatos de configuración heredados y te pide que ejecutes `openclaw doctor --fix`; no reescribe `openclaw.json` al arrancar. 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` - configuraciones de canales configurados sin política visible de respuesta → `messages.groupChat.visibleReplies: "message_tool"` - `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.` - 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.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.` - `messages.tts.provider: "edge"` y `messages.tts.providers.edge` → `messages.tts.provider: "microsoft"` y `messages.tts.providers.microsoft` - `channels.discord.voice.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.voice.tts.providers.` - `channels.discord.accounts..voice.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.accounts..voice.tts.providers.` - `plugins.entries.voice-call.config.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `plugins.entries.voice-call.config.tts.providers.` - `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 persistentes, mueve 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 con nombre/predeterminado coincidente existente) - `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` - elimina `agents.defaults.llm`; usa `models.providers..timeoutSeconds` para tiempos de espera de proveedores/modelos lentos - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` - elimina `browser.relayBindHost` (configuración heredada del relay de la extensión) - `models.providers.*.api: "openai"` heredado → `"openai-completions"` (el inicio del Gateway también omite proveedores cuyo `api` esté configurado con un valor de enumeración futuro o desconocido en lugar de fallar en modo cerrado) - elimina `plugins.entries.codex.config.codexDynamicToolsProfile`; el servidor de app de Codex siempre mantiene nativas las herramientas nativas de espacio de trabajo de Codex Las advertencias de Doctor también incluyen orientación sobre cuentas predeterminadas para canales multicuenta: - Si se configuran dos o más entradas `channels..accounts` sin `channels..defaultAccount` ni `accounts.default`, doctor advierte que el enrutamiento de respaldo puede elegir una cuenta inesperada. - Si `channels..defaultAccount` se define con un ID de cuenta desconocido, doctor advierte y enumera los ID de cuenta configurados. Si agregaste `models.providers.opencode`, `opencode-zen` u `opencode-go` manualmente, eso sobrescribe el catálogo OpenCode integrado de `@earendil-works/pi-ai`. Eso puede forzar modelos a la API incorrecta o poner los costos en cero. Doctor advierte para que puedas eliminar la sobrescritura y restaurar el enrutamiento de API + costos por modelo. 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"` - se elimina `browser.relayBindHost` 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 la configuración del lado de Chrome por ti. Chrome MCP local al host todavía 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í solo trata sobre los prerrequisitos 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 todavía requieren un navegador administrado o un perfil CDP sin procesar. Esta comprobación **no** se aplica a Docker, sandbox, remote-browser ni 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 vencido 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á saludable. Si antes agregaste configuraciones heredadas de transporte de OpenAI bajo `models.providers.openai-codex`, pueden ocultar la ruta integrada del proveedor OAuth de Codex que las versiones más nuevas usan automáticamente. Doctor advierte cuando ve esas configuraciones antiguas de transporte junto con OAuth de Codex para que puedas eliminar o reescribir la sobrescritura de transporte obsoleta y recuperar el comportamiento integrado de enrutamiento/respaldo. Los proxies personalizados y las sobrescrituras solo de encabezados siguen siendo compatibles y no activan esta advertencia. Doctor comprueba referencias de modelo heredadas `openai-codex/*`. El enrutamiento nativo del arnés de Codex usa referencias de modelo canónicas `openai/*`; los turnos de agente de OpenAI pasan por el arnés del servidor de app de Codex en lugar de la ruta OpenAI de OpenClaw PI. En modo `--fix` / `--repair`, doctor reescribe referencias afectadas del agente predeterminado y por agente, incluidos modelos principales, respaldos, sobrescrituras de Heartbeat/subagente/Compaction, hooks, sobrescrituras de modelo de canal y estado obsoleto persistido de ruta de sesión: - `openai-codex/gpt-*` se convierte en `openai/gpt-*`. - La intención de Codex pasa a entradas `agentRuntime.id: "codex"` con ámbito de proveedor/modelo para las referencias de modelo de agente reparadas, de modo que los perfiles de autenticación `openai-codex:...` todavía puedan seleccionarse después de que la referencia de modelo se convierta en `openai/*`. - Se eliminan la configuración obsoleta de runtime de agente completo y los pines persistidos de runtime de sesión 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 ruta de autenticación anterior. - Las listas existentes de respaldos de modelo se conservan con sus entradas heredadas reescritas; las configuraciones por modelo copiadas se mueven de la clave heredada a la clave canónica `openai/*`. - `modelProvider`/`providerOverride`, `model`/`modelOverride`, avisos de respaldo y pines de perfil de autenticación de sesiones persistidas se reparan en todos los almacenes de sesiones de agentes descubiertos. - `/codex ...` significa "controlar o vincular una conversación nativa de Codex desde el chat". - `/acp ...` o `runtime: "acp"` significa "usar el adaptador externo ACP/acpx". Doctor también analiza los almacenes descubiertos de sesiones de agentes 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 limpiar estado obsoleto creado automáticamente, como pines de modelo `modelOverrideSource: "auto"`, metadatos de modelo de runtime, IDs de arnés fijados, vinculaciones de sesión de 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 heredadas de modelo de sesión se notifican 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//sessions/` - Directorio del agente: - de `~/.openclaw/agent/` a `~/.openclaw/agents//agent/` - Estado de autenticación de WhatsApp (Baileys): - de `~/.openclaw/credentials/*.json` heredado (excepto `oauth.json`) - a `~/.openclaw/credentials/whatsapp//...` (ID de cuenta predeterminado: `default`) Estas migraciones son de mejor esfuerzo e idempotentes; doctor emitirá advertencias cuando deje carpetas heredadas como copias de seguridad. El Gateway/CLI también migra automáticamente el almacén de sesiones heredado + el directorio del agente al iniciar, para que el historial/la autenticación/los modelos lleguen a 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 repetidos sin efecto de `doctor --fix`. Doctor analiza todos los manifiestos de Plugin 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 in situ. 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 cron (`~/.openclaw/cron/jobs.json` de forma predeterminada, o `cron.store` cuando se sobrescribe) en busca de formatos antiguos de trabajos que el programador todavía acepta por compatibilidad. Las limpiezas cron actuales incluyen: - `jobId` → `id` - `schedule.cron` → `schedule.expr` - campos de carga útil de nivel superior (`message`, `model`, `thinking`, ...) → `payload` - campos de entrega de nivel superior (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` - alias de entrega `provider` de la carga útil → `delivery.channel` explícito - trabajos simples heredados de respaldo de webhook `notify: true` → `delivery.mode="webhook"` explícito con `delivery.to=cron.webhook` Doctor solo migra automáticamente los trabajos `notify: true` cuando puede hacerlo sin cambiar el comportamiento. Si un trabajo combina el respaldo de notificación heredado con un modo de entrega existente que no es webhook, doctor advierte y deja ese trabajo para revisión manual. En Linux, doctor también advierte cuando el crontab del usuario aún invoca el script heredado `~/.openclaw/bin/ensure-whatsapp.sh`. Ese script local del host no lo mantiene 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 quedan cuando una sesión termina 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, más de 30 minutos, 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 archivos de bloqueo obsoletos; de lo contrario, imprime una nota y te indica que vuelvas a ejecutarlo con `--fix`. Doctor analiza 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 runtime 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 una 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 detecta una discordancia 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 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 con escrituras de sesiones y credenciales. - **Faltan directorios de sesión**: `sessions/` y el directorio de almacenamiento de sesiones son necesarios para conservar el historial y evitar bloqueos `ENOENT`. - **Discrepancia 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` en distintos 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 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 el grupo o por todos y ofrece restringirlo a `600`. Doctor inspecciona los perfiles 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. Las solicitudes 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 de forma permanente (por ejemplo `refresh_token_reused`, `invalid_grant`, o un proveedor te indica que inicies 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 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) Si `hooks.gmail.model` está establecido, 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 sandbox está habilitado, doctor comprueba las imágenes de Docker y ofrece compilarlas o cambiar a nombres heredados si falta la imagen actual. Doctor elimina el estado heredado de preparación de dependencias de plugins generado por OpenClaw 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 paquetes de código anterior de reparación de dependencias de plugins incluidos y copias administradas de npm 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 administrados que declaran `peerDependencies.openclaw`, para que las importaciones de runtime locales del paquete como `openclaw/plugin-sdk/*` sigan resolviéndose después de actualizaciones o reparaciones de npm. Doctor también puede reinstalar plugins descargables faltantes cuando la configuración los referencia pero el registro local de plugins no puede encontrarlos. Los ejemplos incluyen `plugins.entries` materiales, configuraciones de canal/proveedor/búsqueda configuradas y runtimes de agente configurados. Durante actualizaciones de paquetes, 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 de 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 de gateway actual. También puede buscar servicios adicionales similares a 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 de nivel de usuario pero existe un servicio de gateway de OpenClaw de nivel de sistema, doctor no instala automáticamente un segundo servicio de nivel de usuario. Inspecciona con `openclaw gateway status --deep` o `openclaw doctor --deep`, luego elimina el duplicado o establece `OPENCLAW_SERVICE_REPAIR_POLICY=external` cuando un supervisor del sistema es responsable 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 de la comprobación normal de salud. Qué 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 discrepancia 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 sin un token activo para un rol aprobado - tokens emparejados cuyos alcances se desvían fuera de la línea base de emparejamiento aprobada - entradas de token de dispositivo en caché local para la máquina actual anteriores a una rotación de token del lado del gateway o con metadatos de alcance obsoletos Doctor no aprueba automáticamente solicitudes de emparejamiento ni rota automáticamente tokens de dispositivo. En su lugar, imprime los pasos siguientes exactos: - inspeccionar solicitudes pendientes con `openclaw devices list` - aprobar la solicitud exacta con `openclaw devices approve ` - rotar un token nuevo con `openclaw devices rotate --device --role ` - eliminar y volver a aprobar un registro obsoleto con `openclaw devices remove ` Esto cierra el hueco común de "ya emparejado pero todavía aparece que se requiere emparejamiento": doctor ahora distingue el emparejamiento por primera vez de las actualizaciones pendientes de rol/alcance y de la deriva de token/identidad de dispositivo obsoletos. Doctor emite advertencias cuando un proveedor está abierto a mensajes directos sin una allowlist, o cuando una política está configurada de forma peligrosa. Si se ejecuta como servicio de usuario de systemd, doctor se asegura de que linger esté habilitado para que el gateway permanezca 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 allowlist. - **Directorios de espacio de trabajo heredados**: advierte cuando `~/openclaw` u otros directorios de espacio de trabajo heredados existen junto al espacio de trabajo actual. - **Estado de Plugin**: cuenta plugins habilitados/deshabilitados/con error; enumera IDs de plugin para cualquier error; informa capacidades de plugins incluidos. - **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 plugins. 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 recuentos por archivo de caracteres sin procesar frente a inyectados, porcentaje de truncamiento, causa de truncamiento (`max/file` o `max/total`) y caracteres inyectados totales como fracción del presupuesto total. Cuando los archivos se truncan o están 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.`, destinos de Heartbeat que nombraban el canal y sobrescrituras `agents.*.models["/*"]`. Esto evita bucles de arranque de Gateway donde el runtime del canal ya no existe pero la configuración aún pide al gateway enlazarse a él. Doctor comprueba si el autocompletado con tabulación está instalado para el shell actual (zsh, bash, fish o PowerShell): - Si el perfil de shell usa un patrón de completado dinámico lento (`source <(openclaw completion ...)`), doctor lo actualiza a la variante de archivo en caché más rápida. - Si el completado está configurado en el perfil pero falta el archivo de caché, doctor regenera la caché automáticamente. - Si no hay ningún completado 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 en tiempo de ejecución. - `openclaw doctor --fix` ahora usa el mismo modelo de resumen SecretRef de solo lectura que los comandos de la familia de estado para reparaciones de configuración dirigidas. - Ejemplo: la reparación de `allowFrom` / `groupAllowFrom` `@username` de Telegram intenta usar 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 bloquearse o informar incorrectamente que falta el token. Doctor ejecuta una comprobación de estado y ofrece reiniciar el gateway cuando parece no estar saludable. Doctor comprueba si el proveedor configurado de embeddings de búsqueda de 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 puede iniciarse. Si no, imprime orientación de corrección, incluido el paquete npm y una opción de ruta manual al binario. - **Proveedor local explícito**: comprueba si hay 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 sugerencias de corrección accionables si falta. - **Proveedor automático**: comprueba primero la disponibilidad del modelo local y luego prueba cada proveedor remoto en el orden de selección automática. Cuando hay disponible un resultado de sondeo del gateway en caché (el gateway estaba saludable en el momento de la comprobación), doctor contrasta 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 tiempo de ejecución. Si el gateway está saludable, doctor ejecuta un sondeo de estado de canal e informa advertencias con correcciones sugeridas. Doctor comprueba la configuración del supervisor instalada (launchd/systemd/schtasks) en busca de valores predeterminados faltantes u obsoletos (por ejemplo, dependencias de systemd `network-online` y retraso 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 las solicitudes de reparación predeterminadas. - `openclaw doctor --repair` aplica las correcciones recomendadas sin solicitudes. - `openclaw doctor --repair --force` sobrescribe configuraciones personalizadas del supervisor. - `OPENCLAW_SERVICE_REPAIR_POLICY=external` mantiene doctor en solo lectura para el ciclo de vida del servicio del gateway. Aún informa el estado del servicio y ejecuta reparaciones que no son de servicio, pero omite la instalación/inicio/reinicio/bootstrap del servicio, las reescrituras de configuración del supervisor y la limpieza de servicios heredados porque un supervisor externo posee ese ciclo de vida. - En Linux, doctor no reescribe metadatos de comando/punto de entrada mientras la unidad systemd de gateway correspondiente está activa. También ignora unidades adicionales inactivas no heredadas similares a gateway durante el escaneo de servicios duplicados para que los archivos de servicio 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 conserva valores de token en texto sin formato resueltos 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 tiempo de ejecución 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 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 systemd de usuario de Linux, las comprobaciones de desviación de token de doctor ahora incluyen fuentes tanto `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](/es/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). - Siempre puedes forzar una reescritura completa mediante `openclaw gateway install --force`. Doctor inspecciona el tiempo de ejecución del servicio (PID, último estado de salida) y advierte cuando el servicio está instalado pero no está realmente en ejecución. 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 de gateway se ejecuta en Bun o en una ruta de Node administrada 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). Los LaunchAgents de macOS recién instalados o reparados usan un PATH canónico del sistema (`/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) en lugar de copiar el PATH del shell interactivo, de modo que los binarios del sistema administrados por Homebrew sigan disponibles mientras Volta, asdf, fnm, pnpm y otros directorios de gestores de versiones no cambian qué procesos secundarios 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 conserva cualquier cambio de configuración y marca metadatos del asistente para registrar la ejecución de doctor. 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](/es/concepts/agent-workspace) para obtener una guía completa sobre la estructura del espacio de trabajo y la copia de seguridad con git (GitHub o GitLab privado recomendado). ## Relacionado - [Runbook del Gateway](/es/gateway) - [Solución de problemas del Gateway](/es/gateway/troubleshooting)