Por Que Sua Config do Codex Não Está Funcionando: O Problema da Pasta .codex/

Minha config do Codex simplesmente não aplicava. Editei o config.toml, adicionei regras no AGENTS.md, li a documentação duas vezes. Nada mudava. O agente continuava ignorando tudo.

Acabei desmontando a estrutura de pastas inteira. O problema não era o que eu escrevia nos arquivos. Era onde esses arquivos estavam.

Dois objetivos no mesmo repositório

O Codex está tentando resolver duas coisas ao mesmo tempo. Uma é a experimentação rápida com seus próprios recursos beta. A outra é a compatibilidade entre agentes, um padrão compartilhado que ferramentas como Claude Code ou OpenCode também conseguem ler.

Essa divisão gera duas pastas.

.codex/ é o espaço de configuração exclusivo do Codex. Políticas de sandbox, regras de aprovação e guardrails de runtime ficam aqui. .agents/ é o formato compartilhado. Skills, plugins e o registro do marketplace vivem nesse lado, legíveis por qualquer agente que siga o padrão.

No começo eu não sabia dessa separação. Coloquei um arquivo SKILL.md dentro de .codex/ e a skill nunca carregou. Mover para .agents/skills/ resolveu na hora. A fronteira é rígida: se outro agente precisa conseguir ler, o arquivo pertence a .agents/. Todo o resto vai em .codex/.

As duas pastas recebem proteção de somente leitura no modo workspace-write, igual ao .git/.

Config de projeto e config de usuário têm o mesmo nome

Existe um .codex/ na raiz do seu projeto e um ~/.codex/ no seu diretório home. Eles fazem coisas completamente diferentes.

O .codex/ do projeto guarda configurações que você compartilha com o time: políticas de sandbox, fluxos de aprovação, definições de agentes. O ~/.codex/ guarda estado pessoal: tokens de auth, histórico de comandos, arquivos de gerenciamento de worktree.

Criei um agente revisor em ~/.codex/agents/ e fiquei sem entender por que meus colegas não tinham acesso. O arquivo só existia na minha máquina. Mover para .codex/agents/reviewer.toml dentro do projeto fez com que ele viajasse junto com o repositório no clone.

A confusão piora porque o Codex ainda está em beta. Arquivos de worktree do app desktop, dados de sessão e credenciais de auth se acumulam todos em ~/.codex/ sem separação clara. A fronteira entre “minha configuração” e “configuração do projeto” fica mais nebulosa do que deveria.

A prioridade de configuração segue uma ordem específica: managed config tem precedência sobre session overrides, que têm precedência sobre user config. Quando algo não está aplicando, verifique em qual nível você está editando.

O nível de confiança é a barreira real

É aqui que a maioria das pessoas trava, e eu perdi tempo real nisso antes de entender o motivo.

O Codex não carrega o .codex/ do projeto a partir de repositórios não confiáveis. De jeito nenhum. Você pode editar o config.toml à vontade num repo recém-clonado e nada vai aplicar. O arquivo está lá, a sintaxe está correta e o Codex silenciosamente ignora tudo.

O motivo faz sentido quando você entende. .agents/ abre um caminho para skills externas fluírem para o seu ambiente. Qualquer repositório poderia trazer uma config maliciosa. Então o Codex fez essa troca: maior compatibilidade com o ecossistema de agentes, mas verificação de confiança mais rigorosa para configurações fornecidas pelo repositório. Você precisa marcar explicitamente um projeto como confiável antes de a config .codex/ dele ser ativada.

Configure projects.<path>.trust_level = "trusted" no seu user config. O acesso à rede também é bloqueado por padrão, com a busca na web oferecendo três modos: cached, live ou disabled. Mesmo no modo workspace-write, .git/ e .codex/ continuam protegidos contra escrita.

Passei cerca de uma hora editando um config.toml de projeto que estava sendo completamente ignorado porque não tinha definido o trust level. Sem mensagem de erro, sem aviso. Só silêncio. Provavelmente é a fonte de frustração mais comum na configuração do Codex, e mensagens de erro melhores aqui economizariam bastante tempo de muita gente.

A complexidade não é por acaso

A estrutura de pastas é confusa, mas não de forma aleatória. O Codex está perseguindo dois objetivos que puxam em direções opostas.

Iteração rápida em beta significa que .codex/ acumula arquivos de config, definições de regras, hooks e artefatos de gerenciamento de aplicativo num ritmo que supera a documentação. Compatibilidade entre agentes significa que .agents/ precisa de uma estrutura separada e portável para skills e conteúdo do marketplace. E como .agents/ abre a porta para código externo, a camada de verificação de confiança precisou existir.

Quando estiver em dúvida sobre onde colocar um arquivo, faça uma pergunta: isso é específico do Codex ou outros agentes também precisam ler? A primeira resposta aponta para .codex/. A segunda aponta para .agents/.

Quando sua config não está funcionando, não comece editando o conteúdo dos arquivos. Verifique em qual pasta o arquivo está e se o repositório é confiável. É aí que o problema quase sempre está.