OpenClaw é um loop: ele lê seu workspace, executa comandos shell através de sua ferramenta `exec`, lê a saída e decide o que fazer em seguida. Então, por que seus testes de API não estão nesse loop? Eles ficam no Apidog, atrás de uma GUI, e são executados quando alguém se lembra de clicar. Seu agente nunca os toca.
A solução é um único bloco de configuração. O CLI do Apidog é um pacote npm, apidog-cli, que executa os cenários de teste que você construiu no Apidog diretamente de um terminal. Uma vez que o CLI está instalado e o OpenClaw sabe que ele existe, seu agente executa um cenário do Apidog da mesma forma que executa seus testes unitários: dispara o comando, lê o código de saída, corrige o código se ele estiver "vermelho" (falhou).
Este guia aborda a parte específica do OpenClaw que o guia de instalação genérico omite: onde colocar as regras do Apidog para que o agente as mantenha, como a ferramenta `exec` do OpenClaw realmente executa apidog run e como ler o resultado.
Se você ainda não instalou o CLI, faça isso primeiro. Como instalar o CLI do Apidog com um agente de codificação de IA detalha a instalação do npm, a autenticação e a primeira execução. Este artigo assume que apidog --version imprime um número e que sua conta Apidog está logada.
Sobre qual OpenClaw estamos falando
OpenClaw é o agente de IA de código aberto, local-first, que roda na sua própria máquina. Ele tem um workspace, um conjunto de habilidades e uma ferramenta `exec` que executa comandos shell reais. Não é um plugin de preenchimento de código nem um chatbot hospedado. Se você já executou openclaw localmente e o viu editar arquivos e executar comandos, você está no lugar certo. Para a configuração mais ampla, consulte Automação do fluxo de trabalho de desenvolvimento OpenClaw e o guia para uma instalação segura do OpenClaw antes de lhe dar quaisquer comandos.
A distinção importa porque o OpenClaw aprende as regras do projeto a partir dos arquivos do workspace, e esse mecanismo transforma um "execute meus testes" pontual em algo que o OpenClaw busca por conta própria. Esse mecanismo é o AGENTS.md.
Passo 1: Adicione as regras do Apidog ao AGENTS.md
OpenClaw lê os arquivos do workspace como instruções permanentes e os injeta no contexto do agente. O que você precisa é o AGENTS.md, o manual de regras processuais que diz ao agente o que fazer e como. Pense nele como CLAUDE.md para Claude Code; o OpenClaw inclusive já vem com um modelo padrão que você copia para o seu workspace, e ele trata um atalho CLAUDE.md adjacente como o mesmo arquivo. O workspace padrão é ~/.openclaw/workspace, mas você pode apontar um agente para o diretório do seu projeto com agents.list[].workspace, e o OpenClaw suporta arquivos AGENTS.md com escopo por subdiretório (consulte a referência de AGENTS.md do OpenClaw).
Adicione um pequeno bloco ao seu AGENTS.md:
## Testes de API com Apidog
- Para executar testes de API, use o CLI do Apidog: `apidog run -t <scenario_id> -e <env_id> -r cli`.
- Código de saída 0 significa que todas as asserções foram aprovadas. Diferente de zero significa que algo falhou. Trate-o como o critério de aprovação/reprovação.
- A máquina já está autenticada com `apidog login`. Nunca adicione um flag --access-token e nunca coloque um token neste arquivo.
- Se um flag parecer incomum, execute `apidog run --help` em vez de adivinhar.
É por isso que você escreve o CLI no AGENTS.md em vez de mencioná-lo no chat. Um ID de cenário digitado em uma sessão se perde quando a sessão termina. Um em AGENTS.md está lá para cada colega de equipe e cada execução do OpenClaw daqui para frente.
Passo 2: Obtenha o comando do Apidog
Você não precisa escrever o ID do cenário manualmente. Abra o cenário de teste no Apidog, vá para a aba CI/CD e copie o comando gerado. Ele se parece com isto:
apidog run -t 1234567 -e 890123 -r cli
O -t é o cenário de teste, -e é o ambiente, e -r cli é o reporter. Cole os IDs reais no bloco AGENTS.md do Passo 1 para que o OpenClaw sempre chame o cenário certo contra o ambiente certo. O guia completo do CLI do Apidog e a referência de comando apidog run cobrem cada flag, caso você queira ajustá-las.
Passo 3: Peça ao agente para executar o teste
Com o bloco no lugar, inicie o OpenClaw em seu projeto e faça uma alteração que afete sua API, ou simplesmente peça para ele executar a verificação. Como o AGENTS.md já está em contexto, o agente sabe que o CLI existe e emite o comando apidog run através de sua ferramenta `exec`.
A ferramenta `exec` executa comandos shell no workspace, e o OpenClaw a controla com um modo de permissão. Os modos são deny, allowlist, ask, auto e full (documentados na página de modos de permissão do OpenClaw). Para um agente de codificação, auto é a configuração sensata: comandos permitidos são executados sem prompt, e qualquer outra coisa passa por revisão antes que ele lhe pergunte. Se o seu modo for ask, o OpenClaw pausa e solicita aprovação antes de executar apidog run; aprove uma vez, ou adicione o comando à sua lista de permissões para que um teste somente leitura contra o ambiente de staging seja executado por conta própria. Defina o modo em tools.exec no openclaw.json.
Passo 4: Leia o relatório dentro do OpenClaw
O reporter -r cli imprime um resultado passo a passo no terminal: cada requisição, cada asserção e qual falhou com o valor esperado versus o valor real. Essa quebra detalhada em linha é o que o OpenClaw lê para decidir seu próximo passo, então mantenha cli na lista.
Quando você quiser um relatório que possa abrir em um navegador ou entregar a um colega de equipe, adicione o reporter HTML:
apidog run -t 1234567 -e 890123 -r cli,html
O reporter html escreve um arquivo auto-contido em ./apidog-reports. Mantenha cli ao lado dele para que o OpenClaw ainda receba a saída em linha. Para o formato JUnit que os painéis de CI analisam e todos os outros reporters, consulte o guia de relatórios de teste do CLI do Apidog.
Testando o OpenClaw dentro de seu próprio loop
O ponto é o que acontece quando você para de pedir e o OpenClaw executa o cenário por conta própria porque o AGENTS.md o instruiu a fazê-lo.
Imagine o OpenClaw editando um manipulador que constrói uma resposta de checkout. Seu loop muda: ele edita o código, então, em vez de declarar vitória, executa seu cenário Apidog contra o ambiente de staging, lê o código de saída e age sobre ele. Se verde, ele avança. Se vermelho, ele abre o relatório, lê qual asserção falhou (o código de status, o campo ausente, o valor errado), tenta uma correção e reexecuta. O teste de API se torna parte do mesmo loop de edição-teste-correção que o OpenClaw já executa seus testes unitários. Você escreveu uma instrução e o agente incorporou o comando em como ele já funciona.
Este é o modelo de "delegar e verificar" que torna qualquer fluxo de trabalho de agente seguro. O OpenClaw executa o comando e lê o resultado; você continua criando cenários visualmente no Apidog e verifica se o agente lê os códigos de saída honestamente. Para o padrão mais amplo, consulte como usar agentes de IA para teste de API e o harness de teste de IA do Apidog.
Verifique se o OpenClaw está realmente executando o CLI
Agentes relatam sucesso que não conquistaram, e o OpenClaw não é exceção. Três verificações, em ordem de quão frequentemente elas pegam problemas.
Primeiro, confirme se o comando foi executado. A transcrição do OpenClaw mostra os comandos `exec` que ele executou e sua saída. Procure pela linha literal apidog run ... e um resultado abaixo dela. Se o OpenClaw diz que executou os testes, mas você não vê o comando, ele resumiu algo que nunca fez. Peça para ele executar novamente e mostrar a saída bruta.
Segundo, confirme o código de saída, o que realmente importa. Pergunte diretamente:
Qual foi o código de saída daquele comando 'apidog run'?
apidog run retorna 0 quando todas as asserções são aprovadas e um valor diferente de zero quando algo falha. Esse único comportamento permite que o OpenClaw, ou um pipeline, trate a execução como um portão limpo. Quando o texto diz "testes aprovados", mas o código de saída não é zero, o código de saída está correto.
Terceiro, confirme se ele usou o cenário real. Se uma execução falhar com "cenário não encontrado", o OpenClaw pode ter inventado ou se confundido com um ID. Verifique novamente os valores -t e -e em relação ao AGENTS.md e ao comando que o Apidog gerou na aba CI/CD. Os IDs em AGENTS.md são a verdade.
Opcional: conecte o servidor MCP do Apidog
Executar apidog run através da ferramenta `exec` cobre a maioria das suas necessidades. Uma rota vai além: o Protocolo de Contexto do Modelo (Model Context Protocol - MCP).
OpenClaw suporta servidores MCP. Você adiciona um com openclaw mcp add <nome>, que escreve a definição do servidor em ~/.openclaw/openclaw.json sob mcp.servers e aceita flags de stdio como --command e --arg (consulte a documentação MCP do OpenClaw). O servidor MCP do Apidog expõe suas especificações de API via MCP, para que o OpenClaw possa ler seu esquema enquanto escreve código, e não apenas depois. A divisão de trabalho é clara: o CLI executa os testes, e o MCP alimenta o agente com a especificação.
Quando o OpenClaw erra
Algumas falhas aparecem frequentemente durante a configuração.
Ele ignora o bloco AGENTS.md. Se o OpenClaw executa um comando genérico ou nenhum, o arquivo pode não estar sendo carregado no contexto. Confirme se o bloco está no AGENTS.md que pertence ao workspace ativo do agente, e lembre-se de que o OpenClaw percorre os arquivos AGENTS.md com escopo por diretório, então uma regra enterrada na subárvore errada será ignorada. Reiniciar a sessão força uma nova leitura.
Ele nunca executa nada porque `exec` está bloqueado. Desde que a política padrão do OpenClaw foi endurecida, `exec` pode ser negado ou retido por uma lista de permissões. Se apidog run for silenciosamente ignorado, verifique seu modo de permissão em tools.exec e mude para auto ou adicione apidog à lista de permissões. Consulte o guia de instalação segura do OpenClaw para saber como abrir apenas este comando sem abrir tudo.
Ele passa um token de acesso de qualquer maneira. Se o OpenClaw tentar adicionar --access-token, ele está adivinhando a partir de exemplos públicos. O bloco já diz para não fazer isso, já que a máquina está autenticada via apidog login. Reforce a linha e nunca coloque um token real no AGENTS.md; para o padrão correto, consulte autenticação do CLI do Apidog.
Ele inventa um flag. Um erro de "opção desconhecida" significa que o OpenClaw adivinhou um flag que sua versão não possui. Diga a ele para executar apidog run --help e copiar o flag exato de lá, que é sempre correto para a versão instalada.
Ele relata uma aprovação em uma execução falha. O mais custoso, e a razão pela qual a regra do código de saída está no seu AGENTS.md e no seu passo de verificação. Quando o resumo e o código de saída discordam, o código de saída vence. Se você usou outro agente para isso, a mesma regra se aplica; a abordagem espelha o que cobrimos em Apidog CLI no Codex e as diferenças em Claude Code vs OpenClaw.
De um agente diário a um loop testado
Essa é a configuração. Instale o apidog-cli uma vez seguindo o guia de instalação, adicione um pequeno bloco Apidog ao seu AGENTS.md do workspace, defina o modo de permissão de `exec` para que o comando possa ser executado, e o OpenClaw saberá como executar seus testes de API e ler o resultado dentro do mesmo loop que ele já usa para editar código. Um endpoint quebrado é detectado enquanto o OpenClaw ainda está trabalhando na alteração, e não depois que ela é entregue.
Um teste atrás de uma GUI é executado quando um humano clica; um comando de uma linha é executado sempre que o OpenClaw decide. Você continua construindo cenários visualmente no Apidog, e seu agente os executa onde você não está observando. Baixe o Apidog, construa um cenário, insira seu comando apidog run no AGENTS.md e veja o OpenClaw pegá-lo na próxima alteração. Quando você quiser o mesmo controle em um pipeline sem a presença do agente, Apidog CLI no GitHub Actions cobre os segredos, reporters e controle de código de saída.