Configuração avançada

Use estas opções quando precisar de mais controle sobre provedores, políticas e integrações. Para começar rapidamente, consulte Configuração básica.

Para saber mais sobre orientações de projeto, capacidades reutilizáveis, comandos de barra personalizados, fluxos de trabalho de subagentes e integrações, consulte Personalização. Para ver as chaves de configuração, consulte Referência de configuração.

Perfis

Os perfis permitem salvar camadas de configuração nomeadas e alternar entre elas pela CLI. Ao passar --profile profile-name, o Codex carrega ~/.codex/config.toml e, em seguida, aplica ~/.codex/profile-name.config.toml sobre essa configuração. Os nomes dos perfis podem conter letras, números, hífens e sublinhados.

Crie um arquivo TOML separado para cada perfil. Use chaves de configuração de nível superior no arquivo do perfil; não as aninhe em [profiles.profile-name].

# ~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

codex --profile deep-review
codex exec --profile deep-review "review this change"

Como o arquivo de perfil fica em uma camada acima da configuração base do usuário e abaixo da configuração do projeto e da CLI, ele só precisa conter os valores que diferem da configuração base. Os arquivos de perfil também podem substituir model_catalog_json; quando ambos os arquivos definem essa chave, o Codex usa o valor do perfil.

A partir do Codex 0.134.0, --profile não lê mais [profiles.profile-name] de config.toml, e o seletor de nível superior profile = "profile-name" não tem mais suporte. Mova as configurações legadas de perfil para ~/.codex/profile-name.config.toml; depois, remova a tabela correspondente [profiles.profile-name] e o seletor profile = "profile-name" de config.toml.

Substituições pontuais pela CLI

Além de editar ~/.codex/config.toml, você pode substituir configurações para uma única execução pela CLI:

• Prefira flags específicas quando estiverem disponíveis (por exemplo, --model).
• Use -c / --config quando precisar substituir uma chave qualquer.

Exemplos:

# Dedicated flag
codex --model gpt-5.6-terra

# Generic key/value override (value is TOML, not JSON)
codex --config model='"gpt-5.6-terra"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

Observações:

• As chaves podem usar a notação de ponto para definir valores aninhados (por exemplo, mcp_servers.context7.enabled=false).
• Os valores de --config são analisados como TOML. Em caso de dúvida, coloque o valor entre aspas para que o shell não o divida nos espaços.
• Se o valor não puder ser analisado como TOML, o Codex o trata como uma string.

Locais de configuração e estado

O Codex armazena seu estado local em CODEX_HOME (o padrão é ~/.codex).

Arquivos comuns que você pode encontrar nesse local:

• config.toml (sua configuração local)
• auth.json (se você usar armazenamento de credenciais em arquivo) ou o chaveiro do sistema operacional
• history.jsonl (se a persistência do histórico estiver ativada)
• Outros dados de estado específicos do usuário, como logs e caches

Para ver detalhes da autenticação (incluindo os modos de armazenamento de credenciais), consulte Autenticação. Para ver a lista completa das chaves de configuração, consulte Referência de configuração.

Para saber mais sobre valores padrão, regras e habilidades compartilhados mantidos em repositórios ou caminhos do sistema, consulte Configuração da equipe.

Se você só precisa direcionar o provedor integrado da OpenAI para um proxy de LLM, um roteador ou um projeto com residência de dados ativada, defina openai_base_url em config.toml em vez de definir um novo provedor. Isso altera a URL base do provedor integrado openai sem exigir uma entrada model_providers.<id> separada.

openai_base_url = "https://us.api.openai.com/v1"

Arquivos de configuração do projeto (.codex/config.toml)

Além da configuração do usuário, o Codex lê substituições no escopo do projeto em arquivos .codex/config.toml dentro do repositório. O Codex percorre os diretórios desde a raiz do projeto até o diretório de trabalho atual e carrega cada .codex/config.toml que encontrar. Se vários arquivos definirem a mesma chave, prevalece o arquivo mais próximo do diretório de trabalho.

Por segurança, o Codex só carrega arquivos de configuração no escopo do projeto quando o projeto é confiável. Se o projeto não for confiável, o Codex ignora as camadas .codex/ do projeto, incluindo .codex/config.toml, ganchos locais do projeto e regras locais do projeto. As camadas do usuário e do sistema permanecem separadas e continuam sendo carregadas.

Os caminhos relativos em uma configuração de projeto (por exemplo, model_instructions_file) são resolvidos em relação à pasta .codex/ que contém o arquivo config.toml.

Os arquivos de configuração do projeto não podem substituir configurações que redirecionem credenciais, alterem metadados de solicitações do aplicativo controlados pelo host, mudem a autenticação do provedor, selecionem perfis de configuração ou executem, na máquina local, comandos de notificação ou telemetria. O Codex ignora as seguintes chaves no arquivo local do projeto .codex/config.toml e exibe um aviso na inicialização quando as encontra: openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url e otel. Defina as chaves de provedor, notificação e telemetria no arquivo ~/.codex/config.toml do usuário; selecione perfis de configuração com --profile profile-name e ~/.codex/profile-name.config.toml.

Ganchos

O Codex também pode carregar ganchos de ciclo de vida de arquivos hooks.json ou de tabelas [hooks] incluídas em arquivos config.toml localizados junto às camadas de configuração ativas.

Na prática, os quatro locais mais úteis são:

• ~/.codex/hooks.json
• ~/.codex/config.toml
• <repo>/.codex/hooks.json
• <repo>/.codex/config.toml

Os ganchos locais do projeto só são carregados quando a camada .codex/ do projeto é considerada confiável. Os ganchos no nível do usuário não dependem da confiabilidade do projeto.

Os ganchos definidos no próprio arquivo TOML usam a mesma estrutura de eventos de hooks.json:

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

Se uma camada contiver tanto hooks.json quanto uma tabela [hooks] incorporada, o Codex carregará ambos e emitirá um aviso. Prefira uma única representação por camada.

Para ver a lista atual de eventos, os campos de entrada, o comportamento da saída e as limitações, consulte Ganchos.

Funções de agentes ([agents] em config.toml)

Para configurar funções de subagentes ([agents] em config.toml), consulte Subagentes.

Detecção da raiz do projeto

O Codex encontra a configuração do projeto (por exemplo, camadas .codex/ e AGENTS.md) subindo na hierarquia a partir do diretório de trabalho até chegar à raiz de um projeto.

Por padrão, o Codex considera um diretório que contém .git como a raiz do projeto. Para personalizar esse comportamento, defina project_root_markers em config.toml:

# Treat a directory as the project root when it contains any of these markers.
project_root_markers = [".git", ".hg", ".sl"]

Defina project_root_markers = [] para não pesquisar os diretórios superiores e considerar o diretório de trabalho atual como a raiz do projeto.

Provedores de modelos personalizados

Um provedor de modelos define como o Codex se conecta a um modelo (URL base, API de comunicação, autenticação e cabeçalhos HTTP opcionais). Os provedores personalizados não podem reutilizar os IDs reservados dos provedores integrados: openai, ollama e lmstudio.

Defina provedores adicionais e configure model_provider para apontar para eles:

model = "gpt-5.6-terra"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

Se um provedor personalizado oferecer suporte ao endpoint de pesquisa na Web independente, declare essa capacidade na configuração do provedor:

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
env_key = "OPENAI_API_KEY"
supports_standalone_web_search = true

Essa configuração usa false por padrão em provedores personalizados. A pesquisa na Web independente está em desenvolvimento e desativada por padrão. Definir essa capacidade do provedor como true não ativa a pesquisa: o provedor precisa oferecer suporte a um endpoint compatível, e o modelo e o ambiente de execução selecionados precisam oferecer suporte à pesquisa independente. O modo web_search configurado e as restrições de pesquisa gerenciadas continuam em vigor.

Adicione cabeçalhos de solicitação quando necessário:

[model_providers.example]
http_headers = { "X-Example-Header" = "example-value" }
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

Use autenticação baseada em comando quando um provedor precisar que o Codex obtenha tokens bearer de um auxiliar externo de credenciais:

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
wire_api = "responses"

[model_providers.proxy.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

O comando de autenticação não recebe nenhuma entrada por stdin e deve imprimir o token em stdout. O Codex remove os espaços em branco no início e no fim, trata um token vazio como erro e o renova de forma proativa no intervalo definido por refresh_interval_ms; defina refresh_interval_ms = 0 para renová-lo somente após uma nova tentativa de autenticação. Não combine [model_providers.<id>.auth] com env_key, experimental_bearer_token ou requires_openai_auth.

Provedor do Amazon Bedrock

O Codex inclui um provedor de modelos amazon-bedrock integrado. Defina-o diretamente como valor de model_provider; ao contrário dos provedores personalizados, esse provedor integrado oferece suporte apenas às substituições aninhadas de perfil e região da AWS.

model_provider = "amazon-bedrock"
model = "<bedrock-model-id>"

[model_providers.amazon-bedrock.aws]
profile = "default"
region = "eu-central-1"

Se você omitir profile, o Codex usa a cadeia de credenciais padrão da AWS. Defina region como a região compatível do Bedrock que deve processar as solicitações.

Para ver o fluxo completo de configuração, as opções de autenticação, os modelos compatíveis e a disponibilidade dos recursos, consulte Usar o ChatGPT Work e o Codex com o Amazon Bedrock.

Modo OSS (provedores locais)

O Codex pode ser executado com um provedor local de "código aberto", como Ollama ou LM Studio, quando você passa --oss. Escolha um para uma única execução com --local-provider ou defina oss_provider como padrão. Se nenhuma dessas opções estiver definida, a CLI interativa solicita que você escolha um; o comando codex exec termina com erro.

# Default local provider used with `--oss`
oss_provider = "ollama" # or "lmstudio"

Provedor do Azure e ajustes específicos por provedor

[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000

Para alterar a URL base do provedor integrado da OpenAI, use openai_base_url; não crie [model_providers.openai], pois não é possível substituir os IDs dos provedores integrados.

Organizações da API que usam residência de dados

Em projetos criados com a residência de dados ativada, é possível criar um provedor de modelos para atualizar base_url com o prefixo correto. Para workspaces do ChatGPT com residência de dados, não é necessário um provedor personalizado; o Codex respeita as configurações de residência do workspace quando você entra com o ChatGPT.

model_provider = "openaidr"
[model_providers.openaidr]
name = "OpenAI Data Residency"
base_url = "https://us.api.openai.com/v1" # Replace 'us' with domain prefix

Raciocínio do modelo, nível de detalhamento e limites

model_reasoning_summary = "none"          # Disable summaries
model_verbosity = "low"                   # Shorten responses
model_supports_reasoning_summaries = true # Force reasoning
model_context_window = 128000             # Context window size

model_verbosity se aplica apenas aos provedores que usam a Responses API. Os provedores de Chat Completions ignoram essa configuração.

Políticas de aprovação e modos de sandbox

Escolha o grau de rigor das aprovações (afeta quando o Codex faz uma pausa) e o nível do sandbox (afeta o acesso a arquivos e à rede).

Para conhecer os detalhes operacionais a considerar ao editar config.toml, consulte Combinações comuns de sandbox e aprovação, Caminhos protegidos em diretórios raiz com permissão de escrita e Acesso à rede.

O Codex e o ChatGPT Work não oferecem mais suporte a approval_policy = "untrusted". Consulte Migre da política de aprovação descontinuada untrusted para conhecer as configurações compatíveis e as aprovações mais rigorosas derivadas do projeto.

Para saber mais sobre os perfis de permissões em beta que configuram o acesso ao sistema de arquivos e à rede em conjunto, consulte Permissões.

Você também pode usar uma política de aprovação granular (approval_policy = { granular = { ... } }) para permitir ou rejeitar automaticamente categorias individuais de solicitações. Isso é útil quando você quer aprovações interativas normais em alguns casos, mas quer que outros, como solicitações de request_permissions ou de scripts de habilidades, sejam bloqueados automaticamente por segurança.

Defina approvals_reviewer = "auto_review" para encaminhar solicitações interativas de aprovação elegíveis para revisão automática. Isso altera quem faz a revisão, sem alterar os limites do sandbox.

Use [auto_review].policy para instruções locais da política do revisor. A configuração gerenciada guardian_policy_config tem precedência.

approval_policy = "on-request"  # Other options: never or { granular = { ... } }
approvals_reviewer = "user"     # Or "auto_review" for automatic review
sandbox_mode = "workspace-write"
allow_login_shell = false       # Optional hardening: disallow login shells for shell tools

# Example granular approval policy:
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

[sandbox_workspace_write]
exclude_tmpdir_env_var = false  # Allow $TMPDIR
exclude_slash_tmp = false       # Allow /tmp
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false          # Opt in to outbound network

[auto_review]
policy = """
Use your organization's automatic review policy.
"""

Perfis de permissões nomeados

Para saber mais sobre os perfis integrados, a sintaxe dos perfis personalizados e o modelo completo de configuração do sistema de arquivos e da rede, consulte Permissões.

Para ver a lista completa de chaves e as restrições de requisitos, consulte Referência de configuração e Configuração gerenciada.

Desative completamente o ambiente isolado (use apenas se o seu ambiente já isolar processos):

sandbox_mode = "danger-full-access"

Política de ambiente do shell

shell_environment_policy controla quais variáveis do ambiente o Codex passa para os comandos iniciados. Comece com um ambiente vazio usando inherit = "none", ou herde um conjunto reduzido usando inherit = "core". Adicione valores explícitos e filtros por chave para evitar passar segredos desnecessários aos comandos iniciados.

[shell_environment_policy]
inherit = "core"
set = { MY_FLAG = "1" }
ignore_default_excludes = false

[shell_environment_policy.filters]
"AWS_*" = "exclude"
"AZURE_*" = "exclude"

Os padrões de filtro não diferenciam maiúsculas de minúsculas e aceitam * e ?. Use "exclude" para remover as variáveis correspondentes. Quando algum padrão usa "include", o Codex mantém apenas as variáveis que correspondem a um padrão de inclusão. As inclusões não restauram variáveis que já foram excluídas. As chaves de filtro são mescladas entre as camadas de configuração sem diferenciar maiúsculas de minúsculas.

O valor padrão de ignore_default_excludes é true, portanto o Codex não remove automaticamente variáveis cujos nomes contêm KEY, SECRET ou TOKEN. Defina-o como false para aplicar essas exclusões automáticas antes da execução dos seus filtros explícitos.

O Codex aplica primeiro as exclusões automáticas, depois as exclusões personalizadas, os valores de set e, por fim, a lista de permissões baseada em padrões de inclusão. Como set é executado após as exclusões, ele pode restaurar uma variável excluída. Uma lista de permissões baseada em padrões de inclusão ainda pode remover esse valor restaurado.

Os arrays antigos exclude e include_only continuam sendo aceitos nas configurações existentes. Não combine nenhum desses arrays com [shell_environment_policy.filters] na mesma camada de configuração; o Codex rejeita essa combinação.

Servidores MCP

Consulte a documentação específica do MCP para ver os detalhes de configuração.

Observabilidade e telemetria

Ative a exportação de logs do OpenTelemetry (OTel) para acompanhar as execuções do Codex (requisições de API, SSE/eventos, prompts, aprovações/resultados de ferramentas). A exportação vem desativada por padrão; ative-a por meio de [otel]:

[otel]
environment = "staging"   # defaults to "dev"
exporter = "none"         # set to otlp-http or otlp-grpc to send events
log_user_prompt = false   # redact user prompts unless explicitly enabled

Escolha um exportador:

[otel]
exporter = { otlp-http = {
  endpoint = "https://otel.example.com/v1/logs",
  protocol = "binary",
  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}

[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

Se exporter = "none", o Codex registra os eventos, mas não envia nada. Os exportadores agrupam os eventos em lotes de forma assíncrona e enviam os dados pendentes no encerramento. Os metadados dos eventos incluem nome do serviço, versão da CLI, tag do ambiente, ID da conversa, modelo, configurações de sandbox/aprovação e campos específicos de cada evento (consulte Referência de configuração).

O que é emitido

O Codex emite eventos de log estruturados para execuções e uso de ferramentas. Alguns exemplos de tipos de eventos são:

• codex.conversation_starts (modelo, configurações de raciocínio, política de sandbox/aprovação)
• codex.api_request (tentativa, status/sucesso, duração e detalhes do erro)
• codex.sse_event (tipo de evento do fluxo, sucesso/falha, duração e contagens de tokens em response.completed)
• codex.websocket_request e codex.websocket_event (duração da requisição e tipo/sucesso/erro de cada mensagem)
• codex.user_prompt (comprimento; conteúdo ocultado, a menos que seu registro seja explicitamente ativado)
• codex.tool_decision (aprovado/negado e se a decisão veio da configuração ou do usuário)
• codex.tool_result (duração, sucesso, trecho da saída)

Métricas OTel emitidas

Quando o pipeline de métricas OTel está ativado, o Codex emite contadores e histogramas de duração para atividades de API, fluxos e ferramentas.

Cada métrica abaixo também inclui as tags de metadados padrão: auth_mode, originator, session_source, model e app.version.

Para mais orientações de segurança e privacidade sobre telemetria, consulte Segurança.

Métricas

Por padrão, o Codex envia periodicamente uma pequena quantidade de dados anônimos de uso e integridade à OpenAI. Isso ajuda a detectar quando o Codex não está funcionando corretamente e mostra quais recursos e opções de configuração estão sendo usados, para que a equipe do Codex possa se concentrar no que mais importa. Essas métricas não contêm informações de identificação pessoal (PII). A coleta de métricas é independente da exportação de logs/rastreamentos do OTel.

Se quiser desativar completamente a coleta de métricas no aplicativo do ChatGPT para desktop, na Codex CLI e na extensão para IDE em uma máquina, defina a opção de análise de uso na sua configuração:

[analytics]
enabled = false

Cada métrica inclui seus próprios campos, além dos campos de contexto padrão abaixo.

Campos de contexto padrão (aplicáveis a todos os eventos e métricas)

• auth_mode: swic | api | unknown.
• model: nome do modelo usado.
• app.version: versão do Codex.

Catálogo de métricas

Cada métrica inclui os campos obrigatórios, além dos campos de contexto padrão acima. Os nomes das métricas abaixo omitem o prefixo codex.. A maioria dos nomes de métricas está centralizada em codex-rs/otel/src/metrics/names.rs; as métricas específicas de recursos emitidas fora desse arquivo também estão incluídas aqui. Se uma métrica incluir o campo tool, ele indica a ferramenta interna usada (por exemplo, apply_patch ou shell) e não contém o comando de shell ou patch que o codex está tentando aplicar.

Ambiente de execução e transporte do modelo

A métrica cloud_requirements.fetch_attempt inclui os campos trigger, attempt, outcome e status_code. A métrica cloud_requirements.fetch_final inclui os campos trigger, outcome, reason, attempt_count e status_code.

Atividade de turnos e ferramentas

As métricas mcp.call e mcp.call.duration_ms incluem status; os eventos emitidos em chamadas normais de ferramentas também incluem tool, além de connector_id e connector_name quando disponíveis. Chamadas MCP bloqueadas dos Apps do Codex podem emitir mcp.call apenas com status.

Conversas, tarefas e recursos

A métrica shell_snapshot inclui success e, em caso de falha, failure_reason.

Memória e estado local

As métricas external_agent_config.detect e external_agent_config.import incluem migration_type; as migrações de habilidades também incluem skills_count.

Sandbox do Windows

As métricas de falha na configuração com privilégios elevados incluem code e message quando há detalhes disponíveis sobre a falha de configuração do Windows, e podem incluir originator quando emitidas pelo fluxo de configuração compartilhado. A métrica windows_sandbox.legacy_setup_preflight_failed inclui originator quando emitida pelo fluxo de configuração compartilhado, mas as falhas na verificação prévia da solicitação alternativa podem não incluir nenhum campo.

Controles de feedback

Por padrão, os clientes locais permitem que os usuários enviem feedback por meio de /feedback. Para desativar a coleta de feedback no aplicativo do ChatGPT para desktop, na Codex CLI e na extensão para IDE em uma máquina, atualize sua configuração:

[feedback]
enabled = false

Quando a coleta está desativada, /feedback exibe uma mensagem informando isso, e o Codex rejeita os envios de feedback.

Ocultar ou exibir eventos de raciocínio

Se quiser reduzir o ruído causado pela saída de "raciocínio" (por exemplo, nos logs de CI), você pode suprimi-la:

hide_agent_reasoning = true

Se quiser exibir o conteúdo bruto de raciocínio quando um modelo o emitir:

show_raw_agent_reasoning = true

Ative o raciocínio bruto somente se isso for aceitável para seu fluxo de trabalho. Alguns modelos/provedores (como gpt-oss) não emitem raciocínio bruto; nesse caso, essa configuração não tem efeito visível.

Notificações

Use notify para acionar um programa externo sempre que o Codex emitir eventos compatíveis (atualmente, apenas agent-turn-complete). Isso é útil para notificações pop-up na área de trabalho, webhooks de chat, atualizações de CI ou quaisquer alertas por canais externos que as notificações integradas da TUI não cubram.

notify = ["python3", "/path/to/notify.py"]

Exemplo de notify.py (truncado) que reage a agent-turn-complete:

#!/usr/bin/env python3
import json, subprocess, sys

def main() -> int:
    notification = json.loads(sys.argv[1])
    if notification.get("type") != "agent-turn-complete":
        return 0
    title = f"Codex: {notification.get('last-assistant-message', 'Turn Complete!')}"
    message = " ".join(notification.get("input-messages", []))
    subprocess.check_output([
        "terminal-notifier",
        "-title", title,
        "-message", message,
        "-group", "codex-" + notification.get("thread-id", ""),
        "-activate", "com.googlecode.iterm2",
    ])
    return 0

if __name__ == "__main__":
    sys.exit(main())

O script recebe um único argumento JSON. Os campos comuns incluem:

• type (atualmente, agent-turn-complete)
• thread-id (identificador da sessão)
• turn-id (identificador do turno)
• cwd (diretório de trabalho)
• input-messages (mensagens do usuário que deram origem ao turno)
• last-assistant-message (texto da última mensagem do assistente)

Salve o script em algum local do disco e configure notify para apontar para ele.

notify versus tui.notifications

• notify executa um programa externo (útil para webhooks, notificadores da área de trabalho e ganchos de CI).
• tui.notifications é integrado à TUI e pode, opcionalmente, filtrar por tipo de evento (por exemplo, agent-turn-complete e approval-requested).
• tui.notification_method controla como a TUI emite notificações no terminal (auto, osc9 ou bel).
• tui.notification_condition controla se as notificações da TUI são disparadas apenas quando o terminal está sem foco (unfocused) ou sempre (always).

No modo auto, o Codex dá preferência às notificações OSC 9 (uma sequência de escape de terminal que alguns terminais interpretam como uma notificação da área de trabalho) e, caso contrário, usa BEL (\x07) como alternativa.

Consulte a Referência de configuração para ver as chaves exatas.

Persistência do histórico

Por padrão, o Codex salva as transcrições das sessões locais em CODEX_HOME (por exemplo, ~/.codex/history.jsonl). Para desativar a persistência do histórico local:

[history]
persistence = "none"

Para limitar o tamanho do arquivo de histórico, defina history.max_bytes. Quando o arquivo ultrapassa o limite, o Codex remove as entradas mais antigas e compacta o arquivo, preservando os registros mais recentes.

[history]
max_bytes = 104857600 # 100 MiB

Citações clicáveis

Se você usa uma integração de terminal/editor compatível com esse recurso, o Codex pode exibir citações de arquivos como links clicáveis. Configure file_opener para escolher o esquema de URI que o Codex usa:

file_opener = "vscode" # or cursor, windsurf, vscode-insiders, none

Exemplo: uma citação como /home/user/project/main.py:42 pode ser reescrita como um link clicável vscode://file/...:42.

Detecção de instruções do projeto

O Codex lê AGENTS.md (e arquivos relacionados) e inclui uma quantidade limitada de orientações do projeto no primeiro turno de uma sessão. Duas configurações controlam esse comportamento:

• project_doc_max_bytes: quanto conteúdo ler de cada arquivo AGENTS.md
• project_doc_fallback_filenames: nomes de arquivos adicionais a procurar quando AGENTS.md não existe em um nível de diretório

Para um passo a passo detalhado, consulte Instruções personalizadas com AGENTS.md.

Desktop

As opções desta seção se aplicam apenas ao aplicativo do ChatGPT para desktop.

Adicionar manipuladores de arquivos personalizados

No arquivo ~/.codex/config.toml do seu usuário, adicione entradas em desktop.custom_file_handlers para abrir arquivos em editores ou inicializadores internos que o aplicativo do ChatGPT para desktop não suporta por padrão. Cada entrada adiciona uma opção de editor aos menus Abrir em do aplicativo. O aplicativo lista essa opção quando command é um caminho absoluto existente ou pode ser encontrado no PATH do aplicativo.

O exemplo a seguir mostra três maneiras de passar um arquivo para um manipulador:

# Append the opened path directly after the command.
[desktop.custom_file_handlers.vscodium]
label = "VSCodium"
icon = "/Users/you/.codex/icons/vscodium.png"
command = "codium"

# Place fixed arguments before the opened path.
[desktop.custom_file_handlers.textedit]
label = "TextEdit"
icon = "/Users/you/.codex/icons/textedit.png"
command = "/usr/bin/open"
args = ["-a", "TextEdit"]

# Append one JSON argument with the path and editor context.
[desktop.custom_file_handlers.company_editor]
label = "Company Editor"
icon = "/opt/company/editor/icon.png"
command = "/opt/company/bin/editor"
input = "json_argument"

Salve config.toml e reinicie o aplicativo do ChatGPT para desktop.

O ID do manipulador é o último segmento do cabeçalho da tabela TOML. Ele deve conter de 1 a 64 caracteres, começar com uma letra ou um número ASCII e conter, nas demais posições, apenas letras ASCII, números, pontos, sublinhados ou hifens. O aplicativo expõe o ID com o prefixo custom:; por exemplo, company_editor se torna custom:company_editor. Coloque entre aspas um ID que contenha um ponto para que o TOML não o interprete como uma tabela aninhada. Por exemplo:

[desktop.custom_file_handlers."company.editor"]
label = "Company Editor"
icon = "/opt/company/editor/icon.png"
command = "/opt/company/bin/editor"

Cada manipulador aceita estes campos:

O valor de input controla o que vem depois de args:

• path acrescenta o caminho como último argumento do comando.
• json_argument acrescenta um objeto JSON com target, path, appPath e location. O valor de location é um objeto com valores de line e column contados a partir de 1, ou null.
• json_stdin grava o objeto JSON na entrada padrão em vez de adicionar um argumento. Também inclui hostConfig, remoteWorkspaceRoot e remotePath; esses campos têm o valor null quando não se aplicam.

Por exemplo, company_editor pode receber este argumento quando o usuário abre uma posição específica no código-fonte:

{
  "target": "custom:company_editor",
  "path": "/repo/src/index.ts",
  "appPath": null,
  "location": { "line": 12, "column": 3 }
}

Selecionar um manipulador personalizado como editor preferido salva a escolha da mesma forma que selecionar um editor integrado, inclusive nas preferências por projeto.

Opções da TUI

Executar codex sem subcomando inicia a interface interativa de terminal (TUI). O Codex disponibiliza algumas configurações específicas da TUI em [tui], incluindo:

• tui.notifications: ative/desative as notificações (ou restrinja-as a tipos específicos)
• tui.notification_method: escolha auto, osc9 ou bel para as notificações do terminal
• tui.notification_condition: escolha unfocused ou always para definir quando as notificações são disparadas
• tui.animations: ative/desative animações ASCII e efeitos de brilho
• tui.alternate_screen: controle o uso da tela alternativa (defina como never para manter o histórico de rolagem do terminal)
• tui.show_tooltips: mostre ou oculte dicas de primeiros passos na tela de boas-vindas

O padrão de tui.notification_method é auto. No modo auto, o Codex dá preferência às notificações OSC 9 (uma sequência de escape de terminal que alguns terminais interpretam como notificação na área de trabalho) quando o terminal parece oferecer suporte a elas; caso contrário, usa BEL (\x07).

Consulte a Referência de configuração para ver a lista completa de chaves.