Visão Geral dos Conceitos Essenciais do Codex

📚 Navegação da Série: O artigo anterior 01 · Apresentando o Codex e as Quatro Interfaces apresentou as quatro interfaces do Codex — aplicativo desktop, terminal CLI, extensão para IDEs e ambiente em nuvem. Este artigo aprofunda o entendimento sobre os conceitos essenciais que serão repetidamente utilizados nos próximos capítulos. No próximo artigo 03 · Instalação e Login, iniciaremos a instalação prática.

Antes de tudo, cabe compartilhar um erro bobo que cometi no início. Logo ao começar a usar o Codex, pedi para ele "renomear em lote estes três arquivos". Ele processou as edições rapidamente, mas ao verificar o resultado, percebi que ele alterou apenas o arquivo no diretório do projeto ativo; os outros dois que estavam na Área de Trabalho continuavam intocados. Fiquei confuso: se ele executa comandos de shell, por que ignorou parte do pedido? Ao consultar a documentação técnica, entendi a causa: o isolamento em Sandbox estava ativo, restringindo a atuação do agente por padrão ao diretório de trabalho designado. Para sair desse limite, ele exige sua aprovação.

Naquele momento percebi: se você não compreender esses conceitos básicos antes de usar o Codex, sentirá que a ferramenta se comporta de forma inconsistente — na verdade, o fluxo dela é determinístico; o usuário apenas desconhece as restrições de segurança ativas.

Neste artigo, detalharemos essas restrições técnicas de segurança e os parâmetros de configuração exclusivos.

Ao terminar de ler este artigo, você terá:

• Uma explicação direta sobre o papel do "Agente" no Codex e como ele difere de chatbots comuns
• Entendimento detalhado sobre o funcionamento de Sandbox e Aprovações — o motivo da falha na renomeação de arquivos e como ajustar esses parâmetros
• Introdução ao AGENTS.md: o manual técnico de integração que ensina as regras do projeto ao Codex
• O que são as funções de Memória (Memory) e Chronicle, seus estados padrões e viabilidade de uso
• Um experimento prático guiado para observar a atuação do sandbox na contenção de comandos

⚠️ Observação: Comandos, parâmetros de configuração e comportamentos padrões citados abaixo baseiam-se na documentação oficial do Codex; identificadores de modelos e planos comerciais vigentes dependem de atualizações da plataforma e do seu console local.

---

01 O Agente (Agent): Autonomia prática além de respostas de texto

Direto ao ponto: o Codex é o "agente de programação (coding agent)" da OpenAI, capaz de ler, editar e executar código de forma autônoma, em vez de apenas retornar explicações em texto. O termo oficial o define como "OpenAI's coding agent that can read, edit, and run code".

O conceito de "Agente" é o elemento central: Agente representa uma IA capaz de planejar etapas de trabalho de forma independente, acionar ferramentas, auditar resultados e tomar decisões de passos futuros, diferenciando-se de interfaces simples de chat.

A documentação oficial resume o fluxo do Codex: "O agente executa comandos de terminal em loop. Ele edita código, roda testes e tenta validar o próprio trabalho" (original: "The agent runs terminal commands in a loop. It edits code, runs checks, and tries to validate its work").

Traduzido de forma simples, o agente repete o ciclo de pensar → agir → observar:

• Pensar: Ler arquivos mapeados, checar mensagens de erro e contextualizar a tarefa
• Agir: Alterar códigos, criar diretórios e rodar comandos de terminal
• Observar: Executar suítes de testes, analisar retornos e iniciar novas rodadas de ajustes caso identifique falhas

Analogia: um serviço de compras personalizado. Chats convencionais assemelham-se a atendentes de suporte que consultam preços — você pergunta o valor de um item, ele responde e encerra. O Codex funciona como um assistente de compras: ao pedir para "comprar um casaco preto tamanho M", ele busca lojas, compara preços, efetua o pedido e valida o tamanho na entrega, lidando com devoluções se necessário. A capacidade de conduzir o pipeline completo de forma autônoma diferencia o agente de uma caixa de chat.

Cenários reais comuns de uso:

• Ao relatar a falha de um teste, ele executa a suíte de testes → lê os erros gerados → localiza a causa raiz do bug → edita o código → roda os testes de novo para validar, enquanto você acompanha o progresso no console.
• Ao carregar um repositório legado sem documentação para "mapear a arquitetura", o agente analisa a estrutura de pastas, pesquisa palavras-chave e lê os arquivos necessários de forma autônoma para retornar um diagrama estrutural — sem exigir que você indique quais arquivos ler.
• Ao solicitar a implementação de cache em uma função, ele ajusta a declaração e atualiza as chamadas correspondentes em múltiplos arquivos, mantendo a consistência do ecossistema de software.

💡 Resumo em uma frase: O Codex atua como um agente autônomo, não como uma caixa de chat — ele executa tarefas iterando no ciclo "pensar → agir → observar", sob o mesmo princípio operacional do Claude Code, variando apenas a interface de distribuição.

---

02 Sandbox (Isolamento): Limites de atuação do agente

Este é um dos tópicos mais importantes. O isolamento de Sandbox foi a causa da falha de renomeação citada na introdução.

Sandbox: A especificação técnica define como "o limite de contenção (boundary) que permite a atuação autônoma do Codex sem expor sua máquina principal a riscos ou comandos irrestritos". Em termos simples, é um escopo delimitado — o agente executa tarefas locais de forma automatizada dentro da pasta de trabalho; para acessar recursos externos, ele exige confirmação.

Analogia: uma área de recreação infantil delimitada. A criança brinca livremente nos brinquedos internos sem exigir que você aprove cada passo; se ela tentar pular a cerca em direção ao estacionamento, o alarme soará para intervenção. O sandbox atua como essa cerca: autonomia livre na área interna protegida, exigência de aprovação manual para interagir com o ambiente externo — otimizando o fluxo de trabalho com segurança.

Essa contenção regula duas frentes básicas: escrita de arquivos locais e conexões de rede. As três opções básicas de Sandbox são:

Perfil de Sandbox	Escrita de arquivos	Conexão de rede	Cenário de uso
read-only (Apenas leitura)	❌ Negada (exige aprovação para edições)	❌ Negada	Análises estáticas de arquitetura, auditorias de código e propostas de refatorações, sem alterações de arquivos
workspace-write (Escrita no diretório)	✅ Restrita ao diretório de trabalho ativo	❌ Negada por padrão	Modo de desenvolvimento padrão; recomendado em pastas sob versionamento git; pastas comuns iniciam em read-only por segurança
danger-full-access (Acesso total)	✅ Irrestrita em todo o disco local	✅ Permitida	Ambientes totalmente isolados ou confiáveis. O identificador danger alerta para riscos reais, use com cuidado

A restrição de escrita de arquivos no diretório ativo no modo workspace-write esclarece o motivo de o Codex não ter renomeado os arquivos na minha Área de Trabalho — eles estavam fora do diretório do projeto onde inicializei a CLI, logo, fora dos limites del sandbox. O agente não tinha acesso físico a esses arquivos.

A documentação técnica destaca uma particularidade: as restrições do sandbox aplicam-se a todos os subprocessos criados pelo Codex. Comandos de terminal chamados pelo agente, como git, instalações NPM ou testes locais, herdam o mesmo escopo de contenção — mitigando falhas onde comandos filhos burlam os limites de segurança da aplicação principal.

O isolamento de sandbox consome tecnologias específicas de acordo com seu sistema operacional (detalhado no capítulo 03 Instalação e Login):

• macOS: Utiliza o framework Seatbelt nativo do sistema operacional, operacional de forma nativa sem necessidade de configurações.
• Windows: Roda diretamente na máquina principal usando o Windows Sandbox (dividido em perfis elevated e unelevated); execuções sob WSL2 consomem a infraestrutura do ecossistema Linux.
• Linux / WSL2: Exige a instalação prévia do utilitário bubblewrap no sistema para que o sandbox seja inicializado (sendo um pré-requisito explícito da documentação).

💡 Resumo em uma frase: O Sandbox é a primeira barreira do Codex — por padrão (workspace-write), a escrita limita-se ao diretório do projeto e as conexões externas são bloqueadas; expandir a área de atuação exige liberação manual de parâmetros.

---

03 Aprovações (Approval): Regulação das saídas do sandbox

Definidos os limites técnicos do sandbox, o gerenciamento de solicitações de liberação externa é tratado pelo módulo de Aprovações (Approval).

A documentação técnica detalha a distinção para evitar confusões: enquanto o sandbox delimita as restrições lógicas de sistema, a política de aprovações regula o comportamento operacional do Codex ao alcançar a fronteira da restrição, exigindo ou não a sua confirmação.

Analogia: catracas físicas e agentes de portaria. O sandbox funciona como as catracas e trincos eletrônicos (que barram fisicamente a saída); as aprovações funcionam como a postura do agente de portaria — liberando livremente os acessos (política never), auditando apenas perfis de fora (política untrusted) ou exigindo validação manual explícita para cada saída (política on-request). As portas de contenção são rígidas, mas a postura do validador pode ser regulada.

Políticas de aprovação da documentação oficial:

Política de aprovação	Comportamento do Codex	Resumo operacional
untrusted	Exige validação manual para comandos que não pertençam ao catálogo confiável	Protege contra comandos arbitrários ou desconhecidos
on-request	Execução autônoma na área segura, solicitando aprovação apenas ao cruzar a fronteira da restrição	O perfil de equilíbrio recomendado para o dia a dia
never	Execução autônoma sem emitir alertas ou solicitações	Comumente adotado em automações; as restrições físicas continuam ativas dependendo do sandbox, exigindo acesso irrestrito para fazer sentido

Observação: os perfis untrusted, on-request e never correspondem às políticas de aprovação oficiais, representando uma dimensão conceitual complementar aos modos de Sandbox, devendo ser gerenciados separadamente.

A combinação recomendada desses dois parâmetros ajuda a estruturar o fluxo de trabalho ideal:

• Desenvolvimento diário com segurança (recomendado): sandbox_mode = "workspace-write" integrado a approval_policy = "on-request". Mantém as barreiras ativas no repositório, solicitando sua aprovação apenas em saídas de escopo, otimizando o fluxo de forma segura.
• Autonomia irrestrita (usar com cautela): sandbox_mode = "danger-full-access" com approval_policy = "never". Remove as contenções físicas de sistema e as solicitações no terminal. Adote essa configuração estritamente em sandboxes de containers ou servidores isolados de testes.

Recomenda-se adotar o modo read-only (apenas leitura) ao abrir repositórios desconhecidos ou analisar legados novos, permitindo que a IA estude a arquitetura com segurança. Altere a permissão para workspace-write somente após alinhar o plano de alterações. Evite adotar o perfil de acesso irrestrito danger-full-access sem necessidade em sua máquina principal.

As permissões são gerenciáveis de forma rápida: digite /permissions na sessão ativa da CLI para alternar o status (no aplicativo desktop e IDEs, utilize o seletor visual ao lado da barra de prompts). Para persistir um perfil padrão nas sessões, edite o arquivo de inicialização local — detalhado no artigo 18 config.toml Configurações Detalhadas.

O fluxo abaixo esquematiza a interação entre os dois recursos:

O diagrama esclarece o processamento interno: a cada comando chamado pelo Codex, valida-se primeiro se a ação reside nos limites do sandbox (segurança lógica); se cruzar o escopo, a política de aprovações dita se o console exigirá ou não autorização manual do usuário.

💡 Resumo em uma frase: Sandbox controla o escopo técnico de acesso e Approval o disparo de alertas. O par workspace-write + on-request oferece o equilíbrio recomendado de segurança e usabilidade no dia a dia.

---

04 AGENTS.md: O manual técnico do projeto

Abordadas as permissões de acesso, trataremos do alinhamento operacional: como ensinar as convenções e padrões do seu repositório para o Codex, evitando explicações repetitivas a cada nova sessão.

A solução reside na criação de um arquivo chamado AGENTS.md.

Analogia: guia de onboarding de novos engenheiros. Ao receber um novo membro na equipe, você não dita as preferências de desenvolvimento todos os dias ("nossos deploys rodam com pnpm", "as mensagens de commits seguem convenções X") — você entrega o guia técnico para leitura prévia. O arquivo AGENTS.md atua como esse guia para o Codex: salvo no repositório, ele é lido automaticamente na inicialização da sessão para alinhar o agente aos padrões vigentes.

A documentação o define como "durable project guidance" (diretrizes de projeto permanentes) — um arquivo versionado com o código que alinha a atuação do assistente. Regra fundamental: mantenha-o enxuto (Keep it small), evitando documentos prolixos que inflam a janela de contexto.

Tópicos recomendados para inclusão (exemplos oficiais):

• Comandos de builds e suítes de testes (ex: "para rodar os testes, use pytest -q")
• Diretrizes de revisão de código (ex: "modificações exigem rodar o formatador/linter local")
• Convenções específicas do repositório (ex: estruturação de pastas e padrões de nomenclatura)

O arquivo pode ser estruturado em dois níveis de escopo, prevalecendo o de maior proximidade:

Escopo	Localização física	Abrangência das diretrizes
Global	~/.codex/AGENTS.md	Preferências globais do desenvolvedor (ex: "responda de forma concisa"), aplicadas a todas as sessões locais
Local do projeto	Diretório raiz ou subpastas do repositório como AGENTS.md	Convenções específicas do time e do código daquele repositório, versionado sob o git para compartilhamento

Uma estratégia recomendada na documentação consiste em adotar o arquivo como uma malha de feedback (feedback loop): se o Codex fizer suposições erradas sobre a sua base de código durante a sessão, evite corrigir apenas no histórico de chat (pois a correção se perderia no fechamento da sessão). Em vez disso, solicite ao próprio Codex que registre essa regra de correção no AGENTS.md do repositório, garantindo o alinhamento em sessões futuras. Fazer o agente registrar lições aprendidas em depurações consolida a eficiência operacional a longo prazo.

O arquivo AGENTS.md para o Codex possui a mesma finalidade prática do CLAUDE.md para o Claude Code — o mesmo conceito, com nomenclatura adaptada.

💡 Resumo em uma frase: O AGENTS.md funciona como o manual técnico do repositório — registre as diretrizes locais para o agente ler no início das sessões; use a própria IA para inserir aprendizados de erros passados no arquivo.

---

05 Memória (Memory) e Chronicle: Mecanismos de persistência do agente

Estes recursos englobam a persistência de aprendizados e dados entre sessões — como o Codex retém preferências e contextos de interações passadas.

Distinguindo os dois conceitos:

Memory: Permite que o Codex carregue informações úteis extraídas de conversas passadas para sessões futuras — como preferências de stacks tecnológicas, padrões de escrita de código do repositório ou lições aprendidas em depurações, evitando configurações repetitivas.

Analogia: o desenvolvedor parceiro de equipe. Um profissional recém-contratado exige repetições contínuas de diretrizes básicas ("nossos linter desabilita ponto e vírgula no TypeScript"). Um colega experiente do time compreende o padrão imediatamente — pois acumulou histórico das preferências de código. O Memory busca acelerar essa maturidade do agente nas interações.

Particularidades importantes sobre o funcionamento do Memory:

• Inativo por padrão (off by default). O recurso exige ativação explícita para registrar interações. Habilite nas configurações do painel visual do Codex App ou registrando memories = true no bloco [features] do arquivo global ~/.codex/config.toml.
• Restrições regionais: A documentação oficial cita bloqueios regulatórios para contas localizadas no Espaço Econômico Europeu, Reino Unido e Suíça.
• Processamento assíncrono: A compilação de preferências ocorre em segundo plano após o encerramento ou inatividade prolongada de uma sessão, evitando concorrência durante a execução de tarefas. Portanto, aprendizados de uma sessão recém-encerrada podem levar minutos para constar no banco local de memórias.
• Armazenamento local: Gravado no diretório global ~/.codex/memories/ como arquivos markdown.
• Controle individual por sessão: Use o comando /memories na CLI ou App para ativar/desativar a leitura e gravação de memórias na conversa ativa.

A documentação faz um alerta relevante: diretrizes e convenções de projeto críticas devem ser explicitamente registradas no AGENTS.md, sem depender da persistência de memória do agente. A memória atua como uma camada complementar de facilidades locais, não como um validador absoluto de regras de conformidade.

💡 Resumo em uma frase: O Memory auxilia na memorização de padrões do usuário, mas requer ativação explícita e possui restrições regulatórias locais. Mantenha as convenções críticas no AGENTS.md por segurança.

Sobre o recurso experimental Chronicle:

⚠️ Recurso experimental sob preview técnica. O Chronicle constitui uma funcionalidade sob aprovação voluntária (opt-in research preview), restrita a assinantes ChatGPT Pro utilizando o macOS, indisponível nos blocos regulatórios europeus.

O Chronicle coleta contexto diretamente da tela ativa do usuário. Enquanto a memória padrão analisa apenas os históricos de chat do terminal, o Chronicle estende a percepção da IA capturando elementos visuais da sua tela ativa (arquivos no editor, pull requests abertos no navegador ou documentações) para acelerar a inicialização do contexto, mitigando a necessidade de detalhar o cenário do erro em prompts longos.

Analogia: o colega que compartilha a tela de trabalho. Em vez de explicar o log de erro do console por voz, o parceiro acompanha sua tela e compreende a ocorrência imediatamente. O recurso traz agilidade, mas envolve concessões importantes sinalizadas na documentação: alto consumo de limite de cotas, exposição a riscos de injeções de prompt em inputs visuais e dados armazenados localmente sem criptografia nativa. Recomenda-se cautela no uso, desativando a captura (opção "Pause Chronicle" na barra de menus) ao manipular credenciais, dados pessoais ou de clientes.

Parâmetro analítico	Memory (Memória)	Chronicle
Origem dos dados de contexto	Histórico de chat de sessões anteriores	Conteúdo visual e dados da tela ativa
Estágio de maturidade	Recurso estável (desativado por padrão)	Pesquisa sob preview (experimental)
Plataformas suportadas	CLI / Desktop App / IDEs	Exclusivo para macOS (assinaturas Pro)
Recomendação de uso	Útil para agilizar parametrizações	Opcional para testes; pause em telas com dados sensíveis

💡 Resumo em uma frase: O Memory consolida o histórico de interações para otimizar prompts subsequentes (inativo por padrão), sem substituir as diretrizes explícitas do AGENTS.md; o Chronicle atua capturando a tela ativa de forma experimental, trazendo agilidade com riscos de segurança associados.

---

O esquema abaixo resume a interação estrutural entre eles no ambiente de execução:

O diagrama esclarece o processamento interno: o Agente atua no centro como o executor principal, contido nos limites rígidos do Sandbox; acessos externos de arquivos ou conexões exigem a validação do módulo de Aprovações (Approval). O arquivo AGENTS.md fornece as regras do repositório na inicialização, enquanto as camadas de Memory e Chronicle persistem dados de sessões passadas. Todos os recursos orbitam em torno da inteligência do agente.

---

06 Prática: Visualizando a contenção do sandbox

A melhor fixação é prática. Faremos um experimento rápido para observar a atuação do sandbox no modo read-only bloqueando a gravação de um arquivo local. O processo exige apenas um diretório temporário no terminal.

Passo 1: Crie o diretório de testes e inicialize o Codex

Rode no terminal (no Windows PowerShell, adapte mkdir -p para mkdir se necessário):

mkdir -p ~/codex-demo && cd ~/codex-demo
codex

Caso ainda não possua o Codex instalado, conclua as etapas de configuração do capítulo 03 Instalação e Login antes de realizar este teste.

Passo 2: Mude a sessão para o perfil de apenas leitura (read-only)

Envie o comando de barra na CLI para regular as permissões:

/permissions

Selecione a opção de apenas leitura (Read Only) no seletor. Saída esperada: O console registrará a alteração del perfil:

Permissions updated: read-only

⚠️ Nota para versões recentes da CLI: A partir da versão 0.142 do codex-cli, a plataforma introduziu perfis de permissão (permission profiles) (recurso sob Beta sujeito a alterações), substituindo os botões "Read Only / Auto / Full Access". O menu do /permissions pode exibir opções de políticas como Ask for approval / Approval for me / Full access.

Se a opção Read Only não for exibida, utilize o parâmetro legado na inicialização para forçar o isolamento: encerre a CLI e reinicie com codex --sandbox read-only, ou registre sandbox_mode = "read-only" no arquivo global ~/.codex/config.toml.

Passo 3: Solicite a criação de um arquivo local e observe o bloqueio

Envie o seguinte prompt de teste:

帮我新建一个文件 hello.txt，里面写一行字 "hello codex"。

Saída esperada: O agente interromperá a execução antes de criar o arquivo, solicitando autorização manual no terminal — já que operações de gravação de arquivos violam a restrição read-only ativa, exigindo validação pela política de aprovações. A mensagem seguirá o formato:

I need to write to hello.txt, which is outside the current read-only sandbox.
Allow this action? (y/N)

Esse alerta de autorização confirma o funcionamento conjunto do Sandbox e das Aprovações: o sandbox identificou que a escrita excede os limites de segurança configurados, e o módulo de aprovação suspendeu o pipeline interativo aguardando a confirmação do desenvolvedor no terminal. Este é o comportamento prático abordado nas seções anteriores.

Passo 4: Compare o comportamento liberando a escrita

Mude a permissão com /permissions para workspace-write e solicite a gravação do arquivo novamente. Saída esperada: O arquivo hello.txt será criado de forma direta, sem emitir solicitações de confirmação — uma vez que modificações no diretório de trabalho residem nos limites seguros del sandbox local.

File hello.txt created successfully.

Execute o comando /status ao final para verificar as credenciais e as políticas ativas na sessão:

/status

A mesma solicitação de gravação de arquivo foi bloqueada em modo read-only e executada livremente sob permissão de escrita — demonstrando a diferença dos perfis de sandbox. Visualizar o bloqueio e a solicitação no terminal confirma o entendimento sobre os escopos de segurança da ferramenta.

💡 Resumo em uma frase: A prática demonstra que o sandbox atua restringindo as chamadas e o módulo de aprovação gerenciando os alertas, permitindo ou barrando edições com base nas regras ativas.

---

07 Resumo

Este capítulo consolidou os pilares operacionais do Codex:

Conceito técnico	Definição resumida	Equivalência no Claude Code
Agente (Agent)	IA autônoma operando sob o ciclo pensar → agir → observar, além de chats convencionais	Loop de agente (idêntico)
Sandbox (Isolamento)	Limite técnico de acessos a arquivos locais e rede	Restrições de permissões (mais explícito)
Aprovação (Approval)	Controle interativo de solicitações ao cruzar escopos do sandbox	Modos de permissão e confirmação
AGENTS.md	Manual técnico de convenções do repositório lido na inicialização	CLAUDE.md (idêntico, com alteração de nomenclatura)
Memory / Chronicle	Persistência de preferências; Chronicle captura telas ativas (experimental)	Memory e histórico de contextos local

Agora você compreende os motivos de edições de arquivos serem bloqueadas (limites do sandbox), as razões de interrupções de pipelines para autorização manual (módulo de aprovação) e a importância de usar o AGENTS.md para firmar regras no repositório.

Conceito principal a reter: O Codex não é um poço de desejos automático, mas um desenvolvedor assistente sênior operando sob diretrizes lógicas estruturadas — sua função consiste em guiar o escopo, regular os limites seguros da mesa de trabalho e validar as entregas. Dominar essas bases simplificará a configuração das interfaces e parâmetros abordados nos próximos artigos.

---

O próximo artigo 03 · Instalação e Login guiará o processo prático de configuração do Codex em sua máquina Windows, macOS ou Linux, cobrando as etapas de login de contas e testes iniciais de comandos CLI — incluindo a instalação do pacote bubblewrap requerido para a inicialização del sandbox em ambientes Linux.

---

Leituras Recomendadas

• Apresentando o Codex e as Quatro Interfaces
• Conectando Modelos Nacionais e o DeepSeek
• Boas Práticas: Diretrizes reais aplicadas ao desenvolvimento