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 ou subpasta específicos, 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 essas camadas 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. Sinalizadores 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. Valores padrão de config.toml gerenciados na nuvem, quando fornecidos para o workspace em que você está conectado
6. Configuração do sistema (se houver): /etc/codex/config.toml no Unix
7. Valores padrão integrados

Use essa precedência para definir valores padrão compartilhados em config.toml e manter nos arquivos de perfil apenas os valores que diferem.

A configuração gerenciada na nuvem e a configuração do sistema podem definir marketplaces de plug-ins e determinar se os plug-ins ficam habilitados por padrão. Essas configurações são distintas das políticas obrigatórias de requirements.toml. Consulte Configurar marketplaces de plug-ins e valores padrão.

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

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

Opções comuns de configuração

Veja 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 comandos gerados.

approval_policy = "on-request"

Para saber as diferenças de comportamento entre on-request e never, consulte Executar sem solicitações de aprovação e Combinações comuns de Sandbox e aprovação. Se uma configuração existente usa approval_policy = "untrusted", consulte Migrar da política de aprovação descontinuada untrusted.

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 o comportamento de cada modo (incluindo os caminhos protegidos .git/.codex e os padrões de rede), consulte Sandbox e aprovações, Caminhos protegidos em diretórios raiz com permissão de escrita e Acesso à rede.

Perfis de permissão

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

Modo do Sandbox do Windows

Ao executar o Codex nativamente no Windows, defina o modo do 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 habilita a pesquisa na Web por padrão para chats locais e fornece resultados de um cache de pesquisa na Web. O cache é um índice de resultados da Web mantido pela OpenAI, portanto o modo em cache retorna resultados previamente indexados em vez de buscar páginas em tempo real. Isso reduz a exposição à injeção de prompt de conteúdos arbitrários obtidos 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 do Sandbox com acesso completo, a pesquisa na Web usa resultados em tempo real por padrão. Escolha um modo com web_search:

• "cached" (padrão) fornece resultados do cache de pesquisa na Web.
• "indexed" permite acesso externo à Web somente quando a solicitação passa pelo controle do índice de pesquisa.
• "live" busca os dados mais recentes da Web (equivalente 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 que o modelo aplica, 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 posteriormente em uma sessão ativa com /personality ou por conversa ou turno ao usar as APIs do app-server.

Mapeamento de teclas da TUI

Personalize os atalhos do terminal em tui.keymap. Algumas ações do editor usam os atalhos correspondentes de tui.keymap.global como alternativa; atalhos específicos do contexto têm precedência quando há suporte. Uma lista vazia remove os atalhos da ação.

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

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

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

Ambiente dos comandos

Controle quais variáveis do ambiente o Codex repassa aos comandos iniciados. 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 contêm KEY, SECRET ou TOKEN. Defina como false quando quiser essa filtragem automática. Para saber 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 habilita nesse diretório o log opcional da TUI em texto simples, codex-tui.log.

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

Para execuções pontuais, você também pode definir esse diretório pela CLI:

codex -c log_dir=./.codex-log

Sinalizadores de recursos

Use a tabela [features] em config.toml para habilitar ou desabilitar capacidades opcionais e experimentais.

Sinalizadores de recursos comuns

Para configurar ganchos de ciclo de vida, consulte Ganchos.

Ativação de recursos

• Em config.toml, adicione feature_name = true na 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 em config.toml.