Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Esta es la lista de verificación dedicada para la validación de actualizaciones y plugins. El objetivo es simple: demostrar que el paquete instalable puede actualizar el estado real del usuario, reparar el estado heredado obsoleto mediante doctor, y seguir instalando, cargando, actualizando y desinstalando plugins desde las fuentes compatibles. Para el mapa más amplio del ejecutor de pruebas, consulta Pruebas. Para claves de proveedores en vivo y conjuntos que tocan la red, consulta Pruebas en vivo.

​
Qué protegemos

Las pruebas de actualización y plugins protegen estos contratos:
  • Un tarball de paquete está completo, tiene un dist/postinstall-inventory.json válido, y no depende de archivos del repositorio sin empaquetar.
  • Un usuario puede pasar de un paquete publicado anterior al paquete candidato sin perder configuración, agentes, sesiones, espacios de trabajo, listas de permitidos de plugins ni configuración de canales.
  • openclaw doctor --fix --non-interactive es responsable de las rutas de limpieza y reparación heredadas. El inicio no debería acumular migraciones de compatibilidad ocultas para el estado obsoleto de plugins.
  • Las instalaciones de plugins funcionan desde directorios locales, repositorios git, paquetes npm y la ruta del registro de ClawHub.
  • Las dependencias npm de plugins se instalan en la raíz npm administrada, se analizan antes de confiar en ellas y se eliminan mediante npm durante la desinstalación para que las dependencias elevadas no permanezcan.
  • La actualización de plugins es estable cuando nada cambió: los registros de instalación, la fuente resuelta, la disposición de dependencias instaladas y el estado habilitado permanecen intactos.

​
Prueba local durante el desarrollo

Empieza con un alcance reducido: 
pnpm changed:lanes --json
pnpm check:changed
pnpm test:changed
Para cambios de instalación, desinstalación, dependencias o inventario de paquete de plugins, ejecuta también las pruebas enfocadas que cubren el punto de unión editado: 
pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts
Antes de que cualquier lane Docker de paquete consuma un tarball, demuestra el artefacto del paquete: 
pnpm release:check
release:check ejecuta comprobaciones de deriva de configuración/docs/API, escribe el inventario dist del paquete, ejecuta npm pack --dry-run, rechaza archivos empaquetados prohibidos, instala el tarball en un prefijo temporal, ejecuta postinstall y prueba superficialmente los puntos de entrada de canales incluidos.

​
Lanes Docker

Las lanes Docker son la prueba a nivel de producto. Instalan o actualizan un paquete real dentro de contenedores Linux y verifican el comportamiento mediante comandos CLI, inicio del Gateway, sondas HTTP, estado RPC y estado del sistema de archivos. Usa lanes enfocadas mientras iteras: 
pnpm test:docker:plugins
pnpm test:docker:plugin-lifecycle-matrix
pnpm test:docker:plugin-update
pnpm test:docker:upgrade-survivor
pnpm test:docker:published-upgrade-survivor
pnpm test:docker:update-restart-auth
pnpm test:docker:update-migration
Lanes importantes:
  • test:docker:plugins valida una prueba superficial de instalación de plugins, instalaciones desde carpetas locales, comportamiento de omisión de actualización en carpetas locales, carpetas locales con dependencias preinstaladas, instalaciones de paquetes file:, instalaciones git con ejecución de CLI, actualizaciones de referencias móviles git, instalaciones desde registro npm con dependencias transitivas elevadas, operaciones sin cambios de actualización npm, instalaciones desde fixtures locales de ClawHub y operaciones sin cambios de actualización, comportamiento de actualización de marketplace, y habilitación/inspección del paquete Claude. Define OPENCLAW_PLUGINS_E2E_CLAWHUB=0 para mantener el bloque de ClawHub hermético/sin conexión.
  • test:docker:plugin-lifecycle-matrix instala el paquete candidato en un contenedor básico, ejecuta un Plugin npm a través de instalación, inspección, deshabilitación, habilitación, actualización explícita, degradación explícita y desinstalación después de eliminar el código del Plugin. Registra métricas RSS y CPU para cada fase.
  • test:docker:plugin-update valida que un Plugin instalado sin cambios no se reinstale ni pierda metadatos de instalación durante openclaw plugins update.
  • test:docker:upgrade-survivor instala el tarball candidato sobre un fixture de usuario antiguo con estado sucio, ejecuta actualización de paquete más doctor no interactivo, luego inicia un Gateway local loopback y verifica la preservación del estado.
  • test:docker:published-upgrade-survivor primero instala una base publicada, la configura mediante una receta openclaw config set integrada, la actualiza al tarball candidato, ejecuta doctor, verifica la limpieza heredada, inicia el Gateway y sondea /healthz, /readyz y el estado RPC.
  • test:docker:update-restart-auth instala el paquete candidato, inicia un Gateway administrado con autenticación por token, elimina las variables de entorno de autenticación del Gateway llamador para openclaw update --yes --json, y exige que el comando de actualización candidato reinicie el Gateway antes de las sondas normales.
  • test:docker:update-migration es la lane de actualización publicada con mucha limpieza. Parte de un estado de usuario configurado al estilo Discord/Telegram, ejecuta doctor en la base para que las dependencias de plugins configurados tengan oportunidad de materializarse, siembra restos heredados de dependencias de plugins para un Plugin empaquetado configurado, actualiza al tarball candidato y exige que doctor posterior a la actualización elimine las raíces de dependencias heredadas.
Variantes útiles de published-upgrade survivor: 
OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.4.23 \
OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=versioned-runtime-deps \
pnpm test:docker:published-upgrade-survivor

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@latest \
OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=bootstrap-persona \
pnpm test:docker:published-upgrade-survivor
Los escenarios disponibles son base, feishu-channel, bootstrap-persona, plugin-deps-cleanup, configured-plugin-installs, stale-source-plugin-shadow, tilde-log-path y versioned-runtime-deps. En ejecuciones agregadas, OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues se expande a todos los escenarios con forma de problemas reportados, incluida la migración de instalación de plugins configurados. La migración de actualización completa está separada intencionalmente de Full Release CI. Usa el flujo de trabajo manual Update Migration cuando la pregunta de lanzamiento sea “¿pueden todas las versiones estables publicadas desde 2026.4.23 en adelante actualizarse a este candidato y limpiar restos de dependencias de plugins?”: 
gh workflow run update-migration.yml \
  --ref main \
  -f workflow_ref=main \
  -f package_ref=main \
  -f baselines=all-since-2026.4.23 \
  -f scenarios=plugin-deps-cleanup

​
Aceptación de paquetes

Package Acceptance es la puerta de paquete nativa de GitHub. Resuelve un paquete candidato en un tarball package-under-test, registra versión y SHA-256, y luego ejecuta lanes Docker E2E reutilizables contra ese tarball exacto. La referencia del arnés del flujo de trabajo está separada de la referencia de origen del paquete, por lo que la lógica de pruebas actual puede validar versiones confiables anteriores. Fuentes candidatas:
  • source=npm: valida openclaw@beta, openclaw@latest o una versión publicada exacta.
  • source=ref: empaqueta una rama, etiqueta o commit confiable con el arnés actual seleccionado.
  • source=url: valida un tarball HTTPS con package_sha256 requerido.
  • source=artifact: reutiliza un tarball cargado por otra ejecución de Actions.
Full Release Validation usa source=artifact de forma predeterminada, construido desde el SHA de lanzamiento resuelto. Para prueba posterior a la publicación, pasa package_acceptance_package_spec=openclaw@YYYY.M.D para que la misma matriz de actualización apunte al paquete npm entregado en su lugar. Las comprobaciones de lanzamiento llaman a Package Acceptance con el conjunto de paquete/actualización/reinicio/plugins: 
doctor-switch update-channel-switch update-corrupt-plugin upgrade-survivor published-upgrade-survivor update-restart-auth plugins-offline plugin-update
Cuando el período de observación de lanzamiento está habilitado, también pasan: 
published_upgrade_survivor_baselines=last-stable-4 2026.4.23 2026.5.2 2026.4.15
published_upgrade_survivor_scenarios=reported-issues
telegram_mode=mock-openai
Esto mantiene la migración de paquetes, el cambio de canal de actualización, la tolerancia a plugins administrados corruptos, la limpieza de dependencias obsoletas de plugins, la cobertura sin conexión de plugins, el comportamiento de actualización de plugins y la QA de paquete de Telegram sobre el mismo artefacto resuelto sin hacer que la puerta predeterminada de paquete de lanzamiento recorra todas las versiones publicadas. last-stable-4 se resuelve a las cuatro versiones estables de OpenClaw publicadas en npm más recientes. La aceptación de paquetes de lanzamiento fija 2026.4.23 como el primer límite de compatibilidad de actualización de plugins, 2026.5.2 como un límite de cambio de arquitectura de plugins, y 2026.4.15 como una base de actualización publicada más antigua de 2026.4.1x; el resolvedor deduplica los pines que ya estén en las cuatro más recientes. Para cobertura exhaustiva de migración de actualización publicada, usa all-since-2026.4.23 en el flujo de trabajo separado Update Migration en lugar de Full Release CI. release-history permanece disponible para muestreo manual más amplio cuando también quieras el ancla heredada anterior a esa fecha. Cuando se seleccionan varias bases de published-upgrade survivor, el flujo de trabajo Docker reutilizable divide cada base en su propio job de ejecutor dirigido. Cada shard de base sigue ejecutando el conjunto de escenarios seleccionado, pero los registros y artefactos permanecen por base y el tiempo total queda limitado por el shard más lento en lugar de un gran job serial. Ejecuta manualmente un perfil de paquete al validar un candidato antes del lanzamiento: 
gh workflow run package-acceptance.yml \
  --ref main \
  -f workflow_ref=main \
  -f source=npm \
  -f package_spec=openclaw@beta \
  -f suite_profile=package \
  -f published_upgrade_survivor_baselines="last-stable-4 2026.4.23 2026.5.2 2026.4.15" \
  -f published_upgrade_survivor_scenarios=reported-issues \
  -f telegram_mode=mock-openai
Usa suite_profile=product cuando la pregunta de lanzamiento incluya canales MCP, limpieza de Cron/subagentes, búsqueda web de OpenAI u OpenWebUI. Usa suite_profile=full solo cuando necesites cobertura completa de la ruta de lanzamiento Docker.

​
Valor predeterminado de lanzamiento

Para candidatos de lanzamiento, la pila de prueba predeterminada es:
  1. pnpm check:changed y pnpm test:changed para regresiones a nivel de código fuente.
  2. pnpm release:check para integridad del artefacto de paquete.
  3. Perfil package de Package Acceptance o las lanes personalizadas de paquete de release-check para contratos de instalación/actualización/reinicio/plugins.
  4. Comprobaciones de lanzamiento entre sistemas operativos para comportamiento específico de instalador, incorporación y plataforma.
  5. Conjuntos en vivo solo cuando la superficie cambiada toca comportamiento de proveedores o servicios alojados.
En máquinas de mantenedores, las puertas amplias y la prueba de producto Docker/paquete deberían ejecutarse en Testbox salvo que se esté haciendo explícitamente prueba local.

​
Compatibilidad heredada

La flexibilidad de compatibilidad es estrecha y limitada en el tiempo:
  • Los paquetes hasta 2026.4.25, incluido 2026.4.25-beta.*, pueden tolerar brechas de metadatos de paquete ya entregadas en Package Acceptance.
  • El paquete publicado 2026.4.26 puede advertir por archivos de sello de metadatos de compilación local ya entregados.
  • Los paquetes posteriores deben satisfacer los contratos modernos. Las mismas brechas fallan en lugar de advertir o saltarse.
No agregues nuevas migraciones de inicio para estas formas antiguas. Agrega o extiende una reparación de doctor, y luego demuéstrala con upgrade-survivor, published-upgrade-survivor o update-restart-auth cuando el comando de actualización sea responsable del reinicio.

​
Añadir cobertura

Al cambiar el comportamiento de actualización o plugins, añade cobertura en la capa más baja que pueda fallar por la razón correcta:
  • Lógica pura de rutas o metadatos: prueba unitaria junto al código fuente.
  • Inventario de paquete o comportamiento de archivos empaquetados: prueba package-dist-inventory o del verificador de tarball.
  • Comportamiento de instalación/actualización de CLI: aserción o fixture de lane Docker.
  • Comportamiento de migración de versión publicada: escenario published-upgrade-survivor.
  • Comportamiento de reinicio propiedad de la actualización: update-restart-auth.
  • Comportamiento de origen de registro/paquete: fixture test:docker:plugins o servidor de fixture de ClawHub.
  • Comportamiento de disposición o limpieza de dependencias: verifica tanto la ejecución en runtime como el límite del sistema de archivos. Las dependencias npm pueden elevarse bajo la raíz npm administrada, por lo que las pruebas deberían demostrar que la raíz se analiza/limpia en lugar de asumir un árbol node_modules local del paquete.
Mantén los nuevos fixtures Docker herméticos de forma predeterminada. Usa registros de fixtures locales y paquetes falsos salvo que el objetivo de la prueba sea el comportamiento de un registro en vivo.

​
Triaje de fallos

Empieza con la identidad del artefacto:
  • Resumen de aceptación de paquetes resolve_package: origen, versión, SHA-256 y nombre del artefacto.
  • Artefactos de Docker: .artifacts/docker-tests/**/summary.json, failures.json, registros de carril y comandos de repetición.
  • Resumen de superviviente de actualización: .artifacts/upgrade-survivor/summary.json, incluida la versión de referencia, la versión candidata, el escenario, los tiempos de fase y los pasos de la receta.
Prefiere volver a ejecutar el carril exacto que falló con el mismo artefacto de paquete en lugar de volver a ejecutar todo el paraguas de release.