Como configurar o config.toml do Codex CLI: modelo, perfis e aprovação

Ilustração de um arquivo config.toml com seções de modelo e perfis do Codex CLI
Resposta rápida

O Codex CLI lê a configuração persistente de ~/.codex/config.toml, e cada repositório pode ter um .codex/config.toml próprio, que só vale em projeto confiável. Perfis nomeados ficam em arquivos separados, como ~/.codex/review.config.toml, e são ativados com codex --profile review. Flags como --sandbox e --config ganham de qualquer arquivo, e o comando /status confirma o que está ativo na sessão.

Este guia é para quem já tem o Codex rodando e cansou de passar as mesmas flags toda vez que abre o terminal. Se você ainda não chegou nesse ponto, comece pelo guia de instalação do Codex CLI e volte aqui depois.

A ideia é montar três coisas: uma config base com o modelo padrão, dois perfis (um de revisão somente leitura e um de edição no workspace) e uma config por projeto. No fim você confere tudo dentro da sessão, sem achismo.

O que você precisa antes de editar o config.toml

Você precisa de três coisas antes de mexer em qualquer arquivo:

  • Codex CLI instalado e autenticado. Sem isso não tem sessão para conferir a configuração.
  • Acesso à pasta ~/.codex/ e um editor de texto. O arquivo é TOML puro, então qualquer editor resolve.
  • Um repositório marcado como confiável no Codex, se você quiser usar config por projeto. Em projeto não confiável, o Codex ignora a pasta .codex/ do repositório.

Se você nunca viu TOML, é bem parecido com um .ini: pares chave = "valor" e tabelas que agrupam chaves relacionadas, como a sandbox_workspace_write que aparece mais abaixo.

Passo a passo para configurar o config.toml do Codex CLI

Os blocos TOML abaixo são exemplos didáticos montados a partir da documentação oficial da OpenAI. Eles não são resultado de teste meu, então ajuste os valores ao seu caso.

  1. Abra ou crie ~/.codex/config.toml e defina o modelo padrão.

    Esse é o arquivo no nível do usuário, segundo a página Config basics do Codex. A chave model define o modelo que o Codex usa quando você não diz nada.

    # ~/.codex/config.toml
    model = "nome-do-modelo"
    model_reasoning_effort = "high"

    Troque nome-do-modelo pelo identificador do modelo que você quer usar. A chave model_reasoning_effort ajusta o esforço de raciocínio, mas só tem efeito quando o modelo oferece suporte, conforme a Configuration Reference.

    Quer outro modelo só numa execução? Use --model na linha de comando. Ele vale só para aquela sessão e não altera o arquivo, segundo a referência de linha de comando.

  2. Entenda que sandbox_mode e approval_policy são controles separados.

    Esse é o ponto que mais confunde. Segundo a página Agent approvals & security, sandbox_mode define o que o Codex consegue fazer tecnicamente, e approval_policy define quando ele precisa pedir permissão antes.

    Pensa assim: o sandbox é a cerca, a aprovação é o porteiro. Dá para ter cerca larga com porteiro chato, ou cerca apertada com porteiro liberado.

    Os valores de sandbox_mode são read-only, workspace-write e danger-full-access. Se quiser entender o que cada modo isola em cada sistema, tem o post sobre como funciona o sandbox do Codex.

    Em approval_policy, os valores aceitos são on-request, never ou um objeto de configuração granular. Com on-request o Codex para e pede antes de rodar comandos. O never é indicado para execuções não interativas.

    # ~/.codex/config.toml
    model = "nome-do-modelo"
    sandbox_mode = "workspace-write"
    approval_policy = "on-request"

    Erro comum deste passo: escrever approval_policy = "untrusted". O Codex não aceita mais esse valor ali. Ele só continua válido em allowed_approval_policies, ligado ao comportamento mais restrito que o Codex aplica a projetos não confiáveis.

  3. Crie o perfil de revisão somente leitura.

    Os perfis hoje são arquivos separados, ao lado do config.toml, no formato ~/.codex/<nome>.config.toml, segundo a Advanced Configuration. O exemplo oficial é justamente um perfil de revisão:

    # ~/.codex/review.config.toml
    approval_policy = "on-request"
    sandbox_mode = "read-only"

    Para ativar:

    codex --profile review

    Se liga no detalhe: o Codex carrega primeiro o ~/.codex/config.toml e depois aplica o perfil por cima. Então o model que você definiu no passo 1 continua valendo, e só o sandbox e a aprovação mudam.

  4. Crie o perfil de edição no workspace.

    Para quando você quer que o Codex escreva arquivos de verdade, mas sem sair do projeto:

    # ~/.codex/edit.config.toml
    sandbox_mode = "workspace-write"
    approval_policy = "on-request"
    
    sandbox_workspace_write.network_access = false
    # sandbox_workspace_write.writable_roots = ["/caminho/para/outra/pasta"]

    A tabela sandbox_workspace_write é opcional. No exemplo, as chaves dela aparecem no formato sandbox_workspace_write.chave, que no TOML equivale a declarar a tabela e listar as chaves embaixo. O network_access libera rede de saída dentro do sandbox workspace-write, e o writable_roots adiciona outras pastas com permissão de escrita. Os dois estão descritos na Configuration Reference.

    Ativa com codex --profile edit.

    Erro comum deste passo: colocar network_access = true "só por garantia". Tome cuidado! Rede de saída aberta é exatamente o tipo de permissão que você quer liberar quando sabe por que precisa, e não por padrão.

  5. Configure por projeto com .codex/config.toml no repositório.

    Quer que um repositório específico sempre abra com certas regras? Crie a pasta .codex/ na raiz dele e coloque um config.toml lá dentro.

    # meu-repo/.codex/config.toml
    sandbox_mode = "workspace-write"
    sandbox_workspace_write.network_access = false

    Se houver mais de um .codex/config.toml (um na raiz e outro numa subpasta, por exemplo), o Codex percorre da raiz até o diretório atual, e vale o arquivo mais próximo de onde você está trabalhando, segundo a Advanced Configuration.

    Erro comum deste passo: criar o arquivo num repositório que não está marcado como confiável e achar que o Codex está ignorando a configuração por bug. Não é bug. Em projeto não confiável, o Codex ignora as camadas de .codex/, incluindo config, hooks e rules locais.

  6. Sobrescreva pontualmente com flags.

    Às vezes você quer mudar uma coisa só naquela execução, sem criar perfil. Para isso existem --sandbox e --config:

    codex --sandbox read-only
    codex --profile edit --config approval_policy=on-request

    O --config usa o formato chave=valor e pode ser repetido quantas vezes precisar. E é aqui que entra a ordem de precedência, da maior para a menor, segundo a Config basics:

  7. Flags da CLI e overrides via --config
  8. .codex/config.toml do projeto (vale o mais próximo, só em projeto confiável)
  9. Perfil escolhido com --profile (~/.codex/<nome>.config.toml)
  10. Config do usuário em ~/.codex/config.toml
  11. Config do sistema em /etc/codex/config.toml no Unix, se existir
  12. Padrões embutidos

    Repara que a config do projeto ganha do perfil. Então se o repositório define sandbox_mode e você abre com --profile review, quem manda nessa chave é o arquivo do projeto, e só uma flag passaria por cima dele.

  13. Faça a checagem final com /status.

Abra uma sessão com o perfil que você quer testar:

codex --profile review

Dentro da sessão, digite:

/status

Segundo a página de slash commands do Codex CLI, o /status mostra a configuração da sessão e o uso de tokens. Confira o modelo ativo, a política de aprovação e as raízes com permissão de escrita.

Resultado esperado: o modelo é o do seu config.toml base, a aprovação está como on-request e não aparecem raízes de escrita além do esperado para um perfil somente leitura. Se algo não bater, volte na ordem de precedência do passo 6 e procure quem está sobrescrevendo.

Erro "--profile cannot be used while config.toml contains legacy profile"

Sintoma: você roda codex --profile work e recebe algo assim, como relatado numa issue do repositório databricks-agents:

Error loading config.toml: --profile `work` cannot be used while ~/.codex/config.toml contains legacy `profile = "work"` or `[profiles.work]` config

Causa: seu config.toml ainda usa o formato antigo de perfis, com tabelas [profiles.<nome>] e o seletor profile = "<nome>" no topo. Segundo a Advanced Configuration, o --profile não lê mais esse formato.

Solução: mover o conteúdo da tabela para um arquivo próprio e apagar a tabela e o seletor do arquivo base.

Antes, tudo dentro do ~/.codex/config.toml:

# ~/.codex/config.toml (formato antigo)
model = "nome-do-modelo"
profile = "work"

[profiles.work]
sandbox_mode = "workspace-write"
approval_policy = "on-request"

Depois, separado em dois arquivos:

# ~/.codex/config.toml
model = "nome-do-modelo"
# ~/.codex/work.config.toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"

Agora codex --profile work volta a funcionar, carregando a base e aplicando o work.config.toml por cima.

Como prevenir: um arquivo por perfil e nada de tabelas profiles.<nome> nem profile = no config.toml base. Se você copia configs de tutoriais antigos, vale dar uma olhada nisso antes de colar.

Próximo passo: deixe o perfil de revisão como hábito

Crie agora os dois arquivos, review.config.toml e edit.config.toml. No próximo code review, abra com codex --profile review e rode /status antes de pedir qualquer coisa ao agente.

Se os valores baterem, você ganhou um modo "só olha, não mexe" que abre em um comando. Quando a revisão virar correção, é só sair e abrir com --profile edit 🙂.

E se o Codex ainda nem autentica direito na sua máquina, resolve isso primeiro no guia de instalação mencionado lá no começo.

Perguntas frequentes

Dá para usar dois perfis do Codex CLI ao mesmo tempo?

Não. Cada chamada aceita um --profile por vez, que carrega o ~/.codex/config.toml base e aplica esse perfil por cima. Se quiser ajustar algo além do perfil só naquela execução, combine com --config chave=valor na mesma chamada.

Fontes consultadas

Consulta em .

Explore os vídeos do canal Hora de Codar.

Escrito por | Matheus Battisti

Matheus Battisti
Fundador da Hora de Codar

Programador apaixonado pelo mundo das tecnologias, sempre buscando em aprender e se aprofundar em linguagens, frameworks e o que mais for necessário para executar um bom trabalho. Agora tem uma nova missão que é de passar seu conhecimento adiante para formar novos programadores e especializar mais os que já são.

Formações

Formação Vibe Coding

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

  • 474 aulas
  • 20 projetos
  • 39h 30min

Blog | Mais populares