Saltar para o conteúdo principal

​
Testes

O OpenClaw tem três suítes Vitest (unit/integration, e2e, live) e um pequeno conjunto de runners Docker. Este documento é um guia de “como testamos”:
  • O que cada suíte cobre (e o que deliberadamente não cobre)
  • Quais comandos executar para fluxos de trabalho comuns (local, pré-push, depuração)
  • Como os testes live descobrem credenciais e selecionam modelos/provedores
  • Como adicionar regressões para problemas reais de modelo/provedor

​
Início rápido

Na maioria dos dias:
  • Gate completo (esperado antes do push): pnpm build && pnpm check && pnpm test
Quando você mexe em testes ou quer mais confiança:
  • Gate de cobertura: pnpm test:coverage
  • Suíte E2E: pnpm test:e2e
Ao depurar provedores/modelos reais (exige credenciais reais):
  • Suíte live (modelos + sondas de ferramenta/imagem do gateway): pnpm test:live
Dica: quando você precisa apenas de um caso com falha, prefira restringir os testes live via as variáveis de ambiente de allowlist descritas abaixo.

​
Suítes de teste (o que roda onde)

Pense nas suítes como “realismo crescente” (e aumento de instabilidade/custo):

​
Unit / integration (padrão)

  • Comando: pnpm test
  • Config: scripts/test-parallel.mjs (executa vitest.unit.config.ts, vitest.extensions.config.ts, vitest.gateway.config.ts)
  • Arquivos: src/**/*.test.ts
  • Enquadramento:
    • Testes unitários puros
    • Testes de integração in-process (autenticação do gateway, roteamento, ferramentas, parsing, configuração)
    • Regressões determinísticas para bugs conhecidos
  • Expectativas:
    • Roda em CI
    • Não requer chaves reais
    • Deve ser rápido e estável
  • Observação sobre o pool:
    • O OpenClaw usa Vitest vmForks no Node 22/23 para shards de unidade mais rápidos.
    • No Node 24+, o OpenClaw volta automaticamente para forks regulares para evitar erros de vinculação do Node VM (ERR_VM_MODULE_LINK_FAILURE / module is already linked).
    • Substitua manualmente com OPENCLAW_TEST_VM_FORKS=0 (forçar forks) ou OPENCLAW_TEST_VM_FORKS=1 (forçar vmForks).

​
E2E (gateway smoke)

  • Comando: pnpm test:e2e
  • Configuração: vitest.e2e.config.ts
  • Arquivos: src/**/*.e2e.test.ts
  • Padrões de execução:
    • Usa Vitest vmForks para inicialização de arquivos mais rápida.
    • Usa workers adaptativos (CI: 2-4, local: 4-8).
    • Executa em modo silencioso por padrão para reduzir a sobrecarga de I/O no console.
  • Substituições úteis:
    • OPENCLAW_E2E_WORKERS=<n> para forçar a quantidade de workers (limitado a 16).
    • OPENCLAW_E2E_VERBOSE=1 para reativar a saída detalhada no console.
  • Enquadramento:
    • Comportamento end-to-end do gateway com múltiplas instâncias
    • Superfícies WebSocket/HTTP, pareamento de nós e networking mais pesado
  • Expectativas:
    • Roda em CI (quando habilitado no pipeline)
    • Não requer chaves reais
    • Mais partes móveis do que testes unitários (pode ser mais lento)

​
Live (provedores reais + modelos reais)

  • Comando: pnpm test:live
  • Configuração: vitest.live.config.ts
  • Arquivos: src/**/*.live.test.ts
  • Padrão: habilitado por pnpm test:live (define OPENCLAW_LIVE_TEST=1)
  • Enquadramento:
    • “Este provedor/modelo realmente funciona hoje com credenciais reais?”
    • Capturar mudanças de formato do provedor, peculiaridades de tool-calling, problemas de autenticação e comportamento de rate limit
  • Expectativas:
    • Não é estável para CI por design (redes reais, políticas reais do provedor, cotas, indisponibilidades)
    • Custa dinheiro / usa rate limits
    • Prefira rodar subconjuntos restritos em vez de “tudo”
    • Execuções live buscarão ~/.profile para obter chaves de API ausentes
    • Rotação de chaves Anthropic: defina OPENCLAW_LIVE_ANTHROPIC_KEYS="sk-...,sk-..." (ou OPENCLAW_LIVE_ANTHROPIC_KEY=sk-...) ou múltiplas variáveis ANTHROPIC_API_KEY*; os testes farão retry em rate limits

​
Qual suíte eu deveria correr?

Use esta tabela de decisão:
  • Editando lógica/testes: rode pnpm test (e pnpm test:coverage se você mudou bastante coisa)
  • Tocando em networking do gateway / protocolo WS / pareamento: adicione pnpm test:e2e
  • Depurando “meu bot está fora do ar” / falhas específicas de provedor / tool calling: rode um pnpm test:live restrito

​
Live: smoke de modelos (chaves de perfil)

Os testes live são divididos em duas camadas para isolar falhas:
  • “Modelo direto” nos diz se o provedor/modelo responde com a chave fornecida.
  • “Gateway smoke” nos diz se o pipeline completo gateway+agente funciona para esse modelo (sessões, histórico, ferramentas, política de sandbox, etc.).

​
Camada 1: conclusão direta do modelo (sem gateway)

  • Teste: src/agents/models.profiles.live.test.ts
  • Objetivo:
    • Enumerar modelos descobertos
    • Usar getApiKeyForModel para selecionar modelos para os quais você tem credenciais
    • Rodar uma pequena conclusão por modelo (e regressões direcionadas quando necessário)
  • Como habilitar:
    • pnpm test:live (ou OPENCLAW_LIVE_TEST=1 se chamar o Vitest diretamente)
  • Defina OPENCLAW_LIVE_MODELS=modern (ou all, alias moderno) para realmente rodar esta suíte; caso contrário, ela é pulada para manter pnpm test:live focado no gateway smoke
  • Como selecionar modelos:
    • OPENCLAW_LIVE_MODELS=modern para rodar a allowlist moderna (Opus/Sonnet/Haiku 4.5, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.1, Grok 4)
    • OPENCLAW_LIVE_MODELS=all é um alias para a allowlist moderna
    • ou OPENCLAW_LIVE_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-6,..." (allowlist separada por vírgulas)
  • Como selecionar provedores:
    • OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli" (allowlist separada por vírgulas)
  • De onde vêm as chaves:
    • Por padrão: store de perfis e fallbacks de ambiente
    • Defina OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 para impor apenas store de perfis
  • Por que isso existe:
    • Separa “API do provedor está quebrada / chave inválida” de “pipeline do agente do gateway está quebrado”
    • Contém regressões pequenas e isoladas (exemplo: replay de reasoning + fluxos de tool-call do OpenAI Responses/Codex Responses)

​
Camada 2: Gateway + agente de desenvolvimento (o que “@openclaw” realmente faz)

  • Teste: src/gateway/gateway-models.profiles.live.test.ts
  • Objetivo:
    • Subir um gateway in-process
    • Criar/atualizar uma sessão agent:dev:* (override de modelo por execução)
    • Iterar modelos-com-chaves e verificar:
      • resposta “significativa” (sem ferramentas)
      • uma invocação real de ferramenta funciona (sonda de leitura)
      • sondas extras opcionais de ferramentas (sonda exec+read)
      • caminhos de regressão do OpenAI (apenas tool-call → follow-up) continuam funcionando
  • Detalhes das sondas (para explicar falhas rapidamente):
    • Sonda read: o teste escreve um arquivo nonce no workspace e pede ao agente para read-lo e ecoar o nonce de volta.
    • Sonda exec+read: o teste pede ao agente para exec-escrever um nonce em um arquivo temporário e depois read-lo de volta.
    • Sonda de imagem: o teste anexa um PNG gerado (gato + código aleatório) e espera que o modelo retorne cat <CODE>.
    • Referência de implementação: src/gateway/gateway-models.profiles.live.test.ts e src/gateway/live-image-probe.ts.
  • Como habilitar:
    • pnpm test:live (ou OPENCLAW_LIVE_TEST=1 se chamar o Vitest diretamente)
  • Como selecionar modelos:
    • Padrão: allowlist 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 é um alias para a allowlist moderna
    • Ou defina OPENCLAW_LIVE_GATEWAY_MODELS="provider/model" (ou lista separada por vírgulas) para restringir
  • Como selecionar provedores (evite “OpenRouter tudo”):
    • OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax" (allowlist separada por vírgulas)
  • Sondas de ferramenta + imagem estão sempre ativas neste teste live:
    • Sonda read + sonda exec+read (stress de ferramentas)
    • A sonda de imagem roda quando o modelo anuncia suporte a entrada de imagem
    • Fluxo (alto nível):
      • O teste gera um PNG minúsculo com “CAT” + código aleatório (src/gateway/live-image-probe.ts)
      • Envia via agent attachments: [{ mimeType: "image/png", content: "<base64>" }]
      • O Gateway faz parsing dos anexos em images[] (src/gateway/server-methods/agent.ts + src/gateway/chat-attachments.ts)
      • O agente embutido encaminha uma mensagem de usuário multimodal ao modelo
      • Asserção: a resposta contém cat + o código (tolerância de OCR: pequenos erros permitidos)
Dica: para ver o que você pode testar na sua máquina (e os ids exatos de provider/model), execute: 
openclaw models list
openclaw models list --json

​
Live: smoke de setup-token Anthropic

  • Teste: src/agents/anthropic.setup-token.live.test.ts
  • Objetivo: verificar se o setup-token do Claude Code CLI (ou um perfil de setup-token colado) consegue completar um prompt Anthropic.
  • Habilitar:
    • pnpm test:live (ou OPENCLAW_LIVE_TEST=1 se chamar o Vitest diretamente)
    • OPENCLAW_LIVE_SETUP_TOKEN=1
  • Fontes de token (escolha uma):
    • Perfil: OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test
    • Token bruto: OPENCLAW_LIVE_SETUP_TOKEN_VALUE=sk-ant-oat01-...
  • Override de modelo (opcional):
    • OPENCLAW_LIVE_SETUP_TOKEN_MODEL=anthropic/claude-opus-4-6
Exemplo de setup: 
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: smoke de backend CLI (Claude Code CLI ou outros CLIs locais)

  • Teste: src/gateway/gateway-cli-backend.live.test.ts
  • Objetivo: validar o pipeline Gateway + agente usando um backend CLI local, sem tocar na sua configuração padrão.
  • Habilitar:
    • pnpm test:live (ou OPENCLAW_LIVE_TEST=1 se chamar o Vitest diretamente)
    • OPENCLAW_LIVE_CLI_BACKEND=1
  • Padrões:
    • Modelo: claude-cli/claude-sonnet-4-5
    • Comando: claude
    • Args: ["-p","--output-format","json","--dangerously-skip-permissions"]
  • Overrides (opcional):
    • OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-opus-4-6"
    • OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.3-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 um anexo de imagem real (os caminhos são injetados no prompt).
    • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image" para passar caminhos de arquivos de imagem como args da CLI em vez de injeção no prompt.
    • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat" (ou "list") para controlar como os args de imagem são passados quando IMAGE_ARG está definido.
    • OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1 para enviar um segundo turno e validar o fluxo de retomada.
  • OPENCLAW_LIVE_CLI_BACKEND_DISABLE_MCP_CONFIG=0 para manter a configuração MCP do Claude Code CLI habilitada (o padrão desabilita a config MCP com um arquivo temporário vazio).
Exemplo: 
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

​
Receitas live recomendadas

Allowlists explícitas e restritas são mais rápidas e menos instáveis:
  • Modelo único, direto (sem gateway):
    • OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts
  • Modelo único, gateway smoke:
    • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
  • Tool calling em vários provedores:
    • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
  • Foco Google (chave da API Gemini + Antigravity):
    • Gemini (chave 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-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
Notas:
  • google/... usa a API Gemini (chave de API).
  • google-antigravity/... usa a ponte OAuth Antigravity (endpoint de agente no estilo Cloud Code Assist).
  • google-gemini-cli/... usa a CLI Gemini local na sua máquina (autenticação separada + peculiaridades de ferramentas).
  • API Gemini vs CLI Gemini:
    • API: o OpenClaw chama a API Gemini hospedada do Google via HTTP (chave de API / autenticação por perfil); é isso que a maioria dos usuários quer dizer por “Gemini”.
    • CLI: o OpenClaw executa um binário gemini local; ele tem sua própria autenticação e pode se comportar de forma diferente (streaming/suporte a ferramentas/desalinhamento de versão).

​
Live: matriz de modelos (o que cobrimos)

Não há uma “lista fixa de modelos em CI” (live é opt-in), mas estes são os modelos recomendados para cobrir regularmente em uma máquina de desenvolvimento com chaves.

​
Conjunto smoke moderno (tool calling + imagem)

Este é o conjunto de “modelos comuns” que esperamos manter funcionando:
  • OpenAI (não-Codex): openai/gpt-5.2 (opcional: openai/gpt-5.1)
  • OpenAI Codex: openai-codex/gpt-5.3-codex (opcional: openai-codex/gpt-5.3-codex-codex)
  • Anthropic: anthropic/claude-opus-4-6 (ou anthropic/claude-sonnet-4-5)
  • Google (API Gemini): google/gemini-3-pro-preview e google/gemini-3-flash-preview (evite modelos Gemini 2.x mais antigos)
  • Google (Antigravity): google-antigravity/claude-opus-4-6-thinking e google-antigravity/gemini-3-flash
  • Z.AI (GLM): zai/glm-4.7
  • MiniMax: minimax/minimax-m2.1
Execute gateway smoke com ferramentas + imagem: OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.3-codex,anthropic/claude-opus-4-6,google/gemini-3-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.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

​
Baseline: tool calling (Read + Exec opcional)

Escolha pelo menos um por família de provedor:
  • OpenAI: openai/gpt-5.2 (ou openai/gpt-5-mini)
  • Anthropic: anthropic/claude-opus-4-6 (ou anthropic/claude-sonnet-4-5)
  • Google: google/gemini-3-flash-preview (ou google/gemini-3-pro-preview)
  • Z.AI (GLM): zai/glm-4.7
  • MiniMax: minimax/minimax-m2.1
Cobertura adicional opcional (bom ter):
  • xAI: xai/grok-4 (ou o mais recente disponível)
  • Mistral: mistral/… (escolha um modelo “tools” que você tenha habilitado)
  • Cerebras: cerebras/… (se você tiver acesso)
  • LM Studio: lmstudio/… (local; tool calling depende do modo da API)

​
Visão: envio de imagem (anexo → mensagem multimodal)

Inclua pelo menos um modelo com capacidade de imagem em OPENCLAW_LIVE_GATEWAY_MODELS (variantes do Claude/Gemini/OpenAI com visão, etc.) para exercitar a sonda de imagem.

​
Agregadores / gateways alternativos

Se você tiver chaves habilitadas, também suportamos testes via:
  • OpenRouter: openrouter/... (centenas de modelos; use openclaw models scan para encontrar candidatos com ferramentas+imagem)
  • OpenCode Zen: opencode/... (autenticação via OPENCODE_API_KEY / OPENCODE_ZEN_API_KEY)
Mais provedores que você pode incluir na matriz live (se tiver credenciais/configuração):
  • Integrados: openai, openai-codex, anthropic, google, google-vertex, google-antigravity, google-gemini-cli, zai, openrouter, opencode, xai, groq, cerebras, mistral, github-copilot
  • Via models.providers (endpoints customizados): minimax (cloud/API), além de qualquer proxy compatível com OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, etc.)
Dica: não tente codificar “todos os modelos” nos docs. A lista autoritativa é o que discoverModels(...) retorna na sua máquina + as chaves disponíveis.

​
Credenciais (nunca commitar)

Os testes live descobrem credenciais da mesma forma que a CLI. Implicações práticas:
  • Se a CLI funciona, os testes live devem encontrar as mesmas chaves.
  • Se um teste live disser “sem credenciais”, depure da mesma forma que você depuraria openclaw models list / seleção de modelo.
  • Store de perfis: ~/.openclaw/credentials/ (preferido; é o que “chaves de perfil” significa nos testes)
  • Configuração: ~/.openclaw/openclaw.json (ou OPENCLAW_CONFIG_PATH)
Se você quiser depender de chaves de ambiente (por exemplo, exportadas no seu ~/.profile), execute testes locais após source ~/.profile, ou use os runners Docker abaixo (eles podem montar ~/.profile no container).

​
Deepgram live (transcrição de áudio)

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

​
Runners Docker (checks opcionais “funciona no Linux”)

Eles executam pnpm test:live dentro da imagem Docker do repo, montando seu diretório de configuração local e workspace (e fazendo source de ~/.profile se montado):
  • Modelos diretos: pnpm test:docker:live-models (script: scripts/test-live-models-docker.sh)
  • Gateway + agente de desenvolvimento: pnpm test:docker:live-gateway (script: scripts/test-live-gateway-models-docker.sh)
  • Assistente de onboarding (TTY, scaffolding completo): pnpm test:docker:onboard (script: scripts/e2e/onboard-docker.sh)
  • Networking do gateway (dois containers, auth WS + health): pnpm test:docker:gateway-network (script: scripts/e2e/gateway-network-docker.sh)
  • Plugins (carregamento de extensão customizada + smoke do registry): pnpm test:docker:plugins (script: scripts/e2e/plugins-docker.sh)
Env vs úteis:
  • OPENCLAW_CONFIG_DIR=... (padrão: ~/.openclaw) montado em /home/node/.openclaw
  • OPENCLAW_WORKSPACE_DIR=... (padrão: ~/.openclaw/workspace) montado em /home/node/.openclaw/workspace
  • OPENCLAW_PROFILE_FILE=... (padrão: ~/.profile) montado em /home/node/.profile e aplicado antes de rodar os testes
  • OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... para restringir a execução
  • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 para garantir que as credenciais venham do store de perfis (não do ambiente)

​
Sanidade dos docs

Execute checagens de docs após edições: pnpm docs:list.

​
Regressão offline (segura para CI)

Estas são regressões de “pipeline real” sem provedores reais:
  • Tool calling do gateway (OpenAI mockado, gateway + loop do agente reais): src/gateway/gateway.tool-calling.mock-openai.test.ts
  • Assistente do gateway (WS wizard.start/wizard.next, grava configuração + autenticação aplicada): src/gateway/gateway.wizard.e2e.test.ts

​
Avaliações de confiabilidade do agente (skills)

Já temos alguns testes seguros para CI que se comportam como “avaliações de confiabilidade do agente”:
  • Tool-calling mockado através do loop real do gateway + agente (src/gateway/gateway.tool-calling.mock-openai.test.ts).
  • Fluxos end-to-end do assistente que validam o encadeamento de sessões e efeitos de configuração (src/gateway/gateway.wizard.e2e.test.ts).
O que ainda falta para skills (veja Skills):
  • Decisão: quando skills são listadas no prompt, o agente escolhe a skill certa (ou evita as irrelevantes)?
  • Conformidade: o agente lê SKILL.md antes de usar e segue os passos/args exigidos?
  • Contratos de workflow: cenários multi-turn que verificam ordem de ferramentas, carryover do histórico da sessão e limites de sandbox.
Avaliações futuras devem permanecer determinísticas primeiro:
  • Um runner de cenários usando provedores mock para verificar chamadas de ferramentas + ordem, leituras de arquivos de skill e encadeamento de sessões.
  • Um pequeno conjunto de cenários focados em skills (usar vs evitar, gating, prompt injection).
  • Avaliações live opcionais (opt-in, controladas por env) somente depois que a suíte segura para CI estiver pronta.

​
Adicionando regressões (orientação)

Quando você corrige um problema de provedor/modelo descoberto em live:
  • Adicione uma regressão segura para CI se possível (mock/stub do provedor, ou capture a transformação exata do formato da requisição)
  • Se for inerentemente apenas live (rate limits, políticas de auth), mantenha o teste live restrito e opt-in via variáveis de ambiente
  • Prefira atingir a menor camada que captura o bug:
    • bug de conversão/replay de requisição do provedor → teste de modelos diretos
    • bug no pipeline de sessão/histórico/ferramentas do gateway → gateway live smoke ou teste mockado do gateway seguro para CI