Documentation Index
Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
A trilha de QA do Matrix executa o Plugin @openclaw/matrix incluído contra um homeserver Tuwunel descartável no Docker, com contas temporárias de driver, SUT e observador, além de salas semeadas. Ela é a cobertura ao vivo com transporte real para Matrix.
Esta é uma ferramenta apenas para mantenedores. As versões empacotadas do OpenClaw omitem intencionalmente qa-lab, então openclaw qa só está disponível a partir de um checkout do código-fonte. Checkouts do código-fonte carregam o runner incluído diretamente - nenhuma etapa de instalação de Plugin é necessária.
Para contexto mais amplo do framework de QA, consulte Visão geral de QA.
Início rápido
pnpm openclaw qa matrix --profile fast --fail-fast
pnpm openclaw qa matrix simples executa --profile all e não para na primeira falha. Use --profile fast --fail-fast para um gate de release; fragmente o catálogo com --profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli ao executar o inventário completo em paralelo.
O que a trilha faz
- Provisiona um homeserver Tuwunel descartável no Docker (imagem padrão
ghcr.io/matrix-construct/tuwunel:v1.5.1, nome do servidor matrix-qa.test, porta 28008).
- Registra três usuários temporários -
driver (envia tráfego de entrada), sut (a conta Matrix do OpenClaw em teste), observer (captura de tráfego de terceiros).
- Semeia as salas exigidas pelos cenários selecionados (principal, threading, mídia, reinicialização, secundária, allowlist, E2EE, DM de verificação etc.).
- Inicia um Gateway filho do OpenClaw com o Plugin Matrix real escopado à conta SUT;
qa-channel não é carregado no filho.
- Executa cenários em sequência, observando eventos pelos clientes Matrix driver/observador.
- Encerra o homeserver, grava artefatos de relatório e resumo, então sai.
CLI
pnpm openclaw qa matrix [options]
Flags comuns
| Flag | Padrão | Descrição |
|---|
--profile <profile> | all | Perfil de cenário. Consulte Perfis. |
--fail-fast | desativado | Para após a primeira verificação ou cenário com falha. |
--scenario <id> | - | Executa apenas este cenário. Repetível. Consulte Cenários. |
--output-dir <path> | <repo>/.artifacts/qa-e2e/matrix-<timestamp> | Onde relatórios, resumo, eventos observados e o log de saída são gravados. Caminhos relativos são resolvidos contra --repo-root. |
--repo-root <path> | process.cwd() | Raiz do repositório ao invocar a partir de um diretório de trabalho neutro. |
--sut-account <id> | sut | ID da conta Matrix dentro da configuração do Gateway de QA. |
Flags de provedor
A trilha usa um transporte Matrix real, mas o provedor de modelo é configurável:
| Flag | Padrão | Descrição |
|---|
--provider-mode <mode> | live-frontier | mock-openai para despacho mock determinístico ou live-frontier para provedores frontier ao vivo. O alias legado live-openai ainda funciona. |
--model <ref> | padrão do provedor | Ref provider/model principal. |
--alt-model <ref> | padrão do provedor | Ref provider/model alternativa quando cenários alternam no meio da execução. |
--fast | desativado | Ativa o modo rápido do provedor quando compatível. |
--credential-source nem --credential-role. A trilha provisiona usuários descartáveis localmente; não há pool de credenciais compartilhado para locação.
Perfis
O perfil selecionado decide quais cenários são executados.
| Perfil | Use para |
|---|
all (padrão) | Catálogo completo. Lento, mas exaustivo. |
fast | Subconjunto de gate de release que exercita o contrato de transporte ao vivo: canário, gate por menção, bloqueio por allowlist, formato de resposta, retomada após reinicialização, follow-up em thread, isolamento de thread, observação de reações e entrega de metadados de aprovação de exec. |
transport | Cenários de threading, DM, sala, autojoin, menção/allowlist, aprovação e reações em nível de transporte. |
media | Cobertura de anexos de imagem, áudio, vídeo, PDF e EPUB. |
e2ee-smoke | Cobertura mínima de E2EE - resposta criptografada básica, follow-up em thread, sucesso de bootstrap. |
e2ee-deep | Cenários exaustivos de perda de estado, backup, chaves e recuperação de E2EE. |
e2ee-cli | Cenários de CLI openclaw matrix encryption setup e verify * conduzidos pelo harness de QA. |
extensions/qa-matrix/src/runners/contract/scenario-catalog.ts.
Cenários
A lista completa de IDs de cenário é a união MatrixQaScenarioId em extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15. As categorias incluem:
- threading -
matrix-thread-*, matrix-subagent-thread-spawn
- nível superior / DM / sala -
matrix-top-level-reply-shape, matrix-room-*, matrix-dm-*
- streaming e progresso de ferramentas -
matrix-room-partial-streaming-preview, matrix-room-quiet-streaming-preview, matrix-room-tool-progress-*, matrix-room-block-streaming
- mídia -
matrix-media-type-coverage, matrix-room-image-understanding-attachment, matrix-attachment-only-ignored, matrix-unsupported-media-safe
- roteamento -
matrix-room-autojoin-invite, matrix-secondary-room-*
- reações -
matrix-reaction-*
- aprovações -
matrix-approval-* (metadados de exec/Plugin, fallback em partes, reações de negação, threads e roteamento target: "both")
- reinicialização e replay -
matrix-restart-*, matrix-stale-sync-replay-dedupe, matrix-room-membership-loss, matrix-homeserver-restart-resume, matrix-initial-catchup-then-incremental
- gate por menção, bot para bot e allowlists -
matrix-mention-*, matrix-allowbots-*, matrix-allowlist-*, matrix-multi-actor-ordering, matrix-inbound-edit-*, matrix-mxid-prefixed-command-block, matrix-observer-allowlist-override
- E2EE -
matrix-e2ee-* (resposta básica, follow-up em thread, bootstrap, ciclo de vida da chave de recuperação, variantes de perda de estado, comportamento de backup do servidor, higiene de dispositivos, verificação por SAS / QR / DM, reinicialização, redação de artefatos)
- CLI de E2EE -
matrix-e2ee-cli-* (configuração de criptografia, configuração idempotente, falha de bootstrap, ciclo de vida de chave de recuperação, várias contas, ida e volta de resposta do Gateway, autoverificação)
Passe --scenario <id> (repetível) para executar um conjunto escolhido manualmente; combine com --profile all para ignorar o gate por perfil.
Variáveis de ambiente
| Variável | Padrão | Efeito |
|---|
OPENCLAW_QA_MATRIX_TIMEOUT_MS | 1800000 (30 min) | Limite superior rígido para toda a execução. |
OPENCLAW_QA_MATRIX_CANARY_TIMEOUT_MS | 45000 | Limite para a resposta inicial do canário. A CI de release aumenta isso em runners compartilhados para que um primeiro turno lento do Gateway não falhe antes do início da cobertura do cenário. |
OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS | 8000 | Janela silenciosa para asserções negativas de ausência de resposta. Limitada a ≤ o timeout da execução. |
OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS | 90000 | Limite para o encerramento do Docker. Superfícies de falha incluem o comando de recuperação docker compose ... down --remove-orphans. |
OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE | ghcr.io/matrix-construct/tuwunel:v1.5.1 | Substitui a imagem do homeserver ao validar contra uma versão diferente do Tuwunel. |
OPENCLAW_QA_MATRIX_PROGRESS | ativado | 0 silencia as linhas de progresso [matrix-qa] ... no stderr. 1 as força a ficarem ativadas. |
OPENCLAW_QA_MATRIX_CAPTURE_CONTENT | ocultado | 1 mantém o corpo da mensagem e formatted_body em matrix-qa-observed-events.json. O padrão oculta para manter os artefatos de CI seguros. |
OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT | desativado | 1 ignora o process.exit determinístico após a gravação do artefato. O padrão força a saída porque os handles de criptografia nativa do matrix-js-sdk podem manter o loop de eventos ativo após a conclusão do artefato. |
OPENCLAW_RUN_NODE_OUTPUT_LOG | não definido | Quando definido por um inicializador externo (por exemplo, scripts/run-node.mjs), a QA do Matrix reutiliza esse caminho de log em vez de iniciar seu próprio tee. |
Artefatos de saída
Gravados em --output-dir:
matrix-qa-report.md - Relatório de protocolo em Markdown (o que passou, falhou, foi ignorado e por quê).matrix-qa-summary.json - Resumo estruturado adequado para parsing de CI e dashboards.matrix-qa-observed-events.json - Eventos Matrix observados dos clientes driver e observador. Os corpos são ocultados, a menos que OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1; os metadados de aprovação são resumidos com campos seguros selecionados e prévia truncada do comando.matrix-qa-output.log - stdout/stderr combinados da execução. Se OPENCLAW_RUN_NODE_OUTPUT_LOG estiver definido, o log do inicializador externo será reutilizado.
O diretório de saída padrão é <repo>/.artifacts/qa-e2e/matrix-<timestamp>, para que execuções sucessivas não sobrescrevam umas às outras.
Dicas de triagem
- A execução trava perto do fim: os handles de criptografia nativa do
matrix-js-sdk podem sobreviver ao harness. O padrão força um process.exit limpo após a gravação do artefato; se você definiu OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1, espere que o processo permaneça ativo.
- Erro de limpeza: procure o comando de recuperação impresso (uma invocação
docker compose ... down --remove-orphans) e execute-o manualmente para liberar a porta do homeserver.
- Janelas instáveis de asserção negativa na CI: reduza
OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS (padrão 8 s) quando a CI for rápida; aumente em runners compartilhados lentos.
- Precisa de corpos ocultados para um relatório de bug: execute novamente com
OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1 e anexe matrix-qa-observed-events.json. Trate o artefato resultante como sensível.
- Versão diferente do Tuwunel: aponte
OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE para a versão em teste. A lane verifica somente a imagem padrão fixada.
Contrato de transporte ao vivo
Matrix é uma das três lanes de transporte ao vivo (Matrix, Telegram, Discord) que compartilham uma única checklist de contrato definida em Visão geral de QA → Cobertura de transporte ao vivo. qa-channel continua sendo a suíte sintética ampla e intencionalmente não faz parte dessa matriz.
Relacionado
- Visão geral de QA - pilha geral de QA e contrato de transporte ao vivo
- QA Channel - adaptador de canal sintético para cenários baseados no repositório
- Testes - execução de testes e adição de cobertura de QA
- Matrix - o Plugin de canal em teste
