openclaw update

Actualiza OpenClaw y cambia entre los canales stable/extended-stable/beta/dev.

Si se instaló mediante npm/pnpm/bun (instalación global, sin metadatos de git), las actualizaciones siguen 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 lanzamiento).

Opciones

No existe ningún indicador --verbose. Se usa --dry-run para obtener una vista previa de las acciones previstas, --json para obtener resultados legibles por máquina y openclaw update status --json solo para consultar el canal y la disponibilidad. El nivel de detalle de la consola del Gateway (--verbose) y el nivel de registro de archivos (logging.level: "debug"/"trace") son controles independientes; véase Registro del Gateway.

update status

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

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

Para las instalaciones de paquetes extended-stable, el estado realiza la misma selección pública y verificación exacta del paquete que la actualización en primer plano. Puede indicar ahead of extended-stable cuando la versión instalada es más reciente. Los errores 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 del núcleo ya haya cambiado, pero las tareas de reparación posteriores no hayan terminado correctamente. Esta es la ruta de recuperación compatible cuando openclaw update instaló el nuevo paquete del núcleo, pero la sincronización de plugins posterior a la actualización del núcleo, los metadatos de plugins de 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 rastreados para el canal de actualización activo, actualiza las instalaciones administradas de plugins de npm, repara las cargas útiles faltantes 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 del núcleo 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 (de forma predeterminada, se reinicia). Al seleccionar dev sin un checkout de git, se ofrece la posibilidad de crear uno.

Qué hace

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

• dev -> garantiza que exista un checkout de git (de forma predeterminada, ~/openclaw, o $OPENCLAW_HOME/openclaw cuando se establece OPENCLAW_HOME; se puede reemplazar con OPENCLAW_GIT_DIR), lo actualiza e instala la CLI global desde ese checkout.
• 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 para los checkouts de Git.
• beta -> da preferencia a la etiqueta de distribución beta de npm y recurre a latest cuando la versión beta no existe o es anterior a la versión estable actual.

Transferencia del reinicio

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

Las selecciones de estabilidad extendida 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. 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 siguen siendo compatibles.

Cuando hay instalado un servicio Gateway administrado local y el reinicio está habilitado, las actualizaciones mediante el gestor de paquetes y mediante un 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.. Además, las actualizaciones mediante el gestor de paquetes verifican que el Gateway reiniciado informe la versión esperada del paquete; las actualizaciones mediante un checkout de Git verifican el estado del Gateway y la disponibilidad del servicio después de la recompilación.

Normalmente, 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 demostrado que el servicio pertenece al paquete que se está actualizando, una actualización con 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 la misma incompatibilidad 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 y en ejecución para el perfil activo y que el puerto de bucle invertido configurado funcione correctamente. Si el plist está instalado, pero launchd no lo está supervisando, 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 termina 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 se puede ejecutar 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.

Formato de respuesta del plano de control

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

• 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 proceso auxiliar desacoplado 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 supervisado 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 de procesos systemd del entorno). 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 proceso auxiliar desacoplado.

La carga útil sentinel se escribe antes de que el Gateway termine, y el traspaso de la CLI actualiza ese mismo indicador de reinicio después de que finalicen las comprobaciones de estado del reinicio del servicio administrado. Durante el traspaso, el indicador puede contener stats.reason: "restart-health-pending" sin continuación de éxito; el Gateway reiniciado lo sondea y activa la continuación únicamente después de que la CLI haya verificado el estado del servicio y reescrito el indicador con el resultado final ok. openclaw status y openclaw status --all muestran una fila Update restart mientras ese indicador está pendiente o ha fallado, y update.status actualiza y devuelve el indicador 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: prioriza la etiqueta -beta más reciente y recurre a la etiqueta stable más reciente cuando no existe una beta o esta es más antigua.
• dev: obtiene main y, a continuación, descarga los cambios y ejecuta rebase.
• extended-stable: no es compatible con los checkouts de Git; no se produce ninguna modificación del checkout.

Pasos de actualización

Detalles de la sincronización de plugins

En el canal beta, las instalaciones de plugins de npm y ClawHub con seguimiento que siguen la línea predeterminada/latest intentan 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 hacen que falle 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 de estabilidad extendida se complete correctamente, la integridad y la convergencia de los plugins posteriores al núcleo se aplican a los plugins oficiales de npm aptos en la versión exacta instalada del núcleo. Para la intención predeterminada/latest, OpenClaw no consulta @extended-stable del plugin ni recurre a latest de npm; deriva la versión del paquete a partir 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.

Para las instalaciones mediante gestores de paquetes, openclaw update resuelve la versión de destino del paquete 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 empaquetado dist. Una protección de finalización empaquetada permanece fuera de ese inventario hasta que preinstall se completa 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 de la versión candidata de 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, doctor posterior a la actualización, la sincronización de plugins y las tareas de 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 los comandos del núcleo y las tareas de reinicio. Esto mantiene los componentes auxiliares empaquetados y los registros de plugins propiedad del canal alineados con la compilación instalada de OpenClaw, mientras que reserva las recompilaciones 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