Configuração básica

O Codex lê informações de configuração em mais de um local. Seus valores padrão pessoais ficam em ~/.codex/config.toml, e você pode adicionar substituições específicas do projeto com arquivos .codex/config.toml. Por segurança, o Codex só carrega as camadas .codex/ do projeto quando você confia nele.

Arquivo de configuração do Codex

O Codex armazena a configuração no nível do usuário em ~/.codex/config.toml. Para limitar as configurações a um projeto específico ou a uma de suas subpastas, adicione um arquivo .codex/config.toml ao repositório.

Para abrir o arquivo de configuração na extensão do Codex para IDE, selecione o ícone de engrenagem no canto superior direito e, em seguida, selecione Configurações do Codex > Abrir config.toml.

A CLI e a extensão para IDE compartilham as mesmas camadas de configuração. Você pode usar ambas para:

• Definir o modelo e o provedor padrão.
• Configurar políticas de aprovação e configurações do Sandbox.
• Configurar servidores MCP.

Precedência da configuração

O Codex determina os valores nesta ordem (da maior para a menor precedência):

1. Flags da CLI e substituições com --config
2. Arquivos de configuração do projeto: .codex/config.toml, ordenados da raiz do projeto até o diretório de trabalho atual (o mais próximo prevalece; somente projetos confiáveis)
3. Arquivos de perfil selecionados com --profile profile-name (~/.codex/profile-name.config.toml)
4. Configuração do usuário: ~/.codex/config.toml
5. Configuração do sistema (se houver): /etc/codex/config.toml no Unix
6. Valores padrão integrados

Use essa precedência para definir valores padrão compartilhados em config.toml e mantenha os arquivos de perfil limitados aos valores que diferem.

Se você marcar um projeto como não confiável, o Codex ignorará as camadas .codex/ específicas do projeto, incluindo a configuração, os hooks e as regras locais do projeto. As configurações do usuário e do sistema continuarão sendo carregadas, incluindo hooks e regras globais do usuário.

Para substituições pontuais por meio de -c/--config (incluindo as regras de uso de aspas no TOML), consulte Configuração avançada.

Opções comuns de configuração

Estas são algumas das opções alteradas com mais frequência:

Modelo padrão

Escolha o modelo que o Codex usa por padrão na CLI e na IDE.

model = "gpt-5.6"

Solicitações de aprovação

Controle quando o Codex pausa para pedir aprovação antes de executar os comandos gerados.

approval_policy = "on-request"

Para entender as diferenças de comportamento entre untrusted, on-request e never, consulte Executar sem solicitações de aprovação e Combinações comuns de Sandbox e aprovação.

Nível do Sandbox

Ajuste o nível de acesso do Codex ao sistema de arquivos e à rede durante a execução de comandos.

sandbox_mode = "workspace-write"

Para saber como cada modo se comporta (incluindo caminhos .git/.codex protegidos e padrões de rede), consulte Sandbox e aprovações, Caminhos protegidos em raízes graváveis e Acesso à rede.

Perfis de permissão

O Codex também oferece suporte a perfis de permissão nomeados para políticas reutilizáveis do sistema de arquivos e da rede. Os perfis integrados são :read-only, :workspace e :danger-full-access. Os perfis personalizados usam tabelas [permissions.<name>] e um valor default_permissions correspondente. Consulte Permissões.

Modo de Sandbox do Windows

Ao executar o Codex nativamente no Windows, defina o modo de Sandbox nativo como elevated na tabela windows. Use unelevated somente se você não tiver permissões de administrador ou se a configuração com privilégios elevados falhar.

[windows]
sandbox = "elevated"   # Recommended
# sandbox = "unelevated" # Fallback if admin permissions/setup are unavailable

Modo de Pesquisa na Web

O Codex ativa a Pesquisa na Web por padrão em chats locais e fornece resultados de um cache da Pesquisa na Web. O cache é um índice de resultados da Web mantido pela OpenAI, portanto o modo em cache retorna resultados pré-indexados em vez de buscar páginas em tempo real. Isso reduz a exposição à injeção de prompt causada por conteúdo arbitrário obtido em tempo real, mas você ainda deve tratar os resultados da Web como não confiáveis. Se você estiver usando --yolo ou outra configuração de Sandbox com acesso completo, a Pesquisa na Web usará resultados em tempo real por padrão. Escolha um modo com web_search:

• "cached" (padrão) fornece resultados do cache da Pesquisa na Web.
• "indexed" permite acesso externo à Web somente quando o índice de pesquisa autoriza a solicitação.
• "live" busca os dados mais recentes da Web (equivale a --search).
• "disabled" desativa a ferramenta de Pesquisa na Web.

web_search = "cached"  # default; serves results from the web search cache
# web_search = "indexed" # gate external web access through the search index
# web_search = "live"  # fetch the most recent data from the web (same as --search)
# web_search = "disabled"

Esforço de raciocínio

Ajuste o nível de esforço de raciocínio aplicado pelo modelo, quando houver suporte.

model_reasoning_effort = "high"

Estilo de comunicação

Defina um estilo de comunicação padrão para os modelos compatíveis.

personality = "friendly" # or "pragmatic" or "none"

Você pode substituir essa configuração depois, durante uma sessão ativa, com /personality ou por thread/turno ao usar as APIs do App Server.

Mapa de teclas da TUI

Personalize os atalhos do terminal em tui.keymap. Determinadas ações do editor recorrem às associações correspondentes de tui.keymap.global; quando houver suporte, as associações específicas do contexto terão precedência. Uma lista vazia remove a associação da ação.

[tui.keymap.global]
open_transcript = "ctrl-t"

[tui.keymap.composer]
submit = ["enter", "ctrl-m"]

[tui.keymap.chat]
interrupt_turn = "f12"

Ambiente de comandos

Controle quais variáveis do ambiente o Codex encaminha aos comandos que ele inicia. Use filtros por chave para manter apenas as variáveis necessárias:

[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

O valor padrão de ignore_default_excludes é true, o que desativa a filtragem automática de nomes de variáveis que contenham KEY, SECRET ou TOKEN. Defina essa opção como false quando quiser usar essa filtragem automática. Para saber mais sobre regras de exclusão, precedência e configuração legada, consulte Política do ambiente do shell.

Diretório de logs

Altere o local onde o Codex grava os arquivos de log locais. Definir log_dir explicitamente também ativa o log opcional da TUI em texto simples, codex-tui.log, nesse diretório.

log_dir = "/absolute/path/to/codex-logs"

Em execuções pontuais, você também pode defini-lo pela CLI:

codex -c log_dir=./.codex-log

Flags de recursos

Use a tabela [features] em config.toml para ativar ou desativar recursos opcionais e experimentais.

Flags de recursos comuns

Para configurar hooks de ciclo de vida, consulte Hooks.

Ativar recursos

• No arquivo config.toml, adicione feature_name = true à seção [features].
• Na CLI, execute codex --enable feature_name.
• Para ativar mais de um recurso, execute codex --enable feature_a --enable feature_b.
• Para desativar um recurso, defina a chave como false no arquivo config.toml.