Modos de aprovação e sandbox do Codex: controlando o que a IA pode executar

Nos capítulos anteriores você instalou o Codex CLI, abriu sua primeira sessão e viu o agente propor diffs e executar comandos. Agora vamos ao volante e aos freios. Ao terminar este capítulo, você saberá escolher entre os três níveis de autonomia do Codex, entender exatamente o que o sandbox bloqueia e por quê, liberar exceções de forma consciente e revisar um comando perigoso antes de digitar sim.

Duas engrenagens diferentes: aprovação e sandbox

Muita gente trata o controle do Codex como um botão só, mas na verdade existem duas engrenagens que giram juntas. A primeira é a política de aprovação, que responde à pergunta: quando o agente precisa parar e pedir sua permissão? A segunda é o sandbox, que responde a outra pergunta: quando o agente age, até onde ele consegue chegar no seu computador?

No arquivo de configuração, essas engrenagens aparecem como duas chaves separadas, approval_policy e sandbox_mode. Entender que são coisas distintas evita confusão. É possível, por exemplo, ter um agente que nunca pergunta nada, mas que está trancado em um sandbox de leitura apenas. Ele age sozinho, só que não consegue estragar nada.

Os três níveis de autonomia

Na prática, o Codex combina essas duas engrenagens em três presets, que você escolhe ao iniciar a sessão ou durante ela.

Somente sugerir

Esse é o modo de leitura apenas. O agente lê arquivos, roda comandos inofensivos de inspeção e escreve para você o que faria, mas não altera nada em disco. Qualquer escrita ou execução relevante vira um pedido de aprovação. É o modo ideal para explorar um repositório desconhecido, pedir uma explicação de arquitetura ou revisar código sem risco nenhum.

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

Editar arquivos automaticamente

É o modo do dia a dia, às vezes chamado de automático. O agente escreve e altera arquivos livremente dentro da pasta de trabalho, roda testes e comandos locais sem perguntar, mas continua obrigado a pedir permissão para três coisas: escrever fora da pasta do projeto, acessar a rede e executar comandos que o sandbox recusou. Você mantém o fluxo rápido e ainda vê o que importa.

Totalmente autônomo

Aqui o sandbox é desligado e o agente passa a ter o mesmo poder que você teria no terminal: escrita em qualquer lugar do disco, acesso irrestrito à rede, instalação de pacotes. É útil, mas deve ser reservado a ambientes descartáveis, como um contêiner, uma máquina virtual ou um runner de integração contínua. Rodar esse modo na sua máquina pessoal, com chaves de acesso e projetos de clientes ao lado, é um risco que raramente compensa.

Como alternar entre os modos

Dentro de uma sessão em andamento, o comando de sessão /approvals abre o seletor e troca o modo na hora, sem perder o contexto da conversa. É comum começar uma tarefa em somente sugerir, entender o problema e então subir para o modo automático quando a implementação começa.

Ao iniciar a sessão, você escolhe pelos parâmetros de linha de comando:

codex --sandbox read-only
codex --ask-for-approval on-request --sandbox workspace-write
codex --full-auto
codex --sandbox danger-full-access --ask-for-approval never

Atenção a um detalhe que confunde muita gente: o --full-auto não é o modo totalmente autônomo. Ele mantém o sandbox de escrita restrito ao projeto e apenas dispensa as aprovações de rotina. Para desligar de fato o sandbox é preciso combinar --sandbox danger-full-access com --ask-for-approval never, ou usar a variante equivalente de bypass, e isso só em ambiente descartável.

E para fixar o comportamento padrão, use o config.toml na pasta ponto codex do seu usuário:

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

Os valores de approval_policy que você vai encontrar são untrusted, que pede aprovação para quase tudo, on-request, em que o próprio agente pede permissão quando julga necessário, on-failure, que só interrompe quando um comando é bloqueado, e never, que nunca pergunta. Os valores de sandbox_mode são read-only, workspace-write e danger-full-access. O nome do terceiro já entrega o recado.

Uma combinação muito prática é um perfil de configuração nomeado para tarefas de leitura, com política never e sandbox read-only. O agente trabalha sem interrupções e mesmo assim não consegue tocar em nada.

O que o sandbox realmente bloqueia

O sandbox é uma barreira do sistema operacional, não uma promessa do modelo. No macOS ele usa o mecanismo de isolamento do próprio sistema, no Linux usa recursos do kernel que restringem escrita e chamadas de sistema, e no Windows não há sandbox nativo, por isso a recomendação é rodar dentro do WSL2, onde as proteções do Linux valem desde que o kernel tenha suporte a elas; na dúvida, prefira um contêiner ou uma máquina virtual descartável.

Por padrão, no modo automático, o agente pode escrever na pasta de trabalho e em diretórios temporários, e nada além disso. Sua pasta pessoal, o arquivo de configuração do shell, chaves em ponto ssh e outros repositórios ficam fora de alcance. O acesso à rede vem desligado. Isso não é implicância: rede desligada impede que um comando baixe e execute algo inesperado e reduz muito o estrago de uma instrução maliciosa escondida em um arquivo do projeto, algo conhecido como injeção de prompt.

Quando a tarefa realmente exige mais, libere o mínimo necessário e por escrito:

[sandbox_workspace_write]
network_access = true
writable_roots = ["/home/ana/cache-compartilhado"]

Prefira ligar a rede por sessão, por exemplo com codex -c sandbox_workspace_write.network_access=true ou por meio de um perfil nomeado, em vez de deixá-la ligada para sempre no arquivo global. Instalar dependências é o caso legítimo mais comum. Terminada a instalação, volte ao padrão.

Escolhendo o modo pelo risco da tarefa

Um critério simples: pergunte o que acontece se o agente errar feio nesta tarefa. Se a resposta for apenas perda de tempo, solte a rédea. Se envolver dados, infraestrutura ou histórico do repositório, aperte.

• Explicar código, mapear arquitetura, revisar um diff: somente sugerir.
• Implementar uma função, corrigir um bug, escrever testes em um projeto com Git limpo: automático.
• Mexer em scripts de deploy, migrações de banco, arquivos de infraestrutura ou segredos: automático com aprovação para tudo, lendo cada comando.
• Refatoração longa e repetitiva em um contêiner descartável, com o repositório já clonado: totalmente autônomo.

Vale uma regra de ouro que atravessa todo o livro: trabalhe sempre com a árvore do Git limpa antes de soltar o agente. Um git status sem pendências e um commit recente transformam boa parte dos erros do Codex em um git checkout de arrependimento. Só não confie nisso cegamente: arquivos novos que nunca foram adicionados ao Git, conteúdo apagado fora do repositório e alterações já commitadas pelo agente não voltam com um checkout, então mantenha também uma cópia de segurança do que for insubstituível.

Como revisar um comando antes de aprovar

Quando o agente pede permissão, o terminal mostra o comando exato e o motivo. Leia três coisas antes de responder: o verbo, o alvo e o alcance. O verbo é o que o comando faz, o alvo é sobre o que ele age, e o alcance é quanto do sistema ele toca.

Desconfie sempre destes padrões:

• Remoção recursiva e forçada de diretórios, especialmente com caminhos que começam na raiz ou no seu diretório pessoal.
• git push --force, git reset --hard em um repositório com trabalho não commitado, ou exclusão de branches remotos.
• Baixar um script da internet e executá-lo direto no shell, o famoso cano entre um download e o interpretador.
• Qualquer coisa com sudo, alteração de permissões amplas ou edição de arquivos do sistema.
• Comandos que publicam artefatos, como publicar um pacote, ou que apagam e recriam bancos de dados.

Se não entender um comando, recuse e peça ao agente que explique o que ele faz e por que é necessário. Recusar é barato; desfazer nem sempre é.

Credenciais e segredos

O sandbox protege arquivos, mas variáveis de ambiente do processo podem ser herdadas por comandos que o agente executa. Alguns cuidados práticos resolvem quase tudo.

• Não inicie o Codex em um terminal onde você acabou de exportar tokens de produção.
• Mantenha segredos em arquivos ponto env fora do controle de versão e diga ao agente para não abri-los nem imprimi-los.
• Prefira credenciais de desenvolvimento, com escopo reduzido e curta duração.
• Nunca aponte a pasta de trabalho para o seu diretório pessoal inteiro. Abra o agente na pasta do projeto.
• Se suspeitar que uma chave vazou em um log ou em um commit, revogue a chave imediatamente. Trocar é mais rápido que investigar.

O sandbox é uma rede de proteção, não um substituto da sua atenção. O responsável por tudo que roda na sua máquina continua sendo você.

Recapitulando

O controle do Codex nasce de duas engrenagens: a política de aprovação, que define quando o agente pergunta, e o sandbox, que define até onde ele alcança. Os três presets vão de somente sugerir, para leitura e exploração, passando por automático, o padrão do dia a dia com escrita restrita ao projeto e rede desligada, até o totalmente autônomo, reservado a ambientes descartáveis. Você alterna com /approvals na sessão, com parâmetros ao iniciar ou fixando approval_policy e sandbox_mode no config.toml. Libere rede e diretórios extras só quando a tarefa exigir e volte ao padrão depois. Escolha o modo pelo risco, trabalhe sempre com Git limpo, leia verbo, alvo e alcance de cada comando antes de aprovar e mantenha credenciais longe do alcance do agente.