Configuração básica

O Codex lê as configurações de vários locais. Suas configurações padrão ficam em ~/.codex/config.toml, e você pode usar arquivos .codex/config.toml para substituir esses valores em projetos específicos. Por segurança, o Codex só carrega as camadas de configuração de .codex/ do projeto quando você confia nele.

Arquivo de configuração do Codex

O Codex armazena as configurações do usuário em ~/.codex/config.toml. Para aplicar configurações a um projeto ou a uma subpasta específica, adicione um arquivo .codex/config.toml ao repositório.

Para abrir o arquivo de configuração pela 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 usam as mesmas camadas de configuração. Com elas, você pode:

• Definir o modelo e o provedor padrão.
• Configurar as políticas de aprovação e as opções de sandbox.
• Configurar os servidores MCP.

Ordem de precedência das configurações

Os requisitos impõem limites ao comportamento do Codex. As configurações definem os valores padrão. O acesso ao computador local pelo Work Cloud segue estes requisitos:

• Entre políticas: a política de maior prioridade prevalece, mesmo que a de menor prioridade seja mais específica.
• Dentro de uma política: as substituições de configuração do ambiente específicas de um sistema operacional prevalecem sobre as que se aplicam a todos os sistemas operacionais. A configuração Global vem por último.
• Na execução local: os requisitos de MDM e os requisitos legados para dispositivos gerenciados têm prioridade sobre o Agent Security. O arquivo de requisitos do sistema no dispositivo tem prioridade inferior à do Agent Security.
• No Work Cloud: os contêineres do Work na nuvem mantêm as políticas existentes do Work Cloud. No modo Work com acesso local e dots, quando a política gerenciada está ativada, a política Global compatível rege o orquestrador compartilhado na nuvem. O computador conectado segue os requisitos de execução local aplicáveis.

Alguns requisitos têm regras de combinação específicas para cada campo. Consulte Configuração gerenciada para conhecer o escopo das políticas e os limites de execução, e a Referência de configuração para verificar a compatibilidade com o modo Work.

O Codex determina os valores nesta ordem, da maior para a menor prioridade:

1. Opções da CLI e valores definidos com --config
2. Arquivos de configuração do projeto: .codex/config.toml, da raiz do projeto até o diretório de trabalho atual (o arquivo mais próximo do diretório atual prevalece, e só projetos confiáveis são considerados)
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 espaço de trabalho em que você iniciou sessão
6. Configuração do sistema (se houver): /etc/codex/config.toml no Unix
7. Valores padrão do Codex

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

Tanto a configuração gerenciada na nuvem quanto a configuração do sistema podem definir marketplaces de plugins e determinar se os plugins ficam ativados por padrão. Essas configurações são independentes das políticas obrigatórias de requirements.toml. Consulte Configurar marketplaces e valores padrão de plugins.

Se você marcar um projeto como não confiável, o Codex ignora as camadas de .codex/ desse projeto, inclusive as configurações, os hooks e as regras locais do projeto. O Codex continua carregando as configurações do usuário e do sistema, inclusive os hooks e as regras do usuário e os globais.

Para substituir valores pontualmente com -c/--config e consultar as regras de uso de aspas do TOML, veja Configuração avançada.

Opções de configuração comuns

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-6.1-sol"

Solicitações de aprovação

Defina quando o Codex deve pausar para pedir aprovação antes de executar os comandos gerados.

approval_policy = "on-request"

Para entender as diferenças 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 de 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 entender o comportamento de cada modo, inclusive a proteção dos caminhos .git, .agents, .codex e .aws e as configurações padrão de rede, consulte Sandbox e aprovações, Caminhos protegidos em diretórios raiz com permissão de gravação e Acesso à rede.

Perfis de permissão

O Codex também permite criar perfis de permissão com nome para reutilizar políticas de acesso ao sistema de arquivos e à rede. Os perfis integrados são :read-only, :workspace e :danger-full-access. Os perfis personalizados usam tabelas [permissions.<name>] e um valor correspondente em default_permissions. Consulte Permissões.

Modo de sandbox no Windows

No Windows, dê preferência ao MXC quando o dispositivo e a política forem compatíveis. Configure uma implementação legada como alternativa:

[windows]
sandbox = "elevated" # Legacy fallback

[features]
prefer_mxc = true

Use unelevated apenas quando a configuração com privilégios elevados estiver indisponível e a política da sua organização permitir. Consulte o guia de sandbox do Windows para conhecer os limites de compatibilidade e os controles de implantação gradual.

Modo de pesquisa na Web

O Codex ativa a pesquisa na Web por padrão nos chats locais e fornece resultados a partir de um cache de pesquisa na Web. Esse cache é um índice de resultados da Web mantido pela OpenAI. No modo de cache, o Codex retorna resultados já indexados em vez de buscar páginas em tempo real. Isso reduz a exposição a ataques de injeção de prompt por meio de conteúdo de fontes arbitrárias consultadas em tempo real. Trate os resultados da Web como não confiáveis. Se você usar --yolo ou outra configuração de sandbox com acesso completo, a pesquisa na Web retornará resultados em tempo real por padrão. Escolha um modo com web_search:

• "cached" (padrão) retorna resultados do cache de 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 esforço de raciocínio do modelo quando ele oferecer suporte a essa opção.

model_reasoning_effort = "medium"

Estilo de comunicação

Para omitir as instruções de personalidade integradas, use a seguinte configuração:

personality = "none"

Isso remove a seção Personality das instruções integradas do modelo. As instruções de base personalizadas que você definiu explicitamente continuam valendo. Os valores antigos friendly e pragmatic já não selecionam um estilo. O Codex deixou de oferecer o comando /personality.

Atalhos de teclado da TUI

Personalize os atalhos do terminal em tui.keymap. Algumas ações do editor usam os atalhos correspondentes de tui.keymap.global quando não há um atalho mais específico. Os atalhos específicos do contexto têm prioridade quando há suporte a eles. 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

Defina quais variáveis de ambiente o Codex repassa aos comandos que 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"

Por padrão, ignore_default_excludes tem o valor true, o que desativa a filtragem automática de variáveis cujo nome contém KEY, SECRET ou TOKEN. Defina o valor como false para ativar essa filtragem. Para conhecer as regras de exclusão, a ordem de precedência e a configuração legada, consulte Política de ambiente do shell.

Diretório de logs

Altere o diretório em que 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"

Para uma execução específica, você também pode definir o diretório 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 os hooks de ciclo de vida, consulte Hooks.

Como ativar recursos

• Em config.toml, adicione feature_name = true à tabela [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 sua chave como false em config.toml.