Codex é um loop: ele edita arquivos, executa comandos, 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, sendo executados quando alguém se lembra de clicar. Seu agente nunca os toca.
A solução é um único bloco de configuração. A 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 a CLI esteja instalada e o Codex saiba de sua existência, seu agente executa um cenário do Apidog da mesma forma que executa seus testes de unidade: 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 Codex que o guia de instalação genérico omite: a linha exata para o seu AGENTS.md, o prompt a ser entregue ao Codex, como ele executa apidog run dentro de seu próprio loop e como ler o resultado.
Se você ainda não instalou a CLI, faça isso primeiro. Como instalar a CLI do Apidog com um agente de codificação de IA detalha a instalação do npm, o token de acesso e a primeira execução, com o Codex fazendo a digitação. Este artigo pressupõe que apidog --version imprime um número e que sua conta Apidog está autenticada.
Sobre qual Codex estamos falando
Tanto o OpenAI Codex CLI quanto o Codex App. Ele executa localmente, lê seu repositório, edita arquivos e executa comandos de shell dentro de um sandbox, solicitando aprovação com base no seu modo de permissão. Não é a antiga API de preenchimento de código do Codex. Se você executar codex e obter uma interface em tela cheia mostrando as diferenças e a saída de comandos, você está no lugar certo. O guia da CLI do OpenAI Codex aborda os conceitos básicos.
A distinção importa porque o Codex tem sua própria maneira de aprender as regras do projeto, e esse mecanismo transforma um "execute meus testes" pontual em algo que o Codex busca por conta própria. Esse mecanismo é o AGENTS.md.
O mecanismo: AGENTS.md, não um lembrete no chat
O Codex lê os arquivos AGENTS.md antes de começar a trabalhar. Pense nele como CLAUDE.md para Claude Code: um arquivo Markdown simples de instruções do projeto que o Codex carrega no contexto no início de cada sessão. Ele constrói o conjunto de instruções caminhando da raiz do seu Git até o seu diretório atual, concatenando cada AGENTS.md da raiz primeiro, de modo que arquivos mais próximos prevalecem em caso de conflitos. Também existe um ~/.codex/AGENTS.md global. Para nosso propósito, um arquivo na raiz do repositório é suficiente.
É por isso que você escreve a CLI em AGENTS.md em vez de mencioná-la no chat. Um ID de cenário digitado no chat desaparece quando a sessão termina. Um em AGENTS.md estará lá para cada colega de equipe e para cada execução do Codex daqui para frente.
Passo 1: Dê o prompt ao Codex e observe-o executar
Com o bloco no lugar, inicie o Codex em seu repositório:
O Codex carrega o AGENTS.md ao iniciar, então ele já sabe que a CLI está lá. Faça uma alteração que afete sua API ou peça para ele executar a verificação:
O Codex emite o comando apidog run do seu AGENTS.md. Em seu modo Auto padrão, ele pode ler arquivos, editá-los e executar comandos dentro do diretório de trabalho por conta própria, então um simples apidog run geralmente é executado sem um prompt. O repórter -r cli imprime um resultado passo a passo e um resumo diretamente no terminal, onde você observa cada requisição e asserção conforme elas acontecem.
Você vai querer ver a execução do teste e o Codex reportando tanto o resumo quanto o código de saída. Se seu modo de permissão for Somente Leitura, o Codex pausa e pergunta antes de executar; aprove, ou altere o modo com /permissions dentro da sessão. O modo Automático é o padrão sensato, já que um cenário de teste somente leitura contra um ambiente de homologação é exatamente o tipo de comando seguro, dentro do espaço de trabalho, para o qual esse modo foi criado.
Passo 2: Testes do Codex dentro de seu próprio loop
O ponto é o que acontece quando você para de pedir e o Codex executa o cenário por conta própria porque o AGENTS.md o instruiu a fazer isso.
Imagine o Codex editando um handler 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 homologação, lê o código de saída e age sobre ele. Se verde (sucesso), ele avança. Se vermelho (falha), ele abre o relatório, lê qual asserção falhou (o código de status, o campo ausente, o valor incorreto), tenta uma correção e executa novamente. O teste de API torna-se parte do mesmo loop de edição-teste-correção que o Codex já executa para seus testes de unidade. Você escreveu uma instrução e o Codex 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 Codex 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 testes de API e o harness de teste de IA do Apidog.
Verifique se o Codex está realmente executando a CLI
Agentes relatam sucesso que não conquistaram, e o Codex não é exceção. Três verificações, em ordem de quão frequentemente elas detectam problemas.
Primeiro, confirme se o comando foi executado. A interface do Codex mostra os comandos que ele executou e sua saída em linha. Procure a linha literal apidog run ... e um resultado abaixo dela. Se o Codex disser que executou os testes, mas você não vir 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:
Qual foi o código de saída desse comando apidog run?
O comando apidog run sai com 0 quando todas as asserções são aprovadas e com um valor diferente de zero quando algo falha. Esse comportamento único permite que o Codex, ou um pipeline, trate a execução como um portão limpo. Quando a prosa do Codex diz “testes aprovados” mas o código de saída é diferente de 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 Codex pode ter inventado ou se lembrado de um ID incorretamente. Verifique novamente os valores de -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.
Lendo o relatório de teste
Quando uma execução falha, o relatório contém a resposta. Com -r cli, o Codex obtém um detalhamento legível no terminal: cada requisição, cada asserção e qual falhou com o valor esperado versus o valor real. A asserção com falha nomeia o campo exato ou o código de status, o que geralmente é suficiente para o Codex encontrar a correção.
Para um relatório que você pode abrir em um navegador ou entregar a um colega de equipe, adicione o repórter HTML
O repórter html grava um arquivo autocontido em ./apidog-reports. Mantenha cli na lista para que o Codex ainda receba a saída em linha que ele lê para decidir seu próximo passo. Para todas as flags e repórteres, incluindo o formato JUnit que os painéis de CI analisam, consulte o guia completo da CLI do Apidog e a referência do comando apidog run.
Duas maneiras de ir além dos comandos de shell
Executar apidog run a partir do AGENTS.md cobre a maior parte do que você precisa. Duas rotas vão além.
O primeiro é o MCP. O Codex suporta o Protocolo de Contexto de Modelo (Model Context Protocol), e você adiciona servidores com codex mcp add ou editando ~/.codex/config.toml com um bloco [mcp_servers.NAME]. O servidor MCP do Apidog expõe suas especificações de API via MCP, para que o Codex possa ler seu esquema enquanto escreve código, e não apenas depois. A CLI executa os testes; o MCP alimenta o agente com a especificação.
O segundo é codex exec. Onde um codex simples abre a interface interativa, codex exec "..." executa o Codex de forma não interativa e direciona o resultado para stdout, que é o que você usa em scripts e CI. Para executar apidog run em um pipeline sem o Codex presente, A CLI do Apidog no GitHub Actions aborda os segredos, repórteres e o controle de código de saída.
Quando o Codex erra
Algumas falhas aparecem frequentemente durante a configuração.
Ele ignora o bloco AGENTS.md. Se o Codex executa um comando genérico ou nenhum, o bloco pode não estar sendo carregado. Confirme se o arquivo está nomeado exatamente como AGENTS.md e se ele está na raiz do seu Git ou em um diretório pai do seu diretório atual. Um erro de digitação no nome do arquivo significa que o Codex nunca o lê; reiniciar a sessão força uma nova leitura.
Ele passa um token de acesso de qualquer forma. Se o Codex tentar adicionar --access-token, ele está adivinhando a partir de exemplos públicos. O bloco já o informa para não fazer isso, já que a máquina está autenticada via apidog login. Reforce a linha e nunca coloque um token real em AGENTS.md.
Ele inventa uma flag. Um erro de “opção desconhecida” significa que o Codex adivinhou uma flag que sua versão não possui. Diga a ele para executar apidog run --help e copiar a flag exata de lá, o que é sempre correto para sua versão instalada.
Ele relata um sucesso em uma execução falha. Este é o mais custoso, e a razão pela qual a regra do código de saída está no seu AGENTS.md e na sua etapa de verificação. Quando o resumo e o código de saída discordam, o código de saída prevalece.
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 do Apidog ao AGENTS.md do seu repositório, e o Codex 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 Codex ainda está trabalhando na mudança, não depois que ela é lançada.
Um teste atrás de uma GUI é executado quando um humano clica; um comando de uma linha é executado sempre que o Codex 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, adicione seu comando apidog run ao AGENTS.md e observe o Codex detectá-lo na próxima alteração.