Guía de pruebas y benchmarks para OpenClaw

A veces, mantener la estabilidad de un proyecto a medida que crece se siente como intentar reparar un motor en pleno vuelo. Si alguna vez has lidiado con pruebas que fallan de forma intermitente o con la incertidumbre de si un cambio afectará el rendimiento de tu CLI, sabes exactamente a qué me refiero.

Para ayudarte a mantener todo bajo control, OpenClaw ofrece un conjunto de herramientas de testing y benchmarking diseñadas para que tus pruebas sean rápidas, fiables y fáciles de ejecutar.

Pruebas

Aquí tienes el kit completo para gestionar tus pruebas, incluyendo suites, entornos en vivo y Docker:

pnpm test:force: Elimina cualquier proceso de Gateway persistente que esté ocupando el puerto de control predeterminado, luego ejecuta la suite completa de Vitest con un puerto de Gateway aislado para que las pruebas del servidor no colisionen con una instancia en ejecución. Úsalo cuando una ejecución previa de Gateway haya dejado el puerto 18789 ocupado.
pnpm test:coverage: Ejecuta la suite de unidades con cobertura V8 (vía vitest.unit.config.ts). Este es un control de cobertura de archivos cargados, no de todo el repositorio. Los umbrales son 70% para líneas/funciones/sentencias y 55% para ramas. Como coverage.all es falso, el control mide los archivos cargados por la suite de cobertura de unidades en lugar de tratar cada archivo fuente como no cubierto.
pnpm test:coverage:changed: Ejecuta la cobertura de unidades solo para los archivos modificados desde origin/main.
pnpm test:changed: Expande las rutas de GitHub modificadas en carriles de Vitest con alcance cuando el diff solo afecta a archivos fuente/prueba enrutables. Los cambios en la configuración/setup vuelven a los proyectos raíz nativos para que las ediciones de cableado se vuelvan a ejecutar ampliamente cuando sea necesario.
pnpm changed:lanes: Muestra los carriles arquitectónicos activados por el diff contra origin/main.
pnpm check:changed: Ejecuta el control inteligente de cambios para el diff contra origin/main. Ejecuta el trabajo principal con carriles de prueba principales, el trabajo de extensiones con carriles de prueba de extensiones, el trabajo exclusivo de pruebas con typecheck/pruebas, y expande los cambios del Plugin SDK público o contratos de plugins a la validación de extensiones.
pnpm test: Enruta objetivos explícitos de archivos/directorios a través de carriles de Vitest con alcance. Las ejecuciones sin objetivos usan grupos de fragmentos fijos y se expanden a configuraciones hoja para ejecución paralela local; el grupo de extensiones siempre se expande a las configuraciones de fragmentos por extensión en lugar de un proceso de proyecto raíz gigante.
Las ejecuciones completas y de fragmentos de extensiones actualizan los datos de tiempo locales en .artifacts/vitest-shard-timings.json; las ejecuciones posteriores usan esos tiempos para equilibrar fragmentos lentos y rápidos. Configura OPENCLAW_TEST_PROJECTS_TIMINGS=0 para ignorar el artefacto de tiempo local.
Los archivos de prueba seleccionados de plugin-sdk y commands ahora se enrutan a través de carriles ligeros dedicados que mantienen solo test/setup.ts, dejando los casos pesados en tiempo de ejecución en sus carriles existentes.
Los archivos fuente de ayuda seleccionados de plugin-sdk y commands también mapean pnpm test:changed a pruebas hermanas explícitas en esos carriles ligeros, para que las ediciones pequeñas de ayuda eviten volver a ejecutar las suites pesadas respaldadas por el tiempo de ejecución.
auto-reply ahora también se divide en tres configuraciones dedicadas (core, top-level, reply) para que el arnés de respuesta no domine las pruebas más ligeras de estado/token/ayuda de nivel superior.
La configuración base de Vitest ahora usa por defecto pool: "threads" y isolate: false, con el ejecutor compartido no aislado habilitado en las configuraciones del repositorio.
pnpm test:channels ejecuta vitest.channels.config.ts.
pnpm test:extensions y pnpm test extensions ejecutan todos los fragmentos de extensión/plugin. Las extensiones de canal pesadas y OpenAI se ejecutan como fragmentos dedicados; otros grupos de extensiones permanecen agrupados. Usa pnpm test extensions/<id> para un carril de plugin empaquetado.
pnpm test:perf:imports: Habilita el reporte de duración y desglose de importaciones de Vitest, mientras sigue usando el enrutamiento de carril con alcance para objetivos explícitos de archivos/directorios.
pnpm test:perf:imports:changed: Mismo perfilado de importaciones, pero solo para archivos modificados desde origin/main.
pnpm test:perf:changed:bench -- --ref <git-ref> compara el camino de modo cambiado enrutado contra la ejecución del proyecto raíz nativo para el mismo diff de GitHub confirmado.
pnpm test:perf:changed:bench -- --worktree compara el conjunto de cambios actual del árbol de trabajo sin confirmar primero.
pnpm test:perf:profile:main: Escribe un perfil de CPU para el hilo principal de Vitest (.artifacts/vitest-main-profile).
pnpm test:perf:profile:runner: Escribe perfiles de CPU + heap para el ejecutor de unidades (.artifacts/vitest-runner-profile).
Integración de Gateway: opt-in vía OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test o pnpm test:gateway.
pnpm test:e2e: Ejecuta pruebas de humo de extremo a extremo de Gateway (emparejamiento multi-instancia WS/HTTP/node). Usa por defecto threads + isolate: false con trabajadores adaptativos en vitest.e2e.config.ts; ajusta con OPENCLAW_E2E_WORKERS=<n> y configura OPENCLAW_E2E_VERBOSE=1 para registros detallados.
pnpm test:live: Ejecuta pruebas en vivo del proveedor (minimax/zai). Requiere claves de API y LIVE=1 (o *_LIVE_TEST=1 específico del proveedor) para des-saltar.
pnpm test:docker:openwebui: Inicia OpenClaw + Open WebUI en Docker, inicia sesión a través de Open WebUI, verifica /api/models, luego ejecuta un chat proxy real a través de /api/chat/completions. Requiere una clave de modelo en vivo utilizable (por ejemplo, OpenAI en ~/.profile), descarga una imagen externa de Open WebUI y no se espera que sea estable en CI como las suites normales de unidad/e2e.
pnpm test:docker:mcp-channels: Inicia un contenedor de Gateway sembrado y un segundo contenedor cliente que genera openclaw mcp serve, luego verifica el descubrimiento de conversaciones enrutadas, lecturas de transcripciones, metadatos de adjuntos, comportamiento de la cola de eventos en vivo, enrutamiento de envío saliente y notificaciones de canal + permisos al estilo Claude sobre el puente stdio real. La aserción de notificación de Claude lee los marcos stdio MCP crudos directamente para que el humo refleje lo que el puente realmente emite.

Local PR gate

Para comprobaciones locales antes de enviar tu PR, ejecuta los siguientes comandos:

pnpm check:changed
pnpm check
pnpm check:test-types
pnpm build
pnpm test
pnpm check:docs

Si pnpm test falla en un host cargado, vuelve a ejecutarlo una vez antes de tratarlo como una regresión, luego aísla con pnpm test <path/to/test>. Para hosts con memoria limitada, usa:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed

Model latency bench (local keys)

Puedes medir la latencia de los modelos usando el script scripts/bench-model.ts disponible en el repositorio de GitHub.

source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10
Variables de entorno opcionales: MINIMAX_API_KEY, MINIMAX_BASE_URL, MINIMAX_MODEL, ANTHROPIC_API_KEY
Prompt por defecto: “Reply with a single word: ok. No punctuation or extra text.”

Ejecución reciente (2025-12-31, 20 ejecuciones):

minimax median 1279ms (min 1114, max 2431)
opus median 2454ms (min 1224, max 3170)

CLI startup bench

Utiliza el script scripts/bench-cli-startup.ts para medir el rendimiento de inicio de la CLI y asegurar que los cambios no introduzcan regresiones.

pnpm test:startup:bench
pnpm test:startup:bench:smoke
pnpm test:startup:bench:save
pnpm test:startup:bench:update
pnpm test:startup:bench:check
pnpm tsx scripts/bench-cli-startup.ts
pnpm tsx scripts/bench-cli-startup.ts --runs 12
pnpm tsx scripts/bench-cli-startup.ts --preset real
pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --case gatewayStatus --runs 3
pnpm tsx scripts/bench-cli-startup.ts --entry openclaw.mjs --entry-secondary dist/entry.js --preset all
pnpm tsx scripts/bench-cli-startup.ts --preset all --output .artifacts/cli-startup-bench-all.json
pnpm tsx scripts/bench-cli-startup.ts --preset real --case gatewayStatusJson --output .artifacts/cli-startup-bench-smoke.json
pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu
pnpm tsx scripts/bench-cli-startup.ts --json

Presets disponibles:

startup: --version, --help, health, health --json, status --json, status
real: health, status, status --json, sessions, sessions --json, agents list --json, gateway status, gateway status --json, gateway health --json, config get gateway.port
all: ambos presets

La salida incluye sampleCount, promedio, p50, p95, min/max, distribución de código de salida/señal y resúmenes de RSS máximo para cada comando. Opcionalmente, --cpu-prof-dir / --heap-prof-dir escribe perfiles V8 por ejecución.

Convenciones de salida guardada:

pnpm test:startup:bench:smoke escribe el artefacto de humo objetivo en .artifacts/cli-startup-bench-smoke.json
pnpm test:startup:bench:save escribe el artefacto de la suite completa en .artifacts/cli-startup-bench-all.json usando runs=5 y warmup=1
pnpm test:startup:bench:update refresca la fixture base en test/fixtures/cli-startup-bench.json usando runs=5 y warmup=1

Fixture registrada:

test/fixtures/cli-startup-bench.json
Refresca con pnpm test:startup:bench:update
Compara resultados actuales contra la fixture con pnpm test:startup:bench:check

Onboarding E2E (Docker)

El uso de Docker es opcional y solo se requiere para pruebas de humo de incorporación en contenedores.

Para ejecutar el flujo completo de inicio en frío dentro de un contenedor Linux limpio, utiliza el siguiente comando:

scripts/e2e/onboard-docker.sh

Este script maneja el asistente interactivo a través de un pseudo-tty, verifica los archivos de configuración/espacio de trabajo/sesión, luego inicia el Gateway y ejecuta openclaw health.

QR import smoke (Docker)

Asegúrate de que qrcode-terminal se cargue correctamente bajo los entornos de ejecución de Node.js soportados en Docker (Node 24 por defecto, compatible con Node 22):

pnpm test:docker:qr

¿Necesitas más ayuda con la configuración? Consulta nuestro AI Setup Assistant.

Siguientes pasos

OpenClaw Expert

Sigues atascado?

Si esta pagina no resolvio tu caso, pregunta a OpenClaw Expert para pasos concretos.