Guía de Testing en OpenClaw: Ejecuta Suites y QA

Inicio rápido

La mayoría de los días, puedes seguir este flujo de trabajo para asegurar la calidad de OpenClaw:

1. Ejecución completa antes de subir cambios (gate): pnpm build && pnpm check && pnpm check:test-types && pnpm test
2. Ejecución rápida de toda la suite en una máquina potente: pnpm test:max
3. Bucle de observación directa de Vitest: pnpm test:watch
4. Ejecución dirigida a un archivo específico (ahora también funciona para rutas de extensiones/canales): pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
5. Prefiere ejecuciones dirigidas cuando estés iterando sobre un error puntual.
6. Sitio de QA basado en Docker: pnpm qa:lab:up
7. Carril de QA basado en Linux VM: pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline

Cuando modifiques pruebas o necesites confianza adicional:

1. Control de cobertura: pnpm test:coverage
2. Suite E2E: pnpm test:e2e

Cuando depures proveedores/modelos reales (requiere credenciales reales):

1. Suite en vivo (modelos + herramientas de Gateway/pruebas de imagen): pnpm test:live
2. Ejecutar un archivo en vivo de forma silenciosa: pnpm test:live -- src/agents/models.profiles.live.test.ts

Consejo: cuando solo necesites un caso que falla, prefiere limitar las pruebas en vivo mediante las variables de entorno de lista de permitidos descritas más adelante.

Ejecutores específicos de QA

Estos comandos acompañan a las suites de prueba principales cuando necesitas realismo de laboratorio de QA:

1. pnpm openclaw qa suite
   • Ejecuta escenarios de QA respaldados por el repositorio directamente en el host.
   • Ejecuta múltiples escenarios seleccionados en paralelo por defecto con trabajadores de Gateway aislados. qa-channel usa una concurrencia de 4 por defecto (limitada por el número de escenarios seleccionados). Usa --concurrency <count> para ajustar el número de trabajadores, o --concurrency 1 para el carril serial antiguo.
   • Sale con un código distinto de cero cuando falla cualquier escenario. Usa --allow-failures cuando quieras artefactos sin un código de salida de error.
   • Soporta modos de proveedor live-frontier, mock-openai y aimock. aimock inicia un servidor de proveedor local respaldado por AIMock para cobertura de fixtures experimentales y simulación de protocolos sin reemplazar el carril mock-openai consciente del escenario.
2. pnpm openclaw qa suite --runner multipass
   • Ejecuta la misma suite de QA dentro de una VM de 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 en vivo reenvían las entradas de autenticación de QA soportadas que son prácticas para el invitado: claves de proveedor basadas en entorno, la ruta de configuración del proveedor en vivo 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 a través del espacio de trabajo montado.
   • Escribe el informe de QA normal + resumen además de los registros de Multipass bajo .artifacts/qa-e2e/....
3. pnpm qa:lab:up
   • Inicia el sitio de QA respaldado por Docker para trabajo de QA estilo operador.
4. pnpm openclaw qa aimock
   • Inicia solo el servidor de proveedor AIMock local para pruebas de humo de protocolo directas.
5. pnpm openclaw qa matrix
   • Ejecuta el carril de QA en vivo de Matrix contra un servidor doméstico Tuwunel desechable respaldado por Docker.
   • Este host de QA es solo para el repositorio/desarrollo actualmente. Las instalaciones empaquetadas de OpenClaw no incluyen qa-lab, por lo que no exponen openclaw qa.
   • Los clones del repositorio cargan el ejecutor incluido directamente; no se necesita un paso de instalación de plugin separado.
   • Provee tres usuarios de Matrix temporales (driver, sut, observer) más una sala privada, luego inicia un hijo de Gateway de QA con el plugin de Matrix real como transporte SUT.
   • Usa la imagen estable fijada de Tuwunel ghcr.io/matrix-construct/tuwunel:v1.5.1 por defecto. Sobrescribe con OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE cuando necesites probar una imagen diferente.
   • Matrix no expone banderas de fuentes de credenciales compartidas porque el carril provee usuarios desechables localmente.
   • Escribe un informe de QA de Matrix, resumen, artefacto de eventos observados y salida combinada de stdout/stderr bajo .artifacts/qa-e2e/....
6. pnpm openclaw qa telegram
   • Ejecuta el carril de QA en vivo de Telegram contra un grupo privado real usando los tokens de bot del driver y del SUT desde el entorno.
   • 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 de chat de Telegram.
   • Soporta --credential-source convex para credenciales compartidas agrupadas. Usa el modo de entorno por defecto, o establece OPENCLAW_QA_CREDENTIAL_SOURCE=convex para optar por arrendamientos agrupados.
   • Sale con un código distinto de cero cuando falla cualquier escenario. Usa --allow-failures cuando quieras artefactos sin un código de salida de error.
   • 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 de bot a bot, habilita el Modo de Comunicación Bot-a-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, resumen y artefacto de mensajes observados bajo .artifacts/qa-e2e/....

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

Piensa en las suites como un “aumento de realismo” (y un aumento de inestabilidad/costo):

Unidad / integración (por defecto)

• Comando: pnpm test
• Configuración: diez ejecuciones de fragmentos secuenciales (vitest.full-*.config.ts) sobre los proyectos de Vitest existentes.
• Archivos: inventarios de unidad/núcleo bajo src/**/*.test.ts, packages/**/*.test.ts, test/**/*.test.ts, y las pruebas de Node.js de la interfaz de usuario incluidas en vitest.unit.config.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 GitHub CI.
  • No requiere claves reales.
  • Debe ser rápido y estable.

E2E (humo de Gateway)

• Comando: pnpm test:e2e
• Configuración: vitest.e2e.config.ts
• Archivos: src/**/*.e2e.test.ts, test/**/*.e2e.test.ts
• Alcance:
  • Comportamiento de extremo a extremo de Gateway con múltiples instancias.
  • Superficies WebSocket/HTTP, emparejamiento de nodos y redes más pesadas.
• Expectativas:
  • Se ejecuta en GitHub CI (cuando está habilitado en el pipeline).
  • No requiere claves reales.
  • Más partes móviles que las pruebas unitarias (puede ser más lento).

E2E: Humo del backend de OpenShell

• Comando: pnpm test:e2e:openshell
• Archivo: test/openshell-sandbox.e2e.test.ts
• Alcance:
  • Inicia un Gateway de OpenShell aislado en el host mediante Docker.
  • Crea un sandbox desde un Dockerfile local temporal.
  • Ejercita el backend de OpenShell de OpenClaw sobre sandbox ssh-config + ejecución SSH real.
  • Verifica el comportamiento del sistema de archivos canónico remoto a través del puente fs del sandbox.
• Expectativas:
  • Solo bajo demanda; no es parte de la ejecución por defecto de pnpm test:e2e.
  • Requiere un CLI de openshell local más un demonio de Docker funcional.

En vivo (proveedores reales + modelos reales)

• Comando: pnpm test:live
• Configuración: vitest.live.config.ts
• Archivos: src/**/*.live.test.ts
• Por defecto: 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 de proveedores, cuotas, cortes).
  • Cuesta dinero / usa límites de tasa.
  • Prefiere ejecutar subconjuntos limitados en lugar de “todo”.

¿Qué suite debería ejecutar?

Usa esta tabla de decisiones:

• Editando lógica/pruebas: ejecuta pnpm test (y pnpm test:coverage si cambiaste mucho).
• Tocando redes de Gateway / protocolo WS / emparejamiento: añade pnpm test:e2e.
• Depurando “mi bot está caído” / fallos específicos del proveedor / llamadas a herramientas: ejecuta un pnpm test:live limitado.

AI Setup Assistant

Live: Android node capability sweep

Esta prueba verifica que los nodos de Android funcionen correctamente dentro de tu entorno. OpenClaw Android node permite validar la ejecución de comandos y asegurar que el contrato de comportamiento se cumpla en dispositivos conectados.

• Test: src/gateway/android-node.capabilities.live.test.ts
• Script: pnpm android:test:integration
• Objetivo: invocar cada comando anunciado actualmente por un nodo de Android conectado y verificar el comportamiento del contrato del comando.
• Alcance:
  • Configuración manual/precondicionada (la suite no instala, ejecuta ni empareja la aplicación).
  • Validación node.invoke del Gateway comando por comando para el nodo de Android seleccionado.
• Configuración previa requerida:
  • Aplicación de Android ya conectada + emparejada con el Gateway.
  • Aplicación mantenida en primer plano.
  • Permisos/consentimiento de captura otorgados para las capacidades que esperas que pasen.
• Sobrescrituras de destino 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 la configuración de Android: Android App

Live: model smoke (profile keys)

Las pruebas en vivo se dividen en dos capas para que puedas aislar fallos de manera efectiva.

• “Direct model” te indica si el proveedor/modelo puede responder con la clave proporcionada.
• “Gateway smoke” te indica si el pipeline completo de Gateway+agente funciona para ese modelo (sesiones, historial, herramientas, política de sandbox, etc.).

Capa 1: Completado de modelo directo (sin Gateway)

• Test: src/agents/models.profiles.live.test.ts
• Objetivo:
  • Enumerar los modelos descubiertos
  • Usar getApiKeyForModel para seleccionar modelos para los cuales tienes credenciales
  • Ejecutar un pequeño completado por modelo (y regresiones dirigidas donde 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 para modern) para ejecutar esta suite; de lo contrario, se saltará para mantener pnpm test:live enfocado en el Gateway smoke.
• Cómo seleccionar modelos:
  • OPENCLAW_LIVE_MODELS=modern para ejecutar la lista de permitidos 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 para la lista de permitidos moderna
  • o OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..." (lista de permitidos separada por comas)
  • Los barridos modern/all tienen 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 de permitidos separada por comas)
• De dónde provienen las claves:
  • Por defecto: almacén de perfiles y respaldos de variables de entorno
  • Establece OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 para forzar solo el almacén de perfiles
• Por qué existe esto:
  • Separa si “la API del proveedor está rota / la clave no es válida” de “el pipeline del agente del Gateway está roto”
  • Contiene regresiones pequeñas y aisladas (ejemplo: flujos de reproducción de razonamiento de OpenAI Responses/Codex Responses + llamadas a herramientas)

Capa 2: Gateway + dev agent smoke (lo que “@openclaw” realmente hace)

• Test: src/gateway/gateway-models.profiles.live.test.ts
• Objetivo:
  • Iniciar un Gateway en proceso
  • Crear/parchear una sesión agent:dev:* (sobrescritura de modelo por ejecución)
  • Iterar modelos-con-claves y verificar:
    • Respuesta “significativa” (sin herramientas)
    • Que una invocación de herramienta real funcione (sonda de lectura)
    • Sondas de herramientas adicionales opcionales (sonda exec+read)
    • Rutas de regresión de OpenAI (tool-call-only → seguimiento) sigan funcionando
• Detalles de la sonda (para que puedas explicar fallos rápidamente):
  • Sonda read: el test escribe un archivo nonce en el espacio de trabajo y le pide al agente que lo read y devuelva el nonce.
  • Sonda exec+read: el test le pide al agente que exec-escriba un nonce en un archivo temporal, luego lo read de vuelta.
  • Sonda de imagen: el test 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:
  • Por defecto: lista de permitidos 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 para la lista de permitidos moderna
  • O establece OPENCLAW_LIVE_GATEWAY_MODELS="provider/model" (o lista separada por comas) para reducir
  • Los barridos de Gateway modern/all tienen 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 (evita “OpenRouter everything”):
  • OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax" (lista de permitidos separada por comas)
• Las sondas de herramientas + imagen siempre están activas en esta prueba en vivo:
  • Sonda read + sonda exec+read (estrés de herramientas)
  • La sonda de imagen se ejecuta cuando el modelo anuncia soporte de entrada de imagen
  • Flujo (alto nivel):
    • El test genera un pequeño PNG con “CAT” + código aleatorio (src/gateway/live-image-probe.ts)
    • Lo envía vía 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 embebido reenvía un mensaje de usuario multimodal al modelo
    • Aserció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 de provider/model), ejecuta:

openclaw models list
openclaw models list --json

Live: CLI backend smoke (Claude, Codex, Gemini, or other local CLIs)

Esta prueba valida el pipeline de Gateway + agente utilizando un backend de CLI local, sin tocar tu configuración por defecto.

• Test: src/gateway/gateway-cli-backend.live.test.ts
• Objetivo: validar el pipeline de Gateway + agente usando un backend de CLI local, sin tocar tu configuración por defecto.
• Los valores por defecto del smoke específico del backend residen 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
• Valores por defecto:
  • Proveedor/modelo por defecto: claude-cli/claude-sonnet-4-6
  • El comportamiento de comando/args/imagen proviene de los metadatos del plugin de CLI backend propietario.
• Sobrescrituras (opcional):
  • 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 archivo 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 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 IMAGE_ARG está configurado.
  • 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 la sonda de continuidad de sesión Claude Sonnet -> Opus por defecto (configura en 1 para forzarla cuando el modelo seleccionado soporte 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 Docker:

pnpm test:docker:live-cli-backend

Recetas Docker de proveedor único:

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 Docker reside en scripts/test-live-cli-backend-docker.sh.
• Ejecuta el smoke de CLI-backend en vivo dentro de la imagen Docker del repositorio como el usuario node no root.
• Resuelve los metadatos de smoke de CLI desde la extensión propietaria, luego instala el paquete de CLI de Linux coincidente (@anthropic-ai/claude-code, @openai/codex, o @google/gemini-cli) en un prefijo grabable en caché en OPENCLAW_DOCKER_CLI_TOOLS_DIR (por defecto: ~/.cache/openclaw/docker-cli-tools).
• pnpm test:docker:live-cli-backend:claude-subscription requiere OAuth de suscripción portátil de Claude Code a través de ~/.claude/.credentials.json con claudeAiOauth.subscriptionType o CLAUDE_CODE_OAUTH_TOKEN desde claude setup-token. Primero prueba claude -p directo en Docker, luego ejecuta dos turnos de Gateway CLI-backend sin preservar las variables de entorno de la API-key de Anthropic. Este carril de suscripción deshabilita las sondas de imagen y MCP de Claude por defecto porque Claude actualmente enruta el uso de aplicaciones de terceros a través de facturación de uso extra en lugar de los límites normales del plan de suscripción.
• El smoke de CLI-backend en vivo ahora ejercita el mismo flujo de extremo a extremo para Claude, Codex y Gemini: turno de texto, turno de clasificación de imagen, luego llamada a herramienta MCP cron verificada a través del CLI del Gateway.
• El smoke por defecto 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: ACP bind smoke (/acp spawn ... --bind here)

Esta prueba valida el flujo real de vinculación de conversación ACP con un agente ACP en vivo.

• Test: src/gateway/gateway-acp-bind.live.test.ts
• Objetivo: validar el flujo real de vinculación de conversación ACP con un agente ACP en vivo:
  • enviar /acp spawn <agent> --bind here
  • vincular una conversación de canal de mensajes sintético en el lugar
  • enviar un seguimiento normal en esa misma conversación
  • verificar que el seguimiento aterrice en la transcripción de la sesión ACP vinculada
• Habilitar:
  • pnpm test:live src/gateway/gateway-acp-bind.live.test.ts
  • OPENCLAW_LIVE_ACP_BIND=1
• Valores por defecto:
  • Agentes ACP en Docker: claude,codex,gemini
  • Agente ACP para pnpm test:live ... directo: claude
  • Canal sintético: contexto de conversación estilo Slack DM
  • Backend ACP: acpx
• Sobrescrituras:
  • 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 carril utiliza la superficie chat.send del Gateway con campos de ruta de origen sintéticos solo para administradores, de modo que las pruebas puedan adjuntar contexto de canal de mensajes sin pretender realizar entregas externas.
  • Cuando OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND no está configurado, la prueba utiliza el registro de agentes incorporado del plugin acpx embebido 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 Docker:

pnpm test:docker:live-acp-bind

Recetas Docker de agente único:

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

Notas Docker:

• El ejecutor Docker reside en scripts/test-live-acp-bind-docker.sh.
• Por defecto, ejecuta el smoke de vinculación ACP contra todos los agentes CLI en vivo soportados en secuencia: claude, codex, luego gemini.
• Usa OPENCLAW_LIVE_ACP_BIND_AGENTS=claude, OPENCLAW_LIVE_ACP_BIND_AGENTS=codex, o OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini para reducir la matriz.
• Obtiene ~/.profile, prepara el material de autenticación CLI coincidente en el contenedor, instala acpx en un prefijo npm grabable, luego instala el CLI en vivo solicitado (@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 las variables de entorno del proveedor del perfil obtenido disponibles para el CLI de arnés hijo.

AI Setup Assistant

Live: Codex app-server harness smoke

El objetivo principal es validar el harness de Codex que pertenece al plugin a través del Gateway estándar. Para lograr esto, el método agent carga el plugin codex incluido, selecciona OPENCLAW_AGENT_RUNTIME=codex, envía un primer turno al Gateway hacia codex/gpt-5.4, realiza un segundo turno a la misma sesión de OpenClaw para verificar que el hilo del app-server pueda reanudarse, y finalmente ejecuta /codex status y /codex models mediante la misma ruta de comandos del Gateway.

• Test: src/gateway/gateway-codex-harness.live.test.ts
• Habilitar: OPENCLAW_LIVE_CODEX_HARNESS=1
• Modelo predeterminado: codex/gpt-5.4
• Sonda de imagen opcional: OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1
• Sonda MCP/tool opcional: OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1
• El smoke establece OPENCLAW_AGENT_HARNESS_FALLBACK=none para que un harness de Codex defectuoso no pase desapercibido al recurrir silenciosamente a PI.
• Autenticación: OPENAI_API_KEY desde el shell/perfil, además de los archivos opcionales copiados ~/.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 para Docker:

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

Notas sobre Docker:

• El ejecutor de Docker se encuentra en scripts/test-live-codex-harness-docker.sh.
• Este script carga el ~/.profile montado, pasa la OPENAI_API_KEY, copia los archivos de autenticación del CLI de Codex cuando están presentes, instala @openai/codex en un prefijo de npm montado y escribible, prepara el árbol de fuentes y luego ejecuta solo el test en vivo del harness de Codex.
• Docker habilita las sondas de imagen y MCP/tool de forma predeterminada. Configura 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 específica.
• Docker también exporta OPENCLAW_AGENT_HARNESS_FALLBACK=none, coincidiendo con la configuración del test en vivo para que el fallback a openai-codex/* o PI no pueda ocultar una regresión en el harness de Codex.

Recetas en vivo recomendadas

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

• Modelo único, directo (sin Gateway):

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

• Modelo único, smoke del Gateway:

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

• Llamada a herramientas (tool calling) 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 (API key de Gemini + Antigravity):

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

Live: matriz de modelos (lo que cubrimos)

No existe una “lista de modelos de CI” fija (el modo live es opcional), pero estos son los modelos recomendados para cubrir regularmente en una máquina de desarrollo con las llaves configuradas.

Conjunto de smoke moderno (llamada a herramientas + imagen)

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

• 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 el smoke del 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 (Lectura + Ejecución 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 (es bueno tenerla):

• xAI: xai/grok-4 (o la última disponible)
• Mistral: mistral/… (elige un modelo capaz de “herramientas” 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 imágenes (adjunto → mensaje multimodal)

Incluye al menos un modelo capaz de procesar imágenes en OPENCLAW_LIVE_GATEWAY_MODELS (variantes de Claude/Gemini/OpenAI capaces de visión, etc.) para ejercitar la sonda de imagen.

Agregadores / Gateways alternativos

Si tienes llaves habilitadas, también admitimos pruebas a través de:

• OpenRouter: openrouter/... (cientos de modelos; usa openclaw models scan para encontrar candidatos capaces 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 en vivo (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
• Vía 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 oficial es lo que discoverModels(...) devuelve en tu máquina + las llaves que tengas disponibles.

Credenciales (nunca las subas al repositorio)

Los tests en vivo descubren las credenciales de la misma manera que lo hace el CLI. Implicaciones prácticas:

• Si el CLI funciona, los tests en vivo deberían encontrar las mismas llaves.

• Si un test en vivo dice “no creds”, depura de la misma manera que lo harías con openclaw models list / selección de modelo.

• Perfiles de autenticación por agente: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (esto es a lo que se refieren las “llaves de perfil” en los tests en vivo)

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

• Directorio de estado heredado: ~/.openclaw/credentials/ (copiado en el home de prueba en vivo cuando está presente, pero no es el almacén principal de llaves de perfil)

• Las ejecuciones locales en vivo copian la configuración activa, los archivos auth-profiles.json por agente, las credentials/ heredadas y los directorios de autenticación de CLI externos compatibles en un home de prueba temporal de forma predeterminada; los homes en vivo preparados omiten workspace/ y sandboxes/, y las anulaciones de ruta agents.*.workspace / agentDir se eliminan para que las sondas se mantengan fuera de tu espacio de trabajo real.

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

Deepgram live (transcripción de audio)

• Test: 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

AI Setup Assistant

Pruebas en vivo del plan de codificación de BytePlus

Para verificar que tu integración con BytePlus funcione correctamente, puedes ejecutar pruebas específicas que validan la conexión con la API y el comportamiento del modelo.

1. Prueba: src/agents/byteplus.live.test.ts
2. Habilitar: BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts
3. Sustitución de modelo opcional: BYTEPLUS_CODING_MODEL=ark-code-latest

Pruebas en vivo de medios para el flujo de trabajo de ComfyUI

Estas pruebas aseguran que tu configuración de OpenClaw con ComfyUI procese correctamente las imágenes, el video y la generación de música.

1. Prueba: extensions/comfy/comfy.live.test.ts
2. Habilitar: OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
3. Alcance:
   • Ejecuta las rutas integradas de imagen, video y music_generate de Comfy.
   • Omite cada capacidad a menos que esté configurada en models.providers.comfy.<capability>.
   • Es útil después de realizar cambios en el envío, sondeo, descargas o registro de plugins de Comfy.

Pruebas en vivo de generación de imágenes

Utiliza estas pruebas para validar que los proveedores de generación de imágenes estén correctamente conectados a través de OpenClaw y respondan según lo esperado.

1. Prueba: src/image-generation/runtime.live.test.ts
2. Comando: pnpm test:live src/image-generation/runtime.live.test.ts
3. Arnés: pnpm test:live:media image
4. Alcance:
   • Enumera cada plugin de proveedor de generación de imágenes registrado.
   • Carga las variables de entorno faltantes del proveedor desde tu shell de inicio (~/.profile) antes de realizar el sondeo.
   • Utiliza las API keys de entorno en vivo antes que los perfiles de autenticación almacenados, para que las claves obsoletas en auth-profiles.json no oculten las credenciales reales del shell.
   • Omite proveedores sin autenticación, perfil o modelo utilizable.
   • Ejecuta las variantes estándar de generación de imágenes a través de la capacidad de runtime compartida:
     • google:flash-generate
     • google:pro-generate
     • google:pro-edit
     • openai:default-generate
5. Proveedores integrados cubiertos actualmente:
   • openai
   • google
6. Restricció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"
7. Comportamiento de autenticación opcional:
   • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 para forzar la autenticación desde el almacenamiento de perfiles e ignorar las sustituciones solo de entorno.

Pruebas en vivo de generación de música

Estas pruebas verifican la capacidad de OpenClaw para interactuar con proveedores de música y asegurar que los modos de generación y edición funcionen correctamente.

1. Prueba: extensions/music-generation-providers.live.test.ts
2. Habilitar: OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
3. Arnés: pnpm test:live:media music
4. Alcance:
   • Ejercita la ruta compartida del proveedor de generación de música integrado.
   • Actualmente cubre Google y MiniMax.
   • Carga las variables de entorno del proveedor desde tu shell de inicio (~/.profile) antes de realizar el sondeo.
   • Utiliza las API keys de entorno en vivo antes que los perfiles de autenticación almacenados.
   • Omite proveedores sin autenticación, perfil o modelo utilizable.
   • Ejecuta ambos modos de runtime declarados cuando están disponibles:
     • generate con entrada de solo prompt.
     • edit cuando el proveedor declara capabilities.edit.enabled.
   • Cobertura actual del carril compartido:
     • google: generate, edit
     • minimax: generate
     • comfy: archivo de prueba en vivo de Comfy separado, no este barrido compartido.
5. Restricción opcional:
   • OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"
   • OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"
6. Comportamiento de autenticación opcional:
   • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 para forzar la autenticación desde el almacenamiento de perfiles e ignorar las sustituciones solo de entorno.

AI Setup Assistant

Video generation live

Para realizar pruebas en tiempo real con OpenClaw video generation, puedes ejecutar el conjunto de pruebas integrado que verifica la conectividad y funcionalidad de los proveedores.

1. Prueba: extensions/video-generation-providers.live.test.ts
2. Habilitar: OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
3. Harness: pnpm test:live:media video
4. Alcance:
   • Ejecuta la ruta compartida del proveedor de video-generation.
   • Utiliza por defecto la ruta de prueba segura: proveedores que no son FAL, una solicitud de texto a video por proveedor, un prompt de “lobster” de un segundo y un límite de operación por proveedor definido en OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS (180000 por defecto).
   • Omite FAL por defecto debido a que la latencia de la cola del proveedor puede afectar el tiempo de lanzamiento; usa --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 (~/.profile) antes de realizar las pruebas.
   • Utiliza las API keys de entorno en vivo antes que los perfiles de autenticación almacenados, para que las claves obsoletas en auth-profiles.json no oculten las credenciales reales del shell.
   • Omite proveedores sin autenticación, perfil o modelo utilizable.
   • Ejecuta solo generate por defecto.
   • Configura 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 modelo seleccionado acepta entrada de imagen local respaldada por buffer en el barrido compartido.
     • videoToVideo cuando el proveedor declara capabilities.videoToVideo.enabled y el modelo seleccionado acepta entrada de video local respaldada por buffer en el barrido compartido.
   • Proveedores imageToVideo declarados pero omitidos actualmente en el barrido compartido:
     • vydra porque el veo3 incluido es solo de texto y el kling incluido requiere una URL de imagen remota.
   • Cobertura de Vydra específica del proveedor:
     • 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 una línea de kling que utiliza un fixture de URL de imagen remota por defecto.
   • Cobertura en vivo de videoToVideo actual:
     • runway solo cuando el modelo seleccionado es runway/gen4_aleph.
   • Proveedores videoToVideo declarados pero omitidos actualmente en el barrido compartido:
     • alibaba, qwen, xai porque esas rutas actualmente requieren URLs de referencia http(s) / MP4 remotas.
     • google porque la línea actual de Gemini/Veo compartida usa entrada respaldada por buffer local y esa ruta no es aceptada en el barrido compartido.
     • openai porque la línea compartida actual carece de garantías de acceso a inpaint/remix de video específicas de la organización.
5. Restricció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 cada proveedor en el barrido por defecto, incluyendo FAL.
   • OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000 para reducir el límite de operación de cada proveedor para una ejecución de prueba rápida.
6. Comportamiento de autenticación opcional:
   • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 para forzar la autenticación del almacenamiento de perfiles e ignorar las anulaciones solo de entorno.

Media live harness

Esta herramienta centraliza las pruebas de los diferentes tipos de medios para asegurar que todo funcione correctamente en tu entorno de desarrollo.

1. Comando: pnpm test:live:media
2. Propósito:
   • Ejecuta los conjuntos de pruebas en vivo de imagen, música y video a través de un único punto de entrada nativo del repositorio.
   • Carga automáticamente las variables de entorno del proveedor faltantes desde ~/.profile.
   • Reduce automáticamente cada conjunto a los proveedores que actualmente tienen autenticación utilizable por defecto.
   • Reutiliza scripts/test-live.mjs, por lo que el comportamiento de heartbeat y el modo silencioso se mantienen consistentes.
3. 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 (verificaciones opcionales de “funciona en Linux”)

Estos ejecutores de Docker se dividen en dos categorías principales:

1. Ejecutores de modelos en vivo: test:docker:live-models y test:docker:live-gateway ejecutan únicamente su archivo correspondiente de perfil activo dentro de la imagen de 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 tu espacio de trabajo (y cargando ~/.profile si está montado). Los puntos de entrada locales equivalentes son test:live:models-profiles y test:live:gateway-profiles.
2. Los ejecutores en vivo de Docker utilizan por defecto un límite de humo (smoke cap) más pequeño para que un barrido completo de 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. Puedes sobrescribir estas variables de entorno cuando necesites explícitamente un escaneo exhaustivo.
3. test:docker:all construye la imagen de Docker en vivo una vez mediante test:docker:live-build y luego la reutiliza para los dos carriles de Docker en vivo.
4. Ejecutores de humo para contenedores: 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 las rutas de integración de alto nivel.

Los ejecutores de Docker para modelos en vivo también montan mediante bind-mount solo los directorios de autenticación de la CLI necesarios (o todos los soportados si la ejecución no está restringida), y luego los copian al directorio home del contenedor antes de la ejecución, para que el OAuth de la CLI externa pueda refrescar los tokens sin modificar el almacén de autenticación del host:

• Modelos directos: pnpm test:docker:live-models (script: scripts/test-live-models-docker.sh)
• Humo de bind ACP: pnpm test:docker:live-acp-bind (script: scripts/test-live-acp-bind-docker.sh)
• Humo de backend de CLI: pnpm test:docker:live-cli-backend (script: scripts/test-live-cli-backend-docker.sh)
• Humo de arnés de servidor de aplicaciones 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)
• Humo en vivo de Open WebUI: pnpm test:docker:openwebui (script: scripts/e2e/openwebui-docker.sh)
• Asistente de incorporación (TTY, andamiaje completo): pnpm test:docker:onboard (script: scripts/e2e/onboard-docker.sh)
• Red de Gateway (dos contenedores, autenticación WS + salud): pnpm test:docker:gateway-network (script: scripts/e2e/gateway-network-docker.sh)
• Puente de canales MCP (Gateway con semillas + puente stdio + humo de trama de notificación cruda de Claude): pnpm test:docker:mcp-channels (script: scripts/e2e/mcp-channels-docker.sh)
• Plugins (humo de instalación + alias /plugin + semántica de reinicio de paquete de Claude): pnpm test:docker:plugins (script: scripts/e2e/plugins-docker.sh)

Los ejecutores de Docker para modelos en vivo también montan el checkout actual como solo lectura y lo preparan en un directorio de trabajo temporal dentro del contenedor. Esto mantiene la imagen de tiempo de ejecución ligera mientras se ejecuta Vitest contra tu código fuente/configuración local exacta. El paso de preparación omite cachés locales grandes y salidas de compilación de aplicaciones como .pnpm-store, .worktrees, __openclaw_vitest__, y directorios de salida de la aplicación local o Gradle, para que las ejecuciones en vivo de Docker no pierdan minutos copiando artefactos específicos de la máquina. También establecen OPENCLAW_SKIP_CHANNELS=1 para que las sondas en vivo del Gateway no inicien trabajadores de canales reales de Telegram/Discord/etc. dentro del contenedor. test:docker:live-models sigue ejecutando pnpm test:live, así que pasa también OPENCLAW_LIVE_GATEWAY_* cuando necesites restringir o excluir la cobertura en vivo del Gateway de ese carril de Docker. test:docker:openwebui es un humo de compatibilidad de alto nivel: inicia un contenedor de Gateway de OpenClaw con los endpoints HTTP compatibles con OpenAI habilitados, inicia un contenedor de Open WebUI anclado contra ese Gateway, inicia sesión a través de Open WebUI, verifica que /api/models expone openclaw/default y luego envía una solicitud de chat real a través del 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 carril espera una clave de modelo en vivo utilizable, y OPENCLAW_PROFILE_FILE (~/.profile por defecto) es la forma principal de proporcionarla en ejecuciones dockerizadas. Las ejecuciones exitosas imprimen un pequeño payload 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 de Gateway con semillas, arranca un segundo contenedor que ejecuta openclaw mcp serve, y luego verifica el descubrimiento de conversaciones enrutadas, lecturas de transcripciones, metadatos de archivos adjuntos, comportamiento de la cola de eventos en vivo, enrutamiento de envío saliente y notificaciones de canales + permisos al estilo Claude sobre el puente MCP stdio real. La verificación de notificación inspecciona las tramas MCP stdio crudas directamente para que el humo valide lo que el puente realmente emite, no solo lo que un SDK de cliente específico muestra.

Humo manual de hilos en lenguaje sencillo ACP (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 ser necesario de nuevo para la validación del enrutamiento de hilos ACP, así que no lo borres.

Variables de entorno útiles:

• OPENCLAW_CONFIG_DIR=... (por defecto: ~/.openclaw) montado en /home/node/.openclaw
• OPENCLAW_WORKSPACE_DIR=... (por defecto: ~/.openclaw/workspace) montado en /home/node/.openclaw/workspace
• OPENCLAW_PROFILE_FILE=... (por defecto: ~/.profile) montado en /home/node/.profile y cargado antes de ejecutar las pruebas
• OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1 para verificar solo las variables de entorno cargadas desde OPENCLAW_PROFILE_FILE, usando directorios temporales de configuración/espacio de trabajo y sin montajes de autenticación de CLI externa
• OPENCLAW_DOCKER_CLI_TOOLS_DIR=... (por defecto: ~/.cache/openclaw/docker-cli-tools) montado en /home/node/.npm-global para instalaciones de CLI en caché dentro de Docker
• Los directorios/archivos de autenticación de CLI externa bajo $HOME se montan como solo lectura bajo /host-auth..., y luego se copian a /home/node/... antes de que comiencen las pruebas
  • Directorios por defecto: .minimax
  • Archivos por defecto: ~/.codex/auth.json, ~/.codex/config.toml, .claude.json, ~/.claude/.credentials.json, ~/.claude/settings.json, ~/.claude/settings.local.json
  • Las ejecuciones de proveedores restringidos montan solo los directorios/archivos necesarios inferidos de OPENCLAW_LIVE_PROVIDERS / OPENCLAW_LIVE_GATEWAY_PROVIDERS
  • Sobrescribe 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 restringir la ejecución
• OPENCLAW_LIVE_GATEWAY_PROVIDERS=... / OPENCLAW_LIVE_PROVIDERS=... para filtrar proveedores en el contenedor
• OPENCLAW_SKIP_DOCKER_BUILD=1 para reutilizar una imagen existente openclaw:local-live para re-ejecuciones que no necesitan una reconstrucción
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 para asegurar que las credenciales provengan del almacén de perfiles (no del entorno)
• OPENCLAW_OPENWEBUI_MODEL=... para elegir el modelo expuesto por el Gateway para el humo de Open WebUI
• OPENCLAW_OPENWEBUI_PROMPT=... para sobrescribir el prompt de verificación de nonce utilizado por el humo de Open WebUI
• OPENWEBUI_IMAGE=... para sobrescribir la etiqueta de imagen anclada de Open WebUI

Cordura de la documentación

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

AI Setup Assistant

Regresión offline (CI-safe)

Estas son regresiones de “pipeline real” que funcionan sin necesidad de proveedores reales:

1. Llamadas a herramientas de Gateway (usando OpenAI simulado, Gateway real + bucle de agente): src/gateway/gateway.test.ts (caso: “runs a mock OpenAI tool call end-to-end via gateway agent loop”)
2. Asistente de Gateway (WS wizard.start/wizard.next, escribe la configuración + validación de autenticación): src/gateway/gateway.test.ts (caso: “runs wizard over ws and writes auth token config”)

src/gateway/gateway.test.ts

Evaluaciones de fiabilidad del agente (skills)

Ya contamos con algunas pruebas seguras para CI que funcionan como “evaluaciones de fiabilidad del agente”:

1. Llamadas a herramientas simuladas a través del Gateway real + bucle de agente (src/gateway/gateway.test.ts).
2. Flujos de asistente de extremo a extremo que validan la conexión de la sesión y los efectos de la configuración (src/gateway/gateway.test.ts).

Lo que todavía falta para las skills (consulta Skills):

1. Toma de decisiones: cuando las skills aparecen en el prompt, ¿el agente elige la skill correcta (o evita las irrelevantes)?
2. Cumplimiento: ¿el agente lee el archivo SKILL.md antes de usarlo y sigue los pasos/argumentos requeridos?
3. Contratos de flujo de trabajo: escenarios de múltiples turnos que verifican el orden de las herramientas, la persistencia del historial de la sesión y los límites del sandbox.

Las evaluaciones futuras deben mantenerse deterministas en primer lugar:

1. Un ejecutor de escenarios que utilice proveedores simulados para verificar las llamadas a herramientas + orden, lectura de archivos de skills y conexión de sesiones.
2. Un pequeño conjunto de escenarios centrados en skills (uso vs. omisión, control de acceso, inyección de prompts).
3. Evaluaciones en vivo opcionales (bajo demanda, activadas por variables de entorno) solo después de que el conjunto de pruebas CI-safe esté implementado.

src/gateway/gateway.test.ts

Pruebas de contrato (forma de plugin y canal)

Las pruebas de contrato verifican que cada plugin y canal registrado cumpla con su contrato de interfaz. Estas pruebas iteran sobre todos los plugins descubiertos y ejecutan un conjunto de aserciones sobre su forma y comportamiento. La línea de pruebas unitarias predeterminada de pnpm test omite intencionalmente estos archivos de unión y humo; ejecuta los comandos de contrato explícitamente cuando modifiques superficies compartidas de canales o proveedores en OpenClaw.

Comandos

1. Todos los contratos: pnpm test:contracts
2. Solo contratos de canal: pnpm test:contracts:channels
3. Solo contratos de proveedor: pnpm test:contracts:plugins

Contratos de canal

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

1. plugin - Forma básica del plugin (id, nombre, capacidades)
2. setup - Contrato del asistente de configuración
3. session-binding - Comportamiento de vinculación de sesión
4. outbound-payload - Estructura del payload del mensaje
5. inbound - Manejo de mensajes entrantes
6. actions - Manejadores de acciones del canal
7. threading - Manejo de ID de hilos
8. directory - API de directorio/lista
9. group-policy - Aplicación de políticas de grupo

Contratos de estado del proveedor

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

1. status - Sondas de estado del canal
2. registry - Forma del registro de plugins

Contratos de proveedor

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

1. auth - Contrato de flujo de autenticación
2. auth-choice - Elección/selección de autenticación
3. catalog - API de catálogo de modelos
4. discovery - Descubrimiento de plugins
5. loader - Carga de plugins
6. runtime - Entorno de ejecución del proveedor
7. shape - Forma/interfaz del plugin
8. wizard - Asistente de configuración

Cuándo ejecutar

1. Después de cambiar las exportaciones o subrutas del plugin-sdk
2. Después de añadir o modificar un plugin de canal o proveedor
3. Después de refactorizar el registro o descubrimiento de plugins

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

Añadir regresiones (guía)

Cuando soluciones un problema de proveedor/modelo descubierto en producción, sigue estas pautas para asegurar la estabilidad a largo plazo.

1. Añade una regresión segura para CI si es posible (usando un proveedor simulado o capturando la transformación exacta de la forma de la solicitud).
2. Si el problema ocurre solo en vivo (límites de tasa, políticas de autenticación), mantén la prueba de vivo limitada y actívala mediante variables de entorno.
3. Prefiere apuntar a la capa más pequeña que detecte el error:
   • Error de conversión/reproducción de solicitud de proveedor → prueba directa de modelos.
   • Error en la tubería de sesión/historial/herramientas del Gateway → prueba de humo en vivo del Gateway o prueba simulada segura para CI del Gateway.
4. Barrera de protección para el recorrido de SecretRef:
   • src/secrets/exec-secret-ref-id-parity.test.ts deriva un objetivo muestreado por clase SecretRef desde los metadatos del registro (listSecretTargetRegistryEntries()), y luego asegura que los IDs de ejecución del segmento de recorrido sean rechazados.
   • Si añades una nueva familia de objetivos SecretRef de tipo includeInPlan en src/secrets/target-registry-data.ts, actualiza classifyTargetClass en esa prueba. La prueba falla intencionalmente con IDs de objetivo no clasificados para que las nuevas clases no puedan omitirse silenciosamente.

AI Setup Assistant

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>