Flags de diagnóstico

Os sinalizadores de diagnóstico permitem ativar logs de depuração direcionados sem habilitar logs detalhados em todos os lugares. Os sinalizadores são opcionais e não têm efeito a menos que um subsistema os verifique.

# Como funciona

• Os sinalizadores são strings (sem diferenciar maiúsculas de minúsculas).
• Você pode ativar sinalizadores na configuração ou por meio de uma substituição de env.
• Curingas são compatíveis:
  • telegram.* corresponde a telegram.http
  • * ativa todos os sinalizadores

# Ativar via configuração

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

Vários sinalizadores:

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

Reinicie o gateway após alterar os sinalizadores.

# Substituição por env (uso único)

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Desativar todos os sinalizadores:

OPENCLAW_DIAGNOSTICS=0

# Artefatos de linha do tempo

O sinalizador timeline grava eventos estruturados de temporização de inicialização e execução para estruturas externas de QA:

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

Você também pode ativá-lo na configuração:

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

O caminho do arquivo de linha do tempo ainda vem de OPENCLAW_DIAGNOSTICS_TIMELINE_PATH. Quando timeline é ativado apenas pela configuração, os primeiros intervalos de carregamento da configuração não são emitidos porque o OpenClaw ainda não leu a configuração; os intervalos subsequentes de inicialização usam o sinalizador da configuração.

OPENCLAW_DIAGNOSTICS=1, OPENCLAW_DIAGNOSTICS=all e OPENCLAW_DIAGNOSTICS=* também ativam a linha do tempo porque ativam todos os sinalizadores de diagnóstico. Prefira timeline quando você quiser apenas o artefato de temporização JSONL.

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

# Para onde vão os logs

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

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

Se você definir logging.file, use esse caminho em vez disso. Os logs são JSONL (um objeto JSON por linha). A redação ainda se aplica com base em logging.redactSensitive.

# Extrair logs

Escolha o arquivo de log mais recente:

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

Filtre diagnósticos HTTP do Telegram:

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

Filtre diagnósticos HTTP do Brave Search:

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

Ou acompanhe enquanto reproduz:

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

Para gateways remotos, você também pode usar openclaw logs --follow (consulte /cli/logs).

# Observações

• Se logging.level estiver definido acima de warn, esses logs poderão ser suprimidos. O padrão info é adequado.
• brave.http registra URLs/parâmetros de consulta de solicitações do Brave Search, status/tempo de resposta e eventos de acerto/erro/gravação de cache. Ele não registra chaves de API nem corpos de resposta, mas consultas de busca podem ser sensíveis.
• É seguro deixar os sinalizadores ativados; eles afetam apenas o volume de logs do subsistema específico.
• Use /logging para alterar destinos, níveis e redação de logs.

# Relacionado

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