openclaw update

Actualiza OpenClaw y cambia entre los canales estable/estable extendido/beta/dev.

Si se instaló mediante npm/pnpm/bun (instalación global, sin metadatos de git), las actualizaciones se realizan mediante el flujo del gestor de paquetes descrito en Actualización.

Uso

openclaw updateopenclaw update statusopenclaw update repairopenclaw update wizardopenclaw update --channel extended-stableopenclaw update --channel betaopenclaw update --channel devopenclaw update --tag betaopenclaw update --tag mainopenclaw update --dry-runopenclaw update --no-restartopenclaw update --yesopenclaw update --acknowledge-clawhub-riskopenclaw update --jsonopenclaw --update

openclaw --update se reescribe como openclaw update (útil para shells y scripts de inicio).

Opciones

No existe el indicador --verbose. Use --dry-run para previsualizar las acciones previstas, --json para obtener resultados legibles por máquinas y openclaw update status --json solo para consultar el canal y la disponibilidad. El nivel de detalle de la consola de Gateway (--verbose) y el nivel de registro en archivos (logging.level: "debug"/"trace") son controles independientes; consulte Registro de Gateway.

update status

Muestra el canal de actualización activo, la etiqueta/rama/SHA de git (solo en copias de trabajo del código fuente) y la disponibilidad de actualizaciones.

openclaw update statusopenclaw update status --jsonopenclaw update status --timeout 10

Para las instalaciones de paquetes del canal estable extendido, el estado realiza el mismo selector público y la misma verificación exacta del paquete que la actualización en primer plano. Puede informar de ahead of extended-stable cuando la versión instalada es más reciente. Los errores de JSON incluyen registry.reason (selector_missing, selector_query_failed, exact_package_mismatch o unsupported_git_channel).

update repair

Vuelve a ejecutar la finalización de la actualización después de que el paquete principal ya haya cambiado, pero las tareas de reparación posteriores no hayan finalizado correctamente. Esta es la ruta de recuperación compatible cuando openclaw update instaló el nuevo paquete principal, pero la sincronización de plugins posterior, los metadatos de plugins npm administrados, la actualización del registro o la reparación de Doctor no convergieron.

openclaw update repairopenclaw update repair --channel betaopenclaw update repair --acknowledge-clawhub-riskopenclaw update repair --json

update repair ejecuta openclaw doctor --fix, vuelve a cargar la configuración reparada y los registros de instalación, sincroniza los plugins registrados para el canal de actualización activo, actualiza las instalaciones administradas de plugins npm, repara las cargas útiles que faltan de los plugins configurados, actualiza el registro de plugins y escribe los metadatos convergentes de los registros de instalación. No instala un nuevo paquete principal ni reinicia el Gateway.

update wizard

Flujo interactivo para elegir un canal de actualización y confirmar si se debe reiniciar el Gateway después (se reinicia de forma predeterminada). Al seleccionar dev sin una copia de trabajo de git, se ofrece crear una.

Qué hace

El cambio explícito de canal (--channel ...) también mantiene alineado el método de instalación:

• dev -> garantiza que haya una copia de trabajo de git (~/openclaw de forma predeterminada, o $OPENCLAW_HOME/openclaw cuando se establece OPENCLAW_HOME; se puede sustituir con OPENCLAW_GIT_DIR), la actualiza e instala la CLI global desde esa copia de trabajo.
• stable -> instala desde npm mediante latest.
• extended-stable -> resuelve el selector público extended-stable de npm, verifica el paquete exacto seleccionado e instala esa versión exacta. No recurre a otro selector y se rechaza en las copias de trabajo de Git.
• beta -> da preferencia a la etiqueta de distribución beta de npm y recurre a latest cuando la versión beta no está disponible o es anterior a la versión estable actual.

Transferencia del reinicio

El actualizador automático del núcleo de Gateway (cuando está habilitado mediante la configuración) inicia la ruta de actualización de la CLI fuera del controlador de solicitudes activo de Gateway. Las actualizaciones mediante el gestor de paquetes de update.run del plano de control y las actualizaciones supervisadas de copias de trabajo de git usan la misma transferencia del servicio administrado en lugar de sustituir el árbol de paquetes o recompilar dist/ dentro del proceso activo de Gateway: Gateway inicia un proceso auxiliar independiente y finaliza, y ese proceso auxiliar ejecuta openclaw update --yes --json desde fuera del árbol de procesos de Gateway. Si la transferencia no está disponible, update.run devuelve una respuesta estructurada con el comando seguro del shell que debe ejecutarse manualmente.

Las selecciones extended-stable almacenadas reciben indicaciones de inicio de solo lectura y de actualización cada 24 horas cuando update.checkOnStart está habilitado. Estas comprobaciones nunca aplican una actualización, inician un traspaso, reinician el Gateway, usan el retraso o la variación aleatoria de stable ni usan la cadencia de sondeo de beta. Se siguen admitiendo las actualizaciones explícitas en primer plano, las actualizaciones sin argumentos en primer plano con update.channel: "extended-stable" almacenado, el estado bajo demanda y su traspaso administrado del Gateway.

Cuando hay instalado un servicio local administrado del Gateway y el reinicio está habilitado, las actualizaciones mediante el gestor de paquetes y el checkout de Git detienen el servicio en ejecución antes de reemplazar el árbol de paquetes o modificar la salida del checkout o de la compilación. A continuación, el actualizador renueva los metadatos del servicio, reinicia el servicio y verifica el Gateway reiniciado antes de informar Gateway: restarted and verified.. Las actualizaciones mediante el gestor de paquetes también verifican que el Gateway reiniciado informe la versión esperada del paquete; las actualizaciones del checkout de Git verifican el estado del Gateway y la disponibilidad del servicio después de la recompilación.

Por lo general, las actualizaciones mediante el gestor de paquetes siguen usando el binario de Node registrado en el servicio administrado. Si ese Node no puede ejecutar la versión de destino, pero el Node de la CLI actual sí puede y se ha comprobado que el servicio pertenece al paquete que se está actualizando, una actualización con el reinicio habilitado usa el Node actual para la finalización y reescribe los metadatos del servicio para ese entorno de ejecución. --no-restart no puede reparar los metadatos del servicio, por lo que el mismo conflicto del entorno de ejecución detiene el proceso antes de modificar el paquete.

En macOS, la comprobación posterior a la actualización también verifica que el LaunchAgent esté cargado o en ejecución para el perfil activo y que el puerto de bucle invertido configurado esté en buen estado. Si el plist está instalado, pero launchd no lo supervisa, OpenClaw vuelve a inicializar automáticamente el LaunchAgent y repite las comprobaciones de estado, versión y disponibilidad del canal (una inicialización nueva carga directamente el trabajo RunAtLoad, por lo que la recuperación no ejecuta inmediatamente kickstart -k en el Gateway recién iniciado). Si el Gateway sigue sin alcanzar un estado correcto, el comando finaliza con un código distinto de cero e imprime la ruta del registro de reinicio, además de instrucciones para reiniciar, reinstalar y revertir el paquete.

Si no es posible realizar el reinicio, el comando imprime Gateway: restart skipped (...) o Gateway: restart failed: ... con una indicación manual de openclaw gateway restart. Con --no-restart, el reemplazo del paquete o la recompilación de Git se siguen ejecutando, pero el servicio administrado no se detiene ni se reinicia, por lo que el Gateway en ejecución conserva el código anterior hasta que se reinicie manualmente.

Estructura de la respuesta del plano de control

Cuando update.run se ejecuta mediante el plano de control del Gateway en una instalación del gestor de paquetes o un checkout de Git supervisado, el controlador informa del inicio del traspaso por separado de la actualización de la CLI que continúa después de que el Gateway finaliza:

• ok: true, result.status: "skipped", result.reason: "managed-service-handoff-started" y handoff.status: "started": el Gateway creó el traspaso del servicio administrado y programó su propio reinicio para que el auxiliar desvinculado pueda ejecutar openclaw update --yes --json fuera del proceso activo del servicio.
• ok: false, result.reason: "managed-service-handoff-unavailable" y handoff.status: "unavailable": OpenClaw no pudo encontrar un límite de servicio supervisor ni una identidad de servicio persistente para realizar un traspaso seguro (por ejemplo, el traspaso de systemd requiere la identidad de unidad OPENCLAW_SYSTEMD_UNIT, no solo indicadores ambientales del proceso systemd). La respuesta incluye handoff.command, el comando de shell que se debe ejecutar desde fuera del Gateway.
• ok: false, result.reason: "managed-service-handoff-failed": el Gateway intentó crear el traspaso, pero no pudo iniciar el auxiliar desvinculado.

La carga útil sentinel se escribe antes de que finalice el Gateway y el traspaso de la CLI actualiza ese mismo centinela de reinicio después de que finalicen las comprobaciones de estado del reinicio del servicio administrado. Durante el traspaso, el centinela puede contener stats.reason: "restart-health-pending" sin ninguna continuación correcta; el Gateway reiniciado lo sondea y activa la continuación solo después de que la CLI haya verificado el estado del servicio y reescrito el centinela con el resultado final ok. openclaw status y openclaw status --all muestran una fila Update restart mientras ese centinela está pendiente o ha fallado, y update.status actualiza y devuelve el centinela más reciente.

Flujo de checkout de Git

Selección del canal

• stable: obtiene la etiqueta no beta más reciente y, a continuación, compila y ejecuta doctor.
• beta: prefiere la etiqueta -beta más reciente y recurre a la etiqueta stable más reciente cuando beta no existe o es más antigua.
• dev: obtiene main y, a continuación, recupera los cambios y ejecuta rebase.
• extended-stable: no se admite en los checkouts de Git; no se modifica el checkout.

Pasos de actualización

Detalles de la sincronización de plugins

En el canal beta, las instalaciones registradas de plugins de npm y ClawHub que siguen la línea predeterminada/latest prueban primero una versión @beta del plugin. Si el plugin no tiene una versión beta, OpenClaw recurre a la especificación predeterminada/latest registrada e informa de una advertencia. Para los plugins de npm, OpenClaw también recurre a la alternativa cuando el paquete beta existe, pero no supera la validación de instalación. Estas advertencias de uso de alternativas no provocan un error en la actualización del núcleo. Las versiones exactas y las etiquetas explícitas nunca se reescriben.

Después de que una actualización del núcleo extended-stable finalice correctamente, la integridad y la convergencia de plugins posteriores a la actualización del núcleo se aplican a los plugins npm oficiales aptos en la versión exacta del núcleo instalada. Para la intención predeterminada/latest, OpenClaw no consulta @extended-stable del plugin ni recurre a latest de npm; obtiene la versión del paquete del núcleo instalado. Las versiones fijadas explícitamente, las etiquetas explícitas distintas de latest, los paquetes de terceros y las fuentes que no sean npm conservan su intención existente.

En las instalaciones mediante el gestor de paquetes, openclaw update resuelve la versión del paquete de destino antes de invocar el gestor de paquetes. Las instalaciones globales de npm usan una instalación por etapas: OpenClaw instala el nuevo paquete en un prefijo temporal de npm, permite que el paquete candidato valide la versión de Node del host durante preinstall y verifica allí el inventario dist incluido. Una protección de finalización incluida permanece fuera de ese inventario hasta que preinstall finaliza correctamente, por lo que los gestores de paquetes que omiten los scripts del ciclo de vida también se detienen antes de la activación. En npm 12 y versiones posteriores, el actualizador aprueba únicamente el ciclo de vida del candidato OpenClaw; los scripts de dependencias transitivas permanecen bloqueados. A continuación, OpenClaw intercambia el árbol de paquetes limpio en el prefijo global real. Si la verificación falla, las tareas de doctor posteriores a la actualización, sincronización de plugins y reinicio no se ejecutan desde el árbol sospechoso. Incluso cuando la versión instalada ya coincide con la de destino, el comando renueva la instalación global del paquete y, a continuación, ejecuta la sincronización de plugins, una renovación de finalización de comandos del núcleo y las tareas de reinicio. Esto mantiene los componentes auxiliares incluidos y los registros de plugins pertenecientes al canal alineados con la compilación instalada de OpenClaw, al tiempo que reserva las reconstrucciones completas de finalización de comandos de plugins para ejecuciones explícitas de openclaw completion --write-state.

Contenido relacionado

• openclaw doctor (ofrece ejecutar primero la actualización en los checkouts de Git)
• Canales de desarrollo
• Actualización
• Referencia de la CLI