Registro em log

O OpenClaw tem duas superfícies principais de logs:

• Logs de arquivo (linhas JSON) gravados pelo Gateway.
• Saída do console no terminal que executa o Gateway.

A aba Logs da interface de controle acompanha continuamente 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 por dia:

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

A data usa o fuso horário local do host do Gateway. Quando /tmp/openclaw não é seguro ou está indisponível (e sempre no Windows), o OpenClaw usa um diretório openclaw-<uid> com escopo de usuário no diretório temporário do sistema operacional. Os arquivos de log datados são removidos após 24 horas.

Cada arquivo é rotacionado quando a próxima gravação excederia 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 substituir o caminho em ~/.openclaw/openclaw.json:

{  "logging": {    "file": "/path/to/openclaw.log"  }}

Como ler os logs

CLI: acompanhamento em tempo real (recomendado)

Acompanhe o arquivo de log do Gateway via RPC:

openclaw logs --follow

Opções:

Modos de saída:

• Sessões TTY: linhas de log estruturadas, formatadas e coloridas.
• Sessões não TTY: texto simples.

Quando você fornece explicitamente --url, a CLI não aplica automaticamente as credenciais da configuração ou do ambiente; inclua --token por conta própria ou a chamada falhará com gateway url override requires explicit credentials.

No modo JSON, a CLI emite objetos identificados por type:

• meta: metadados do fluxo (arquivo, origem, tipo da origem, serviço, cursor, tamanho)
• log: entrada de log analisada
• notice: avisos de truncamento/rotação
• raw: linha de log não analisada
• error: falhas de conexão com o Gateway (gravadas em stderr)

Se o Gateway local loopback implícito solicitar pareamento, fechar durante a conexão ou atingir o tempo limite antes que logs.tail responda, openclaw logs recorrerá automaticamente ao log de arquivo configurado do Gateway. Destinos definidos explicitamente com --url não usam esse fallback. openclaw logs --follow é mais rigoroso: no Linux, ele usa o diário do Gateway do systemd do usuário ativo pelo PID quando disponível; caso contrário, tenta novamente o Gateway em tempo real com espera progressiva, em vez de acompanhar um arquivo paralelo potencialmente desatualizado.

Se o Gateway estiver inacessível, a CLI exibirá uma breve sugestão para executar:

openclaw doctor

Interface de controle (web)

A aba Logs da interface de controle acompanha continuamente o mesmo arquivo usando logs.tail. Consulte Interface de controle para saber como abri-la.

Logs somente de canais

Para filtrar a atividade dos canais (WhatsApp/Telegram/etc.), use:

openclaw channels logs --channel whatsapp

O padrão de --channel é all; --lines <n> (padrão: 200) e --json também estão disponíveis.

Formatos de log

Logs de arquivo (JSONL)

Cada linha do arquivo de log é um objeto JSON. A CLI e a interface de controle analisam essas entradas para exibir uma saída estruturada (horário, nível, subsistema, mensagem).

Os registros JSONL dos logs 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 simples da mensagem de log para pesquisa de texto completo.
• agent_id: identificador do agente ativo quando a chamada de log contém contexto de agente.
• session_id: identificador/chave da sessão ativa quando a chamada de log contém contexto de sessão.
• channel: canal ativo quando a chamada de log contém contexto de canal.

O OpenClaw preserva os argumentos estruturados originais do log junto a esses campos para que os analisadores existentes que leem chaves numeradas de argumentos do tslog continuem funcionando.

As atividades de conversação, voz em tempo real e salas gerenciadas emitem registros delimitados de log do ciclo de vida por meio desse mesmo pipeline de logs de arquivo. Esses registros incluem tipo de evento, modo, transporte, provedor e medições de tamanho/tempo quando disponíveis, mas omitem texto da transcrição, cargas de áudio, identificadores de turnos, identificadores de chamadas e identificadores de itens do provedor.

Saída do console

Os logs do console reconhecem TTY e são formatados para facilitar a leitura:

• Prefixos de subsistema (por exemplo, gateway/channels/whatsapp)
• Coloração por nível (informação/aviso/erro)
• Modo compacto ou JSON opcional

A formatação do console é controlada por logging.consoleStyle.

Logs do WebSocket do Gateway

openclaw gateway também tem registro do protocolo WebSocket para tráfego RPC:

• modo normal: apenas resultados relevantes (erros, erros de análise, chamadas lentas)
• --verbose: todo o tráfego de solicitações/respostas
• --ws-log auto|compact|full: seleciona o estilo de exibição detalhada
• --compact: alias para --ws-log compact

Exemplos:

openclaw gatewayopenclaw gateway --verbose --ws-log compactopenclaw gateway --verbose --ws-log full

Configuração dos logs

Toda a configuração de logs fica em logging dentro de ~/.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

Níveis: silent, fatal, error, warn, info, debug, trace.

• logging.level: nível dos logs de arquivo (JSONL) (padrão: info).
• logging.consoleLevel: nível de detalhamento do console.

Você pode substituir ambos por meio da 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, portanto você pode aumentar o detalhamento em uma única execução sem editar openclaw.json. Você também pode fornecer a opção global da CLI --log-level <level> (por exemplo, openclaw --log-level debug gateway run), que substitui a variável de ambiente para esse comando.

--verbose afeta apenas a saída do console e o detalhamento dos logs de WS; ele não altera os níveis dos logs de arquivo.

Diagnósticos direcionados do transporte do modelo

Ao depurar chamadas do provedor, use sinalizadores de ambiente direcionados em vez de aumentar todos os logs para debug:

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gatewayOPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway

Sinalizadores disponíveis:

• OPENCLAW_DEBUG_MODEL_TRANSPORT=1: emite o início da solicitação, a resposta da busca, os cabeçalhos do SDK, o primeiro evento de transmissão, a conclusão da transmissão e erros de transporte no nível info.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: inclui um resumo delimitado da carga da solicitação nos logs de solicitação do modelo.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: inclui todos os nomes de ferramentas expostos ao modelo no resumo da carga.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: inclui um instantâneo JSON limitado e com dados sensíveis ocultados. Use somente durante a depuração; os segredos são ocultados, mas os prompts e o texto das mensagens ainda podem estar presentes.
• OPENCLAW_DEBUG_SSE=events: emite os tempos do primeiro evento e da conclusão da transmissão.
• OPENCLAW_DEBUG_SSE=peek: também emite as cargas dos primeiros cinco eventos SSE com dados sensíveis ocultados e limite por evento.
• OPENCLAW_DEBUG_CODE_MODE=1: emite diagnósticos da superfície de modelo do modo de código, inclusive quando as ferramentas nativas do provedor são ocultadas porque o modo de código controla a superfície de ferramentas.

Esses sinalizadores registram informações por meio do sistema normal de logs do OpenClaw, portanto openclaw logs --follow e a aba Logs da interface de controle os exibem. Sem os sinalizadores, os mesmos diagnósticos permanecem disponíveis no nível debug.

Os metadados de início e resposta de [model-fetch] (provedor, API, modelo, status, latência e campos da solicitação, como método, URL, tempo limite, proxy e política) são sempre emitidos no nível info, independentemente de OPENCLAW_DEBUG_MODEL_TRANSPORT, para que a integridade básica do transporte do modelo fique visível sem sinalizadores de depuração.

Correlação de rastreamento

Os logs de arquivo usam JSONL. Quando uma chamada de log contém um contexto válido de rastreamento de diagnóstico, o OpenClaw grava os campos de rastreamento como chaves JSON de nível superior (traceId, spanId, parentSpanId, traceFlags), permitindo que processadores externos de logs correlacionem a linha com spans do OTEL e a propagação de traceparent do provedor.

As solicitações HTTP e os quadros WebSocket do Gateway estabelecem um escopo interno de rastreamento da solicitação. Logs e eventos de diagnóstico emitidos dentro desse escopo assíncrono herdam o rastreamento da solicitação quando não fornecem um contexto explícito de rastreamento. Os rastreamentos de execução do agente e de chamada do modelo tornam-se filhos do rastreamento ativo da solicitação, portanto logs locais, instantâneos de diagnóstico, spans do OTEL e cabeçalhos traceparent de provedores confiáveis podem ser associados pelo traceId sem registrar o conteúdo bruto da solicitação ou do modelo.

Os registros de log do ciclo de vida de conversação também são enviados à exportação de logs do diagnostics-otel quando a exportação de logs do OpenTelemetry está ativada, usando os mesmos atributos delimitados dos logs de arquivo. Configure diagnostics.otel.logsExporter para selecionar OTLP, JSONL no stdout ou ambos os destinos.

Tamanho e tempo das chamadas do modelo

Os diagnósticos das chamadas do modelo registram medições delimitadas de solicitação/resposta sem capturar o conteúdo bruto do prompt ou da resposta:

• requestPayloadBytes: tamanho em bytes UTF-8 da carga final da solicitação do modelo
• responseStreamBytes: tamanho em bytes UTF-8 das cargas dos fragmentos transmitidos da resposta do modelo. Eventos de alta frequência de texto, raciocínio e deltas de chamadas de ferramentas contabilizam apenas os bytes incrementais de delta, em vez dos instantâneos completos de partial.
• timeToFirstByteMs: tempo decorrido até o primeiro evento de resposta transmitido
• durationMs: duração total da chamada do modelo

Esses campos ficam disponíveis para instantâneos de diagnóstico, hooks de Plugin de chamadas do modelo e spans/métricas de chamadas do modelo no OTEL quando a exportação de diagnósticos está ativada.

Estilos do console

logging.consoleStyle:

• pretty: amigável para leitura humana, colorido e com carimbos de data e hora.
• compact: saída mais concisa (ideal para sessões longas).
• json: um JSON por linha (para processadores de logs).

Ocultação de dados sensíveis

O OpenClaw pode ocultar tokens sensíveis antes que cheguem à saída do console, aos logs de arquivo, aos registros de log OTLP, ao texto persistido da transcrição da sessão ou às cargas de eventos de ferramentas da interface de controle (argumentos de início da ferramenta, cargas de resultados parciais/finais, saída derivada de execução e resumos de patches):

• logging.redactSensitive: off | tools (padrão: tools)
• logging.redactPatterns: lista de strings de expressões regulares que substitui o conjunto padrão para a saída de logs/transcrições. Para cargas de ferramentas da interface de controle, os padrões personalizados são aplicados além dos padrões internos, portanto adicionar um padrão nunca reduz a ocultação de valores já detectados pelos padrões predefinidos.

Os logs de arquivo e as transcrições de sessões permanecem em JSONL, mas os valores de segredos correspondentes são mascarados antes que a linha ou mensagem seja gravada no disco. A ocultação de dados sensíveis é feita com o melhor esforço: ela se aplica ao conteúdo textual das mensagens e às strings de log, não a todos os identificadores ou campos de cargas binárias.

Os padrões integrados abrangem credenciais de API comuns 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 da CLI ou atribuições.

logging.redactSensitive: "off" desativa apenas essa política geral de logs/transcrições. O OpenClaw ainda oculta cargas úteis dos limites de segurança que podem ser exibidas para clientes da interface, pacotes de suporte, observadores de diagnóstico, solicitações de aprovação ou ferramentas do agente. Alguns exemplos incluem eventos de chamada de ferramenta da interface de controle, saída de sessions_history, exportações de suporte de diagnóstico, observações de erros do provedor, exibição de comandos para aprovação de execução e logs do protocolo WebSocket do Gateway. Padrões personalizados em logging.redactPatterns ainda podem adicionar padrões específicos do projeto nessas superfícies.

Diagnóstico e OpenTelemetry

Os diagnósticos são eventos estruturados e legíveis por máquina para execuções de modelos e telemetria do fluxo de mensagens (webhooks, enfileiramento, estado da sessão). Eles não substituem os logs — eles alimentam métricas, rastreamentos e exportadores. Por padrão, os eventos são emitidos no processo (defina diagnostics.enabled: false para desativá-los); a exportação é configurada separadamente.

Duas superfícies relacionadas:

• Exportação do OpenTelemetry — envie métricas, rastreamentos e logs por OTLP/HTTP para qualquer coletor ou backend compatível com OpenTelemetry (Datadog, Grafana, Honeycomb, New Relic, Tempo etc.). A configuração completa, o catálogo de sinais, os nomes de métricas/spans, as variáveis de ambiente e o modelo de privacidade estão em uma página dedicada: Exportação do OpenTelemetry.
• Flags de diagnóstico — flags direcionadas de logs de depuração que encaminham logs adicionais para logging.file sem aumentar logging.level. As flags não diferenciam maiúsculas de minúsculas e aceitam curingas (telegram.*, *). Configure-as em diagnostics.flags ou por meio da substituição pela variável de ambiente OPENCLAW_DIAGNOSTICS=.... Guia completo: Flags de diagnóstico.

Para exportar via OTLP para um coletor, consulte Exportação do OpenTelemetry.

Dicas de solução de problemas

• Não consegue acessar o Gateway? Execute openclaw doctor primeiro.
• Os logs estão vazios? Verifique se o Gateway está em execução e gravando no caminho de arquivo definido em logging.file.
• Precisa de mais detalhes? Defina logging.level como debug ou trace e tente novamente.

Relacionados

• Exportação do OpenTelemetry — exportação via OTLP/HTTP, catálogo de métricas/spans e modelo de privacidade
• Flags de diagnóstico — flags direcionadas de logs de depuração
• Detalhes internos dos logs do Gateway — estilos de logs de WS, prefixos de subsistemas e captura do console
• Referência de configuração — referência completa dos campos diagnostics.*