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.6-sol"
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 do perfil é uma camada acima da configuração base do usuário e abaixo das configurações do projeto e da CLI, ele só precisa conter os valores que diferem da configuração base. Os arquivos de perfil também podem sobrescrever model_catalog_json; o Codex usa o valor do perfil quando ambos os arquivos definem essa chave.

No Codex 0.134.0 e versões posteriores, --profile não lê mais [profiles.profile-name] de config.toml, e o seletor de nível superior profile = "profile-name" não é mais aceito. Mova as configurações de perfis legados para ~/.codex/profile-name.config.toml e, em seguida, remova a tabela [profiles.profile-name] e o seletor profile = "profile-name" correspondentes de config.toml.

Sobrescritas pontuais pela CLI

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

• Prefira flags específicas quando existirem (por exemplo, --model).
• Use -c / --config quando precisar sobrescrever uma chave arbitrária.

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 interpretados 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 interpretado como TOML, o Codex o tratará como uma string.

Locais de configuração e estado

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

Arquivos comuns que você pode encontrar nesse local:

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

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

Para saber mais sobre configurações padrão compartilhadas, regras e habilidades armazenadas em repositórios ou caminhos do sistema, consulte Configuração de equipe.

Se você só precisa apontar 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ê sobrescritas específicas do projeto nos arquivos .codex/config.toml do repositório. O Codex percorre o caminho da raiz do projeto até o diretório de trabalho atual e carrega cada .codex/config.toml que encontra. Se vários arquivos definirem a mesma chave, prevalecerá o arquivo mais próximo do diretório de trabalho.

Por segurança, o Codex carrega arquivos de configuração específicos do projeto somente quando o projeto é confiável. Se o projeto não for confiável, o Codex ignorará 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 config.toml.

Os arquivos de configuração do projeto não podem sobrescrever configurações que redirecionem credenciais, alterem metadados de requisições do aplicativo controlados pelo host, mudem a autenticação do provedor, selecionem perfis de configuração ou executem comandos de notificação/telemetria locais da máquina. O Codex ignora as seguintes chaves no .codex/config.toml local do projeto 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 de configuração do usuário ~/.codex/config.toml; selecione os 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] definidas diretamente 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 é confiável. Os ganchos do usuário independem da confiança no projeto.

Os ganchos definidos diretamente em 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 mesma camada contiver tanto hooks.json quanto [hooks] definido diretamente, o Codex carregará ambos e emitirá um aviso. Prefira uma 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.

Papéis dos agentes ([agents] em config.toml)

Para saber mais sobre a configuração dos papéis dos 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) percorrendo os diretórios superiores 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 nos 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). Provedores personalizados não podem reutilizar os IDs reservados dos provedores integrados: openai, ollama e lmstudio.

Defina provedores adicionais e aponte model_provider 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 independente de pesquisa na Web, 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

O valor padrão dessa configuração é false para provedores personalizados. A pesquisa na Web independente está em desenvolvimento e desativada por padrão. Definir a capacidade do provedor como true não a ativa: 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 se aplicando.

Adicione cabeçalhos de requisiçã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 comandos 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 dados 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 renova o token proativamente 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 Amazon Bedrock

O Codex inclui um provedor de modelos integrado chamado amazon-bedrock. Defina-o diretamente como model_provider; ao contrário dos provedores personalizados, esse provedor integrado oferece suporte apenas às sobrescritas 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 usará a cadeia de credenciais padrão da AWS. Defina region com a região compatível do Bedrock que deve processar as requisiçõ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 usar 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 solicitará que você escolha; codex exec será encerrado com um erro.

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

Provedor Azure e ajustes 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 sobrescrever IDs de provedores integrados.

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

Em projetos criados com 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, nível de detalhamento e limites do modelo

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 a provedores que usam a Responses API. Provedores de Chat Completions ignoram essa configuração.

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

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

Para conhecer os detalhes operacionais que você deve considerar ao editar config.toml, consulte Combinações comuns de sandbox e aprovação, Caminhos protegidos em diretórios raiz com permissão de gravação 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 untrusted descontinuada para conhecer as configurações compatíveis e as aprovações mais rigorosas derivadas do projeto.

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

Você também pode usar uma política de aprovação granular (approval_policy = { granular = { ... } }) para permitir ou rejeitar automaticamente categorias específicas 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 as solicitações elegíveis de aprovação interativa para revisão automática. Isso altera o revisor, mas não os limites do sandbox.

Use [auto_review].policy para definir 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ão nomeados

Para conhecer os perfis integrados, a sintaxe de 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 seu ambiente já isolar os processos):

sandbox_mode = "danger-full-access"

Política de ambiente do shell

shell_environment_policy controla quais variáveis de ambiente o Codex passa aos comandos que inicia. 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 contenham KEY, SECRET ou TOKEN. Defina-o como false para aplicar essas exclusões automáticas antes da execução dos 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 de 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 fica 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 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 de ambiente, ID da conversa, modelo, configurações de sandbox/aprovação e campos específicos de cada evento (consulte a 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 evento 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 de streaming, 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 (tamanho; 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, streaming e ferramentas.

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

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

Métricas

Por padrão, o Codex envia periodicamente à OpenAI uma pequena quantidade de dados anônimos sobre uso e funcionamento. 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 e rastreamentos do OTel.

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

[analytics]
enabled = false

Cada métrica inclui seus próprios campos e os 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 e os campos de contexto padrão acima. Os nomes das métricas abaixo omitem o prefixo codex.. A maioria dos nomes das 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 em si nem o 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 normais de chamadas 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 no Windows e podem incluir originator quando emitidas pelo fluxo compartilhado de configuração. A métrica windows_sandbox.legacy_setup_preflight_failed inclui originator quando emitida pelo fluxo compartilhado de configuração, mas as falhas de verificação preliminar no prompt de 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, no 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 envios de feedback.

Ocultar ou exibir eventos de raciocínio

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

hide_agent_reasoning = true

Para exibir o conteúdo bruto do raciocínio quando um modelo o emitir:

show_raw_agent_reasoning = true

Ative a exibição do 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, esta 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 no desktop, webhooks de chat, atualizações de CI ou qualquer alerta por canais adicionais que as notificações integradas da TUI não contemplem.

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 no disco e aponte notify para ele.

notify versus tui.notifications

• notify executa um programa externo (útil para webhooks, notificadores de desktop 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 do terminal que alguns terminais interpretam como uma notificação de desktop) 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 descarta as entradas mais antigas e compacta o arquivo, mantendo 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, o Codex pode exibir citações de arquivos como links clicáveis. Configure file_opener para escolher o esquema de URI usado pelo Codex:

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.

Descoberta 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 opções controlam esse comportamento:

• project_doc_max_bytes: quanto ler de cada arquivo AGENTS.md
• project_doc_fallback_filenames: nomes de arquivo adicionais a procurar quando AGENTS.md não estiver presente em um nível de diretório

Para ver 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 oferece suporte 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 segmento final 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, nas demais posições, conter apenas letras ASCII, números, pontos, sublinhados ou hífens. O aplicativo disponibiliza 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 oferece suporte a estes campos:

O valor de input controla o que vem após 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 cuja contagem começa em 1, ou null.
• json_stdin grava o objeto JSON na entrada padrão em vez de adicionar um argumento. Ele 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, incluindo as 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 ou 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 ou 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 uma notificação da á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.