openclaw update

Actualiza OpenClaw de forma segura y cambia entre los canales stable/beta/dev.

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

Uso

openclaw updateopenclaw update statusopenclaw update repairopenclaw update wizardopenclaw 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

Opciones

• --no-restart: omite reiniciar el servicio Gateway después de una actualización correcta. Las actualizaciones del gestor de paquetes que sí reinician el Gateway verifican que el servicio reiniciado informe la versión actualizada esperada antes de que el comando se complete correctamente.
• --channel <stable|beta|dev>: establece el canal de actualización (git + npm; persistido en la configuración).
• --tag <dist-tag|version|spec>: sobrescribe el destino del paquete solo para esta actualización. Para instalaciones de paquetes, main se asigna a github:openclaw/openclaw#main; las especificaciones de origen GitHub/git se empaquetan en un tarball temporal antes de la instalación global de npm por etapas.
• --dry-run: muestra una vista previa de las acciones de actualización planificadas (flujo de canal/etiqueta/destino/reinicio) sin escribir configuración, instalar, sincronizar plugins ni reiniciar.
• --json: imprime JSON UpdateRunResult legible por máquina, incluidos postUpdate.plugins.warnings cuando plugins administrados corruptos o no cargables necesitan reparación después de que la actualización del núcleo se complete correctamente, detalles de reserva de plugins del canal beta cuando un plugin no tiene versión beta, y postUpdate.plugins.integrityDrifts cuando se detecta deriva de artefactos de plugins npm durante la sincronización de plugins posterior a la actualización.
• --timeout <seconds>: tiempo de espera por paso (el valor predeterminado es 1800s).
• --yes: omite las solicitudes de confirmación (por ejemplo, la confirmación de degradación de versión).
• --acknowledge-clawhub-risk: después de revisar las advertencias de confianza de la comunidad de ClawHub, permite que la sincronización de plugins posterior a la actualización continúe sin una solicitud interactiva. Sin esto, las versiones de plugins comunitarios de ClawHub con riesgo se omiten y se dejan sin cambios cuando OpenClaw no puede solicitar confirmación. Los paquetes oficiales de ClawHub y las fuentes de plugins de OpenClaw incluidas omiten esta solicitud de confianza de versión.

openclaw update no tiene una marca --verbose. Usa --dry-run para previsualizar las acciones planificadas de canal/etiqueta/instalación/reinicio, --json para obtener resultados legibles por máquina, y openclaw update status --json cuando solo necesites detalles de canal y disponibilidad. Si estás depurando registros de Gateway alrededor de una actualización, la verbosidad de consola y el nivel de registro en archivo son independientes: Gateway --verbose afecta la salida de terminal/WebSocket, mientras que los registros en archivo requieren logging.level: "debug" o "trace" en la configuración. Consulta Registros de Gateway.

update status

Muestra el canal de actualización activo + etiqueta/rama/SHA de git (para checkouts de origen), además de la disponibilidad de actualización.

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

Opciones:

• --json: imprime JSON de estado legible por máquina.
• --timeout <seconds>: tiempo de espera para comprobaciones (el valor predeterminado es 3s).

update repair

Vuelve a ejecutar la finalización de actualización después de que el paquete principal ya haya cambiado pero el trabajo posterior de reparación no haya terminado correctamente. Esta es la ruta de recuperación admitida cuando openclaw update instaló el nuevo paquete principal pero la sincronización de plugins posterior al núcleo, los metadatos de plugins npm administrados, la actualización del registro o la reparación de doctor aún necesitan converger.

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

Opciones:

• --channel <stable|beta|dev>: persiste el canal de actualización antes de reparar y ejecuta la convergencia de plugins contra ese canal.
• --json: imprime JSON de finalización legible por máquina.
• --timeout <seconds>: tiempo de espera para los pasos de reparación (predeterminado 1800).
• --yes: omite las solicitudes de confirmación.
• --acknowledge-clawhub-risk: después de revisar las advertencias de confianza de la comunidad de ClawHub, permite que la convergencia de plugins durante la reparación continúe sin una solicitud interactiva. Los paquetes oficiales de ClawHub y las fuentes de plugins de OpenClaw incluidas omiten esta solicitud de confianza de versión.
• --no-restart: se acepta por paridad con el comando de actualización; repair nunca reinicia el Gateway.

openclaw update repair ejecuta openclaw doctor --fix, recarga la configuración reparada y los registros de instalación, sincroniza los plugins rastreados para el canal de actualización activo, actualiza las instalaciones de plugins npm administrados, repara payloads de plugins configurados faltantes, actualiza el registro de plugins y escribe los metadatos convergidos del registro 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 actualizar (el valor predeterminado es reiniciar). Si seleccionas dev sin un checkout de git, ofrece crear uno.

Opciones:

• --timeout <seconds>: tiempo de espera para cada paso de actualización (predeterminado 1800)

Qué hace

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

• dev → asegura un checkout de git (predeterminado: ~/openclaw, o $OPENCLAW_HOME/openclaw cuando OPENCLAW_HOME está establecido; sobrescribe con OPENCLAW_GIT_DIR), lo actualiza e instala la CLI global desde ese checkout.
• stable → instala desde npm usando latest.
• beta → prefiere la dist-tag de npm beta, pero recurre a latest cuando beta falta o es anterior a la versión estable actual.

El autoactualizador del núcleo Gateway (cuando está habilitado mediante configuración) inicia la ruta de actualización de la CLI fuera del manejador de solicitudes activo de Gateway. Las actualizaciones de gestor de paquetes de update.run del plano de control y las actualizaciones supervisadas de checkout de git también usan una transferencia de servicio administrado en lugar de reemplazar el árbol de paquetes o reconstruir dist/ dentro del proceso Gateway activo. El Gateway inicia un ayudante desacoplado, sale, y el ayudante ejecuta la ruta normal de la CLI openclaw update --yes --json desde fuera del árbol de procesos de Gateway. Si esa transferencia no está disponible, update.run devuelve una respuesta estructurada con el comando de shell seguro para ejecutar manualmente.

Para instalaciones con 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 nuevo paquete en un prefijo npm temporal, verifica el inventario dist empaquetado allí y luego intercambia ese á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 el trabajo de reinicio no se ejecutan desde el árbol sospechoso. Incluso cuando la versión instalada ya coincide con el destino, el comando actualiza la instalación global del paquete, luego ejecuta la sincronización de plugins, una actualización de finalización de comandos del núcleo y el trabajo de reinicio. Esto mantiene los sidecars empaquetados y los registros de plugins propiedad del canal alineados con la compilación instalada de OpenClaw, mientras deja las reconstrucciones completas de finalización de comandos de plugins para ejecuciones explícitas de openclaw completion --write-state.

Cuando hay instalado un servicio Gateway administrado local y el reinicio está habilitado, las actualizaciones de gestor de paquetes y checkout de git detienen el servicio en ejecución antes de reemplazar el árbol de paquetes o mutar la salida de checkout/compilación. El actualizador luego actualiza los metadatos del servicio desde la instalación actualizada, reinicia el servicio y verifica el Gateway reiniciado antes de informar Gateway: restarted and verified.. Las actualizaciones de gestor de paquetes además verifican que el Gateway reiniciado informe la versión de paquete esperada; las actualizaciones de checkout de git verifican la salud del gateway y la preparación del servicio después de la reconstrucción. En macOS, la comprobación posterior a la actualización también verifica que LaunchAgent esté cargado/en ejecución para el perfil activo y que el puerto loopback configurado esté saludable. Si el plist está instalado pero launchd no lo está supervisando, OpenClaw vuelve a arrancar el LaunchAgent automáticamente, y luego vuelve a ejecutar las comprobaciones de salud/versión/canal. Un arranque nuevo carga el trabajo RunAtLoad directamente, por lo que la recuperación de actualización no ejecuta inmediatamente kickstart -k sobre el Gateway recién generado. Si el Gateway aún no se vuelve saludable, el comando sale con código distinto de cero e imprime la ruta del registro de reinicio más instrucciones explícitas de reinicio, reinstalación y reversión de paquete. Si el reinicio no puede ejecutarse, el comando imprime Gateway: restart skipped (...) o Gateway: restart failed: ... con una sugerencia manual de openclaw gateway restart. Con --no-restart, el reemplazo del paquete o la reconstrucción de git aún se ejecutan, pero el servicio administrado no se detiene ni se reinicia, por lo que el Gateway en ejecución puede conservar el código antiguo hasta que lo reinicies manualmente.

Forma de respuesta del plano de control

Cuando update.run se invoca a través del plano de control de Gateway en una instalación de gestor de paquetes o un checkout de git supervisado, el manejador informa el inicio de la transferencia por separado de la actualización de CLI que continúa después de que Gateway sale:

• ok: true, result.status: "skipped", result.reason: "managed-service-handoff-started", y handoff.status: "started" significan que el Gateway creó la transferencia de servicio administrado y programó su propio reinicio para que el ayudante 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" significan que OpenClaw no pudo encontrar un límite de servicio supervisor y una identidad de servicio duradera para una transferencia segura. Por ejemplo, la transferencia de systemd requiere la identidad de unidad de OpenClaw (OPENCLAW_SYSTEMD_UNIT), no solo marcadores ambientales de proceso systemd. La respuesta incluye handoff.command, el comando de shell que debe ejecutarse desde fuera del Gateway.
• ok: false, result.reason: "managed-service-handoff-failed" significa que el Gateway intentó crear la transferencia pero no pudo iniciar el ayudante desacoplado.

El payload sentinel aún se escribe antes de que el Gateway salga, y la transferencia de CLI actualiza el mismo centinela de reinicio después de que se completen las comprobaciones de salud de reinicio del servicio administrado. Durante la transferencia, el centinela puede llevar stats.reason: "restart-health-pending" sin continuación de éxito; el Gateway reiniciado sigue sondeándolo y solo dispara la continuación después de que la CLI haya verificado la salud 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 fallido, y update.status actualiza y devuelve el centinela más reciente.

Flujo de checkout de git

Selección de canal

• stable: hace checkout de la última etiqueta no beta, luego compila y ejecuta doctor.
• beta: prefiere la última etiqueta -beta, pero recurre a la última etiqueta estable cuando beta falta o es anterior.
• dev: hace checkout de main, luego hace fetch y rebase.

Pasos de actualización

En el canal de actualización 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 versión beta, OpenClaw vuelve a la especificación predeterminada/latest registrada e informa eso como una advertencia. Para plugins de npm, OpenClaw también vuelve atrás cuando el paquete beta existe pero falla la validación de instalación. Estas advertencias de fallback de plugins no hacen que falle la actualización del núcleo. Las versiones exactas y las etiquetas explícitas no se reescriben.

Abreviatura --update

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

Relacionado

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