Pruebas

Pruebas

OpenClaw tiene tres suites de Vitest (unit/integration, 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, pre-push, depuración)
• Cómo las pruebas en vivo descubren las credenciales y seleccionan modelos/proveedores
• Cómo agregar regresiones para problemas reales de modelos/proveedores

Inicio rápido

La mayoría de los días:

• Puerta completa (se espera antes de hacer push): pnpm build && pnpm check && pnpm test

Cuando tocas pruebas o quieres mayor confianza:

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

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

• Suite Live (modelos + sondas de herramientas/imágenes de gateway): pnpm test:live

Consejo: cuando solo necesitas un caso fallido, prefiere limitar las pruebas en vivo mediante las variables de entorno de allowlist descritas a continuación.

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

Piensa en las suites como “realismo incremental” (y mayor inestabilidad/costo):

Unitaria / integración (predeterminada)

• Comando: pnpm test
• Configuración: vitest.config.ts
• Archivos: src/**/*.test.ts
• Alcance:
  • Pruebas unitarias puras
  • Pruebas de integración en proceso (autenticación de gateway, enrutamiento, herramientas, análisis, configuración)
  • Regresiones deterministas para errores conocidos
• Expectativas:
  • Se ejecuta en CI
  • No se requieren claves reales
  • Debe ser rápida y estable

E2E (gateway smoke)

• Comando: pnpm test:e2e
• Configuración: vitest.e2e.config.ts
• Archivos: src/**/*.e2e.test.ts
• Alcance:
  • Comportamiento end-to-end de gateway de múltiples instancias
  • Superficies WebSocket/HTTP, emparejamiento de nodos y redes más pesadas
• Expectativas:
  • Se ejecuta en CI (cuando está habilitado en la canalización)
  • No se requieren claves reales
  • Más partes móviles que las pruebas unitarias (pueden ser más lentas)

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:
  • “¿Funciona este proveedor/modelo realmente 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 velocidad
• Expectativas:
  • No es estable en CI por diseño (redes reales, políticas de proveedor reales, cuotas, interrupciones)
  • Cuesta dinero / usa límites de velocidad
  • Preferir ejecutar subconjuntos reducidos en lugar de “todo”
  • Las ejecuciones en vivo obtendrán ~/.profile para recuperar las claves de API faltantes
  • Rotación de claves de Anthropic: establezca OPENCLAW_LIVE_ANTHROPIC_KEYS="sk-...,sk-..." (o OPENCLAW_LIVE_ANTHROPIC_KEY=sk-...) o múltiples variables ANTHROPIC_API_KEY*; las pruebas reintentarán en los límites de velocidad

¿Qué suite debería ejecutar?

Use esta tabla de decisiones:

• Editando lógica/pruebas: ejecute pnpm test (y pnpm test:coverage si cambió mucho)
• Tocando redes de puerta de enlace / protocolo WS / emparejamiento: agregue pnpm test:e2e
• Depurando “mi bot está caído” / fallas específicas del proveedor / llamadas a herramientas: ejecute un pnpm test:live reducido

En vivo: prueba de humo del modelo (claves de perfil)

Las pruebas en vivo se dividen en dos capas para poder aislar fallas:

• “Modelo directo” nos indica que el proveedor/modelo puede responder en absoluto con la clave dada.
• “Prueba de humo de puerta de enlace” nos indica que la tubería completa de puerta de enlace+agente funciona para ese modelo (sesiones, historial, herramientas, política de sandbox, etc.).

Capa 1: Finalización de modelo directo (sin puerta de enlace)

• Prueba: src/agents/models.profiles.live.test.ts
• Objetivo:
  • Enumerar modelos descubiertos
  • Use getApiKeyForModel para seleccionar modelos para los que tenga 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 invoca Vitest directamente)
• Establezca OPENCLAW_LIVE_MODELS=modern (o all, alias para moderno) para ejecutar realmente esta suite; de lo contrario, la omite para mantener pnpm test:live enfocado en la prueba de humo de la puerta de enlace
• Cómo seleccionar modelos:
  • OPENCLAW_LIVE_MODELS=modern para ejecutar la lista blanca moderna (Opus/Sonnet/Haiku 4.5, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.1, Grok 4)
  • OPENCLAW_LIVE_MODELS=all es un alias para la lista blanca moderna
  • o OPENCLAW_LIVE_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-5,..." (lista blanca separada por comas)
• Cómo seleccionar proveedores:
  • OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli" (lista blanca separada por comas)
• De dónde provienen las claves:
  • Por defecto: almacenamiento de perfiles y alternativas de entorno
  • Establezca OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 para forzar solo el almacenamiento 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 la puerta de enlace está rota”
  • Contiene pequeñas regresiones aisladas (ejemplo: repetición del razonamiento de OpenAI Responses/Codex Responses + flujos de llamadas a herramientas)

Capa 2: Prueba de humo de la puerta de enlace + agente de desarrollo (lo que realmente hace “@openclaw”)

• Prueba: src/gateway/gateway-models.profiles.live.test.ts
• Objetivo:
  • Iniciar una puerta de enlace dentro del proceso
  • Crear/Parchear una sesión agent:dev:* (anulación del modelo por ejecución)
  • Iterar modelos con claves y afirmar:
    • respuesta “significativa” (sin herramientas)
    • una invocación de herramienta real funciona (sondeo de lectura)
    • sondeos de herramientas adicionales opcionales (sondeo exec+read)
    • las rutas de regresión de OpenAI (solo llamada a herramienta → seguimiento) siguen funcionando
• Detalles del sondeo (para que pueda explicar los fallos rápidamente):
  • sondeo read: la prueba escribe un archivo nonce en el espacio de trabajo y pide al agente que lo read y devuelva el nonce.
  • sondeo exec+read: la prueba pide al agente que exec-escriba un nonce en un archivo temporal y luego lo 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 se invoca Vitest directamente)
• Cómo seleccionar modelos:
  • Por defecto: lista blanca moderna (Opus/Sonnet/Haiku 4.5, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.1, Grok 4)
  • OPENCLAW_LIVE_GATEWAY_MODELS=all es un alias para la lista blanca moderna
  • O establezca OPENCLAW_LIVE_GATEWAY_MODELS="provider/model" (o lista separada por comas) para reducir
• Cómo seleccionar proveedores (evitar “todo OpenRouter”):
  • OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax" (lista blanca separada por comas)
• Los sondeos de herramientas e imágenes siempre están activos en esta prueba en vivo:
  • sondeo read + sondeo exec+read (estrés de herramientas)
  • el sondeo de imagen se ejecuta cuando el modelo anuncia soporte de entrada de imagen
  • Flujo (nivel alto):
    • La prueba genera un pequeño PNG con “CAT” + código aleatorio (src/gateway/live-image-probe.ts)
    • Lo envía a través de agent attachments: [{ mimeType: "image/png", content: "<base64>" }]
    • El Gateway analiza los archivos adjuntos en images[] (src/gateway/server-methods/agent.ts + src/gateway/chat-attachments.ts)
    • El agente integrado reenvía un mensaje multimodal del usuario al modelo
    • Aserción: la respuesta contiene cat + el código (tolerancia OCR: se permiten errores menores)

Consejo: para ver qué puede probar en su máquina (y los ids exactos de provider/model), ejecute:

openclaw models list
openclaw models list --json

Live: prueba de humo del setup-token de Anthropic

• Prueba: src/agents/anthropic.setup-token.live.test.ts
• Objetivo: verificar que el setup-token de la CLI de Claude Code (o un perfil de setup-token pegado) pueda completar un prompt de Anthropic.
• Activar:
  • pnpm test:live (o OPENCLAW_LIVE_TEST=1 si invoca Vitest directamente)
  • OPENCLAW_LIVE_SETUP_TOKEN=1
• Fuentes del token (elija una):
  • Perfil: OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test
  • Token sin procesar: OPENCLAW_LIVE_SETUP_TOKEN_VALUE=sk-ant-oat01-...
• Anulación de modelo (opcional):
  • OPENCLAW_LIVE_SETUP_TOKEN_MODEL=anthropic/claude-opus-4-5

Ejemplo de configuración:

openclaw models auth paste-token --provider anthropic --profile-id anthropic:setup-token-test
OPENCLAW_LIVE_SETUP_TOKEN=1 OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test pnpm test:live src/agents/anthropic.setup-token.live.test.ts

Live: prueba de humo del backend de CLI (CLI de Claude Code u otras CLIs locales)

• Prueba: src/gateway/gateway-cli-backend.live.test.ts
• Objetivo: validar la canalización del Gateway + agente utilizando un backend de CLI local, sin tocar su configuración predeterminada.
• Activar:
  • pnpm test:live (o OPENCLAW_LIVE_TEST=1 si invoca Vitest directamente)
  • OPENCLAW_LIVE_CLI_BACKEND=1
• Valores predeterminados:
  • Modelo: claude-cli/claude-sonnet-4-5
  • Comando: claude
  • Argumentos: ["-p","--output-format","json","--dangerously-skip-permissions"]
• Anulaciones (opcional):
  • OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-opus-4-5"
  • OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2-codex"
  • OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/claude"
  • OPENCLAW_LIVE_CLI_BACKEND_ARGS='["-p","--output-format","json","--permission-mode","bypassPermissions"]'
  • OPENCLAW_LIVE_CLI_BACKEND_CLEAR_ENV='["ANTHROPIC_API_KEY","ANTHROPIC_API_KEY_OLD"]'
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1 para enviar un archivo adjunto de imagen real (las rutas se inyectan en el prompt).
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image" para pasar las rutas de archivos de imagen como argumentos de CLI en lugar de inyección de prompt.
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat" (o "list") para controlar cómo se pasan los argumentos 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_DISABLE_MCP_CONFIG=0 para mantener la configuración MCP de Claude Code CLI habilitada (por defecto se deshabilita la configuración MCP con un archivo temporal vacío).

Ejemplo:

OPENCLAW_LIVE_CLI_BACKEND=1 \
  OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-sonnet-4-5" \
  pnpm test:live src/gateway/gateway-cli-backend.live.test.ts

Recetas live recomendadas

Las listas de permitidos estrechas y explícitas son las más rápidas y menos propensas a fallos:

• Modelo único, directo (sin gateway):

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

• Modelo único, prueba de humo del gateway:

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

• Llamada a herramientas en varios proveedores:

  • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-5,google/gemini-3-flash-preview,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

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

  • Gemini (clave de 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-5-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 de API).
• google-antigravity/... usa el puente OAuth de Antigravity (extremo del agente estilo Cloud Code Assist).
• google-gemini-cli/... usa la CLI de Gemini local en su máquina (autenticación separada + peculiaridades de herramientas).
• API de Gemini vs CLI de Gemini:
  • API: OpenClaw llama a la API alojada de Gemini de Google a través de HTTP (clave de API / autenticación de perfil); esto es lo que la mayoría de los usuarios entienden por “Gemini”.
  • CLI: OpenClaw ejecuta un binario gemini local; tiene su propia autenticación y puede comportarse de manera diferente (transmisión / soporte de herramientas / discrepancia de versión).

Live: matriz de modelos (lo que cubrimos)

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

Conjunto moderno de pruebas de humo (llamada a herramientas + imagen)

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

• OpenAI (no Codex): openai/gpt-5.2 (opcional: openai/gpt-5.1)
• OpenAI Codex: openai-codex/gpt-5.2 (opcional: openai-codex/gpt-5.2-codex)
• Anthropic: anthropic/claude-opus-4-5 (o anthropic/claude-sonnet-4-5)
• Google (API de Gemini): google/gemini-3-pro-preview y google/gemini-3-flash-preview (evitar los modelos más antiguos de Gemini 2.x)
• Google (Antigravity): google-antigravity/claude-opus-4-5-thinking y google-antigravity/gemini-3-flash
• Z.AI (GLM): zai/glm-4.7
• MiniMax: minimax/minimax-m2.1

Ejecutar prueba de humo del gateway con herramientas + imagen: OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-5,google/gemini-3-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-5-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

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

Elija al menos uno por familia de proveedores:

• OpenAI: openai/gpt-5.2 (o openai/gpt-5-mini)
• Anthropic: anthropic/claude-opus-4-5 (o anthropic/claude-sonnet-4-5)
• Google: google/gemini-3-flash-preview (o google/gemini-3-pro-preview)
• Z.AI (GLM): zai/glm-4.7
• MiniMax: minimax/minimax-m2.1

Cobertura adicional opcional (deseable):

• xAI: xai/grok-4 (o la última disponible)
• Mistral: mistral/… (elija un modelo capaz de usar “herramientas” que tenga habilitado)
• Cerebras: cerebras/… (si tiene acceso)
• LM Studio: lmstudio/… (local; el uso de herramientas depende del modo API)

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

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

Agregadores / gateways alternativos

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

• OpenRouter: openrouter/... (cientos de modelos; use openclaw models scan para encontrar candidatos capaces de usar herramientas e imágenes)
• OpenCode Zen: opencode/... (autenticación mediante OPENCODE_API_KEY / OPENCODE_ZEN_API_KEY)

Más proveedores que puede incluir en la matriz en vivo (si tiene credenciales/configuración):

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

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

Credenciales (nunca las confirmes)

Las pruebas en vivo descubren las credenciales de la misma manera que lo hace la CLI. Implicaciones prácticas:

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

• Si una prueba en vivo dice “no creds” (sin credenciales), depura de la misma manera en la que depurarías openclaw models list / la selección de modelos.

• Almacén de perfiles: ~/.openclaw/credentials/ (preferido; a lo que se refiere “profile keys” en las pruebas)

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

Si deseas confiar en claves de entorno (por ejemplo, exportadas en tu ~/.profile), ejecuta pruebas locales después de source ~/.profile, o usa los ejecutores de Docker a continuación (pueden montar ~/.profile en el contenedor).

Deepgram en vivo (transcripción de audio)

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

Ejecutores de Docker (verificaciones opcionales de “funciona en Linux”)

Estos ejecutan pnpm test:live dentro de la imagen Docker del repositorio, montando tu directorio de configuración local y el espacio de trabajo (y sourceando ~/.profile si está montado):

• Modelos directos: pnpm test:docker:live-models (script: scripts/test-live-models-docker.sh)
• Gateway + agente de desarrollo: pnpm test:docker:live-gateway (script: scripts/test-live-gateway-models-docker.sh)
• Asistente de incorporación (TTY, andamiaje completo): pnpm test:docker:onboard (script: scripts/e2e/onboard-docker.sh)
• Red del Gateway (dos contenedores, autenticación WS + estado): pnpm test:docker:gateway-network (script: scripts/e2e/gateway-network-docker.sh)
• Complementos (carga de extensiones personalizadas + prueba de humo del registro): pnpm test:docker:plugins (script: scripts/e2e/plugins-docker.sh)

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 sourceado antes de ejecutar las pruebas
• OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... para limitar la ejecución
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 para asegurar que las credenciales provengan del almacén de perfiles (no de env)

Cordura de la documentación

Ejecute las comprobaciones de documentación después de editar los documentos: pnpm docs:list.

Regresión sin conexión (segura para CI)

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

• Llamada a herramientas de la puerta de enlace (OpenAI simulada, puerta de enlace real + bucle de agente): src/gateway/gateway.tool-calling.mock-openai.test.ts
• Asistente de puerta de enlace (WS wizard.start/wizard.next, escribe config + autenticación forzada): src/gateway/gateway.wizard.e2e.test.ts

Evaluaciones de confiabilidad del agente (habilidades)

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

• Llamada a herramientas simulada a través de la puerta de enlace real + bucle de agente (src/gateway/gateway.tool-calling.mock-openai.test.ts).
• Flujos de extremo a extremo del asistente que validan el cableado de la sesión y los efectos de configuración (src/gateway/gateway.wizard.e2e.test.ts).

Lo que aún falta para las habilidades (consulte Habilidades):

• Toma de decisiones: cuando las habilidades se enumeran en el mensaje, ¿el agente elige la habilidad correcta (o evita las irrelevantes)?
• Cumplimiento: ¿el agente lee SKILL.md antes de usarlo y sigue los pasos/argumentos requeridos?
• Contratos de flujo de trabajo: escenarios de múltiples turnos que afirman el orden de las herramientas, la continuidad del historial de sesión y los límites del espacio aislado.

Las evaluaciones futuras deben mantenerse primero deterministas:

• Un ejecutor de escenarios que utiliza proveedores simulados para afirmar las llamadas a herramientas + el orden, las lecturas de archivos de habilidades y el cableado de la sesión.
• Un pequeño conjunto de escenarios centrados en habilidades (uso frente a evitación, bloqueo, inyección de mensajes).
• Evaluaciones en vivo opcionales (opcional, limitadas por entorno) solo después de que el conjunto seguro para CI esté en su lugar.

Adición de regresiones (guía)

Cuando soluciona un problema de proveedor/modelo descubierto en vivo:

• Agregue una regresión segura para CI si es posible (proveedor simulado/tipo stub, o capture la transformación exacta de la forma de la solicitud)
• Si es inherentemente solo en vivo (límites de velocidad, políticas de autenticación), mantenga la prueba en vivo limitada y opcional mediante variables de entorno
• Prefiera 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 de canalización de sesión/historial/herramientas de puerta de enlace → prueba de humo en vivo de puerta de enlace o prueba simulada de puerta de enlace segura para CI