Noções básicas de configuração

O Codex lê os detalhes de configuração a partir de mais do que uma localização. As suas predefinições pessoais encontram-se em ~/.codex/config.toml e pode adicionar substituições específicas de projetos com ficheiros .codex/config.toml. Por motivos de segurança, o Codex apenas carrega camadas .codex/ do projeto quando confia no projeto.

Ficheiro de configuração do Codex

O Codex guarda a configuração ao nível do utilizador em ~/.codex/config.toml. Para limitar as definições a um projeto ou uma subpasta específicos, adicione um ficheiro .codex/config.toml ao seu repositório.

Para abrir o ficheiro de configuração a partir da extensão do Codex para o IDE, selecione o ícone de engrenagem no canto superior direito e, em seguida, selecione Codex Settings > Open config.toml.

A CLI e a extensão para o IDE partilham as mesmas camadas de configuração. Pode utilizá-las para:

• Definir o modelo e o fornecedor predefinidos.
• Configurar políticas de aprovação e definições de sandbox.
• Configurar servidores MCP.

Precedência da configuração

O Codex resolve os valores pela seguinte ordem (da precedência mais elevada para a mais baixa):

1. Sinalizadores da CLI e substituições --config
2. Ficheiros de configuração do projeto: .codex/config.toml, ordenados desde a raiz do projeto até ao diretório de trabalho atual (vence o mais próximo; apenas projetos fidedignos)
3. Ficheiros de perfil selecionados com --profile profile-name (~/.codex/profile-name.config.toml)
4. Configuração do utilizador: ~/.codex/config.toml
5. Configuração do sistema (se existir): /etc/codex/config.toml em Unix
6. Predefinições incorporadas

Utilize esta precedência para definir predefinições partilhadas em config.toml e mantenha os ficheiros de perfil centrados nos valores que diferem.

Se marcar um projeto como não fidedigno, o Codex ignora as camadas .codex/ limitadas ao projeto, incluindo a configuração, os hooks e as regras locais do projeto. A configuração do utilizador e do sistema continua a ser carregada, incluindo os hooks e as regras globais/do utilizador.

Para substituições pontuais através de -c/--config (incluindo regras de utilização de aspas em TOML), consulte Configuração avançada.

Opções de configuração comuns

Estas são algumas das opções que as pessoas alteram com maior frequência:

Modelo predefinido

Escolha o modelo que o Codex utiliza por predefinição na CLI e no IDE.

model = "gpt-5.6"

Pedidos de aprovação

Controle quando o Codex coloca o trabalho em pausa para pedir autorização antes de executar comandos gerados.

approval_policy = "on-request"

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

Nível de sandbox

Ajuste o nível de acesso ao sistema de ficheiros e à rede de que o Codex dispõe ao executar comandos.

sandbox_mode = "workspace-write"

Para conhecer o comportamento de cada modo (incluindo caminhos .git/.codex protegidos e predefinições de rede), consulte Sandbox e aprovações, Caminhos protegidos em raízes graváveis e Acesso à rede.

Perfis de permissões

O Codex também suporta perfis de permissões com nome para políticas reutilizáveis de sistema de ficheiros e rede. Os perfis incorporados são :read-only, :workspace e :danger-full-access. Os perfis personalizados utilizam 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. Utilize unelevated apenas se 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 predefinição para conversas locais e fornece resultados a partir de uma cache de pesquisa na Web. A cache é um índice de resultados da Web mantido pela OpenAI, pelo que o modo em cache devolve resultados pré-indexados em vez de obter páginas em tempo real. Isto reduz a exposição à injeção de prompts proveniente de conteúdo arbitrário em tempo real, mas deve continuar a tratar os resultados da Web como não fidedignos. Se estiver a utilizar --yolo ou outra definição de sandbox com acesso total, a pesquisa na Web utiliza por predefinição resultados em tempo real. Escolha um modo com web_search:

• "cached" (predefinição) fornece resultados a partir da cache de pesquisa na Web.
• "indexed" permite acesso externo à Web apenas quando o índice de pesquisa autoriza o pedido.
• "live" obtém 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 aplicado pelo modelo, quando suportado.

model_reasoning_effort = "high"

Estilo de comunicação

Defina um estilo de comunicação predefinido para os modelos suportados.

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

Pode substituir esta definição posteriormente numa sessão ativa com /personality ou por thread/turno ao utilizar as APIs app-server.

Mapeamento de teclas da TUI

Personalize os atalhos do terminal em tui.keymap. As ações selecionadas do compositor recorrem às associações tui.keymap.global correspondentes como alternativa; as associações específicas do contexto têm precedência quando são suportadas. 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 dos comandos

Controle as variáveis de ambiente que o Codex encaminha para os comandos iniciados. Utilize filtros com chaves para manter apenas as variáveis de que necessita:

[shell_environment_policy]
ignore_default_excludes = false

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

ignore_default_excludes tem como predefinição true, o que ignora a filtragem automática de nomes de variáveis que contenham KEY, SECRET ou TOKEN. Defina-o como false quando pretender essa filtragem automática. Para conhecer as regras de exclusão, a precedência e a configuração legada, consulte Política do ambiente da shell.

Diretório de registos

Substitua a localização onde o Codex grava os ficheiros de registo locais. Definir explicitamente log_dir também ativa o registo TUI opcional em texto simples, codex-tui.log, nesse diretório.

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

Para execuções pontuais, também pode defini-lo a partir da CLI:

codex -c log_dir=./.codex-log

Sinalizadores de funcionalidades

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

Sinalizadores de funcionalidades comuns

Para configurar hooks de ciclo de vida, consulte Hooks.

Ativar funcionalidades

• Em config.toml, adicione feature_name = true em [features].
• A partir da CLI, execute codex --enable feature_name.
• Para ativar mais do que uma funcionalidade, execute codex --enable feature_a --enable feature_b.
• Para desativar uma funcionalidade, defina a chave como false em config.toml.