Automatizando tarefas com o Codex: modo não interativo, scripts e pipelines

Até aqui você usou o Codex conversando com ele: fazia um pedido, lia o plano, aprovava um diff. Neste capítulo você vai aprender a fazer o contrário: deixar o Codex trabalhar sozinho, disparado por um script ou por um servidor, sem ninguém olhando a tela. Ao terminar, você saberá usar o modo não interativo para gerar um changelog, atualizar dependências, converter arquivos, aplicar a mesma mudança em vários repositórios e revisar código automaticamente em um passo de integração contínua.

O modo não interativo: codex exec

O modo não interativo é a forma de executar o Codex como qualquer outro programa de linha de comando: você passa a instrução, ele trabalha, imprime o resultado e termina. Não há perguntas no meio, não há tecla para aprovar. O comando é codex exec, seguido do pedido entre aspas.

codex exec --sandbox read-only \
  "Liste os cinco arquivos mais longos do projeto e diga o que cada um faz, em uma linha cada."

Como não existe ninguém para aprovar comandos, a política de aprovação deixa de ter efeito prático e o sandbox passa a ser a sua única trava. Por isso, em automação, sempre declare o sandbox de forma explícita. Use read-only quando o agente só precisa ler e produzir texto, e workspace-write quando ele precisa editar arquivos do projeto. Reserve danger-full-access apenas para contêineres descartáveis, nunca na sua máquina de trabalho.

Os parâmetros mais úteis nesse modo são quatro. O primeiro é --cd, que define a pasta de trabalho do agente sem precisar mudar de diretório antes. O segundo é --output-last-message, que grava a resposta final em um arquivo, o que é ideal quando outro passo do script vai consumir esse texto. O terceiro é --json, que imprime o fluxo de eventos do agente em formato estruturado, uma linha por evento, no estilo conhecido como JSONL, ou JSON por linha. O quarto é --model, para escolher um modelo mais barato em tarefas simples.

codex exec --cd ~/repos/api --sandbox workspace-write \
  --output-last-message /tmp/resumo.md \
  --model gpt-5-codex \
  "$(cat pedidos/atualiza-changelog.md)"

Observe o detalhe importante: o pedido veio de um arquivo, não digitado na hora. Em automação, o prompt é código. Ele merece versionamento, revisão e reuso, com a mesma estrutura de cinco partes que você aprendeu no capítulo de prompts.

Continue em nosso aplicativo e ...

• Ouça o áudio com a tela desligada
• Ganhe Certificado após a conclusão
• + de 5000 cursos para você explorar!

ou continue lendo abaixo...

Baixar o aplicativo

Por fim, aprenda a olhar o código de saída, que é o número que todo programa de terminal devolve ao sistema ao terminar. Zero significa sucesso e qualquer outro valor significa falha. É esse número que faz um script parar ou um passo de integração contínua ficar vermelho.

O que faz uma automação ser confiável

Uma sessão interativa tolera ambiguidade porque você corrige o rumo na hora. Uma automação não. Três regras reduzem quase todos os problemas.

• Critérios de aceitação verificáveis pelo próprio agente. Termine o pedido com algo como: rode o comando de teste do AGENTS.md e, se falhar, desfaça as alterações e explique o motivo.
• Escopo negativo agressivo. Diga quais pastas e arquivos não podem ser tocados, e proíba instalar dependências novas sem autorização.
• Idempotência. Uma automação é idempotente quando rodar duas vezes produz o mesmo resultado que rodar uma vez. Peça explicitamente que o agente não duplique seções de changelog nem reescreva o que já está correto.

E mantenha uma regra de ouro: o resultado de uma execução automática nunca vai direto para a branch principal. Ele vai para um branch novo, um commit isolado ou um pull request, onde um humano decide.

Cinco automações práticas

Changelog a partdo do histórico

O changelog é o caso mais fácil, porque a informação já existe no Git. Como o agente precisa gravar no arquivo, use workspace-write: em modo somente leitura ele conseguiria ler o histórico, mas não escrever o CHANGELOG.md.

codex exec --sandbox workspace-write \
  "Leia os commits entre a tag anterior e HEAD com git log.
   Acrescente ao topo do CHANGELOG.md uma seção da nova versão
   agrupada em Adicionado, Corrigido e Alterado.
   Não altere seções já existentes. Ignore commits de merge."

Atualização de dependências

Aqui o agente precisa de rede para consultar versões, então libere o acesso de forma consciente com a chave network_access em um perfil de configuração dedicado. O pedido deve ser conservador: atualizar apenas versões de correção e de recurso, nunca versões maiores, rodar a suíte de testes e relatar em tabela o que subiu.

Conversão de formatos em lote

Converter dezenas de arquivos de YAML para JSON, de CSV para SQL ou de um padrão de configuração antigo para o novo é trabalho repetitivo e verificável. Peça ao agente que escreva primeiro um script de conversão, rode o script e depois valide alguns arquivos comparando origem e destino. Isso é melhor do que pedir a conversão arquivo por arquivo, porque o script fica no repositório e pode ser reexecutado.

A mesma mudança em vários repositórios

Esse é o ganho mais visível do modo não interativo. Um laço de shell aplica o mesmo pedido em uma lista de projetos.

#!/usr/bin/env bash
set -uo pipefail

PEDIDO="$(cat pedidos/troca-logger.md)"

for repo in ~/repos/api ~/repos/web ~/repos/worker; do
  echo "=== $repo"
  git -C "$repo" switch -c chore/troca-logger || continue
  codex exec --cd "$repo" --sandbox workspace-write \
    --output-last-message "/tmp/$(basename $repo).md" \
    "$PEDIDO"
  if [ $? -ne 0 ]; then
    echo "FALHOU em $repo" >> /tmp/falhas.txt
    continue
  fi
  git -C "$repo" diff --stat
done

Note dois cuidados. Cada repositório ganha um branch próprio antes de qualquer edição, e as falhas são registradas em um arquivo em vez de interromper o laço. Antes de trocar de branch, confirme que a árvore de trabalho está limpa, porque git switch -c leva as alterações não salvas para o novo branch, e verifique se aquele branch já não existe, senão o comando falha e o repositório é pulado. Rode primeiro em um único repositório de teste.

Revisão de código em um passo de integração contínua

Integração contínua, abreviada como CI, é a prática de rodar verificações automáticas a cada alteração enviada ao repositório. Colocar o Codex ali dentro, em modo somente leitura, dá uma revisão rápida antes da revisão humana.

Codex dentro do GitHub Actions

GitHub Actions é o serviço de automação do GitHub. Você descreve um workflow, que é um arquivo em formato YAML dentro da pasta ponto github barra workflows, dizendo quando rodar e quais passos executar. O exemplo abaixo comenta uma revisão em cada pull request.

name: Revisao Codex
on: pull_request

jobs:
  revisar:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g @openai/codex
      - name: Gerar revisao
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          git diff origin/${{ github.base_ref }}...HEAD > /tmp/mudancas.patch
          codex exec --sandbox read-only \
            --output-last-message /tmp/revisao.md \
            "Leia /tmp/mudancas.patch e o AGENTS.md.
             Liste no maximo dez problemas concretos, cada um com
             arquivo, linha e sugestao. Nao elogie. Se nao houver
             problema relevante, escreva apenas: sem apontamentos."
      - name: Comentar no PR
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh pr comment ${{ github.event.number }} --body-file /tmp/revisao.md

Três decisões desse arquivo merecem atenção. A primeira é o sandbox somente leitura: um revisor não precisa escrever nada. A segunda é o limite de dez apontamentos, que evita comentários intermináveis. A terceira é a chave de API vindo de um segredo de repositório, que é um valor guardado de forma cifrada nas configurações do GitHub e injetado apenas durante a execução. Guarde um limite importante: em pull requests abertos a partir de forks, o GitHub não expõe os segredos do repositório e o GITHUB_TOKEN é somente leitura, então esse workflow funciona apenas para branches do próprio repositório. Não tente contornar isso trocando para pull_request_target com checkout do código do fork, porque isso executaria código não confiável com acesso aos seus segredos.

Cuidados que não são opcionais

Execução autônoma amplia erros na mesma velocidade em que amplia trabalho. Adote estas precauções.

• Chaves de API nunca no código. Use segredos do repositório ou variáveis de ambiente do sistema. Nunca escreva a chave em um arquivo versionado, em um log ou no próprio prompt. Crie uma chave separada para automação, com limite de gasto próprio, para poder revogá-la sem afetar seu uso pessoal.
• Segredos fora do alcance do agente. Em pipelines, exponha apenas as variáveis de ambiente estritamente necessárias ao passo do Codex. Lembre que conteúdo de terceiros, como o texto de um pull request externo, pode conter injeção de prompt.
• Limites de uso. Contas e chaves têm limite de taxa, isto é, um teto de requisições e de consumo em uma janela de tempo. Automação em laço estoura esse teto com facilidade. Trate a falha por limite como temporária, com uma pausa crescente entre tentativas, e nunca dispare dezenas de execuções em paralelo por hábito.
• Falhas do agente. Ele pode parar no meio, deixar o repositório sujo ou concluir uma tarefa pela metade afirmando sucesso. Por isso: sempre um branch novo, sempre a suíte de testes como juiz, sempre o código de saída verificado, sempre o relatório final salvo em arquivo para auditoria.
• Custo visível. Guarde os logs com os eventos em JSONL e revise periodicamente quanto cada automação consome. Automação silenciosa e caríssima é um risco real.

Recapitulando

O comando codex exec transforma o agente em uma peça de script, com pedido vindo de arquivo, sandbox declarado, resposta final gravada em disco e código de saída informando sucesso ou falha. Automações confiáveis têm critérios de aceitação verificáveis, escopo negativo firme e comportamento idempotente, e sempre entregam o resultado em um branch para revisão humana. Com isso você constrói geração de changelog, atualização conservadora de dependências, conversões em lote, mudanças coordenadas em vários repositórios e revisão automática dentro do GitHub Actions. E as precauções são inseparáveis do ganho: chave de API em segredo, apenas as variáveis necessárias expostas, respeito aos limites de taxa e a suposição permanente de que o agente pode falhar no meio do caminho.