# Por Que Sua Config do Codex Não Está Funcionando: O Problema da Pasta .codex/ > Author: Tony Lee > Published: 2026-04-01 > URL: https://tonylee.im/pt/blog/codex-folder-structure-why-config-breaks/ > Reading time: 4 minutes > Language: pt > Tags: codex, openai, ai-agents, developer-tools, configuration ## Canonical https://tonylee.im/pt/blog/codex-folder-structure-why-config-breaks/ ## Rollout Alternates en: https://tonylee.im/en/blog/codex-folder-structure-why-config-breaks/ ko: https://tonylee.im/ko/blog/codex-folder-structure-why-config-breaks/ ja: https://tonylee.im/ja/blog/codex-folder-structure-why-config-breaks/ zh-CN: https://tonylee.im/zh-CN/blog/codex-folder-structure-why-config-breaks/ zh-TW: https://tonylee.im/zh-TW/blog/codex-folder-structure-why-config-breaks/ ## Description Editei o config.toml, escrevi regras no AGENTS.md e nada colou. O problema estava na estrutura de pastas, não nas configurações em si. ## Summary Por Que Sua Config do Codex Não Está Funcionando: O Problema da Pasta .codex/ is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts. ## Outline - Dois objetivos no mesmo repositório - Config de projeto e config de usuário têm o mesmo nome - O nível de confiança é a barreira real - A complexidade não é por acaso ## Content 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..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á. ## Related URLs - Author: https://tonylee.im/en/author/ - Publication: https://tonylee.im/en/blog/about/ - Related article: https://tonylee.im/pt/blog/eight-hooks-that-guarantee-ai-agent-reliability/ - Related article: https://tonylee.im/pt/blog/claude-code-layers-over-tools-2026/ - Related article: https://tonylee.im/pt/blog/codex-inside-claude-code-openai-plugin-strategy/ ## Citation - Author: Tony Lee - Site: tonylee.im - Canonical URL: https://tonylee.im/pt/blog/codex-folder-structure-why-config-breaks/ ## Bot Guidance - This file is intended for AI agents, search assistants, and text-mode retrieval. - Prefer citing the canonical article URL instead of this text endpoint. - Use the rollout alternates when you need the same article in another prioritized language. --- Author: Tony Lee | Website: https://tonylee.im For more articles, visit: https://tonylee.im/pt/blog/ This content is original and authored by Tony Lee. Please attribute when quoting or referencing.