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

Opciones

No existe el indicador --verbose. Use --dry-run para obtener una vista previa de las acciones planificadas, --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 del Gateway (--verbose) y el nivel de registro en archivos (logging.level: "debug"/"trace") son controles independientes; consulte Registro del 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 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 informar 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 principal ya haya cambiado, pero el trabajo de reparación posterior no haya finalizado correctamente. Esta es la vía de recuperación admitida cuando openclaw update instaló el nuevo paquete principal, pero la sincronización de plugins posterior a la actualización del núcleo, los metadatos de plugins de npm gestionados, la actualización del registro o la reparación mediante 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 con seguimiento para el canal de actualización activo, actualiza las instalaciones de plugins de npm gestionadas, repara las cargas útiles faltantes de plugins configurados, actualiza el registro de plugins y escribe 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 (de forma predeterminada, se reinicia). Al seleccionar dev sin una copia de trabajo de git, se ofrece la posibilidad de crear una.

Qué hace

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

• dev -> garantiza que exista una copia de trabajo de git (de forma predeterminada, ~/openclaw, 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 como alternativa y se rechaza para copias de trabajo de Git.
• beta -> prefiere la etiqueta de distribución beta de npm y recurre a latest como alternativa cuando beta no está disponible o es anterior a la versión estable actual.

Transferencia del reinicio

El actualizador automático del núcleo del Gateway (cuando se habilita 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 copias de trabajo de git utilizan la misma transferencia al servicio gestionado, en lugar de sustituir el árbol de paquetes o recompilar dist/ dentro del proceso activo del Gateway: el Gateway inicia un proceso auxiliar desacoplado y finaliza, y dicho 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 debe ejecutarse manualmente.

Las selecciones de estabilidad extendida almacenadas reciben avisos 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 una transferencia, reinician el Gateway, usan el retraso o la variación aleatoria de estable ni usan la cadencia de sondeo de beta. Siguen siendo compatibles las actualizaciones explícitas en primer plano, las actualizaciones simples en primer plano con update.channel: "extended-stable" almacenado, el estado bajo demanda y su transferencia administrada del Gateway.

Cuando hay instalado un servicio local administrado del Gateway y el reinicio está habilitado, las actualizaciones mediante el gestor de paquetes y desde un checkout de Git detienen el servicio en ejecución antes de reemplazar el árbol de paquetes o modificar el checkout o la salida de 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 indique la versión de paquete esperada; las actualizaciones desde un checkout de Git verifican el estado del gateway y la disponibilidad del servicio después de la recompilación.

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 esté operativo. Si el plist está instalado pero launchd no lo supervisa, OpenClaw vuelve a inicializar el LaunchAgent automáticamente y ejecuta de nuevo 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 estar operativo, 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 para ejecutar manualmente openclaw gateway restart. Con --no-restart, el reemplazo del paquete o la recompilación de Git siguen ejecutándose, 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 del inicio de la transferencia por separado de la actualización de la CLI que continúa después de que el Gateway termina:

• ok: true, result.status: "skipped", result.reason: "managed-service-handoff-started" y handoff.status: "started": el Gateway creó la transferencia del servicio administrado y programó su propio reinicio para que el proceso auxiliar desacoplado pueda ejecutar openclaw update --yes --json fuera del proceso del servicio activo.
• 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 una transferencia segura (por ejemplo, la transferencia de systemd requiere la identidad de unidad OPENCLAW_SYSTEMD_UNIT, no solo marcadores de proceso de systemd presentes en el entorno). La respuesta incluye handoff.command, el comando de shell que debe ejecutarse desde fuera del Gateway.
• ok: false, result.reason: "managed-service-handoff-failed": el Gateway intentó crear la transferencia, pero no pudo iniciar el proceso auxiliar desacoplado.

La carga útil sentinel se escribe antes de que el Gateway termine, y la transferencia de la CLI actualiza ese mismo centinela de reinicio después de que finalicen las comprobaciones de estado posteriores al reinicio del servicio administrado. Durante la transferencia, el centinela puede contener stats.reason: "restart-health-pending" sin una continuación de éxito; 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 ok final. openclaw status y openclaw status --all muestran una fila Update restart mientras ese centinela esté pendiente o haya 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: da preferencia a la etiqueta -beta más reciente y recurre a la etiqueta estable más reciente cuando beta no existe o es más antigua.
• dev: obtiene main y, a continuación, recupera y reorganiza los commits mediante 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 sincronización de plugins

En el canal beta, las instalaciones registradas de plugins de npm y ClawHub que siguen la línea predeterminada o más reciente intentan primero usar una versión @beta del plugin. Si el plugin no tiene una versión beta, OpenClaw recurre a la especificación predeterminada o más reciente 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 finalice correctamente, la integridad y convergencia de plugins posteriores al núcleo se dirigen a los plugins oficiales de npm aptos en la versión exacta del núcleo instalada. Para la intención predeterminada o latest, OpenClaw no consulta @extended-stable del plugin ni recurre a latest de npm; obtiene 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 un gestor de paquetes, openclaw update resuelve la versión de paquete de destino antes de invocar el gestor de paquetes. Las instalaciones globales de npm usan una instalación por etapas: OpenClaw instala el paquete nuevo en un prefijo temporal de npm, verifica allí el inventario de dist del paquete y, a continuación, intercambia ese árbol de paquetes limpio con el prefijo global real. Si la verificación falla, las tareas posteriores de doctor, 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, después, ejecuta la sincronización de plugins, una actualización de la finalización de comandos del núcleo y las tareas de reinicio. Esto mantiene los componentes auxiliares incluidos en el paquete y los registros de plugins propiedad del canal alineados con la compilación instalada de OpenClaw, mientras deja 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 checkouts de Git)
• Canales de desarrollo
• Actualización
• Referencia de la CLI