Configuração avançada

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

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

Como aplicar estes exemplos ao acesso ao computador local com o modo Work na nuvem

Estes exemplos descrevem a configuração do Codex. Consulte a Referência de configuração antes de adaptá-los ao acesso ao computador local com o modo Work na nuvem.

• Escopo das políticas: No modo Work com acesso local e nos dots, quando a política gerenciada está habilitada, o orquestrador compartilhado na nuvem segue as disposições compatíveis da política global. O computador conectado segue os requisitos de execução local aplicáveis. Os contêineres do modo Work na nuvem continuam seguindo as políticas existentes do modo Work na nuvem.
• Execução local: Os requisitos de MDM e os requisitos legados para dispositivos gerenciados têm precedência sobre a Segurança do agente. A Segurança do agente, por sua vez, tem precedência sobre o arquivo de requisitos do sistema do dispositivo.
• Hooks corporativos: Quando habilitado para o espaço de trabalho, esse recurso oferece suporte a hooks MCP definidos por administradores. Eles são executados no coordenador da nuvem (orquestrador) em eventos compatíveis do ciclo de vida e das ferramentas. A orquestração na nuvem não oferece suporte a hooks de comando nem a hooks provenientes da configuração local ou de plugins, mesmo quando as ferramentas são executadas localmente.
• Auditoria: Antes de usar esses hooks para auditoria, teste a conexão de callback, confirme quais eventos ela recebe e verifique como as falhas afetam a tarefa. Os hooks MCP não fornecem uma trilha de auditoria completa da API de Compliance.
• Outras configurações: A configuração gerenciada não transfere provedores de modelos personalizados nem caminhos locais do host para esse recurso. Consulte as restrições de rede e as regras de mesclagem de cada campo em Configuração gerenciada.

Consulte Hooks para saber quais recursos são compatíveis e como configurá-los.

Perfis

Os perfis permitem salvar camadas de configuração com nomes próprios e alternar entre elas pela CLI. Quando você passa --profile profile-name, o Codex carrega ~/.codex/config.toml e, em seguida, aplica a configuração de ~/.codex/profile-name.config.toml sobre ela. Os nomes dos perfis podem conter letras, números, hífens e sublinhados.

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

O exemplo usa o GPT-6.1 Sol. Para usá-lo, a conta ou o espaço de trabalho com que você fez login precisa ter acesso ao modelo. Se ele estiver indisponível, escolha um modelo ao qual você tenha acesso.

1
2
3
4
5# ~/.codex/deep-review.config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
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"

O arquivo de perfil tem precedência sobre a configuração básica do usuário, mas fica abaixo das configurações do projeto e da CLI. Por isso, basta incluir nele os valores que diferem da configuração básica. Os arquivos de perfil também podem substituir model_catalog_json. Quando os dois arquivos definem essa chave, o Codex usa o valor do perfil.

A partir do Codex 0.134.0, --profile deixou de ler [profiles.profile-name] de config.toml, e o Codex deixou de aceitar o seletor de nível superior profile = "profile-name". Mova as configurações legadas do perfil para ~/.codex/profile-name.config.toml e remova a tabela [profiles.profile-name] correspondente e o seletor profile = "profile-name" de config.toml.

Como substituir configurações em uma única execução pela CLI

Você pode editar ~/.codex/config.toml ou substituir configurações em uma única execução pela CLI:

• Prefira opções específicas quando disponíveis (por exemplo, --model).
• Use -c / --config para substituir o valor de uma chave qualquer.

Os exemplos abaixo que selecionam o GPT-6.1 Sol também exigem acesso a esse modelo. Se você não tiver acesso, substitua-o por um modelo disponível para você:

1
2
3
4
5
6# Dedicated flag
codex --model gpt-6.1-sol
# Generic key/value override (value is TOML, not JSON)
codex --config model='"gpt-6.1-sol"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

Observações:

• As chaves podem usar notação de ponto para definir valores aninhados (por exemplo, mcp_servers.context7.enabled=false).
• Os valores de --config são interpretados como TOML. Na dúvida, coloque o valor entre aspas para que o shell não o divida nos espaços.
• Se não conseguir interpretar o valor como TOML, o Codex o tratará como uma string.

Onde ficam a configuração e os dados de estado

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

Entre os arquivos e dados mais comuns estão:

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

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

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

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

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ê configurações 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 valor do arquivo mais próximo do diretório de trabalho.

Por segurança, o Codex só carrega os arquivos de configuração específicos do projeto 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, os hooks locais e as regras locais do projeto. As camadas do usuário e do sistema são independentes e continuam sendo carregadas.

Caminhos relativos na configuração de um projeto (por exemplo, model_instructions_file) são resolvidos a partir da pasta .codex/ que contém o config.toml.

Os arquivos de configuração do projeto não podem substituir configurações que redirecionam credenciais, alteram metadados de solicitações de aplicativos sob controle do host, mudam a autenticação do provedor, selecionam perfis de configuração ou executam comandos de notificação ou telemetria na máquina local. O Codex ignora as seguintes chaves no arquivo .codex/config.toml 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. Para selecionar perfis de configuração, use --profile profile-name e ~/.codex/profile-name.config.toml.

Hooks

O Codex também pode carregar hooks do ciclo de vida a partir de arquivos hooks.json ou de tabelas [hooks] definidas diretamente nos arquivos config.toml que ficam 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 hooks locais do projeto só são carregados quando a camada .codex/ do projeto é confiável. Os hooks do usuário independem da confiança atribuída ao projeto.

Os hooks 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 a mesma camada contiver tanto hooks.json quanto uma tabela [hooks], o Codex carregará ambos e exibirá um aviso. Prefira um único formato por camada.

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

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

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

Detecção da raiz do projeto

O Codex localiza a configuração do projeto (por exemplo, camadas .codex/ e arquivos AGENTS.md) percorrendo os diretórios superiores a partir do diretório de trabalho até encontrar a raiz do projeto.

Por padrão, o Codex considera como raiz do projeto um diretório que contém .git. 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 pular a busca nos diretórios superiores e usar o diretório de trabalho atual como raiz do projeto.

Provedores de modelos personalizados

Se sua organização oferece um gateway de modelos, siga as instruções em Conectar-se a um gateway para configurar e verificar o cliente. Para implantar o gateway em toda a organização, consulte Implantar um gateway.

Um provedor de modelos define como o Codex se conecta a um modelo, incluindo a URL base, a API de comunicação, a autenticação e os cabeçalhos HTTP opcionais. Escolha um ID exclusivo para cada provedor personalizado. O Codex reserva os IDs openai, ollama, lmstudio, amazon-bedrock, amazon-bedrock-runtime e gcp para seus provedores integrados.

Defina outros provedores e use model_provider para indicar qual deles usar:

1
2
3
4
5
6
7
8
9
10
11
12
13model = "gpt-6.1-sol"
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 esse recurso 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 independente na Web está em desenvolvimento e vem desativada por padrão. Definir o recurso do provedor como true não basta para ativá-lo. O provedor precisa oferecer um endpoint compatível, e tanto o modelo selecionado quanto o ambiente de execução precisam oferecer suporte à pesquisa independente. O modo de web_search configurado e as restrições gerenciadas de pesquisa continuam valendo.

Adicione cabeçalhos às solicitações quando necessário:

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

Para fazer login pelo navegador com o provedor de identidade da organização, use o OAuth nativo do gateway. Configure [model_providers.<id>.gateway_oauth] com as URLs de autorização e de token, o ID público do cliente e as configurações de envio do token. Essa opção funciona com requires_openai_auth = false e dispensa o login com o ChatGPT, o PowerShell, a CLI do Azure e um utilitário externo de credenciais. O gateway precisa aceitar o token OAuth no cookie ou no cabeçalho personalizado configurado.

Use a autenticação por comando quando o provedor exigir que o Codex obtenha tokens de portador de um utilitário 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 em stdin e precisa escrever o token na saída padrão. O Codex remove os espaços em branco no início e no fim, trata um token vazio como erro e renova o token antecipadamente no intervalo definido por refresh_interval_ms. Defina refresh_interval_ms = 0 para renovar o token somente após uma nova tentativa de autenticação. Não combine [model_providers.<id>.auth] com env_key, experimental_bearer_token ou requires_openai_auth.

Provedor do Amazon Bedrock

Defina model_provider como amazon-bedrock para usar o endpoint do Bedrock Mantle ou como amazon-bedrock-runtime para usar o endpoint do Runtime. Para selecionar as credenciais e a região da AWS para o Mantle, configure a tabela aws desse provedor.

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 como a região compatível do Bedrock que deverá processar as solicitações.

Para ver todas as etapas 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.

Provedor do Google Cloud Vertex AI

Para usar um modelo ao qual seu projeto tem acesso no Vertex AI, defina o provedor integrado em config.toml.

model_provider = "gcp"

[model_providers.gcp]
project_id = "my-project"
location = "global"

Se você omitir project_id ou location, o Codex lerá GOOGLE_CLOUD_PROJECT ou GOOGLE_CLOUD_LOCATION, respectivamente. O local padrão é global.

Para usar a autenticação padrão, instale a CLI do Google Cloud na máquina que executa o Codex. Para fazer login localmente, execute gcloud auth application-default login. O Codex executa gcloud auth application-default print-access-token para obter tokens de acesso.

Para usar um arquivo ADC específico, defina credential_file com o caminho absoluto do arquivo na tabela [model_providers.gcp]. O Codex atribui esse caminho à variável GOOGLE_APPLICATION_CREDENTIALS ao executar o comando de autenticação.

Se sua implantação usar outro endpoint, um comando diferente para obter tokens ou cabeçalhos estáticos, configure base_url, auth ou http_headers, conforme o caso, em [model_providers.gcp].

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 provedor para uma única execução com --local-provider ou defina o provedor padrão em oss_provider. Se você não definir nenhum dos dois, a CLI interativa pedirá que escolha um provedor. Nesse caso, codex exec encerrará a execução com um erro.

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

Provedor do 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 substituir os IDs dos provedores integrados.

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

Em projetos criados com a residência de dados habilitada, você pode criar um provedor de modelos para atualizar base_url com o prefixo correto. Espaços de trabalho do ChatGPT com residência de dados dispensam um provedor personalizado. Quando você faz login com o ChatGPT, o Codex respeita as configurações de residência do espaço de trabalho.

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 detalhe e limites do modelo

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

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

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

Escolha o rigor da política de aprovação, que determina quando o Codex pausa, e o nível da sandbox, que determina o acesso a arquivos e à rede.

Para saber como editar config.toml, consulte Combinações comuns de sandbox e aprovação, Caminhos protegidos em raízes com permissão de gravação e Acesso à rede.

O Codex e o ChatGPT Work deixaram de oferecer suporte a approval_policy = "untrusted". Consulte Migrar da política de aprovação descontinuada untrusted para conhecer as configurações compatíveis e as opções mais rigorosas para aprovações decorrentes da configuração do projeto.

Para saber mais sobre os perfis de permissão em versão 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. Assim, você mantém as aprovações interativas habituais em alguns casos e nega automaticamente outras solicitações, como as de request_permissions ou de execução de scripts de habilidades.

Defina approvals_reviewer = "auto_review" para encaminhar as solicitações de aprovação interativa elegíveis à Revisão automática. Para substituir a política do revisor, consulte Configuração da Revisão automática.

approval_policy = "on-request"  # Other options: never or { granular = { ... } }
approvals_reviewer = "user"     # Or "auto_review" for Auto-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

Perfis de permissão nomeados

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

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

Para desativar completamente o ambiente isolado, use a configuração abaixo somente se o 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 de variáveis com inherit = "core". Adicione valores explícitos e filtros por chave para evitar passar segredos desnecessários aos comandos.

[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 diferenciam maiúsculas de minúsculas e aceitam * e ?. Use "exclude" para remover as variáveis que correspondem ao padrão. Quando algum padrão usa "include", o Codex mantém apenas as variáveis que correspondem a um padrão de inclusão. Os filtros de inclusão não restauram variáveis já excluídas. Ao mesclar as chaves de filtro de diferentes camadas de configuração, o Codex não diferencia maiúsculas de minúsculas.

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

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

As listas legadas exclude e include_only continuam compatíveis com as configurações existentes. Não combine nenhuma delas 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 para obter detalhes sobre a configuração.

Observabilidade e telemetria

Habilite a exportação de logs do OpenTelemetry (OTel) para acompanhar as execuções do Codex, incluindo solicitações à API, eventos SSE e outros eventos, prompts, aprovações e resultados de ferramentas. A exportação vem desativada por padrão. Para ativá-la, use [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

Os administradores podem definir quais exportadores e configurações individuais de log são obrigatórios em requirements.toml.

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 registra os eventos sem enviá-los. Os exportadores agrupam os eventos em lotes de forma assíncrona e enviam os dados pendentes no encerramento. Os metadados dos eventos incluem o nome do serviço, a versão da CLI, a etiqueta de ambiente, o ID da conversa, o modelo, as configurações de sandbox e aprovação e campos específicos de cada evento (consulte a Referência de configuração).

Eventos emitidos

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

• codex.conversation_starts (modelo, configurações de raciocínio e política de sandbox e aprovação)
• codex.api_request (tentativa, status, indicação de sucesso, duração e detalhes do erro)
• codex.sse_event (tipo de evento do fluxo, sucesso ou falha, duração e contagem de tokens em response.completed)
• codex.websocket_request e codex.websocket_event (duração da solicitação e, para cada mensagem, tipo, indicação de sucesso e erro)
• codex.user_prompt (comprimento do prompt, com o conteúdo oculto a menos que seu registro seja habilitado explicitamente)
• codex.agent_response (respostas finais do agente principal e dos subagentes iniciados, registradas quando otel.log_agent_responses = true)
• codex.guardian_assessment (revisões automáticas de solicitações de aprovação já concluídas, registradas quando otel.log_guardian_assessments = true)
• codex.tool_decision (aprovação ou recusa e se a decisão veio da configuração ou do usuário)
• codex.tool_result (duração, indicação de sucesso e trecho da saída)

Métricas OTel emitidas

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

Cada métrica abaixo também inclui as etiquetas 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 um pequeno volume de dados anônimos sobre uso e funcionamento. Esses dados ajudam a detectar problemas no Codex e mostram quais recursos e opções de configuração estão em uso, para que a equipe do Codex possa definir prioridades. As métricas não contêm informações de identificação pessoal (PII). A coleta de métricas independe da exportação de logs e rastreamentos do OTel.

Para desativar a análise de uso e o exportador de métricas integrado statsig, defina a opção de análise na configuração:

[analytics]
enabled = false

Para desativar também um exportador personalizado de métricas OTLP, defina otel.metrics_exporter = "none".

Cada métrica inclui seus próprios campos e os campos de contexto padrão abaixo.

Campos de contexto padrão (presentes em 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 descritos acima. Os nomes das métricas abaixo omitem o prefixo codex.. A maioria dos nomes de métricas fica em codex-rs/otel/src/metrics/names.rs. O catálogo também inclui métricas de recursos específicos emitidas fora desse arquivo. Quando uma métrica inclui o campo tool, ele indica a ferramenta interna usada (por exemplo, apply_patch ou shell). O campo não contém o comando de shell que o codex tenta executar nem o patch que tenta aplicar.

Ambiente de execução e transporte de dados 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 dos turnos e das ferramentas

As métricas mcp.call e mcp.call.duration_ms incluem status. Em chamadas normais de ferramentas, também incluem tool e, quando disponíveis, connector_id e connector_name. Chamadas MCP bloqueadas nos 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 de configuração com privilégios elevados incluem code e message quando há detalhes sobre a falha de configuração do Windows. Também podem incluir originator quando emitidas pelo fluxo de configuração compartilhado. A métrica windows_sandbox.legacy_setup_preflight_failed inclui originator quando emitida pelo fluxo de configuração compartilhado, mas as falhas na verificação preliminar da solicitação com alternativas podem não incluir nenhum campo.

Controles de feedback

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

[feedback]
enabled = false

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

Ocultar ou exibir eventos de raciocínio

Para reduzir o ruído causado pela saída de “raciocínio”, por exemplo, nos logs de CI, você pode ocultá-la:

hide_agent_reasoning = true

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

show_raw_agent_reasoning = true

Habilite a exibição do raciocínio bruto somente se isso for aceitável no seu fluxo de trabalho. Alguns modelos ou provedores, como gpt-oss, não emitem raciocínio bruto. Nesse caso, a configuração não tem efeito visível.

Notificações

Use notify para acionar um programa externo sempre que o Codex emitir um evento compatível (atualmente, apenas agent-turn-complete). Essa opção é útil para notificações na área de trabalho, webhooks de chat, atualizações de CI ou alertas por outros canais que as notificações integradas da TUI não abrangem.

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

Exemplo abreviado de notify.py que reage a agent-turn-complete:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35#!/usr/bin/env python3
import argparse
import json
import subprocess
import sys


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Show a Codex turn-completion notification on macOS."
    )
    parser.add_argument("notification", type=json.loads, help="Codex notification JSON")
    notification = parser.parse_args().notification
    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. Entre os campos comuns estão:

• 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 no disco e indique seu caminho em notify.

Diferenças entre notify e tui.notifications

• notify executa um programa externo (útil para webhooks, notificadores de desktop e hooks de CI).
• tui.notifications é um recurso integrado à TUI que permite filtrar as notificações 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 determina se as notificações da TUI são emitidas 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 que alguns terminais interpretam como notificação de desktop) e 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, preservando os registros mais recentes.

[history]
max_bytes = 104857600 # 100 MiB

Citações clicáveis

Se a integração entre o terminal e o editor oferecer suporte ao recurso, o Codex poderá 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

Por exemplo, uma citação como /home/user/project/main.py:42 pode ser convertida em um link clicável como vscode://file/...:42.

Como o Codex localiza as instruções do projeto

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

• project_doc_max_bytes: quantidade de dados a ler de cada arquivo AGENTS.md
• project_doc_fallback_filenames: outros nomes de arquivo a procurar quando não houver AGENTS.md em determinado nível da hierarquia de diretórios

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

Desktop

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

Adicionar manipuladores de arquivos personalizados

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

O exemplo a seguir mostra três maneiras de passar um arquivo a 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 ChatGPT para desktop.

O ID do manipulador é o último segmento do cabeçalho da tabela TOML. Ele deve ter de 1 a 64 caracteres e começar com uma letra ou um número ASCII. Os demais caracteres podem ser apenas letras ou números ASCII, 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 os IDs que contêm ponto para que o TOML não os interprete como tabelas aninhadas. Por exemplo:

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

Cada manipulador aceita os seguintes campos:

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

• path acrescenta o caminho como último argumento do comando.
• json_argument acrescenta um objeto JSON com target, path, appPath e location. O valor de location é um objeto com line e column numerados a partir de 1, ou null.
• json_stdin escreve o objeto JSON na entrada padrão em vez de acrescentar um argumento. O objeto 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 um ponto específico do código-fonte:

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

Quando você seleciona um manipulador personalizado como editor preferido, o aplicativo salva a escolha da mesma forma que para um editor integrado, inclusive nas preferências específicas de cada projeto.

Opções da TUI

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

• tui.notifications: habilitar ou desabilitar 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 emitir notificações
• tui.animations: habilitar ou desabilitar animações ASCII e efeitos de brilho
• tui.alternate_screen: controlar o uso da tela alternativa (defina como never para preservar o histórico de rolagem do terminal)
• tui.show_tooltips: mostrar ou ocultar as dicas de introdução na tela de boas-vindas

O valor 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 que alguns terminais interpretam como notificação de desktop) 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.