Configuração avançada

Utilize estas opções quando precisar de maior controlo sobre fornecedores, políticas e integrações. Para começar rapidamente, consulte Noções básicas de configuração.

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

Perfis

Os perfis permitem guardar camadas de configuração com nome e alternar entre elas a partir da CLI. Quando fornece --profile profile-name, o Codex carrega ~/.codex/config.toml e, em seguida, sobrepõe ~/.codex/profile-name.config.toml. Os nomes de perfis podem conter letras, números, hífenes e sublinhados.

Crie um ficheiro TOML separado para cada perfil. Utilize chaves de configuração de nível superior no ficheiro de 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"

Uma vez que o ficheiro de perfil é uma camada acima da configuração base do utilizador e abaixo da configuração do projeto e da CLI, só precisa de conter os valores que diferem da configuração base. Os ficheiros de perfil também podem substituir model_catalog_json; o Codex utiliza o valor do perfil quando ambos os ficheiros o definem.

No Codex 0.134.0 e posteriores, --profile já não lê [profiles.profile-name] de config.toml, e o seletor de nível superior profile = "profile-name" deixou de ser suportado. Mova as definições de perfil legadas para ~/.codex/profile-name.config.toml e, em seguida, remova a tabela [profiles.profile-name] correspondente e o seletor profile = "profile-name" de config.toml.

Substituições pontuais a partir da CLI

Além de editar ~/.codex/config.toml, pode substituir a configuração para uma única execução a partir da CLI:

• Dê preferência a sinalizadores dedicados quando existirem (por exemplo, --model).
• Utilize -c / --config quando precisar de substituir 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"]'

Notas:

• As chaves podem utilizar notação de pontos 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 a shell não o divida nos espaços.
• Se não for possível analisar o valor como TOML, o Codex trata-o como uma cadeia de caracteres.

Localizações da configuração e do estado

O Codex armazena o respetivo estado local em CODEX_HOME (a predefinição é ~/.codex).

Ficheiros comuns que poderá encontrar nessa localização:

• config.toml (a sua configuração local)
• auth.json (se utilizar armazenamento de credenciais baseado em ficheiros) ou o porta-chaves do seu sistema operativo
• history.jsonl (se a persistência do histórico estiver ativada)
• Outro estado específico do utilizador, como registos e caches

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

Para obter informações sobre predefinições, regras e competências partilhadas e registadas em repositórios ou caminhos do sistema, consulte Configuração de equipa.

Se precisar apenas de encaminhar o fornecedor OpenAI incorporado para um proxy de LLM, um encaminhador ou um projeto com residência de dados ativada, defina openai_base_url em config.toml em vez de definir um novo fornecedor. Isto altera o URL base do fornecedor openai incorporado sem exigir uma entrada model_providers.<id> separada.

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

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

Além da configuração do utilizador, o Codex lê substituições ao nível do projeto a partir de ficheiros .codex/config.toml no repositório. O Codex percorre o caminho desde a raiz do projeto até ao diretório de trabalho atual e carrega todos os .codex/config.toml que encontra. Se vários ficheiros definirem a mesma chave, prevalece o ficheiro mais próximo do diretório de trabalho.

Por motivos de segurança, o Codex apenas carrega ficheiros de configuração ao nível do projeto quando este é considerado fidedigno. Se o projeto não for fidedigno, o Codex ignora as camadas .codex/ do projeto, incluindo .codex/config.toml, hooks locais do projeto e regras locais do projeto. As camadas do utilizador e do sistema permanecem separadas e continuam a ser carregadas.

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

Os ficheiros de configuração do projeto não podem substituir definições que redirecionem credenciais, alterem metadados de pedidos de aplicações controlados pelo anfitrião, alterem a autenticação do fornecedor, selecionem perfis de configuração ou executem comandos locais de notificação/telemetria. O Codex ignora as seguintes chaves no .codex/config.toml local do projeto e apresenta um aviso no arranque quando as deteta: 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 fornecedor, notificação e telemetria no seu ~/.codex/config.toml ao nível do utilizador; selecione perfis de configuração com --profile profile-name e ~/.codex/profile-name.config.toml.

Hooks

O Codex também pode carregar hooks de ciclo de vida a partir de ficheiros hooks.json ou de tabelas [hooks] inline em ficheiros config.toml adjacentes às camadas de configuração ativas.

Na prática, as quatro localizações mais úteis são:

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

Os hooks locais do projeto apenas são carregados quando a camada .codex/ do projeto é considerada fidedigna. Os hooks ao nível do utilizador permanecem independentes da confiança atribuída ao projeto.

Os hooks TOML inline utilizam a mesma estrutura de eventos que 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 única camada contiver hooks.json e [hooks] inline, o Codex carrega ambos e apresenta um aviso. Prefira uma única representação por camada.

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

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

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

Deteção da raiz do projeto

O Codex deteta a configuração do projeto (por exemplo, camadas .codex/ e AGENTS.md) percorrendo os diretórios ascendentes a partir do diretório de trabalho até alcançar uma raiz de projeto.

Por predefinição, o Codex considera um diretório que contenha .git como a raiz do projeto. Para personalizar este 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 ignorar a pesquisa nos diretórios superiores e tratar o diretório de trabalho atual como a raiz do projeto.

Fornecedores de modelos personalizados

Um fornecedor de modelos define a forma como o Codex se liga a um modelo (URL base, API de comunicação, autenticação e cabeçalhos HTTP opcionais). Os fornecedores personalizados não podem reutilizar os IDs de fornecedores incorporados reservados: openai, ollama e lmstudio.

Defina fornecedores adicionais e faça model_provider 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 fornecedor personalizado suportar o endpoint autónomo de pesquisa na Web, anuncie essa capacidade na respetiva configuração:

[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

A predefinição desta definição é false para fornecedores personalizados. A pesquisa autónoma na Web está em desenvolvimento e desativada por predefinição. Definir a capacidade do fornecedor como true não a ativa: o fornecedor tem de suportar um endpoint compatível, e o modelo e o ambiente de execução selecionados têm de suportar pesquisa autónoma. O modo web_search configurado e as restrições de pesquisa geridas continuam a aplicar-se.

Adicione cabeçalhos de pedido quando necessário:

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

Utilize autenticação baseada em comandos quando um fornecedor precisar que o Codex obtenha tokens bearer através de um auxiliar de credenciais externo:

[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 stdin e tem de imprimir o token em stdout. O Codex remove os espaços em branco circundantes, trata um token vazio como um erro e atualiza-o proativamente em refresh_interval_ms; defina refresh_interval_ms = 0 para o atualizar apenas após uma repetição da autenticação. Não combine [model_providers.<id>.auth] com env_key, experimental_bearer_token ou requires_openai_auth.

Fornecedor Amazon Bedrock

O Codex inclui um fornecedor de modelos amazon-bedrock incorporado. Defina-o diretamente como model_provider; ao contrário dos fornecedores personalizados, este fornecedor incorporado apenas suporta as 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 omitir profile, o Codex utiliza a cadeia de credenciais padrão da AWS. Defina region como a região Bedrock suportada que deverá processar os pedidos.

Para consultar o fluxo de configuração completo, as opções de autenticação, os modelos suportados e a disponibilidade das funcionalidades, consulte Utilizar o ChatGPT Work e o Codex com o Amazon Bedrock.

Modo OSS (fornecedores locais)

O Codex pode ser executado com um fornecedor local de «código aberto», como Ollama ou LM Studio, quando fornece --oss. Escolha um para uma única execução com --local-provider ou defina oss_provider como predefinição. Se nenhum estiver definido, a CLI interativa pede-lhe que escolha; codex exec termina com um erro.

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

Fornecedor Azure e ajuste por fornecedor

[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 o URL base do fornecedor OpenAI incorporado, utilize openai_base_url; não crie [model_providers.openai], porque não pode substituir IDs de fornecedores incorporados.

Clientes do ChatGPT que utilizam residência de dados

Os projetos criados com a residência de dados ativada podem criar um fornecedor de modelos para atualizar base_url com o prefixo correto.

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 detalhe 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 aplica-se apenas a fornecedores que utilizem a Responses API. Os fornecedores de Chat Completions ignoram esta definição.

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

Escolha o rigor da aprovação (afeta quando o Codex pausa) e o nível de sandbox (afeta o acesso a ficheiros e à rede).

Para obter detalhes operacionais a ter em conta ao editar config.toml, consulte Combinações comuns de sandbox e aprovação, Caminhos protegidos em raízes graváveis e Acesso à rede.

Para obter informações sobre perfis de permissões beta que configuram em conjunto o acesso ao sistema de ficheiros e à rede, consulte Permissões.

Também pode utilizar uma política de aprovação granular (approval_policy = { granular = { ... } }) para permitir ou rejeitar automaticamente categorias individuais de pedidos. Isto é útil quando pretende aprovações interativas normais para alguns casos, mas quer que outros, como request_permissions ou pedidos de scripts de competências, sejam automaticamente recusados em caso de dúvida.

Defina approvals_reviewer = "auto_review" para encaminhar pedidos de aprovação interativa elegíveis através de uma revisão automática. Isto altera o revisor, não o limite da sandbox.

Utilize [auto_review].policy para instruções locais da política do revisor. O valor gerido guardian_policy_config tem precedência.

approval_policy = "untrusted"   # Other options: on-request, 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 com nome

Para conhecer os perfis incorporados, a sintaxe de perfis personalizados e o modelo completo de configuração do sistema de ficheiros e da rede, consulte Permissões.

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

Desative completamente a sandbox (utilize esta opção apenas se o seu ambiente já isolar os processos):

sandbox_mode = "danger-full-access"

Política do ambiente da shell

shell_environment_policy controla as variáveis de ambiente que o Codex transmite aos comandos iniciados. Comece com um ambiente vazio utilizando inherit = "none" ou herde um conjunto reduzido utilizando inherit = "core". Adicione valores explícitos e filtros por chave para evitar transmitir 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 filtragem não distinguem maiúsculas de minúsculas e suportam * e ?. Utilize "exclude" para remover variáveis correspondentes. Quando um padrão utiliza "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á tenham sido excluídas. As chaves de filtragem são combinadas sem distinguir maiúsculas de minúsculas entre camadas de configuração.

A predefinição de ignore_default_excludes é true, pelo que o Codex não remove automaticamente nomes de variáveis que contenham KEY, SECRET ou TOKEN. Defina-a 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 dos padrões de inclusão. Uma vez que set é executado depois das exclusões, pode restaurar uma variável excluída. Uma lista de permissões de padrões de inclusão pode ainda remover esse valor restaurado.

As matrizes exclude e include_only mais antigas continuam a ser suportadas para configurações existentes. Não combine nenhuma das matrizes com [shell_environment_policy.filters] na mesma camada de configuração; o Codex rejeita essa combinação.

Servidores MCP

Consulte a documentação do MCP dedicada para obter detalhes de configuração.

Observabilidade e telemetria

Ative a exportação de registos OpenTelemetry (OTel) para acompanhar execuções do Codex (pedidos à API, SSE/eventos, pedidos, aprovações/resultados de ferramentas). Está desativada por predefinição; ative-a através 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 regista eventos, mas não envia nada. Os exportadores processam lotes de forma assíncrona e efetuam a descarga ao encerrar. Os metadados dos eventos incluem o nome do serviço, a versão da CLI, a etiqueta do ambiente, o ID da conversa, o modelo, as definições de sandbox/aprovação e campos específicos de cada evento (consulte a Referência de configuração).

Dados emitidos

O Codex emite eventos de registo estruturados relativos a execuções e à utilização de ferramentas. Entre os tipos de eventos representativos incluem-se:

• codex.conversation_starts (modelo, definições de raciocínio, política de sandbox/aprovação)
• codex.api_request (tentativa, estado/êxito, duração e detalhes do erro)
• codex.sse_event (tipo de evento da transmissão, êxito/falha, duração, além de contagens de tokens em response.completed)
• codex.websocket_request e codex.websocket_event (duração do pedido, além do tipo/êxito/erro de cada mensagem)
• codex.user_prompt (comprimento; conteúdo ocultado, salvo se explicitamente ativado)
• codex.tool_decision (aprovado/recusado e se a decisão teve origem na configuração ou no utilizador)
• codex.tool_result (duração, êxito, excerto 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 relativos à atividade da API, das transmissões e das ferramentas.

Cada métrica abaixo inclui também etiquetas de metadados predefinidas: auth_mode, originator, session_source, model e app.version.

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

Métricas

Por predefinição, o Codex envia periodicamente para a OpenAI uma pequena quantidade de dados anónimos de utilização e de estado de funcionamento. Isto ajuda a detetar quando o Codex não está a funcionar corretamente e mostra quais as funcionalidades e opções de configuração utilizadas, para que a equipa do Codex se possa concentrar no que é mais importante. Estas métricas não contêm informações de identificação pessoal (PII). A recolha de métricas é independente da exportação de registos/rastreios OTel.

Se pretender desativar completamente a recolha de métricas na aplicação de computador ChatGPT, na Codex CLI e na extensão IDE de uma máquina, defina o sinalizador de análise na sua configuração:

[analytics]
enabled = false

Cada métrica inclui os respetivos campos, além dos campos de contexto predefinidos abaixo.

Campos de contexto predefinidos (aplicáveis a todos os eventos/métricas)

• auth_mode: swic | api | unknown.
• model: nome do modelo utilizado.
• 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 predefinidos 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 funcionalidades emitidas fora desse ficheiro também estão incluídas aqui. Se uma métrica incluir o campo tool, este reflete a ferramenta interna utilizada (por exemplo, apply_patch ou shell) e não contém o comando de shell ou o patch que codex está a tentar 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; as emissões normais de chamadas de ferramentas também incluem tool, além de connector_id e connector_name quando disponíveis. As chamadas MCP bloqueadas das Codex Apps podem emitir mcp.call apenas com status.

Threads, tarefas e funcionalidades

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 competências incluem também skills_count.

Sandbox do Windows

As métricas de falha da configuração elevada incluem code e message quando estão disponíveis detalhes sobre a falha da configuração do Windows e podem incluir originator quando são emitidas a partir do caminho de configuração partilhado. A métrica windows_sandbox.legacy_setup_preflight_failed inclui originator quando é emitida a partir do caminho de configuração partilhado, mas as falhas de pré-verificação do pedido de contingência podem não incluir quaisquer campos.

Controlos de feedback

Por predefinição, os clientes locais permitem que os utilizadores enviem feedback a partir de /feedback. Para desativar a recolha de feedback na aplicação ChatGPT para computador, no Codex CLI e na extensão do IDE num computador, atualize a configuração:

[feedback]
enabled = false

Quando esta opção está desativada, /feedback apresenta uma mensagem de desativação e o Codex rejeita os envios de feedback.

Ocultar ou apresentar eventos de raciocínio

Se pretender reduzir resultados de "raciocínio" com demasiado ruído (por exemplo, nos registos de CI), pode suprimi-los:

hide_agent_reasoning = true

Se pretender apresentar o conteúdo de raciocínio em bruto quando um modelo o emite:

show_raw_agent_reasoning = true

Ative o raciocínio em bruto apenas se este for aceitável para o seu fluxo de trabalho. Alguns modelos/fornecedores (como gpt-oss) não emitem raciocínio em bruto; nesse caso, esta definição não tem qualquer efeito visível.

Notificações

Utilize notify para acionar um programa externo sempre que o Codex emitir eventos suportados (atualmente, apenas agent-turn-complete). Isto é útil para notificações no ambiente de trabalho, webhooks de conversação, atualizações de CI ou quaisquer alertas por canais alternativos que não sejam abrangidos pelas notificações incorporadas da TUI.

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 utilizador que deram origem ao turno)
• last-assistant-message (texto da última mensagem do assistente)

Coloque o script numa localização no disco e aponte notify para o mesmo.

notify em comparação com tui.notifications

• notify executa um programa externo (adequado para webhooks, notificadores do ambiente de trabalho e hooks de CI).
• tui.notifications está incorporado na TUI e pode, opcionalmente, filtrar por tipo de evento (por exemplo, agent-turn-complete e approval-requested).
• tui.notification_method controla a forma como a TUI emite notificações do terminal (auto, osc9 ou bel).
• tui.notification_condition controla se as notificações da TUI são acionadas apenas quando o terminal está unfocused ou 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 do ambiente de trabalho) e, caso contrário, recorre a BEL (\x07).

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

Persistência do histórico

Por predefinição, o Codex guarda 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 ficheiro de histórico, defina history.max_bytes. Quando o ficheiro excede o limite, o Codex elimina as entradas mais antigas e compacta o ficheiro, mantendo os registos mais recentes.

[history]
max_bytes = 104857600 # 100 MiB

Citações clicáveis

Se utilizar uma integração de terminal/editor que ofereça suporte para esta funcionalidade, o Codex pode apresentar as citações de ficheiros como ligações clicáveis. Configure file_opener para escolher o esquema de URI utilizado pelo Codex:

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

Exemplo: uma citação como /home/user/project/main.py:42 pode ser transformada numa ligação vscode://file/...:42 clicável.

Deteção das instruções do projeto

O Codex lê AGENTS.md (e ficheiros relacionados) e inclui uma quantidade limitada de orientações do projeto no primeiro turno de uma sessão. Duas opções controlam o funcionamento deste processo:

• project_doc_max_bytes: a quantidade a ler de cada ficheiro AGENTS.md
• project_doc_fallback_filenames: nomes de ficheiro adicionais a experimentar quando AGENTS.md não está presente num nível do diretório

Para obter instruções detalhadas, consulte Instruções personalizadas com AGENTS.md.

Computador

As opções desta secção aplicam-se apenas à aplicação ChatGPT para computador.

Adicionar processadores de ficheiros personalizados

No seu ~/.codex/config.toml ao nível do utilizador, adicione entradas em desktop.custom_file_handlers para abrir ficheiros em editores ou iniciadores internos que a aplicação ChatGPT para computador não suporta por predefinição. Cada entrada adiciona um destino de editor aos menus Abrir em da aplicação. A aplicação apresenta o destino quando command é um caminho absoluto existente ou pode ser resolvido a partir do PATH da aplicação.

O exemplo seguinte mostra três formas de passar um ficheiro para um processador:

# 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"

Guarde config.toml e, em seguida, reinicie a aplicação ChatGPT para computador.

O ID do processador é o segmento final do cabeçalho da tabela TOML. Deve conter entre 1 e 64 carateres, começar por uma letra ou um número ASCII e conter nos restantes carateres apenas letras ASCII, números, pontos, carateres de sublinhado ou hífenes. A aplicação expõe o ID com um prefixo custom:; por exemplo, company_editor torna-se custom:company_editor. Coloque entre aspas um ID que contenha um ponto para impedir que o TOML 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 processador suporta estes campos:

O valor input controla o que é apresentado após args:

• path acrescenta o caminho como argumento final do comando.
• json_argument acrescenta um objeto JSON com target, path, appPath e location. O valor location é um objeto com valores line e column de base 1, ou null.
• json_stdin escreve o objeto JSON na entrada padrão em vez de adicionar um argumento. Também inclui hostConfig, remoteWorkspaceRoot e remotePath; estes campos são null quando não se aplicam.

Por exemplo, company_editor pode receber este argumento quando o utilizador abre uma localização específica do código-fonte:

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

Selecionar um processador personalizado como editor preferido mantém a escolha da mesma forma que a seleção de um editor incorporado, incluindo preferências por projeto.

Opções da TUI

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

• tui.notifications: ativar/desativar notificações (ou restringi-las a tipos específicos)
• tui.notification_method: escolher auto, osc9 ou bel para as notificações do terminal
• tui.notification_condition: escolher unfocused ou always para determinar quando as notificações são acionadas
• tui.animations: ativar/desativar animações ASCII e efeitos de brilho
• tui.alternate_screen: controlar a utilização do ecrã alternativo (defina como never para manter o histórico de deslocamento do terminal)
• tui.show_tooltips: mostrar ou ocultar sugestões de integração no ecrã de boas-vindas

A predefinição de tui.notification_method é auto. 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 do ambiente de trabalho) quando o terminal parece oferecer suporte para as mesmas e, caso contrário, recorre a BEL (\x07).

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