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

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.

Black Week do Nexus
A formação de IA mais completa do Brasil
- 7 formações · 112 cursos · 26 mil alunos
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.
- Abra ou crie
~/.codex/config.tomle defina o modelo padrão.Esse é o arquivo no nível do usuário, segundo a página Config basics do Codex. A chave
modeldefine 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-modelopelo identificador do modelo que você quer usar. A chavemodel_reasoning_effortajusta 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
--modelna linha de comando. Ele vale só para aquela sessão e não altera o arquivo, segundo a referência de linha de comando. - Entenda que
sandbox_modeeapproval_policysão controles separados.Esse é o ponto que mais confunde. Segundo a página Agent approvals & security,
sandbox_modedefine o que o Codex consegue fazer tecnicamente, eapproval_policydefine 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_modesãoread-only,workspace-writeedanger-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ãoon-request,neverou um objeto de configuração granular. Comon-requesto Codex para e pede antes de rodar comandos. Oneveré 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 emallowed_approval_policies, ligado ao comportamento mais restrito que o Codex aplica a projetos não confiáveis. - 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 reviewSe liga no detalhe: o Codex carrega primeiro o
~/.codex/config.tomle depois aplica o perfil por cima. Então omodelque você definiu no passo 1 continua valendo, e só o sandbox e a aprovação mudam. - 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 formatosandbox_workspace_write.chave, que no TOML equivale a declarar a tabela e listar as chaves embaixo. Onetwork_accesslibera rede de saída dentro do sandboxworkspace-write, e owritable_rootsadiciona 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. - Configure por projeto com
.codex/config.tomlno repositório.Quer que um repositório específico sempre abra com certas regras? Crie a pasta
.codex/na raiz dele e coloque umconfig.tomllá dentro.# meu-repo/.codex/config.toml sandbox_mode = "workspace-write" sandbox_workspace_write.network_access = falseSe 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. - Sobrescreva pontualmente com flags.
Às vezes você quer mudar uma coisa só naquela execução, sem criar perfil. Para isso existem
--sandboxe--config:codex --sandbox read-only codex --profile edit --config approval_policy=on-requestO
--configusa o formatochave=valore pode ser repetido quantas vezes precisar. E é aqui que entra a ordem de precedência, da maior para a menor, segundo a Config basics: - Flags da CLI e overrides via
--config .codex/config.tomldo projeto (vale o mais próximo, só em projeto confiável)- Perfil escolhido com
--profile(~/.codex/<nome>.config.toml) - Config do usuário em
~/.codex/config.toml - Config do sistema em
/etc/codex/config.tomlno Unix, se existir - Padrões embutidos
Repara que a config do projeto ganha do perfil. Então se o repositório define
sandbox_modee você abre com--profile review, quem manda nessa chave é o arquivo do projeto, e só uma flag passaria por cima dele. - Faça a checagem final com
/status.

VPS Hostinger para seu sistema
10% OFF extraVPS com SSD NVMe e backups semanais. O cupom MATHEUSHORADECODAR é aplicado automaticamente pelo link.
Ver planos com 10% OFF →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 .
- OpenAI Developers: Config basics (Codex)
- OpenAI Developers: Advanced Configuration (Codex)
- GitHub: IceRhymers/databricks-agents, issue #230
- OpenAI Developers: Agent approvals & security (Codex)
- OpenAI Developers: Codex CLI command line reference
- OpenAI Developers: Configuration Reference (Codex)
- OpenAI Developers: Slash commands in Codex CLI
Formações
Formação Vibe Coding
Do Prompt ao Produto: Crie Software Real com IA
- 474 aulas
- 20 projetos
- 39h 30min
Blog | Mais populares
Codex CLI: como instalar, autenticar e rodar o Codex no terminal
Codex CLI: veja como instalar com npm, autenticar via ChatGPT e rodar o agente de código da OpenAI direto no terminal, com sandbox seguro por padrão.
Quanto custa o Codex? Planos, preços e limites de uso
Codex preço: veja quanto custa o Codex em cada plano do ChatGPT, de US$ 8 no Go até US$ 200 no Pro 20x, e como funcionam os créditos e limites de uso.
Como usar o Codex no ChatGPT: o passo a passo para rodar tarefas sem abrir o terminal
Veja como usar o Codex no ChatGPT: onde acessar pelo navegador, app e celular, como conectar o GitHub e rodar sua primeira tarefa sem abrir o terminal.
