Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw tem duas superfícies principais de log:
  • Logs de arquivo (linhas JSON) gravados pelo Gateway.
  • Saída do console exibida em terminais e na UI de Depuração do Gateway.
A aba Logs da UI de Controle acompanha o log de arquivo do gateway. Esta página explica onde os logs ficam, como lê-los e como configurar níveis e formatos de log.

​
Onde os logs ficam

Por padrão, o Gateway grava um arquivo de log rotativo em: /tmp/openclaw/openclaw-YYYY-MM-DD.log A data usa o fuso horário local do host do gateway. Cada arquivo é rotacionado quando atinge logging.maxFileBytes (padrão: 100 MB). O OpenClaw mantém até cinco arquivos numerados ao lado do arquivo ativo, como openclaw-YYYY-MM-DD.1.log, e continua gravando em um novo log ativo em vez de suprimir diagnósticos. Você pode sobrescrever isso em ~/.openclaw/openclaw.json: 
{
  "logging": {
    "file": "/path/to/openclaw.log"
  }
}

​
Como ler logs

​
CLI: acompanhamento ao vivo (recomendado)

Use a CLI para acompanhar o arquivo de log do gateway via RPC: 
openclaw logs --follow
Opções atuais úteis:
  • --local-time: renderiza carimbos de data/hora no seu fuso horário local
  • --url <url> / --token <token> / --timeout <ms>: flags padrão de RPC do Gateway
  • --expect-final: flag de espera pela resposta final de RPC apoiada por agente (aceita aqui pela camada de cliente compartilhada)
Modos de saída:
  • Sessões TTY: linhas de log estruturadas, bonitas e coloridas.
  • Sessões não TTY: texto simples.
  • --json: JSON delimitado por linhas (um evento de log por linha).
  • --plain: força texto simples em sessões TTY.
  • --no-color: desativa cores ANSI.
Quando você passa um --url explícito, a CLI não aplica automaticamente credenciais de configuração ou ambiente; inclua --token por conta própria se o Gateway de destino exigir autenticação. No modo JSON, a CLI emite objetos marcados por type:
  • meta: metadados do fluxo (arquivo, cursor, tamanho)
  • log: entrada de log analisada
  • notice: dicas de truncamento / rotação
  • raw: linha de log não analisada
Se o Gateway local loopback implícito pedir pareamento, fechar durante a conexão ou expirar antes de logs.tail responder, openclaw logs volta automaticamente para o log de arquivo do Gateway configurado. Destinos --url explícitos não usam esse fallback. Se o Gateway estiver inacessível, a CLI imprime uma dica curta para executar: 
openclaw doctor

​
UI de Controle (web)

A aba Logs da UI de Controle acompanha o mesmo arquivo usando logs.tail. Veja UI de Controle para saber como abri-la.

​
Logs apenas de canal

Para filtrar atividade de canal (WhatsApp/Telegram/etc), use: 
openclaw channels logs --channel whatsapp

​
Formatos de log

​
Logs de arquivo (JSONL)

Cada linha no arquivo de log é um objeto JSON. A CLI e a UI de Controle analisam essas entradas para renderizar saída estruturada (hora, nível, subsistema, mensagem). Registros JSONL de log de arquivo também incluem campos de nível superior filtráveis por máquina quando disponíveis:
  • hostname: nome do host do gateway.
  • message: texto da mensagem de log achatado para busca de texto completo.
  • agent_id: id do agente ativo quando a chamada de log carrega contexto de agente.
  • session_id: id/chave da sessão ativa quando a chamada de log carrega contexto de sessão.
  • channel: canal ativo quando a chamada de log carrega contexto de canal.
O OpenClaw preserva os argumentos estruturados originais do log junto com esses campos para que analisadores existentes que leem chaves numeradas de argumentos do tslog continuem funcionando. Atividades de fala, voz em tempo real e salas gerenciadas emitem registros de log de ciclo de vida limitados por esse mesmo pipeline de log de arquivo. Esses registros incluem tipo de evento, modo, transporte, provedor e medições de tamanho/tempo quando disponíveis, mas omitem texto de transcrição, payloads de áudio, ids de turnos, ids de chamadas e ids de itens do provedor.

​
Saída do console

Logs do console são cientes de TTY e formatados para legibilidade:
  • Prefixos de subsistema (por exemplo, gateway/channels/whatsapp)
  • Coloração por nível (info/warn/error)
  • Modo compacto ou JSON opcional
A formatação do console é controlada por logging.consoleStyle.

​
Logs WebSocket do Gateway

openclaw gateway também tem logging de protocolo WebSocket para tráfego RPC:
  • modo normal: apenas resultados interessantes (erros, erros de análise, chamadas lentas)
  • --verbose: todo o tráfego de requisição/resposta
  • --ws-log auto|compact|full: escolhe o estilo de renderização verbosa
  • --compact: alias para --ws-log compact
Exemplos: 
openclaw gateway
openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full

​
Configurando logging

Toda a configuração de logging fica em logging em ~/.openclaw/openclaw.json. 
{
  "logging": {
    "level": "info",
    "file": "/tmp/openclaw/openclaw-YYYY-MM-DD.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty",
    "redactSensitive": "tools",
    "redactPatterns": ["sk-.*"]
  }
}

​
Níveis de log

  • logging.level: nível dos logs de arquivo (JSONL).
  • logging.consoleLevel: nível de verbosidade do console.
Você pode sobrescrever ambos pela variável de ambiente OPENCLAW_LOG_LEVEL (por exemplo, OPENCLAW_LOG_LEVEL=debug). A variável de ambiente tem precedência sobre o arquivo de configuração, então você pode aumentar a verbosidade para uma única execução sem editar openclaw.json. Você também pode passar a opção global da CLI --log-level <level> (por exemplo, openclaw --log-level debug gateway run), que sobrescreve a variável de ambiente para esse comando. --verbose afeta apenas a saída do console e a verbosidade do log WS; ele não altera níveis de log de arquivo.

​
Diagnósticos direcionados de transporte de modelo

Ao depurar chamadas de provedor, use flags de ambiente direcionadas em vez de elevar todos os logs para debug: 
OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway
Flags disponíveis:
  • OPENCLAW_DEBUG_MODEL_TRANSPORT=1: emite início de requisição, resposta de fetch, cabeçalhos do SDK, primeiro evento de streaming, conclusão do fluxo e erros de transporte no nível info.
  • OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: inclui um resumo limitado do payload da requisição em logs de requisição de modelo.
  • OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: inclui todos os nomes de ferramentas voltadas ao modelo no resumo do payload.
  • OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: inclui um snapshot JSON redigido e limitado do payload. Use apenas durante a depuração; segredos são redigidos, mas prompts e texto de mensagens ainda podem estar presentes.
  • OPENCLAW_DEBUG_SSE=events: emite temporização do primeiro evento e da conclusão do fluxo.
  • OPENCLAW_DEBUG_SSE=peek: também emite os cinco primeiros payloads redigidos de eventos SSE, limitados por evento.
  • OPENCLAW_DEBUG_CODE_MODE=1: emite diagnósticos da superfície de modelo do modo de código, incluindo quando ferramentas nativas do provedor são ocultadas porque o modo de código possui a superfície de ferramentas.
Essas flags registram por meio do logging normal do OpenClaw, então openclaw logs --follow e a aba Logs da UI de Controle as mostram. Sem as flags, os mesmos diagnósticos permanecem disponíveis no nível debug.

​
Correlação de rastreamento

Logs de arquivo são JSONL. Quando uma chamada de log carrega um contexto de rastreamento diagnóstico válido, o OpenClaw grava os campos de rastreamento como chaves JSON de nível superior (traceId, spanId, parentSpanId, traceFlags) para que processadores externos de log possam correlacionar a linha com spans OTEL e propagação de traceparent do provedor. Requisições HTTP do Gateway e frames WebSocket do Gateway estabelecem um escopo interno de rastreamento de requisição. Logs e eventos diagnósticos emitidos dentro desse escopo assíncrono herdam o rastreamento da requisição quando não passam um contexto de rastreamento explícito. Rastreamentos de execução de agente e chamada de modelo se tornam filhos do rastreamento de requisição ativo, de modo que logs locais, snapshots diagnósticos, spans OTEL e cabeçalhos traceparent de provedores confiáveis possam ser unidos por traceId sem registrar conteúdo bruto de requisição ou modelo. Registros de log de ciclo de vida de fala também fluem para logs OTLP quando a exportação de logs OpenTelemetry está habilitada, usando os mesmos atributos limitados dos logs de arquivo.

​
Tamanho e temporização de chamada de modelo

Diagnósticos de chamada de modelo registram medições limitadas de requisição/resposta sem capturar conteúdo bruto de prompt ou resposta:
  • requestPayloadBytes: tamanho em bytes UTF-8 do payload final da requisição de modelo
  • responseStreamBytes: tamanho em bytes UTF-8 dos eventos de resposta de modelo em streaming
  • timeToFirstByteMs: tempo decorrido antes do primeiro evento de resposta em streaming
  • durationMs: duração total da chamada de modelo
Esses campos estão disponíveis para snapshots diagnósticos, hooks de Plugin de chamada de modelo e spans/métricas OTEL de chamada de modelo quando a exportação de diagnósticos está habilitada.

​
Estilos de console

logging.consoleStyle:
  • pretty: amigável para humanos, colorido, com carimbos de data/hora.
  • compact: saída mais enxuta (melhor para sessões longas).
  • json: JSON por linha (para processadores de log).

​
Redação

O OpenClaw pode redigir tokens sensíveis antes que eles cheguem à saída do console, logs de arquivo, registros de log OTLP, texto persistido de transcrição de sessão ou payloads de eventos de ferramentas da UI de Controle (argumentos de início de ferramenta, payloads de resultado parcial/final, saída derivada de exec e resumos de patch):
  • logging.redactSensitive: off | tools (padrão: tools)
  • logging.redactPatterns: lista de strings regex para sobrescrever o conjunto padrão. Padrões personalizados se aplicam além dos padrões integrados para payloads de ferramentas da UI de Controle, então adicionar um padrão nunca enfraquece a redação de valores já capturados pelos padrões.
Logs de arquivo e transcrições de sessão permanecem JSONL, mas valores secretos correspondentes são mascarados antes que a linha ou mensagem seja gravada em disco. A redação é de melhor esforço: ela se aplica a conteúdo de mensagem com texto e strings de log, não a todo identificador ou campo de payload binário. Os padrões integrados cobrem credenciais comuns de API e nomes de campos de credenciais de pagamento, como número do cartão, CVC/CVV, token de pagamento compartilhado e credencial de pagamento quando aparecem como campos JSON, parâmetros de URL, flags de CLI ou atribuições. logging.redactSensitive: "off" desativa apenas essa política geral de log/transcrição. O OpenClaw ainda redige payloads de fronteira de segurança que podem ser mostrados a clientes de UI, pacotes de suporte, observadores de diagnósticos, prompts de aprovação ou ferramentas de agente. Exemplos incluem eventos de chamada de ferramenta da UI de Controle, saída de sessions_history, exportações de suporte de diagnósticos, observações de erro de provedor, exibição de comando de aprovação exec e logs de protocolo WebSocket do Gateway. logging.redactPatterns personalizados ainda podem adicionar padrões específicos do projeto nessas superfícies.

​
Diagnósticos e OpenTelemetry

Diagnósticos são eventos estruturados e legíveis por máquina para execuções de modelo e telemetria de fluxo de mensagens (webhooks, enfileiramento, estado da sessão). Eles não substituem logs — eles alimentam métricas, rastreamentos e exportadores. Eventos são emitidos no processo, independentemente de você exportá-los ou não. Duas superfícies adjacentes:
  • Exportação OpenTelemetry — envia métricas, rastreamentos e logs por OTLP/HTTP para qualquer coletor ou backend compatível com OpenTelemetry (Grafana, Datadog, Honeycomb, New Relic, Tempo, etc.). Configuração completa, catálogo de sinais, nomes de métricas/spans, variáveis de ambiente e modelo de privacidade ficam em uma página dedicada: Exportação OpenTelemetry.
  • Flags de diagnóstico — flags direcionadas de log de depuração que encaminham logs extras para logging.file sem elevar logging.level. As flags não diferenciam maiúsculas de minúsculas e aceitam curingas (telegram.*, *). Configure em diagnostics.flags ou pela substituição de ambiente OPENCLAW_DIAGNOSTICS=.... Guia completo: Flags de diagnóstico.
Para habilitar eventos de diagnóstico para plugins ou coletores personalizados sem exportação OTLP: 
{
  diagnostics: { enabled: true },
}
Para exportação OTLP para um coletor, veja Exportação OpenTelemetry.

​
Dicas de solução de problemas

  • Gateway inacessível? Execute openclaw doctor primeiro.
  • Logs vazios? Verifique se o Gateway está em execução e gravando no caminho de arquivo em logging.file.
  • Precisa de mais detalhes? Defina logging.level como debug ou trace e tente novamente.

​
Relacionado