Guia de Configuração config.toml: Centralizando o controle em um único arquivo
📚 Navegação da Série: Anterior 17 · Controle de computador e navegador (Computer Use) deu ao Codex as mãos — permitindo ver a tela, interagir com o desktop e abrir o navegador. Esta parte retorna dos elementos gráficos para um arquivo de texto simples — o
config.toml. Mapeamos suas aparições anteriores em seções sobre sandboxes, memories e escolha de modelos; esta seção apresenta o arquivo de forma estruturada: onde salvá-lo, suas propriedades, o papel de cada chave e as regras de prioridade entre arquivos de configuração.
Dizem que arquivos de configuração são coisas para se 'ajustar depois de instalar' e que, se estiver rodando, é melhor não mexer — para ser sincero, no caso do Codex essa regra aplica-se de forma inversa.
Minha própria experiência: em março de 2026, quando comecei a usar o Codex, eu não havia alterado o arquivo config.toml. A cada nova conversa, eu precisava rodar /model para trocar o modelo, /permissions para ajustar privilégios e --search para permitir rede. Eu repetia esse conjunto de ações várias vezes ao dia. Percebi que fiz dezenas de ajustes repetidos em apenas uma semana. Foi então que notei a ineficiência: eu estava configurando manualmente o tempo todo um comportamento que poderia ser definido uma única vez de forma permanente.
A utilidade do config.toml é justamente essa — economizar tempo e evitar configurações repetitivas para todos os usuários. Vale a pena dedicar alguns minutos para estruturá-lo.
Além disso, há um detalhe importante sobre o escopo de atuação que costuma confundir iniciantes: definir uma propriedade no diretório principal do sistema ou dentro da pasta do projeto traz comportamentos diferentes, e em alguns casos a configuração local pode ser ignorada. Esta parte detalha as regras de prioridade e restrições para que você configure com confiança.
Ao ler esta parte, você obterá:
- A definição do
config.tomle sua separação de responsabilidades em relação aoAGENTS.md(evitando confusões) - Onde salvar e o que incluir nas configurações global (
~/.codex/config.toml) e local do projeto (.codex/config.toml) - A tabela de prioridade entre os arquivos e uma restrição de segurança importante (algumas chaves são ignoradas no arquivo local do projeto)
- O papel e valores padrão das principais chaves de configuração (
model,approval_policy,sandbox_mode,web_search,[features]...) - Exemplos de configuração padrão prontos para copiar, como rodar substituições temporárias com
-ce alternar grupos de opções com--profile
01 O que é o config.toml e qual sua divisão com o AGENTS.md
O config.toml funciona como a central de parâmetros de execução do Codex — mapeando em formato TOML definições de modelos, restrições de sandbox, políticas de aprovação, conectores MCP e chaves de funcionalidades. Ele difere do AGENTS.md, que serve para guardar contextos e dados do projeto, e não parâmetros de execução.
É comum haver confusão entre as duas ferramentas. Na seção 11, você utilizou o 11 · AGENTS.md para salvar descrições e diretrizes do repositório; e na seção 15, ajustou regras de sandbox. As diretrizes do projeto residem no AGENTS.md, e os parâmetros do sandbox no config.toml.
Analogia: O manual do motorista vs. os botões do painel do carro. O AGENTS.md é como o manual no porta-luvas — contendo informações descritas em linguagem natural como 'use combustível aditivado' ou 'verifique a pressão dos pneus antes de viajar' (dados consumidos pelo Codex como contexto geral). O config.toml funciona como os botões no painel — definindo a temperatura do ar-condicionado, ativação do aquecedor ou modo de condução (parâmetros técnicos que o software lê e aplica diretamente). O manual orienta o comportamento, o painel muda o funcionamento técnico.
O arquivo adota o formato TOML (Tom's Obvious Minimal Language), simples de ler e escrever. A estrutura básica agrupa chaves sob cabeçalhos de tabelas [tabela]:
# ~/.codex/config.toml
model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"A documentação oficial define a localização padrão:
O Codex armazena as configurações globais de usuário no caminho
~/.codex/config.toml.
Mapeando chaves comuns no arquivo:
- Selecionar o modelo padrão: use a chave
model - Definir regras de sandbox e aprovações padrão: use
sandbox_modeeapproval_policy - Configurar a busca web como em tempo real: use
web_search - Habilitar ou desativar recursos específicos: use a tabela
[features]
Essas opções alteram as regras de funcionamento do agente, separando as configurações do config.toml dos dados de contexto do AGENTS.md.
💡 Resumo em uma frase: O
AGENTS.mdguarda instruções em linguagem natural para guiar o Codex, enquanto oconfig.tomldefine os parâmetros de funcionamento técnico do software, separando contexto de execução.
02 Localização dos arquivos: Global e Local do Projeto
Existem dois níveis de configuração para o config.toml: o arquivo global no diretório de usuário do sistema e o arquivo local salvo na pasta do projeto.
Analogia: O disjuntor geral da casa vs. os interruptores nos cômodos. O disjuntor geral (configuração global) define as regras elétricas de toda a casa. O interruptor do quarto (configuração local do projeto) tem prioridade sobre aquele cômodo — permitindo ligar a lâmpada local sem interferir no resto da casa. O disjuntor define a regra geral, o interruptor local aplica o ajuste específico.
Mapeamento dos níveis de configuração:
| Nível | Caminho do arquivo | Escopo de atuação | Configuração recomendada | Regra de ativação |
|---|---|---|---|---|
| Global (User) | ~/.codex/config.toml | Aplica-se a todos os seus projetos | Modelo de uso comum, políticas de aprovação gerais, conectores MCP, notificações | Ativo por padrão |
| Local (Project) | <projeto>/.codex/config.toml | Aplica-se apenas ao repositório ativo | Modelo específico do projeto, restrições locais de sandbox | Mapeado apenas se o projeto for confiável |
Alguns pontos importantes a serem considerados:
1. O caminho do arquivo global é fixo em ~/.codex/config.toml. A pasta ~/.codex (conhecida como CODEX_HOME) concentra os arquivos de credenciais, históricos de comandos, logs e preferências gerais do Codex. Se o arquivo não existir, crie-o manualmente.
2. O arquivo local do projeto deve residir na subpasta .codex/ do repositório (usando o caminho .codex/config.toml, com ponto no nome da pasta para mantê-la oculta). As regras serão aplicadas apenas quando você atuar dentro do diretório do projeto.
3. Configurações locais só são carregadas se o projeto for marcado como confiável. Essa regra impede que repositórios baixados da internet alterem privilégios de execução em sua máquina sem autorização. A documentação confirma:
Caso um projeto seja marcado como não confiável (untrusted), o Codex ignorará a pasta local
.codex/, incluindo configurações, hooks e regras locais.
Se o arquivo .codex/config.toml não surtir efeito, confirme se o projeto foi marcado como confiável (solicitado no primeiro acesso ao repositório).
Como organizar as chaves nos arquivos
Para definir onde salvar uma configuração, faça a pergunta: esta regra vale para todas as tarefas em minha máquina ou é específica deste repositório?
- Uso geral em toda a máquina → Arquivo Global (
~/.codex/config.toml). Ex: preferências de modelo padrão comogpt-5.5, integrações de MCPs locais e notificações. - Uso exclusivo do repositório → Arquivo Local (
<projeto>/.codex/config.toml). Ex: exigir sandbox de apenas leitura para um projeto legada ou especificar um modelo de dados customizado.
Minha prática: mantenho as chaves no arquivo global, deixando o arquivo local do projeto limpo por padrão. Utilizo arquivos locais apenas para cenários específicos (ex: repositórios de auditoria de código onde configuro sandbox_mode = "read-only" para garantir segurança). Isso evita misturar políticas restritivas com o uso diário.
💡 Resumo em uma frase: O arquivo global em
~/.codex/config.tomlmapeia suas preferências em toda a máquina, enquanto o arquivo local em<projeto>/.codex/config.tomlrestringe regras do repositório (exigindo que o projeto seja confiável para carregar).
03 Prioridades de carregamento e restrições de segurança
Se o mesmo parâmetro for definido em múltiplos locais (ex: modelo padrão diferente no arquivo global e no projeto), o Codex aplica regras de prioridade para decidir qual valor adotar.
Ao todo, a prioridade divide-se em seis níveis, do mais prioritário ao menos prioritário:
| Prioridade | Origem do parâmetro | Comportamento |
|---|---|---|
| 1 (Maior) | Parâmetro de linha de comando / --config | Ajuste temporário passado no terminal, válido para a chamada ativa |
| 2 | Arquivo local do projeto (<projeto>/.codex/config.toml) | Configuração local do repositório (se marcado como confiável; prevalece o arquivo mais próximo à pasta ativa) |
| 3 | Perfil de configuração ativo (--profile) | Parâmetros do perfil customizado chamado via CLI |
| 4 | Arquivo global (~/.codex/config.toml) | Preferências de usuário salvas no diretório global |
| 5 | Arquivo do sistema (/etc/codex/config.toml no Unix) | Definições globais aplicadas pelos administradores da máquina |
| 6 (Menor) | Valores internos padrões (default) | Configurações nativas do software |
A imagem abaixo ilustra a hierarquia de carregamento:
Ela demonstra que parâmetros de nível superior sobrepõem definições equivalentes em camadas inferiores, priorizando ajustes específicos (como chamadas de terminal) em relação a políticas globais.
O uso desse empilhamento é simples:
Adote a hierarquia para manter os parâmetros compartilhados no arquivo global
config.tomle utilize arquivos locais ou perfis apenas para especificar valores divergentes.
Mantenha chaves genéricas no arquivo global, use perfis para variações de tarefas e parâmetros na CLI para testes rápidos.
Restrição de segurança: chaves bloqueadas no arquivo local do projeto
Embora as configurações locais tenham prioridade sobre o arquivo global, algumas chaves críticas são ignoradas no arquivo local do projeto por motivos de segurança, gerando avisos no terminal.
Essa trava impede que projetos maliciosos baixados da internet alterem endpoints de conexões de API, scripts de notificações locais ou rotinas de auditoria ao carregar o diretório. A documentação lista as chaves bloqueadas localmente:
O Codex ignora as chaves
openai_base_url,chatgpt_base_url,apps_mcp_product_sku,model_provider,model_providers,notify,profile,profiles,experimental_realtime_ws_base_urleotelquando inseridas no arquivo local.codex/config.toml.
Veja o papel dessas chaves restringidas ao arquivo global:
| Chave | Função | Motivo do bloqueio local |
|---|---|---|
model_provider / model_providers | Endereços e provedores das APIs de LLM | Impede o redirecionamento de chamadas para servidores não autorizados |
openai_base_url / chatgpt_base_url | Endpoints base dos serviços de API | Evita o desvio de credenciais ou dados do usuário |
notify | Comandos de shell executados ao finalizar tarefas | Impede a execução de scripts arbitrários no sistema do usuário |
otel | Configuração de telemetria e rastreamento de dados | Evita a extração e envio de dados de telemetria para destinos desconhecidos |
profile / profiles | Seleção e definição de perfis de configuração | A seleção de perfis deve ser feita pelo usuário na inicialização |
Mapeie chaves que lidam com provedores de rede, segurança, integrações e notificações no arquivo global; salve no arquivo do projeto apenas parâmetros locais como model, sandbox_mode ou approval_policy. Chaves bloqueadas inseridas no arquivo do projeto serão desconsideradas.
💡 Resumo em uma frase: A prioridade segue a ordem Linha de Comando > Projeto Local > Perfis > Global > Sistema; chaves sensíveis como provedores de API (
model_providers) ou rotinas de notificação (notify) são aceitas apenas no arquivo global.
04 Chaves de Configuração mais comuns
Esta seção apresenta as chaves utilizadas com maior frequência no config.toml, seus valores e comportamentos padrão.
| Chave | Função | Valor Padrão | Exemplo de uso |
|---|---|---|---|
model | Define o modelo de linguagem padrão | Valor padrão do software | model = "gpt-5.5" |
approval_policy | Estratégia para solicitação de aprovação | on-request | approval_policy = "on-request" |
sandbox_mode | Configuração do sandbox de escrita e rede | workspace-write (em pastas com Git) | sandbox_mode = "workspace-write" |
model_reasoning_effort | Nível de esforço de raciocínio do modelo | Padrão do modelo ativo | model_reasoning_effort = "high" |
web_search | Configuração da pesquisa web | cached (pesquisa indexada) | web_search = "live" |
personality | Estilo de conversação do agente | friendly (amigável) | personality = "pragmatic" |
file_opener | Editor de texto para links de arquivos | vscode | file_opener = "cursor" |
Nota sobre o sandbox padrão: a inicialização padrão (
codexsem parâmetros) aplica regras inteligentes — pastas com Git utilizam o modoworkspace-writepor padrão, enquanto pastas sem Git iniciam no modo apenas leitura (read-only). A documentação citaworkspace-writecomo a política padrão por ser o cenário de uso mais frequente (projetos versionados).
Detalhes sobre o funcionamento das chaves:
model / model_reasoning_effort / approval_policy / sandbox_mode
Estas chaves definem o comportamento do modelo, regras de escrita e confirmações, descritas detalhadamente nas seções 05 e 15. Inseri-las no config.toml evita ter que declará-las em todas as inicializações.
O esforço de raciocínio (model_reasoning_effort) aceita as opções minimal | low | medium | high | xhigh (dependendo do suporte do modelo). Mantenha valores menores para tarefas rápidas e aumente para auditorias complexas.
web_search: busca web em cache ou tempo real
Por motivos de segurança, a pesquisa web padrão utiliza o índice de cache (cached) da OpenAI em vez de realizar buscas ao vivo. Isso reduz o risco de injeções de instruções contidas em páginas ativas.
Para forçar buscas em tempo real, altere a chave:
web_search = "live" # Busca em tempo real na internet (parâmetro --search)
# web_search = "cached" # Padrão: busca indexada
# web_search = "disabled" # Desativa a ferramenta de busca webSe o sandbox de acesso total for habilitado (modo --yolo), a busca web passa para o modo em tempo real (live) automaticamente.
personality: estilo de resposta
Mapeia a comunicação do agente. Aceita os valores none | friendly | pragmatic. A opção pragmatic fornece respostas curtas e objetivas, recomendada para desenvolvedores experientes.
file_opener: redirecionamento de arquivos
Define o destino ao clicar em links de arquivos no terminal (ex: main.py:10). Aceita valores como vscode | vscode-insiders | windsurf | cursor | none. Ajustar para cursor direciona os cliques diretamente ao editor Cursor.
Regra de escrita TOML: chaves globais no início
Um erro comum na sintaxe TOML é misturar chaves gerais após a declaração de tabelas. Chaves avulsas (sem colchetes) devem ser inseridas no início do arquivo, antes de qualquer marcação de [tabela].
# EXEMPLO CORRETO
model = "gpt-5.5"
approval_policy = "on-request"
[features]
memories = trueMisturar chaves gerais após declarar [features] gera falhas de leitura no parser do TOML.
💡 Resumo em uma frase: Chaves comuns como
model,sandbox_modeouweb_search(que usa cache por padrão) definem o comportamento do agente; declare as chaves gerais no início do arquivo antes das marcações de tabelas.
05 Tabela [features]: Chaves de recursos opcionais
A tabela [features] agrupa os botões de ativação de recursos experimentais ou secundários do Codex (como memórias, hooks locais e subagentes).
Analogia: Recursos experimentais nas configurações de um smartphone. Funções estáveis vêm ativas por padrão, mas você pode habilitar ou desativar opções na aba experimental do sistema. A tabela [features] funciona de forma idêntica: adicione valores booleanos (true ou false) para alterar o comportamento de recursos específicos.
A sintaxe declara a tabela e os recursos desejados:
[features]
memories = true # Habilita a memória persistente
shell_snapshot = true # Habilita snapshots do terminal para acelerar comandos
hooks = false # Desativa os hooks do ciclo de vidaValores padrão dos recursos comuns (sujeitos a alterações do software):
| Recurso | Valor Padrão | Classificação | Função |
|---|---|---|---|
hooks | true | Estável | Scripts disparados por eventos locais (hooks) |
multi_agent | true | Estável | Controle de subagentes em paralelo |
shell_snapshot | true | Estável | Histórico do terminal para aceleração de respostas |
fast_mode | true | Estável | Respostas rápidas na CLI |
shell_tool | true | Estável | Execução de comandos no shell |
personality | true | Estável | Suporte a estilos de conversação |
memories | false | Estável | Para habilitar memórias (memories), use o valor true |
codex_git_commit | false | Experimental | Sugestão automática de mensagens de commit |
apps | false | Experimental | Suporte a conectores de ChatGPT Apps |
⚠️ Recursos experimentais sob constantes atualizações. A nomenclatura e valores padrão de opções experimentais dependem da versão instalada; verifique as opções da CLI antes de utilizá-las.
Evite habilitar recursos antigos com nomes obsoletos (ex: usar codex_hooks = true em vez da chave padrão hooks). Mapeie os recursos usando os parâmetros oficiais.
Formas de alterar recursos:
- No arquivo
config.tomlusando booleanos na tabela[features]; - Temporariamente na inicialização via
--enable <recurso>no terminal; - Desativando recursos definindo-os como
falsena tabela.
Nossa recomendação: mantenha as opções padrões ativas e habilite apenas recursos com utilidade confirmada (como memórias com memories = true).
💡 Resumo em uma frase: A tabela
[features]reúne botões para recursos experimentais ou secundários; as propriedades estáveis (hooks,multi_agent) vêm ativas por padrão, enquanto memórias (memories) e integrações experimentais vêm desativadas.
06 Modificações dinâmicas e perfis customizados: -c e --profile
Para cenários que exigem alterar parâmetros sem modificar o arquivo de configuração, utilize as opções de linha de comando.
Alteração pontual: -c / --config
Permite sobrescrever valores de chaves para a sessão ativa sem alterar o arquivo salvo. Exemplos:
# Para chaves com flags dedicadas
codex --model gpt-5.4
# Para chaves sem flags dedicadas (sintaxe TOML no valor)
codex --config model='"gpt-5.4"'
codex -c log_dir=./.codex-logRegras de sintaxe importantes:
- O parâmetro
-cinterpreta o valor como TOML. Valores de texto (strings) exigem aspas duplas no valor (ex:'"gpt-5.4"'com aspas simples externas para o shell e internas duplas para o TOML); - Parâmetros aninhados usam ponto para demarcação:
codex -c mcp_servers.context7.enabled=false.
Útil para testar modelos ou caminhos de forma rápida antes de salvá-los nas configurações.
Perfis customizados: --profile
Permite criar arquivos de configuração específicos para diferentes tipos de trabalho (ex: desenvolvimento rápido ou auditoria avançada). Os perfis são salvos no diretório global como arquivos independentes com a extensão .config.toml:
# ~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"E chamados na inicialização com --profile:
codex --profile deep-reviewO perfil estende a configuração global config.toml, aplicando as chaves específicas que diferem do padrão. Salve apenas as chaves divergentes no arquivo do perfil.
⚠️ Mudança de comportamento a partir do Codex 0.134.0. O parâmetro
--profilenão consome mais definições aninhadas como[profiles.nome]ou a chaveprofile = "nome"dentro doconfig.tomlgeral. Perfis devem ser mantidos como arquivos independentes com o padrão<nome>.config.tomlna pasta global. Valide o comportamento de acordo com sua versão instalada.
💡 Resumo em uma frase: Modificações temporárias usam
-c chave=valorno terminal, e agrupamento de opções usam arquivos de perfis<nome>.config.tomlchamados por--profile.
07 Laboratório: Criando, alterando e aplicando perfis
Vamos realizar um teste prático de criação e validação de configurações para entender a prioridade das chaves. O laboratório não requer projetos complexos.
Passo 1: Localizar a pasta de configuração.
Confirme a presença do diretório global no terminal:
ls -la ~/.codex/config.tomlCaso o arquivo não exista, prossiga para a criação.
Passo 2: Criar o arquivo global inicial.
Salve as seguintes definições no caminho ~/.codex/config.toml (organizando chaves gerais no início):
# ~/.codex/config.toml
model = "gpt-5.5"
approval_policy = "on-request"
web_search = "cached"
[features]
memories = falsePasso 3: Confirmar o carregamento.
Inicie o terminal do Codex:
codexE verifique o status:
/statusResultado esperado: exibição do modelo gpt-5.5 e política on-request, indicando que o arquivo global foi carregado.
Passo 4: Realizar uma substituição temporária.
Saia do terminal e reinicie o Codex forçando a busca web ativa via linha de comando:
codex -c web_search='"live"'Cheque o status com /status na conversa.
Resultado esperado: a busca web exibirá o estado live temporariamente, mas o arquivo original config.toml permanecerá intocado com cached no próximo carregamento padrão.
Passo 5: Criar e chamar um perfil customizado.
Crie o arquivo de perfil ~/.codex/quick.config.toml com chaves restritivas:
# ~/.codex/quick.config.toml
model = "gpt-5.5"
sandbox_mode = "read-only"
approval_policy = "untrusted"E chame o perfil no terminal:
codex --profile quickExecute /status para verificar. Resultado esperado: o sandbox passará para read-only e aprovação para untrusted conforme definido no arquivo do perfil, mostrando a sobreposição de configurações.
Esse laboratório valida as etapas de carregamento de arquivos e a sintaxe TOML.
💡 Resumo em uma frase: O laboratório prático demonstra o fluxo de leitura do config global, a aplicação de regras temporárias com
-ce o carregamento de perfis restritivos com--profilede forma direta.
08 Resumo
Esta seção detalhou a parametrização do Codex por meio do arquivo config.toml.
Regras consolidadas:
| Objetivo | Diretriz | Ponto de Atenção |
|---|---|---|
| Separar configurações | config.toml vs AGENTS.md | config.toml define chaves de execução; AGENTS.md guarda contextos em linguagem natural |
| Definir escopos | Global vs Local do Projeto | Global em ~/.codex vale para a máquina; local .codex/config.toml restringe o projeto confiável |
| Mapear prioridades | Linha de Comando > Projeto > Perfis > Global | Chaves de privilégios como model_providersounotify são bloqueadas no escopo do projeto |
| Parâmetros comuns | model / sandbox_mode / web_search | A busca web vem configurada como cached por padrão; chaves TOML gerais devem vir no início |
| Habilitar recursos | Tabela [features] | Controla funcionalidades como memories ou hooks locais |
| Ajustes rápidos | Flags -c e --profile | Permite sobrepor parâmetros temporariamente ou chamar conjuntos de regras customizadas |
A partir de agora, você compreende: o papel do config.toml e sua separação do AGENTS.md, onde salvar configurações locais e globais, a hierarquia de carregamento e as restrições de chaves locais, além de parametrizar as chaves de uso diário e perfis de execução. A estruturação dessas chaves automatiza as preferências do agente.
A próxima seção 19 · Sistema de memórias (Memories e Chronicle) — detalhará o funcionamento da memória do agente: como o Codex pode reter informações de conversas anteriores para ajustar suas respostas futuras? Como gerenciar as memórias salvas no Chronicle e limpar registros antigos? Definidas as regras de configuração, analisaremos como o Codex constrói seu histórico de uso.