Sinalizadores de diagnóstico

Os sinalizadores de diagnóstico ativam registros adicionais para um subsistema sem elevar logging.level globalmente. Um sinalizador não tem efeito, a menos que um subsistema o verifique.

Como funciona

• Os sinalizadores são strings que não diferenciam maiúsculas de minúsculas, resolvidas a partir de diagnostics.flags na configuração mais a substituição pela variável de ambiente OPENCLAW_DIAGNOSTICS, com duplicatas removidas e convertidas para minúsculas.
• name.* corresponde ao próprio name e a tudo sob name. (por exemplo, telegram.* corresponde a telegram.http).
• * ou all ativa todos os sinalizadores.
• Reinicie o Gateway após alterar diagnostics.flags na configuração; essa opção não é recarregada dinamicamente.

Sinalizadores conhecidos

Ativar pela configuração

{  "diagnostics": {    "flags": ["telegram.http"]  }}

Vários sinalizadores:

{  "diagnostics": {    "flags": ["telegram.http", "brave.http", "gateway.*"]  }}

Substituição por variável de ambiente (uso pontual)

OPENCLAW_DIAGNOSTICS=telegram.http,brave.http

Os valores são separados por vírgulas ou espaços em branco. Valores especiais:

OPENCLAW_DIAGNOSTICS=0 desativa os sinalizadores provenientes tanto da variável de ambiente quanto da configuração para esse processo, o que é útil para silenciar temporariamente um sinalizador de profiler mantido ativo na configuração sem editar o arquivo.

Sinalizadores de profiler

Os sinalizadores de profiler controlam intervalos leves de medição de tempo; quando desativados, não adicionam sobrecarga.

Ative todos os intervalos controlados por profiler para uma execução do Gateway:

OPENCLAW_DIAGNOSTICS=profiler openclaw gateway run

Ative somente os intervalos do profiler de encaminhamento de respostas:

OPENCLAW_DIAGNOSTICS=reply.profiler openclaw gateway run

Ative somente os intervalos do profiler de inicialização/ferramentas/threads do servidor de aplicativo Codex:

OPENCLAW_DIAGNOSTICS=codex.profiler openclaw gateway run

profiler ativa tanto o profiler de resposta quanto o profiler do Codex; use os nomes de sinalizadores com escopo para ativar apenas um deles.

Ou defina-os na configuração:

{  "diagnostics": {    "flags": ["reply.profiler", "codex.profiler"]  }}

Reinicie o Gateway após alterar os sinalizadores de configuração. Para desativar um sinalizador de profiler, remova-o de diagnostics.flags e reinicie, ou inicie o processo com OPENCLAW_DIAGNOSTICS=0 para substituir todos os sinalizadores de diagnóstico nessa execução.

Artefatos de linha do tempo

O sinalizador timeline (alias: diagnostics.timeline) grava eventos estruturados de medição de tempo da inicialização e da execução como JSONL, para mecanismos externos de QA:

OPENCLAW_DIAGNOSTICS=timeline \OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=/tmp/openclaw-timeline.jsonl \openclaw gateway run

Ou ative-o na configuração:

{  "diagnostics": {    "flags": ["timeline"]  }}

O caminho de saída sempre vem de OPENCLAW_DIAGNOSTICS_TIMELINE_PATH, mesmo quando o próprio sinalizador é definido na configuração; não há uma chave de configuração para o caminho. Quando timeline é ativado somente pela configuração, os primeiros intervalos de carregamento da configuração ficam ausentes porque o OpenClaw ainda não leu a configuração; os intervalos subsequentes da inicialização são capturados normalmente.

OPENCLAW_DIAGNOSTICS=1, =all e =* também ativam a linha do tempo, pois ativam todos os sinalizadores. Prefira o sinalizador específico timeline quando quiser somente o artefato JSONL, e não todos os outros sinalizadores de diagnóstico.

As amostras de atraso do loop de eventos na linha do tempo exigem uma ativação adicional além de timeline: defina OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1 (ou on/true/yes) além de ativar a linha do tempo.

Os registros da linha do tempo usam o envelope openclaw.diagnostics.v1 e podem incluir IDs de processos, nomes de fases, nomes de intervalos, durações, IDs de plugins, contagens de dependências, amostras de atraso do loop de eventos, nomes de operações do provedor, estado de saída de processos filhos e nomes/mensagens de erros de inicialização. Trate os arquivos de linha do tempo como artefatos locais de diagnóstico; revise-os antes de compartilhá-los fora da sua máquina.

Destino dos registros

Os sinalizadores emitem registros no arquivo padrão de diagnóstico. Por padrão:

/tmp/openclaw/openclaw-YYYY-MM-DD.log

Se você definir logging.file, use esse caminho. Os registros estão no formato JSONL (um objeto JSON por linha). A ocultação ainda é aplicada com base em logging.redactSensitive. Consulte Registro em log para ver o modelo completo de resolução do caminho dos registros, rotação e ocultação.

Extrair registros

Selecione o arquivo de registro mais recente:

ls -t /tmp/openclaw/openclaw-*.log | head -n 1

Filtre os diagnósticos HTTP do Telegram:

rg "telegram http error" /tmp/openclaw/openclaw-*.log

Filtre os diagnósticos HTTP do Brave Search:

rg "brave http" /tmp/openclaw/openclaw-*.log

Ou acompanhe enquanto reproduz o problema:

tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"

Para Gateways remotos, use openclaw logs --follow (consulte /cli/logs).

Observações

• Se logging.level estiver definido com um nível superior a warn, os registros controlados por sinalizadores poderão ser suprimidos. O valor padrão info é adequado.
• brave.http registra URLs/parâmetros de consulta das solicitações do Brave Search, status/tempo das respostas e eventos de acerto/falha/gravação no cache. Ele não registra a chave da API (enviada como cabeçalho da solicitação) nem os corpos das respostas, mas as consultas de pesquisa podem ser confidenciais.
• É seguro manter os sinalizadores ativados; eles afetam somente o volume de registros do subsistema específico.
• Use /logging para alterar destinos, níveis e ocultação dos registros.

Relacionado

• Diagnóstico do Gateway
• Solução de problemas do Gateway