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 de contexto 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 dos 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 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 ficheiro do 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 deixou de ler [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 perfis 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 através da CLI

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

• Dê preferência a opções dedicadas 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 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 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 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 por utilizador, como registos e caches

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

Para conhecer as predefinições, regras e competências partilhadas que são integradas nos repositórios ou em caminhos do sistema, consulte Configuração de equipa.

Se apenas precisar de encaminhar o fornecedor OpenAI incorporado para um proxy de LLM, um router 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 cada .codex/config.toml que encontrar. 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 só 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 de notificação/telemetria locais da máquina. O Codex ignora as seguintes chaves em .codex/config.toml local do projeto e apresenta um aviso no arranque 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 do fornecedor, de notificação e de telemetria no ficheiro ~/.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 do ciclo de vida a partir de ficheiros hooks.json ou de tabelas [hooks] inline em ficheiros config.toml situados junto das 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 só 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. Dê preferência a uma única representação por camada.

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

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

Para obter informações sobre a configuração das funções dos subagentes ([agents] em config.toml), consulte Subagentes.

Deteção da raiz do projeto

O Codex descobre 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 a raiz de um 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 reservados dos fornecedores incorporados: openai, ollama e lmstudio.

Defina fornecedores adicionais e direcione model_provider para os mesmos:

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, declare 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 é 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 a pesquisa autónoma. O modo web_search configurado e as restrições de pesquisa geridas continuam a aplicar-se.

Adicione cabeçalhos de pedidos 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 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 nova tentativa de 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 suporta apenas as substituições aninhadas do perfil e da 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 para a região Bedrock suportada que deverá processar os pedidos.

Para obter 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], pois não pode substituir IDs de fornecedores incorporados.

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

Os projetos criados com a residência de dados ativada podem criar um fornecedor de modelos para atualizar o base_url com o prefixo correto. Para espaços de trabalho do ChatGPT com residência de dados, não é necessário um fornecedor personalizado; o Codex respeita as definições de residência do espaço de trabalho quando inicia sessão 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 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 grau de rigor da aprovação (que afeta quando o Codex faz uma pausa) e o nível da sandbox (que 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.

O Codex e o ChatGPT Work já não suportam approval_policy = "untrusted". Consulte Migrar da política de aprovação descontinuada untrusted para conhecer as definições suportadas e as aprovações mais rigorosas baseadas no projeto.

Para obter informações sobre os perfis de permissões beta que configuram conjuntamente 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 em alguns casos, mas quer que outros, como request_permissions ou pedidos de scripts de competências, sejam automaticamente recusados de forma segura.

Defina approvals_reviewer = "auto_review" para encaminhar os pedidos de aprovação interativa elegíveis através da 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. A definição gerida 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 com nome

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

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

Desative totalmente a sandbox (utilize 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 baseados em chaves 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 dos filtros não distinguem maiúsculas de minúsculas e suportam * e ?. Utilize "exclude" para remover as 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 repõem variáveis que já tenham sido excluídas. As chaves dos filtros são combinadas entre as camadas de configuração sem distinção entre maiúsculas e minúsculas.

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 do padrão de inclusão. Como set é executado depois das exclusões, pode repor uma variável excluída. Uma lista de permissões do padrão de inclusão pode ainda remover esse valor reposto.

As matrizes exclude e include_only mais antigas continuam a ser suportadas nas configurações existentes. Não combine nenhuma destas 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 do OpenTelemetry (OTel) para acompanhar as execuções do Codex (pedidos da 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" }
}}

Com exporter = "none", o Codex regista os eventos, mas não envia nada. Os exportadores processam os lotes de forma assíncrona e descarregam-nos no encerramento. 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 os campos específicos de cada evento (consulte a Referência de configuração).

Dados emitidos

O Codex emite eventos de registo estruturados relativos às execuções e à utilização de ferramentas. Alguns tipos de eventos representativos incluem:

• 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 do fluxo, êxito/falha, duração e contagens de tokens em response.completed)
• codex.websocket_request e codex.websocket_event (duração do pedido e tipo/êxito/erro de cada mensagem)
• codex.user_prompt (comprimento; conteúdo ocultado, exceto 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, dos fluxos e das ferramentas.

Cada métrica abaixo também inclui 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 à OpenAI uma pequena quantidade de dados anónimos sobre utilização e estado de funcionamento. Isto ajuda a detetar situações em que 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 totalmente a recolha de métricas na aplicação ChatGPT para computador, na Codex CLI e na extensão IDE de uma máquina, defina o indicador de análise na configuração:

[analytics]
enabled = false

Cada métrica inclui os respetivos campos, bem como os 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 e os campos de contexto predefinidos 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; também se incluem aqui as métricas específicas de funcionalidades emitidas fora desse ficheiro. 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 real da shell nem o patch que codex está a tentar aplicar.

Ambiente de execução e transporte de modelos

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 do 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 também incluem skills_count.

Sandbox do Windows

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

Controlos de comentários

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

[feedback]
enabled = false

Quando está desativada, /feedback apresenta uma mensagem indicando a desativação e o Codex rejeita o envio de comentários.

Ocultar ou apresentar eventos de raciocínio

Se pretender reduzir a saída de "raciocínio" com ruído (por exemplo, nos registos de CI), pode suprimi-la:

hide_agent_reasoning = true

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

show_raw_agent_reasoning = true

Ative o raciocínio em bruto apenas se 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 não abrangidos pelas notificações integradas da TUI.

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

Exemplo de notify.py (abreviado) 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 de ambiente de trabalho e hooks de CI).
• tui.notifications está integrado 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 o suporte, o Codex pode apresentar 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 convertida numa ligação vscode://file/...:42 clicável.

Deteção de 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 definições controlam este funcionamento:

• project_doc_max_bytes: quantidade a ler de cada ficheiro AGENTS.md
• project_doc_fallback_filenames: nomes de ficheiro adicionais a experimentar quando AGENTS.md não existe 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 suporte 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 a 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. Tem de conter entre 1 e 64 caracteres, começar por uma letra ou um número ASCII e, nos restantes caracteres, conter apenas letras ASCII, números, pontos, caracteres 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 se segue a 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 indexados a partir de 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 são aplicáveis.

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

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

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

Opções da TUI

A execução de codex sem um subcomando inicia a interface de terminal interativa (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 definir quando as notificações são acionadas
• tui.animations: ativar/desativar animações ASCII e efeitos cintilantes
• 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 introduçã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 suportá-las e, caso contrário, recorre a BEL (\x07).

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