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 Definições do Codex > Abrir 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 MCP servers.

Precedência da configuração

Os requisitos restringem o comportamento; os valores de configuração fornecem predefinições. O acesso ao computador local com o Work Cloud segue estes requisitos:

• Entre políticas: Uma política de prioridade superior prevalece sobre uma política de prioridade inferior, mesmo quando esta é mais específica.
• Dentro de uma política: As substituições de ambiente específicas de um sistema operativo têm prioridade sobre as substituições de ambiente para todos os sistemas operativos, seguindo-se Global.
• Para execução local: Os requisitos de MDM e os requisitos legados de dispositivos geridos têm prioridade sobre o Agent Security. O ficheiro de requisitos do sistema do dispositivo tem prioridade inferior à do Agent Security.
• Para o Work Cloud: Os contentores do Work na nuvem mantêm as políticas existentes do Work Cloud. Para o Work com acesso local e os dots, a política Global suportada rege o orquestrador partilhado na nuvem quando a política gerida está ativada; os requisitos de execução local aplicáveis regem o computador ligado.

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

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

1. Opções da CLI e substituições com --config
2. Ficheiros de configuração do projeto: .codex/config.toml, ordenados desde a raiz do projeto até ao diretório de trabalho atual (o mais próximo prevalece; apenas projetos de confiança)
3. Ficheiros de perfil selecionados com --profile profile-name (~/.codex/profile-name.config.toml)
4. Configuração do utilizador: ~/.codex/config.toml
5. Valores predefinidos de config.toml geridos na nuvem, quando fornecidos para o espaço de trabalho com sessão iniciada
6. Configuração do sistema (se existir): /etc/codex/config.toml em Unix
7. Valores predefinidos incorporados

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

A configuração gerida na nuvem e a configuração do sistema podem definir marketplaces de plugins e determinar se os plugins estão ativados por predefinição. Estas configurações são distintas das políticas obrigatórias de requirements.toml. Consulte Configurar marketplaces de plugins e valores predefinidos.

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

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 on-request e never, consulte Executar sem pedidos de aprovação e Combinações comuns de sandbox e aprovação. Se uma configuração existente utilizar approval_policy = "untrusted", consulte Migrar da política de aprovação descontinuada untrusted.

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, .agents, .codex e .aws 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

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

[windows]
sandbox = "elevated" # Legacy fallback

[features]
prefer_mxc = true

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

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 de cache devolve resultados previamente indexados em vez de obter páginas em tempo real. Isto reduz a exposição à injeção de prompts a partir de conteúdo arbitrário em tempo real. Trate 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 resultados em tempo real por predefinição. 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 = "medium"

Estilo de comunicação

Para omitir as instruções de personalidade integradas, defina:

personality = "none"

Esta definição remove a secção Personality das instruções integradas do modelo. Não altera as instruções base personalizadas explícitas. Os valores antigos friendly e pragmatic já não selecionam um estilo. O Codex já não disponibiliza o comando /personality.

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.