docs/docs/es/help/testing.md

read_when	summary	title	x-i18n
Ejecutar pruebas localmente o en CI Agregar regresiones para errores de modelo/proveedor Depurar el comportamiento de Gateway + agente	Kit de pruebas: suites unitarias/e2e/live, ejecutores de Docker y qué cubre cada prueba	Pruebas	generated_at model provider source_hash source_path workflow 2026-04-18T04:59:12Z gpt-5.4 openai 7cdd2048ba58e606fd68703977c2b33000abdb1826b6589ce25a35c53468726a help/testing.md 15

Pruebas

OpenClaw tiene tres suites de Vitest (unitarias/integración, e2e, live) y un pequeño conjunto de ejecutores de Docker.

Este documento es una guía de “cómo probamos”:

• Qué cubre cada suite (y qué deliberadamente no cubre)
• Qué comandos ejecutar para flujos de trabajo comunes (local, antes de hacer push, depuración)
• Cómo las pruebas live descubren credenciales y seleccionan modelos/proveedores
• Cómo agregar regresiones para problemas reales de modelo/proveedor

Inicio rápido

La mayoría de los días:

• Puerta completa (esperada antes de hacer push): pnpm build && pnpm check && pnpm test
• Ejecución local más rápida de la suite completa en una máquina con buenos recursos: pnpm test:max
• Bucle directo de vigilancia de Vitest: pnpm test:watch
• El direccionamiento directo a archivos ahora también enruta rutas de extensiones/canales: pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
• Prefiere primero las ejecuciones dirigidas cuando estés iterando sobre un único fallo.
• Sitio de QA respaldado por Docker: pnpm qa:lab:up
• Canal de QA respaldado por VM Linux: pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline

Cuando tocas pruebas o quieres más confianza:

• Puerta de cobertura: pnpm test:coverage
• Suite E2E: pnpm test:e2e

Al depurar proveedores/modelos reales (requiere credenciales reales):

• Suite live (sondeos de modelos + herramientas/imágenes de Gateway): pnpm test:live
• Apuntar silenciosamente a un solo archivo live: pnpm test:live -- src/agents/models.profiles.live.test.ts

Consejo: cuando solo necesites un caso fallido, prefiere acotar las pruebas live mediante las variables de entorno de lista permitida descritas abajo.

Ejecutores específicos de QA

Estos comandos están junto a las suites de prueba principales cuando necesitas el realismo de qa-lab:

• pnpm openclaw qa suite
  • Ejecuta escenarios de QA respaldados por el repositorio directamente en el host.
  • Ejecuta en paralelo varios escenarios seleccionados por defecto con workers de Gateway aislados, hasta 64 workers o la cantidad de escenarios seleccionados. Usa --concurrency <count> para ajustar la cantidad de workers, o --concurrency 1 para el canal serial anterior.
  • Admite los modos de proveedor live-frontier, mock-openai y aimock. aimock inicia un servidor de proveedor local respaldado por AIMock para cobertura experimental de fixtures y simulaciones de protocolo sin reemplazar el canal mock-openai orientado a escenarios.
• pnpm openclaw qa suite --runner multipass
  • Ejecuta la misma suite de QA dentro de una VM Linux Multipass desechable.
  • Mantiene el mismo comportamiento de selección de escenarios que qa suite en el host.
  • Reutiliza las mismas banderas de selección de proveedor/modelo que qa suite.
  • Las ejecuciones live reenvían las entradas de autenticación de QA compatibles que son prácticas para el invitado: claves de proveedor basadas en env, la ruta de configuración del proveedor live de QA y CODEX_HOME cuando está presente.
  • Los directorios de salida deben permanecer bajo la raíz del repositorio para que el invitado pueda escribir de vuelta a través del espacio de trabajo montado.
  • Escribe el informe + resumen normales de QA más los logs de Multipass en .artifacts/qa-e2e/....
• pnpm qa:lab:up
  • Inicia el sitio de QA respaldado por Docker para trabajo de QA estilo operador.
• pnpm openclaw qa aimock
  • Inicia solo el servidor de proveedor local AIMock para pruebas rápidas directas del protocolo.
• pnpm openclaw qa matrix
  • Ejecuta el canal de QA live de Matrix contra un homeserver Tuwunel desechable respaldado por Docker.
  • Este host de QA hoy es solo para repositorio/desarrollo. Las instalaciones empaquetadas de OpenClaw no incluyen qa-lab, por lo que no exponen openclaw qa.
  • Los checkouts del repositorio cargan el ejecutor integrado directamente; no se necesita un paso separado de instalación del Plugin.
  • Aprovisiona tres usuarios temporales de Matrix (driver, sut, observer) más una sala privada, y luego inicia un proceso hijo de Gateway de QA con el Plugin real de Matrix como transporte SUT.
  • Usa la imagen estable fijada de Tuwunel ghcr.io/matrix-construct/tuwunel:v1.5.1 por defecto. Sustitúyela con OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE cuando necesites probar una imagen diferente.
  • Matrix no expone banderas compartidas de origen de credenciales porque el canal aprovisiona usuarios desechables localmente.
  • Escribe un informe de QA de Matrix, un resumen, un artefacto de eventos observados y un log combinado de salida estándar/error estándar en .artifacts/qa-e2e/....
• pnpm openclaw qa telegram
  • Ejecuta el canal de QA live de Telegram contra un grupo privado real usando los tokens del bot driver y del bot SUT desde env.
  • Requiere OPENCLAW_QA_TELEGRAM_GROUP_ID, OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN y OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN. El id del grupo debe ser el id numérico del chat de Telegram.
  • Admite --credential-source convex para credenciales compartidas en pool. Usa el modo env por defecto, o establece OPENCLAW_QA_CREDENTIAL_SOURCE=convex para optar por arrendamientos compartidos.
  • Requiere dos bots distintos en el mismo grupo privado, con el bot SUT exponiendo un nombre de usuario de Telegram.
  • Para una observación estable entre bots, habilita el modo de comunicación Bot-to-Bot en @BotFather para ambos bots y asegúrate de que el bot driver pueda observar el tráfico de bots del grupo.
  • Escribe un informe de QA de Telegram, un resumen y un artefacto de mensajes observados en .artifacts/qa-e2e/....

Los canales de transporte live comparten un contrato estándar para que los nuevos transportes no diverjan:

qa-channel sigue siendo la suite amplia de QA sintética y no forma parte de la matriz de cobertura de transporte live.

Canal	Canary	Mención obligatoria	Bloqueo por lista permitida	Respuesta de nivel superior	Reanudación tras reinicio	Seguimiento en hilo	Aislamiento de hilo	Observación de reacciones	Comando help
Matrix	x	x	x	x	x	x	x	x
Telegram	x								x

Credenciales compartidas de Telegram mediante Convex (v1)

Cuando --credential-source convex (o OPENCLAW_QA_CREDENTIAL_SOURCE=convex) está habilitado para openclaw qa telegram, qa-lab adquiere un arrendamiento exclusivo de un pool respaldado por Convex, envía Heartbeat de ese arrendamiento mientras el canal está en ejecución y libera el arrendamiento al cerrarse.

Andamiaje de referencia del proyecto Convex:

• qa/convex-credential-broker/

Variables de entorno obligatorias:

• OPENCLAW_QA_CONVEX_SITE_URL (por ejemplo https://your-deployment.convex.site)
• Un secreto para el rol seleccionado:
  • OPENCLAW_QA_CONVEX_SECRET_MAINTAINER para maintainer
  • OPENCLAW_QA_CONVEX_SECRET_CI para ci
• Selección del rol de credencial:
  • CLI: --credential-role maintainer|ci
  • Valor predeterminado en env: OPENCLAW_QA_CREDENTIAL_ROLE (por defecto maintainer)

Variables de entorno opcionales:

• OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS (predeterminado 1200000)
• OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS (predeterminado 30000)
• OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS (predeterminado 90000)
• OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS (predeterminado 15000)
• OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX (predeterminado /qa-credentials/v1)
• OPENCLAW_QA_CREDENTIAL_OWNER_ID (id de rastreo opcional)
• OPENCLAW_QA_ALLOW_INSECURE_HTTP=1 permite URLs de Convex http:// de loopback para desarrollo exclusivamente local.

OPENCLAW_QA_CONVEX_SITE_URL debe usar https:// en funcionamiento normal.

Los comandos administrativos de mantenimiento (agregar/eliminar/listar pool) requieren específicamente OPENCLAW_QA_CONVEX_SECRET_MAINTAINER.

Ayudantes de CLI para mantenedores:

pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json
pnpm openclaw qa credentials list --kind telegram
pnpm openclaw qa credentials remove --credential-id <credential-id>

Usa --json para salida legible por máquina en scripts y utilidades de CI.

Contrato predeterminado del endpoint (OPENCLAW_QA_CONVEX_SITE_URL + /qa-credentials/v1):

• POST /acquire
  • Solicitud: { kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }
  • Éxito: { status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }
  • Agotado/reintentable: { status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }
• POST /heartbeat
  • Solicitud: { kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }
  • Éxito: { status: "ok" } (o 2xx vacío)
• POST /release
  • Solicitud: { kind, ownerId, actorRole, credentialId, leaseToken }
  • Éxito: { status: "ok" } (o 2xx vacío)
• POST /admin/add (solo con secreto de maintainer)
  • Solicitud: { kind, actorId, payload, note?, status? }
  • Éxito: { status: "ok", credential }
• POST /admin/remove (solo con secreto de maintainer)
  • Solicitud: { credentialId, actorId }
  • Éxito: { status: "ok", changed, credential }
  • Protección por arrendamiento activo: { status: "error", code: "LEASE_ACTIVE", ... }
• POST /admin/list (solo con secreto de maintainer)
  • Solicitud: { kind?, status?, includePayload?, limit? }
  • Éxito: { status: "ok", credentials, count }

Forma de la carga útil para el tipo Telegram:

• { groupId: string, driverToken: string, sutToken: string }
• groupId debe ser una cadena con el id numérico del chat de Telegram.
• admin/add valida esta forma para kind: "telegram" y rechaza cargas útiles mal formadas.

Agregar un canal a QA

Agregar un canal al sistema de QA en Markdown requiere exactamente dos cosas:

1. Un adaptador de transporte para el canal.
2. Un paquete de escenarios que ejercite el contrato del canal.

No agregues una nueva raíz de comandos de QA de nivel superior cuando el host compartido qa-lab pueda controlar el flujo.

qa-lab controla la mecánica compartida del host:

• la raíz de comandos openclaw qa
• inicio y desmontaje de la suite
• concurrencia de workers
• escritura de artefactos
• generación de informes
• ejecución de escenarios
• alias de compatibilidad para escenarios qa-channel antiguos

Los plugins de ejecutor controlan el contrato de transporte:

• cómo se monta openclaw qa <runner> bajo la raíz compartida qa
• cómo se configura Gateway para ese transporte
• cómo se verifica la preparación
• cómo se inyectan eventos entrantes
• cómo se observan los mensajes salientes
• cómo se exponen las transcripciones y el estado de transporte normalizado
• cómo se ejecutan acciones respaldadas por transporte
• cómo se maneja el restablecimiento o la limpieza específicos del transporte

El requisito mínimo de adopción para un canal nuevo es:

1. Mantener qa-lab como propietario de la raíz compartida qa.
2. Implementar el ejecutor de transporte en la interfaz compartida del host qa-lab.
3. Mantener la mecánica específica del transporte dentro del plugin del ejecutor o del arnés del canal.
4. Montar el ejecutor como openclaw qa <runner> en lugar de registrar una raíz de comandos competidora. Los plugins de ejecutor deben declarar qaRunners en openclaw.plugin.json y exportar un arreglo qaRunnerCliRegistrations coincidente desde runtime-api.ts. Mantén runtime-api.ts liviano; la ejecución diferida de CLI y del ejecutor debe permanecer detrás de entrypoints separados.
5. Crear o adaptar escenarios en Markdown bajo los directorios temáticos qa/scenarios/.
6. Usar los ayudantes genéricos de escenarios para escenarios nuevos.
7. Mantener funcionando los alias de compatibilidad existentes, a menos que el repositorio esté haciendo una migración intencional.

La regla de decisión es estricta:

• Si un comportamiento puede expresarse una sola vez en qa-lab, ponlo en qa-lab.
• Si un comportamiento depende de un transporte de canal, mantenlo en ese plugin de ejecutor o arnés de plugin.
• Si un escenario necesita una nueva capacidad que más de un canal pueda usar, agrega un ayudante genérico en lugar de una rama específica del canal en suite.ts.
• Si un comportamiento solo tiene sentido para un transporte, mantén el escenario específico de ese transporte y hazlo explícito en el contrato del escenario.

Los nombres preferidos de ayudantes genéricos para escenarios nuevos son:

• waitForTransportReady
• waitForChannelReady
• injectInboundMessage
• injectOutboundMessage
• waitForTransportOutboundMessage
• waitForChannelOutboundMessage
• waitForNoTransportOutbound
• getTransportSnapshot
• readTransportMessage
• readTransportTranscript
• formatTransportTranscript
• resetTransport

Los alias de compatibilidad siguen disponibles para escenarios existentes, incluidos:

• waitForQaChannelReady
• waitForOutboundMessage
• waitForNoOutbound
• formatConversationTranscript
• resetBus

El trabajo en canales nuevos debe usar los nombres de ayudantes genéricos. Los alias de compatibilidad existen para evitar una migración de un solo día, no como modelo para la creación de escenarios nuevos.

Suites de prueba (qué se ejecuta dónde)

Piense en las suites como “realismo creciente” (y mayor inestabilidad/costo):

Unitarias / integración (predeterminada)

• Comando: pnpm test
• Configuración: diez ejecuciones secuenciales por shard (vitest.full-*.config.ts) sobre los proyectos de Vitest acotados existentes
• Archivos: inventarios core/unit en src/**/*.test.ts, packages/**/*.test.ts, test/**/*.test.ts y las pruebas de nodo de ui incluidas en la lista permitida cubiertas por vitest.unit.config.ts
• Alcance:
  • Pruebas unitarias puras
  • Pruebas de integración en proceso (autenticación de Gateway, enrutamiento, herramientas, parsing, configuración)
  • Regresiones deterministas para errores conocidos
• Expectativas:
  • Se ejecuta en CI
  • No requiere claves reales
  • Debe ser rápida y estable
• Nota sobre proyectos:
  • pnpm test sin objetivo ahora ejecuta once configuraciones por shard más pequeñas (core-unit-src, core-unit-security, core-unit-ui, core-unit-support, core-support-boundary, core-contracts, core-bundled, core-runtime, agentic, auto-reply, extensions) en lugar de un único proceso raíz nativo gigante. Esto reduce el RSS máximo en máquinas cargadas y evita que el trabajo de auto-reply/extensiones deje sin recursos a suites no relacionadas.
  • pnpm test --watch sigue usando el grafo de proyectos nativo de vitest.config.ts, porque un bucle de watch con múltiples shards no es práctico.
  • pnpm test, pnpm test:watch y pnpm test:perf:imports dirigen primero objetivos explícitos de archivo/directorio a través de canales acotados, por lo que pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts evita pagar el costo de inicio completo del proyecto raíz.
  • pnpm test:changed expande las rutas git modificadas a los mismos canales acotados cuando el diff solo toca archivos fuente/de prueba enrutable; las ediciones de configuración/preparación siguen recurriendo a la reejecución amplia del proyecto raíz.
  • Las pruebas unitarias livianas en importación de agentes, comandos, plugins, ayudantes de auto-reply, plugin-sdk y áreas utilitarias puras similares se dirigen al canal unit-fast, que omite test/setup-openclaw-runtime.ts; los archivos pesados con estado/runtime permanecen en los canales existentes.
  • Algunos archivos fuente auxiliares seleccionados de plugin-sdk y commands también mapean ejecuciones en modo changed a pruebas hermanas explícitas en esos canales livianos, para que las ediciones en ayudantes eviten volver a ejecutar la suite pesada completa de ese directorio.
  • auto-reply ahora tiene tres buckets dedicados: ayudantes core de nivel superior, pruebas de integración reply.* de nivel superior y el subárbol src/auto-reply/reply/**. Esto mantiene el trabajo más pesado del arnés de respuesta fuera de las pruebas baratas de status/chunk/token.
• Nota sobre el ejecutor integrado:
  • Cuando cambies las entradas de descubrimiento de herramientas de mensajes o el contexto de runtime de Compaction, mantén ambos niveles de cobertura.
  • Agrega regresiones centradas en ayudantes para límites puros de enrutamiento/normalización.
  • También mantén sanas las suites de integración del ejecutor integrado: src/agents/pi-embedded-runner/compact.hooks.test.ts, src/agents/pi-embedded-runner/run.overflow-compaction.test.ts y src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts.
  • Estas suites verifican que los ids acotados y el comportamiento de Compaction sigan fluyendo por las rutas reales run.ts / compact.ts; las pruebas solo de ayudantes no son un sustituto suficiente para esas rutas de integración.
• Nota sobre el pool:
  • La configuración base de Vitest ahora usa threads por defecto.
  • La configuración compartida de Vitest también fija isolate: false y usa el ejecutor no aislado en los proyectos raíz, e2e y live.
  • El canal UI raíz mantiene su configuración y optimizador de jsdom, pero ahora también se ejecuta en el ejecutor compartido no aislado.
  • Cada shard de pnpm test hereda los mismos valores predeterminados threads + isolate: false de la configuración compartida de Vitest.
  • El lanzador compartido scripts/run-vitest.mjs ahora también agrega --no-maglev por defecto para los procesos Node hijo de Vitest para reducir la agitación de compilación de V8 durante grandes ejecuciones locales. Establece OPENCLAW_VITEST_ENABLE_MAGLEV=1 si necesitas comparar con el comportamiento estándar de V8.
• Nota sobre iteración local rápida:
  • pnpm test:changed se enruta por canales acotados cuando las rutas modificadas se asignan limpiamente a una suite más pequeña.
  • pnpm test:max y pnpm test:changed:max mantienen el mismo comportamiento de enrutamiento, solo que con un límite mayor de workers.
  • El autoescalado local de workers ahora es intencionalmente conservador y también retrocede cuando la carga media del host ya es alta, por lo que múltiples ejecuciones concurrentes de Vitest causan menos daño por defecto.
  • La configuración base de Vitest marca los archivos de proyectos/configuración como forceRerunTriggers para que las reejecuciones en modo changed sigan siendo correctas cuando cambia el cableado de pruebas.
  • La configuración mantiene OPENCLAW_VITEST_FS_MODULE_CACHE habilitado en hosts compatibles; establece OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path si quieres una ubicación de caché explícita para perfilado directo.
• Nota sobre depuración de rendimiento:
  • pnpm test:perf:imports habilita informes de duración de importación de Vitest más salida de desglose de importaciones.
  • pnpm test:perf:imports:changed limita la misma vista de perfilado a los archivos modificados desde origin/main.
• pnpm test:perf:changed:bench -- --ref <git-ref> compara test:changed enrutado frente a la ruta nativa del proyecto raíz para ese diff confirmado e imprime tiempo total más RSS máximo de macOS.
• pnpm test:perf:changed:bench -- --worktree mide el árbol sucio actual enr utando la lista de archivos modificados a través de scripts/test-projects.mjs y la configuración raíz de Vitest.
  • pnpm test:perf:profile:main escribe un perfil de CPU del hilo principal para la sobrecarga de inicio y transformación de Vitest/Vite.
  • pnpm test:perf:profile:runner escribe perfiles de CPU+heap del ejecutor para la suite unitaria con el paralelismo de archivos deshabilitado.

E2E (prueba rápida de Gateway)

• Comando: pnpm test:e2e
• Configuración: vitest.e2e.config.ts
• Archivos: src/**/*.e2e.test.ts, test/**/*.e2e.test.ts
• Valores predeterminados de runtime:
  • Usa Vitest threads con isolate: false, igual que el resto del repositorio.
  • Usa workers adaptativos (CI: hasta 2, local: 1 por defecto).
  • Se ejecuta en modo silencioso por defecto para reducir la sobrecarga de E/S de consola.
• Overrides útiles:
  • OPENCLAW_E2E_WORKERS=<n> para forzar la cantidad de workers (máximo 16).
  • OPENCLAW_E2E_VERBOSE=1 para volver a habilitar la salida detallada en consola.
• Alcance:
  • Comportamiento end-to-end de Gateway con múltiples instancias
  • Superficies WebSocket/HTTP, emparejamiento de nodos y redes más pesadas
• Expectativas:
  • Se ejecuta en CI (cuando está habilitado en el pipeline)
  • No requiere claves reales
  • Tiene más piezas móviles que las pruebas unitarias (puede ser más lenta)

E2E: prueba rápida del backend OpenShell

• Comando: pnpm test:e2e:openshell
• Archivo: test/openshell-sandbox.e2e.test.ts
• Alcance:
  • Inicia un Gateway OpenShell aislado en el host mediante Docker
  • Crea un sandbox desde un Dockerfile local temporal
  • Ejercita el backend OpenShell de OpenClaw sobre sandbox ssh-config + ejecución SSH reales
  • Verifica el comportamiento canónico remoto del sistema de archivos mediante el puente fs del sandbox
• Expectativas:
  • Solo opcional; no forma parte de la ejecución predeterminada de pnpm test:e2e
  • Requiere un CLI openshell local más un daemon Docker funcional
  • Usa HOME / XDG_CONFIG_HOME aislados, luego destruye el Gateway de prueba y el sandbox
• Overrides útiles:
  • OPENCLAW_E2E_OPENSHELL=1 para habilitar la prueba al ejecutar manualmente la suite e2e más amplia
  • OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell para apuntar a un binario CLI no predeterminado o a un script contenedor

Live (proveedores reales + modelos reales)

• Comando: pnpm test:live
• Configuración: vitest.live.config.ts
• Archivos: src/**/*.live.test.ts
• Predeterminado: habilitado por pnpm test:live (establece OPENCLAW_LIVE_TEST=1)
• Alcance:
  • “¿Este proveedor/modelo realmente funciona hoy con credenciales reales?”
  • Detectar cambios de formato del proveedor, peculiaridades de llamadas a herramientas, problemas de autenticación y comportamiento de límites de tasa
• Expectativas:
  • No es estable en CI por diseño (redes reales, políticas reales de proveedores, cuotas, caídas)
  • Cuesta dinero / consume límites de tasa
  • Conviene ejecutar subconjuntos acotados en lugar de “todo”
• Las ejecuciones live cargan ~/.profile para recoger claves API faltantes.
• Por defecto, las ejecuciones live siguen aislando HOME y copian el material de configuración/autenticación a un home temporal de prueba para que los fixtures unitarios no puedan modificar tu ~/.openclaw real.
• Establece OPENCLAW_LIVE_USE_REAL_HOME=1 solo cuando intencionalmente necesites que las pruebas live usen tu directorio home real.
• pnpm test:live ahora usa por defecto un modo más silencioso: mantiene la salida de progreso [live] ..., pero suprime el aviso adicional de ~/.profile y silencia los logs de arranque de Gateway/el ruido de Bonjour. Establece OPENCLAW_LIVE_TEST_QUIET=0 si quieres recuperar los logs completos de inicio.
• Rotación de claves API (específica por proveedor): establece *_API_KEYS con formato separado por comas/punto y coma o *_API_KEY_1, *_API_KEY_2 (por ejemplo OPENAI_API_KEYS, ANTHROPIC_API_KEYS, GEMINI_API_KEYS) o un override por live mediante OPENCLAW_LIVE_*_KEY; las pruebas reintentan ante respuestas por límite de tasa.
• Salida de progreso/Heartbeat:
  • Las suites live ahora emiten líneas de progreso a stderr para que las llamadas largas a proveedores muestren actividad visible incluso cuando la captura de consola de Vitest está en modo silencioso.
  • vitest.live.config.ts deshabilita la interceptación de consola de Vitest para que las líneas de progreso de proveedor/Gateway se transmitan inmediatamente durante las ejecuciones live.
  • Ajusta los Heartbeat de modelo directo con OPENCLAW_LIVE_HEARTBEAT_MS.
  • Ajusta los Heartbeat de Gateway/sondeo con OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS.

¿Qué suite debo ejecutar?

Usa esta tabla de decisión:

• Si editas lógica/pruebas: ejecuta pnpm test (y pnpm test:coverage si cambiaste bastante)
• Si tocas redes de Gateway / protocolo WS / emparejamiento: agrega pnpm test:e2e
• Si depuras “mi bot está caído” / fallos específicos del proveedor / llamadas a herramientas: ejecuta un pnpm test:live acotado

Live: barrido de capacidades de Node Android

• Prueba: src/gateway/android-node.capabilities.live.test.ts
• Script: pnpm android:test:integration
• Objetivo: invocar cada comando anunciado actualmente por un Node Android conectado y comprobar el comportamiento del contrato del comando.
• Alcance:
  • Configuración previa/manual (la suite no instala/ejecuta/empareja la app).
  • Validación node.invoke de Gateway comando por comando para el Node Android seleccionado.
• Configuración previa obligatoria:
  • App Android ya conectada y emparejada con Gateway.
  • La app debe mantenerse en primer plano.
  • Permisos/consentimiento de captura otorgados para las capacidades que esperas que pasen.
• Overrides de objetivo opcionales:
  • OPENCLAW_ANDROID_NODE_ID o OPENCLAW_ANDROID_NODE_NAME.
  • OPENCLAW_ANDROID_GATEWAY_URL / OPENCLAW_ANDROID_GATEWAY_TOKEN / OPENCLAW_ANDROID_GATEWAY_PASSWORD.
• Detalles completos de configuración de Android: App Android

Live: prueba rápida de modelos (claves de perfil)

Las pruebas live se dividen en dos capas para poder aislar fallos:

• “Modelo directo” nos dice si el proveedor/modelo puede responder con la clave dada.
• “Prueba rápida de Gateway” nos dice si la canalización completa de gateway+agente funciona para ese modelo (sesiones, historial, herramientas, política de sandbox, etc.).

Capa 1: finalización directa del modelo (sin Gateway)

• Prueba: src/agents/models.profiles.live.test.ts
• Objetivo:
  • Enumerar los modelos detectados
  • Usar getApiKeyForModel para seleccionar modelos para los que tienes credenciales
  • Ejecutar una pequeña finalización por modelo (y regresiones específicas cuando sea necesario)
• Cómo habilitar:
  • pnpm test:live (o OPENCLAW_LIVE_TEST=1 si invocas Vitest directamente)
• Establece OPENCLAW_LIVE_MODELS=modern (o all, alias de modern) para ejecutar realmente esta suite; de lo contrario se omite para mantener pnpm test:live centrado en la prueba rápida de Gateway
• Cómo seleccionar modelos:
  • OPENCLAW_LIVE_MODELS=modern para ejecutar la lista permitida moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
  • OPENCLAW_LIVE_MODELS=all es un alias de la lista permitida moderna
  • o OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..." (lista permitida separada por comas)
  • Los barridos modern/all usan por defecto un límite curado de alta señal; establece OPENCLAW_LIVE_MAX_MODELS=0 para un barrido moderno exhaustivo o un número positivo para un límite menor.
• Cómo seleccionar proveedores:
  • OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli" (lista permitida separada por comas)
• De dónde vienen las claves:
  • Por defecto: almacén de perfiles y respaldos en env
  • Establece OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 para exigir solo el almacén de perfiles
• Por qué existe esto:
  • Separa “la API del proveedor está rota / la clave no es válida” de “la canalización del agente de Gateway está rota”
  • Contiene regresiones pequeñas y aisladas (ejemplo: reproducción de razonamiento de OpenAI Responses/Codex Responses + flujos de llamada a herramientas)

Capa 2: prueba rápida de Gateway + agente de desarrollo (lo que realmente hace "@openclaw")

• Prueba: src/gateway/gateway-models.profiles.live.test.ts
• Objetivo:
  • Iniciar un Gateway en proceso
  • Crear/parchear una sesión agent:dev:* (override de modelo por ejecución)
  • Iterar sobre modelos con claves y comprobar:
    • respuesta “significativa” (sin herramientas)
    • que una invocación real de herramienta funcione (sondeo de lectura)
    • sondeos opcionales adicionales de herramientas (sondeo exec+read)
    • que las rutas de regresión de OpenAI (solo llamada a herramienta → seguimiento) sigan funcionando
• Detalles de los sondeos (para que puedas explicar fallos rápidamente):
  • sondeo read: la prueba escribe un archivo nonce en el espacio de trabajo y le pide al agente que lo read y devuelva el nonce.
  • sondeo exec+read: la prueba le pide al agente que escriba mediante exec un nonce en un archivo temporal y luego lo lea de vuelta con read.
  • sondeo de imagen: la prueba adjunta un PNG generado (gato + código aleatorio) y espera que el modelo devuelva cat <CODE>.
  • Referencia de implementación: src/gateway/gateway-models.profiles.live.test.ts y src/gateway/live-image-probe.ts.
• Cómo habilitar:
  • pnpm test:live (o OPENCLAW_LIVE_TEST=1 si invocas Vitest directamente)
• Cómo seleccionar modelos:
  • Predeterminado: lista permitida moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
  • OPENCLAW_LIVE_GATEWAY_MODELS=all es un alias de la lista permitida moderna
  • O establece OPENCLAW_LIVE_GATEWAY_MODELS="provider/model" (o una lista separada por comas) para acotar
  • Los barridos de Gateway modern/all usan por defecto un límite curado de alta señal; establece OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0 para un barrido moderno exhaustivo o un número positivo para un límite menor.
• Cómo seleccionar proveedores (evitar “todo OpenRouter”):
  • OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax" (lista permitida separada por comas)
• Los sondeos de herramientas + imagen siempre están activados en esta prueba live:
  • sondeo read + sondeo exec+read (estrés de herramientas)
  • el sondeo de imagen se ejecuta cuando el modelo anuncia compatibilidad con entrada de imagen
  • Flujo (alto nivel):
    • La prueba genera un pequeño PNG con “CAT” + código aleatorio (src/gateway/live-image-probe.ts)
    • Lo envía mediante agent attachments: [{ mimeType: "image/png", content: "<base64>" }]
    • Gateway analiza los adjuntos en images[] (src/gateway/server-methods/agent.ts + src/gateway/chat-attachments.ts)
    • El agente integrado reenvía un mensaje de usuario multimodal al modelo
    • Comprobación: la respuesta contiene cat + el código (tolerancia OCR: se permiten errores menores)

Consejo: para ver qué puedes probar en tu máquina (y los ids exactos provider/model), ejecuta:

openclaw models list
openclaw models list --json

Live: prueba rápida de backend CLI (Claude, Codex, Gemini u otros CLI locales)

• Prueba: src/gateway/gateway-cli-backend.live.test.ts
• Objetivo: validar la canalización de Gateway + agente usando un backend CLI local, sin tocar tu configuración predeterminada.
• Los valores predeterminados de prueba rápida específicos del backend están en la definición cli-backend.ts de la extensión propietaria.
• Habilitar:
  • pnpm test:live (o OPENCLAW_LIVE_TEST=1 si invocas Vitest directamente)
  • OPENCLAW_LIVE_CLI_BACKEND=1
• Predeterminados:
  • Proveedor/modelo predeterminado: claude-cli/claude-sonnet-4-6
  • El comportamiento de comando/args/imagen proviene de los metadatos del Plugin del backend CLI propietario.
• Overrides opcionales:
  • OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"
  • OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"
  • OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1 para enviar un adjunto de imagen real (las rutas se inyectan en el prompt).
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image" para pasar rutas de archivos de imagen como args de CLI en lugar de inyección en el prompt.
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat" (o "list") para controlar cómo se pasan los args de imagen cuando se establece IMAGE_ARG.
  • OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1 para enviar un segundo turno y validar el flujo de reanudación.
  • OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0 para deshabilitar el sondeo predeterminado de continuidad en la misma sesión de Claude Sonnet -> Opus (establece 1 para forzarlo cuando el modelo seleccionado admita un destino de cambio).

Ejemplo:

OPENCLAW_LIVE_CLI_BACKEND=1 \
  OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4" \
  pnpm test:live src/gateway/gateway-cli-backend.live.test.ts

Receta de Docker:

pnpm test:docker:live-cli-backend

Recetas de Docker para un solo proveedor:

pnpm test:docker:live-cli-backend:claude
pnpm test:docker:live-cli-backend:claude-subscription
pnpm test:docker:live-cli-backend:codex
pnpm test:docker:live-cli-backend:gemini

Notas:

• El ejecutor de Docker está en scripts/test-live-cli-backend-docker.sh.
• Ejecuta la prueba rápida live del backend CLI dentro de la imagen Docker del repositorio como el usuario no root node.
• Resuelve los metadatos de la prueba rápida CLI desde la extensión propietaria y luego instala el paquete CLI de Linux correspondiente (@anthropic-ai/claude-code, @openai/codex o @google/gemini-cli) en un prefijo grabable en caché en OPENCLAW_DOCKER_CLI_TOOLS_DIR (predeterminado: ~/.cache/openclaw/docker-cli-tools).
• pnpm test:docker:live-cli-backend:claude-subscription requiere OAuth portátil de suscripción de Claude Code mediante ~/.claude/.credentials.json con claudeAiOauth.subscriptionType o CLAUDE_CODE_OAUTH_TOKEN de claude setup-token. Primero comprueba claude -p directamente en Docker y luego ejecuta dos turnos del backend CLI de Gateway sin conservar las variables de entorno de clave API de Anthropic. Este canal de suscripción deshabilita por defecto los sondeos de herramienta MCP e imagen de Claude porque Claude actualmente enruta el uso de aplicaciones de terceros mediante facturación por uso adicional en lugar de los límites normales del plan de suscripción.
• La prueba rápida live del backend CLI ahora ejercita el mismo flujo end-to-end para Claude, Codex y Gemini: turno de texto, turno de clasificación de imagen, luego llamada a herramienta MCP cron verificada mediante la CLI de Gateway.
• La prueba rápida predeterminada de Claude también parchea la sesión de Sonnet a Opus y verifica que la sesión reanudada aún recuerde una nota anterior.

Live: prueba rápida de enlace ACP (/acp spawn ... --bind here)

• Prueba: src/gateway/gateway-acp-bind.live.test.ts
• Objetivo: validar el flujo real de enlace de conversación de ACP con un agente ACP live:
  • enviar /acp spawn <agent> --bind here
  • enlazar en su lugar una conversación sintética de canal de mensajes
  • enviar un seguimiento normal en esa misma conversación
  • verificar que el seguimiento llegue a la transcripción de la sesión ACP enlazada
• Habilitar:
  • pnpm test:live src/gateway/gateway-acp-bind.live.test.ts
  • OPENCLAW_LIVE_ACP_BIND=1
• Predeterminados:
  • Agentes ACP en Docker: claude,codex,gemini
  • Agente ACP para pnpm test:live ... directo: claude
  • Canal sintético: contexto de conversación estilo DM de Slack
  • Backend ACP: acpx
• Overrides:
  • OPENCLAW_LIVE_ACP_BIND_AGENT=claude
  • OPENCLAW_LIVE_ACP_BIND_AGENT=codex
  • OPENCLAW_LIVE_ACP_BIND_AGENT=gemini
  • OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini
  • OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@<version>'
• Notas:
  • Este canal usa la superficie chat.send de Gateway con campos sintéticos de ruta de origen solo para administrador, para que las pruebas puedan adjuntar contexto de canal de mensajes sin fingir entrega externa.
  • Cuando OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND no está establecido, la prueba usa el registro integrado de agentes del Plugin acpx incluido para el agente de arnés ACP seleccionado.

Ejemplo:

OPENCLAW_LIVE_ACP_BIND=1 \
  OPENCLAW_LIVE_ACP_BIND_AGENT=claude \
  pnpm test:live src/gateway/gateway-acp-bind.live.test.ts

Receta de Docker:

pnpm test:docker:live-acp-bind

Recetas de Docker para un solo agente:

pnpm test:docker:live-acp-bind:claude
pnpm test:docker:live-acp-bind:codex
pnpm test:docker:live-acp-bind:gemini

Notas de Docker:

• El ejecutor de Docker está en scripts/test-live-acp-bind-docker.sh.
• Por defecto, ejecuta la prueba rápida de enlace ACP contra todos los agentes CLI live compatibles en secuencia: claude, codex y luego gemini.
• Usa OPENCLAW_LIVE_ACP_BIND_AGENTS=claude, OPENCLAW_LIVE_ACP_BIND_AGENTS=codex o OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini para acotar la matriz.
• Carga ~/.profile, prepara el material de autenticación CLI correspondiente dentro del contenedor, instala acpx en un prefijo npm grabable y luego instala la CLI live solicitada (@anthropic-ai/claude-code, @openai/codex o @google/gemini-cli) si falta.
• Dentro de Docker, el ejecutor establece OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx para que acpx mantenga disponibles para la CLI hija del arnés las variables de entorno del proveedor procedentes del perfil cargado.

Live: prueba rápida del arnés app-server de Codex

• Objetivo: validar el arnés Codex propiedad del Plugin mediante el método agent normal de Gateway:
  • cargar el Plugin integrado codex
  • seleccionar OPENCLAW_AGENT_RUNTIME=codex
  • enviar un primer turno del agente de Gateway a codex/gpt-5.4
  • enviar un segundo turno a la misma sesión de OpenClaw y verificar que el hilo del app-server pueda reanudarse
  • ejecutar /codex status y /codex models mediante la misma ruta de comando de Gateway
• Prueba: src/gateway/gateway-codex-harness.live.test.ts
• Habilitar: OPENCLAW_LIVE_CODEX_HARNESS=1
• Modelo predeterminado: codex/gpt-5.4
• Sondeo de imagen opcional: OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1
• Sondeo MCP/herramienta opcional: OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1
• La prueba rápida establece OPENCLAW_AGENT_HARNESS_FALLBACK=none para que un arnés Codex roto no pueda pasar recurriendo silenciosamente a PI.
• Autenticación: OPENAI_API_KEY desde el shell/perfil, más copia opcional de ~/.codex/auth.json y ~/.codex/config.toml

Receta local:

source ~/.profile
OPENCLAW_LIVE_CODEX_HARNESS=1 \
  OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1 \
  OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1 \
  OPENCLAW_LIVE_CODEX_HARNESS_MODEL=codex/gpt-5.4 \
  pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts

Receta de Docker:

source ~/.profile
pnpm test:docker:live-codex-harness

Notas de Docker:

• El ejecutor de Docker está en scripts/test-live-codex-harness-docker.sh.
• Carga el ~/.profile montado, pasa OPENAI_API_KEY, copia los archivos de autenticación de CLI de Codex cuando están presentes, instala @openai/codex en un prefijo npm montado y grabable, prepara el árbol fuente y luego ejecuta solo la prueba live del arnés Codex.
• Docker habilita por defecto los sondeos de imagen y MCP/herramientas. Establece OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 o OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 cuando necesites una ejecución de depuración más acotada.
• Docker también exporta OPENCLAW_AGENT_HARNESS_FALLBACK=none, igual que la configuración de la prueba live, para que el respaldo a openai-codex/* o PI no pueda ocultar una regresión del arnés Codex.

Recetas live recomendadas

Las listas permitidas acotadas y explícitas son las más rápidas y menos inestables:

• Modelo único, directo (sin Gateway):

  • OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts

• Modelo único, prueba rápida de Gateway:

  • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

• Llamada a herramientas en varios proveedores:

  • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

• Enfoque en Google (clave API de Gemini + Antigravity):

  • Gemini (clave API): OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
  • Antigravity (OAuth): OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

Notas:

• google/... usa la API de Gemini (clave API).
• google-antigravity/... usa el puente OAuth de Antigravity (endpoint de agente estilo Cloud Code Assist).
• google-gemini-cli/... usa el CLI local de Gemini en tu máquina (autenticación independiente + peculiaridades de herramientas).
• API de Gemini vs CLI de Gemini:
  • API: OpenClaw llama a la API alojada de Gemini de Google por HTTP (autenticación con clave API / perfil); esto es lo que la mayoría de los usuarios quiere decir con “Gemini”.
  • CLI: OpenClaw ejecuta un binario gemini local; tiene su propia autenticación y puede comportarse de forma diferente (streaming/compatibilidad con herramientas/desfase de versión).

Live: matriz de modelos (qué cubrimos)

No hay una “lista fija de modelos de CI” (live es opcional), pero estos son los modelos recomendados para cubrir regularmente en una máquina de desarrollo con claves.

Conjunto moderno de prueba rápida (llamada a herramientas + imagen)

Esta es la ejecución de “modelos comunes” que esperamos mantener funcional:

• OpenAI (no-Codex): openai/gpt-5.4 (opcional: openai/gpt-5.4-mini)
• OpenAI Codex: openai-codex/gpt-5.4
• Anthropic: anthropic/claude-opus-4-6 (o anthropic/claude-sonnet-4-6)
• Google (API de Gemini): google/gemini-3.1-pro-preview y google/gemini-3-flash-preview (evita modelos antiguos de Gemini 2.x)
• Google (Antigravity): google-antigravity/claude-opus-4-6-thinking y google-antigravity/gemini-3-flash
• Z.AI (GLM): zai/glm-4.7
• MiniMax: minimax/MiniMax-M2.7

Ejecuta la prueba rápida de Gateway con herramientas + imagen: OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

Línea base: llamada a herramientas (Read + Exec opcional)

Elige al menos uno por familia de proveedores:

• OpenAI: openai/gpt-5.4 (o openai/gpt-5.4-mini)
• Anthropic: anthropic/claude-opus-4-6 (o anthropic/claude-sonnet-4-6)
• Google: google/gemini-3-flash-preview (o google/gemini-3.1-pro-preview)
• Z.AI (GLM): zai/glm-4.7
• MiniMax: minimax/MiniMax-M2.7

Cobertura adicional opcional (bueno tenerla):

• xAI: xai/grok-4 (o la última disponible)
• Mistral: mistral/… (elige un modelo con capacidad de “tools” que tengas habilitado)
• Cerebras: cerebras/… (si tienes acceso)
• LM Studio: lmstudio/… (local; la llamada a herramientas depende del modo API)

Visión: envío de imagen (adjunto → mensaje multimodal)

Incluye al menos un modelo con capacidad de imagen en OPENCLAW_LIVE_GATEWAY_MODELS (Claude/Gemini/variantes de OpenAI con visión, etc.) para ejercitar el sondeo de imagen.

Agregadores / gateways alternativos

Si tienes claves habilitadas, también admitimos pruebas mediante:

• OpenRouter: openrouter/... (cientos de modelos; usa openclaw models scan para encontrar candidatos con capacidad de herramientas+imagen)
• OpenCode: opencode/... para Zen y opencode-go/... para Go (autenticación mediante OPENCODE_API_KEY / OPENCODE_ZEN_API_KEY)

Más proveedores que puedes incluir en la matriz live (si tienes credenciales/configuración):

• Integrados: openai, openai-codex, anthropic, google, google-vertex, google-antigravity, google-gemini-cli, zai, openrouter, opencode, opencode-go, xai, groq, cerebras, mistral, github-copilot
• Mediante models.providers (endpoints personalizados): minimax (nube/API), además de cualquier proxy compatible con OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, etc.)

Consejo: no intentes fijar “todos los modelos” en la documentación. La lista autoritativa es la que devuelva discoverModels(...) en tu máquina + las claves disponibles.

Credenciales (nunca las confirmes)

Las pruebas live descubren credenciales del mismo modo que la CLI. Implicaciones prácticas:

• Si la CLI funciona, las pruebas live deberían encontrar las mismas claves.

• Si una prueba live dice “no creds”, depura del mismo modo que depurarías openclaw models list / la selección de modelos.

• Perfiles de autenticación por agente: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (esto es lo que significan las “profile keys” en las pruebas live)

• Configuración: ~/.openclaw/openclaw.json (o OPENCLAW_CONFIG_PATH)

• Directorio de estado heredado: ~/.openclaw/credentials/ (se copia al home live preparado cuando está presente, pero no es el almacén principal de claves de perfil)

• Las ejecuciones live locales copian por defecto la configuración activa, los archivos auth-profiles.json por agente, credentials/ heredado y los directorios de autenticación de CLI externos compatibles a un home temporal de prueba; los homes live preparados omiten workspace/ y sandboxes/, y se eliminan los overrides de ruta agents.*.workspace / agentDir para que los sondeos no toquen tu espacio de trabajo real del host.

Si quieres depender de claves env (por ejemplo, exportadas en tu ~/.profile), ejecuta las pruebas locales después de source ~/.profile, o usa los ejecutores de Docker de abajo (pueden montar ~/.profile dentro del contenedor).

Live de Deepgram (transcripción de audio)

• Prueba: src/media-understanding/providers/deepgram/audio.live.test.ts
• Habilitar: DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts

Live de plan de codificación de BytePlus

• Prueba: src/agents/byteplus.live.test.ts
• Habilitar: BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts
• Override opcional de modelo: BYTEPLUS_CODING_MODEL=ark-code-latest

Live de medios de flujo de trabajo de ComfyUI

• Prueba: extensions/comfy/comfy.live.test.ts
• Habilitar: OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
• Alcance:
  • Ejercita las rutas integradas de imagen, video y music_generate de comfy
  • Omite cada capacidad a menos que models.providers.comfy.<capability> esté configurado
  • Útil después de cambiar el envío de flujos de trabajo de comfy, el sondeo, las descargas o el registro del Plugin

Live de generación de imágenes

• Prueba: src/image-generation/runtime.live.test.ts
• Comando: pnpm test:live src/image-generation/runtime.live.test.ts
• Arnés: pnpm test:live:media image
• Alcance:
  • Enumera todos los plugins de proveedor de generación de imágenes registrados
  • Carga las variables de entorno de proveedor faltantes desde tu shell de inicio de sesión (~/.profile) antes de sondear
  • Usa por defecto claves API live/env antes que los perfiles de autenticación almacenados, para que las claves de prueba obsoletas en auth-profiles.json no oculten las credenciales reales del shell
  • Omite proveedores sin autenticación/perfil/modelo utilizable
  • Ejecuta las variantes estándar de generación de imágenes mediante la capacidad de runtime compartida:
    • google:flash-generate
    • google:pro-generate
    • google:pro-edit
    • openai:default-generate
• Proveedores integrados cubiertos actualmente:
  • openai
  • google
• Acotación opcional:
  • OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"
  • OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"
  • OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"
• Comportamiento de autenticación opcional:
  • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 para forzar autenticación del almacén de perfiles e ignorar los overrides solo de env

Live de generación de música

• Prueba: extensions/music-generation-providers.live.test.ts
• Habilitar: OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
• Arnés: pnpm test:live:media music
• Alcance:
  • Ejercita la ruta compartida integrada del proveedor de generación de música
  • Actualmente cubre Google y MiniMax
  • Carga las variables de entorno del proveedor desde tu shell de inicio de sesión (~/.profile) antes de sondear
  • Usa por defecto claves API live/env antes que los perfiles de autenticación almacenados, para que las claves de prueba obsoletas en auth-profiles.json no oculten las credenciales reales del shell
  • Omite proveedores sin autenticación/perfil/modelo utilizable
  • Ejecuta ambos modos de runtime declarados cuando están disponibles:
    • generate con entrada solo de prompt
    • edit cuando el proveedor declara capabilities.edit.enabled
  • Cobertura actual del canal compartido:
    • google: generate, edit
    • minimax: generate
    • comfy: archivo live de Comfy separado, no este barrido compartido
• Acotación opcional:
  • OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"
  • OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"
• Comportamiento de autenticación opcional:
  • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 para forzar autenticación del almacén de perfiles e ignorar los overrides solo de env

Live de generación de video

• Prueba: extensions/video-generation-providers.live.test.ts
• Habilitar: OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
• Arnés: pnpm test:live:media video
• Alcance:
  • Ejercita la ruta compartida integrada del proveedor de generación de video
  • Usa por defecto la ruta de prueba rápida segura para lanzamiento: proveedores que no son FAL, una solicitud de texto a video por proveedor, prompt lobster de un segundo y un límite de operación por proveedor desde OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS (180000 por defecto)
  • Omite FAL por defecto porque la latencia de cola del lado del proveedor puede dominar el tiempo de lanzamiento; pasa --video-providers fal o OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal" para ejecutarlo explícitamente
  • Carga las variables de entorno del proveedor desde tu shell de inicio de sesión (~/.profile) antes de sondear
  • Usa por defecto claves API live/env antes que los perfiles de autenticación almacenados, para que las claves de prueba obsoletas en auth-profiles.json no oculten las credenciales reales del shell
  • Omite proveedores sin autenticación/perfil/modelo utilizable
  • Ejecuta solo generate por defecto
  • Establece OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1 para ejecutar también los modos de transformación declarados cuando estén disponibles:
    • imageToVideo cuando el proveedor declara capabilities.imageToVideo.enabled y el proveedor/modelo seleccionado acepta entrada de imagen local respaldada por búfer en el barrido compartido
    • videoToVideo cuando el proveedor declara capabilities.videoToVideo.enabled y el proveedor/modelo seleccionado acepta entrada de video local respaldada por búfer en el barrido compartido
  • Proveedores imageToVideo actualmente declarados pero omitidos en el barrido compartido:
    • vydra porque el veo3 integrado es solo texto y el kling integrado requiere una URL de imagen remota
  • Cobertura específica del proveedor Vydra:
    • OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts
    • ese archivo ejecuta veo3 de texto a video más un canal kling que usa por defecto un fixture de URL de imagen remota
  • Cobertura live actual de videoToVideo:
    • solo runway cuando el modelo seleccionado es runway/gen4_aleph
  • Proveedores videoToVideo actualmente declarados pero omitidos en el barrido compartido:
    • alibaba, qwen, xai porque esas rutas actualmente requieren URLs de referencia remotas http(s) / MP4
    • google porque el canal compartido actual de Gemini/Veo usa entrada local respaldada por búfer y esa ruta no se acepta en el barrido compartido
    • openai porque el canal compartido actual carece de garantías de acceso específicas de la organización para inpaint/remix de video
• Acotación opcional:
  • OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"
  • OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"
  • OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS="" para incluir todos los proveedores en el barrido predeterminado, incluido FAL
  • OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000 para reducir el límite de operación de cada proveedor en una ejecución agresiva de prueba rápida
• Comportamiento de autenticación opcional:
  • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 para forzar autenticación del almacén de perfiles e ignorar los overrides solo de env

Arnés live de medios

• Comando: pnpm test:live:media
• Propósito:
  • Ejecuta las suites live compartidas de imagen, música y video mediante un único entrypoint nativo del repositorio
  • Carga automáticamente las variables de entorno de proveedor faltantes desde ~/.profile
  • Acota automáticamente cada suite a los proveedores que actualmente tienen autenticación utilizable por defecto
  • Reutiliza scripts/test-live.mjs, para que el comportamiento de Heartbeat y de modo silencioso siga siendo consistente
• Ejemplos:
  • pnpm test:live:media
  • pnpm test:live:media image video --providers openai,google,minimax
  • pnpm test:live:media video --video-providers openai,runway --all-providers
  • pnpm test:live:media music --quiet

Ejecutores de Docker (comprobaciones opcionales de "funciona en Linux")

Estos ejecutores de Docker se dividen en dos grupos:

• Ejecutores de modelos live: test:docker:live-models y test:docker:live-gateway ejecutan solo su archivo live de claves de perfil correspondiente dentro de la imagen Docker del repositorio (src/agents/models.profiles.live.test.ts y src/gateway/gateway-models.profiles.live.test.ts), montando tu directorio de configuración local y espacio de trabajo (y cargando ~/.profile si está montado). Los entrypoints locales correspondientes son test:live:models-profiles y test:live:gateway-profiles.
• Los ejecutores live de Docker usan por defecto un límite menor de prueba rápida para que un barrido completo en Docker siga siendo práctico: test:docker:live-models usa por defecto OPENCLAW_LIVE_MAX_MODELS=12, y test:docker:live-gateway usa por defecto OPENCLAW_LIVE_GATEWAY_SMOKE=1, OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8, OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000 y OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000. Sustituye esas variables de entorno cuando explícitamente quieras el escaneo exhaustivo más grande.
• test:docker:all construye la imagen Docker live una vez mediante test:docker:live-build, luego la reutiliza para los dos canales Docker live.
• Los ejecutores de prueba rápida en contenedor: test:docker:openwebui, test:docker:onboard, test:docker:gateway-network, test:docker:mcp-channels y test:docker:plugins inician uno o más contenedores reales y verifican rutas de integración de más alto nivel.

Los ejecutores Docker de modelos live también montan mediante bind solo los homes de autenticación CLI necesarios (o todos los compatibles cuando la ejecución no está acotada), luego los copian al home del contenedor antes de la ejecución para que OAuth de CLI externa pueda refrescar tokens sin mutar el almacén de autenticación del host:

• Modelos directos: pnpm test:docker:live-models (script: scripts/test-live-models-docker.sh)
• Prueba rápida de enlace ACP: pnpm test:docker:live-acp-bind (script: scripts/test-live-acp-bind-docker.sh)
• Prueba rápida de backend CLI: pnpm test:docker:live-cli-backend (script: scripts/test-live-cli-backend-docker.sh)
• Prueba rápida del arnés app-server de Codex: pnpm test:docker:live-codex-harness (script: scripts/test-live-codex-harness-docker.sh)
• Gateway + agente de desarrollo: pnpm test:docker:live-gateway (script: scripts/test-live-gateway-models-docker.sh)
• Prueba rápida live de Open WebUI: pnpm test:docker:openwebui (script: scripts/e2e/openwebui-docker.sh)
• Asistente de onboarding (TTY, andamiaje completo): pnpm test:docker:onboard (script: scripts/e2e/onboard-docker.sh)
• Redes de Gateway (dos contenedores, autenticación WS + estado de salud): pnpm test:docker:gateway-network (script: scripts/e2e/gateway-network-docker.sh)
• Puente de canal MCP (Gateway inicializado + puente stdio + prueba rápida de tramas de notificación sin procesar de Claude): pnpm test:docker:mcp-channels (script: scripts/e2e/mcp-channels-docker.sh)
• Plugins (prueba rápida de instalación + alias /plugin + semántica de reinicio del paquete Claude): pnpm test:docker:plugins (script: scripts/e2e/plugins-docker.sh)

Los ejecutores Docker de modelos live también montan mediante bind el checkout actual en modo de solo lectura y lo preparan en un directorio de trabajo temporal dentro del contenedor. Esto mantiene la imagen de runtime liviana y a la vez ejecuta Vitest contra tu código/configuración local exactos. El paso de preparación omite grandes cachés solo locales y salidas de compilación de app como .pnpm-store, .worktrees, __openclaw_vitest__ y directorios locales de .build de app o salida de Gradle para que las ejecuciones live de Docker no pasen minutos copiando artefactos específicos de la máquina. También establecen OPENCLAW_SKIP_CHANNELS=1 para que los sondeos live de Gateway no inicien workers reales de canales de Telegram/Discord/etc. dentro del contenedor. test:docker:live-models sigue ejecutando pnpm test:live, así que transmite también OPENCLAW_LIVE_GATEWAY_* cuando necesites acotar o excluir la cobertura live de Gateway de ese canal Docker. test:docker:openwebui es una prueba rápida de compatibilidad de nivel superior: inicia un contenedor Gateway de OpenClaw con los endpoints HTTP compatibles con OpenAI habilitados, inicia un contenedor fijado de Open WebUI contra ese Gateway, inicia sesión mediante Open WebUI, verifica que /api/models exponga openclaw/default y luego envía una solicitud real de chat mediante el proxy /api/chat/completions de Open WebUI. La primera ejecución puede ser notablemente más lenta porque Docker puede necesitar descargar la imagen de Open WebUI y Open WebUI puede necesitar terminar su propia configuración de arranque en frío. Este canal espera una clave de modelo live utilizable, y OPENCLAW_PROFILE_FILE (~/.profile por defecto) es la forma principal de proporcionarla en ejecuciones con Docker. Las ejecuciones exitosas imprimen una pequeña carga útil JSON como { "ok": true, "model": "openclaw/default", ... }. test:docker:mcp-channels es intencionalmente determinista y no necesita una cuenta real de Telegram, Discord o iMessage. Inicia un contenedor Gateway inicializado, arranca un segundo contenedor que ejecuta openclaw mcp serve y luego verifica descubrimiento de conversaciones enrutadas, lecturas de transcripción, metadatos de adjuntos, comportamiento de la cola de eventos live, enrutamiento de envío saliente y notificaciones de canal + permisos estilo Claude sobre el puente MCP stdio real. La comprobación de notificaciones inspecciona directamente las tramas MCP stdio sin procesar para que la prueba rápida valide lo que el puente realmente emite, no solo lo que una SDK cliente específica casualmente expone.

Prueba manual ACP de hilo en lenguaje natural (no CI):

• bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...
• Mantén este script para flujos de trabajo de regresión/depuración. Puede volver a ser necesario para la validación del enrutamiento de hilos ACP, así que no lo elimines.

Variables de entorno útiles:

• OPENCLAW_CONFIG_DIR=... (predeterminado: ~/.openclaw) montado en /home/node/.openclaw
• OPENCLAW_WORKSPACE_DIR=... (predeterminado: ~/.openclaw/workspace) montado en /home/node/.openclaw/workspace
• OPENCLAW_PROFILE_FILE=... (predeterminado: ~/.profile) montado en /home/node/.profile y cargado antes de ejecutar las pruebas
• OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1 para verificar solo variables de entorno cargadas desde OPENCLAW_PROFILE_FILE, usando directorios temporales de configuración/espacio de trabajo y sin montajes externos de autenticación CLI
• OPENCLAW_DOCKER_CLI_TOOLS_DIR=... (predeterminado: ~/.cache/openclaw/docker-cli-tools) montado en /home/node/.npm-global para instalaciones CLI en caché dentro de Docker
• Los directorios/archivos de autenticación de CLI externos bajo $HOME se montan en modo de solo lectura bajo /host-auth..., luego se copian a /home/node/... antes de iniciar las pruebas
  • Directorios predeterminados: .minimax
  • Archivos predeterminados: ~/.codex/auth.json, ~/.codex/config.toml, .claude.json, ~/.claude/.credentials.json, ~/.claude/settings.json, ~/.claude/settings.local.json
  • Las ejecuciones acotadas por proveedor montan solo los directorios/archivos necesarios inferidos de OPENCLAW_LIVE_PROVIDERS / OPENCLAW_LIVE_GATEWAY_PROVIDERS
  • Sustituye manualmente con OPENCLAW_DOCKER_AUTH_DIRS=all, OPENCLAW_DOCKER_AUTH_DIRS=none o una lista separada por comas como OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex
• OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... para acotar la ejecución
• OPENCLAW_LIVE_GATEWAY_PROVIDERS=... / OPENCLAW_LIVE_PROVIDERS=... para filtrar proveedores dentro del contenedor
• OPENCLAW_SKIP_DOCKER_BUILD=1 para reutilizar una imagen existente openclaw:local-live en reejecuciones que no necesitan recompilación
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 para asegurar que las credenciales provengan del almacén de perfiles (no de env)
• OPENCLAW_OPENWEBUI_MODEL=... para elegir el modelo expuesto por Gateway para la prueba rápida de Open WebUI
• OPENCLAW_OPENWEBUI_PROMPT=... para sustituir el prompt de verificación de nonce usado por la prueba rápida de Open WebUI
• OPENWEBUI_IMAGE=... para sustituir la etiqueta fijada de imagen de Open WebUI

Verificación de documentación

Ejecuta las comprobaciones de documentación después de editar docs: pnpm check:docs. Ejecuta la validación completa de anclas de Mintlify cuando también necesites comprobaciones de encabezados dentro de la página: pnpm docs:check-links:anchors.

Regresión offline (segura para CI)

Estas son regresiones de “canalización real” sin proveedores reales:

• Llamada a herramientas de Gateway (mock OpenAI, loop real de Gateway + agente): src/gateway/gateway.test.ts (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop")
• Asistente de Gateway (WS wizard.start/wizard.next, escribe configuración + autenticación exigida): src/gateway/gateway.test.ts (caso: "runs wizard over ws and writes auth token config")

Evaluaciones de fiabilidad del agente (Skills)

Ya tenemos algunas pruebas seguras para CI que se comportan como “evaluaciones de fiabilidad del agente”:

• Llamada simulada a herramientas mediante el loop real de Gateway + agente (src/gateway/gateway.test.ts).
• Flujos end-to-end del asistente que validan el cableado de la sesión y los efectos de configuración (src/gateway/gateway.test.ts).

Qué sigue faltando para Skills (ver Skills):

• Toma de decisiones: cuando Skills aparecen en el prompt, ¿el agente elige la Skill correcta (o evita las irrelevantes)?
• Cumplimiento: ¿el agente lee SKILL.md antes de usarla y sigue los pasos/args requeridos?
• Contratos de flujo de trabajo: escenarios de varios turnos que comprueban el orden de herramientas, el arrastre del historial de sesión y los límites del sandbox.

Las evaluaciones futuras deben seguir siendo deterministas primero:

• Un ejecutor de escenarios que use proveedores simulados para comprobar llamadas a herramientas + orden, lecturas de archivos de Skill y cableado de sesión.
• Una pequeña suite de escenarios centrados en Skills (usar vs evitar, puertas, prompt injection).
• Evaluaciones live opcionales (opt-in, controladas por env) solo después de que la suite segura para CI esté implementada.

Pruebas de contrato (forma de Plugin y canal)

Las pruebas de contrato verifican que cada Plugin y canal registrados cumplan con su contrato de interfaz. Iteran sobre todos los plugins detectados y ejecutan una suite de comprobaciones de forma y comportamiento. El canal unitario predeterminado pnpm test omite intencionalmente estos archivos compartidos de interfaz y prueba rápida; ejecuta los comandos de contrato explícitamente cuando toques superficies compartidas de canal o proveedor.

Comandos

• Todos los contratos: pnpm test:contracts
• Solo contratos de canal: pnpm test:contracts:channels
• Solo contratos de proveedor: pnpm test:contracts:plugins

Contratos de canal

Ubicados en src/channels/plugins/contracts/*.contract.test.ts:

• plugin - Forma básica del Plugin (id, nombre, capacidades)
• setup - Contrato del asistente de configuración
• session-binding - Comportamiento de vinculación de sesión
• outbound-payload - Estructura de la carga útil del mensaje
• inbound - Manejo de mensajes entrantes
• actions - Manejadores de acciones del canal
• threading - Manejo de id de hilo
• directory - API de directorio/lista
• group-policy - Aplicación de la política de grupo

Contratos de estado del proveedor

Ubicados en src/plugins/contracts/*.contract.test.ts.

• status - Sondeos de estado del canal
• registry - Forma del registro de Plugin

Contratos de proveedor

Ubicados en src/plugins/contracts/*.contract.test.ts:

• auth - Contrato de flujo de autenticación
• auth-choice - Elección/selección de autenticación
• catalog - API del catálogo de modelos
• discovery - Descubrimiento de Plugin
• loader - Carga de Plugin
• runtime - Runtime del proveedor
• shape - Forma/interfaz del Plugin
• wizard - Asistente de configuración

Cuándo ejecutarlas

• Después de cambiar exportaciones o subrutas de plugin-sdk
• Después de agregar o modificar un Plugin de canal o proveedor
• Después de refactorizar el registro o descubrimiento de plugins

Las pruebas de contrato se ejecutan en CI y no requieren claves API reales.

Agregar regresiones (guía)

Cuando corrijas un problema de proveedor/modelo detectado en live:

• Agrega una regresión segura para CI si es posible (proveedor simulado/stub, o captura la transformación exacta de la forma de la solicitud)
• Si es inherentemente solo live (límites de tasa, políticas de autenticación), mantén la prueba live acotada y opt-in mediante variables de entorno
• Prefiere apuntar a la capa más pequeña que detecte el error:
  • error de conversión/reproducción de solicitud del proveedor → prueba de modelos directos
  • error en la canalización de sesión/historial/herramientas de Gateway → prueba rápida live de Gateway o prueba simulada segura para CI de Gateway
• Barandilla de recorrido de SecretRef:
  • src/secrets/exec-secret-ref-id-parity.test.ts deriva un objetivo de muestra por clase de SecretRef a partir de los metadatos del registro (listSecretTargetRegistryEntries()), y luego comprueba que se rechacen los ids exec de segmento de recorrido.
  • Si agregas una nueva familia de objetivos SecretRef includeInPlan en src/secrets/target-registry-data.ts, actualiza classifyTargetClass en esa prueba. La prueba falla intencionalmente en ids de objetivo no clasificados para que las clases nuevas no puedan omitirse en silencio.