# Logging

Para uma visão geral voltada ao usuário (CLI + Control UI + configuração), consulte /logging.

O OpenClaw tem duas "superfícies" de log:

• Saída do console (o que você vê no terminal / Debug UI).
• Logs em arquivo (linhas JSON) gravados pelo logger do Gateway.

Na inicialização, o Gateway registra o modelo padrão de agente resolvido junto com os padrões de modo que afetam novas sessões, por exemplo:

agent model: openai-codex/gpt-5.5 (thinking=medium, fast=on)

thinking vem do agente padrão, dos parâmetros do modelo ou do padrão global do agente; quando não está definido, o resumo de inicialização mostra medium. fast vem do agente padrão ou dos parâmetros fastMode do modelo.

# Logger baseado em arquivo

• O arquivo de log rotativo padrão fica em /tmp/openclaw/ (um arquivo por dia): openclaw-YYYY-MM-DD.log
  • A data usa o fuso horário local do host do Gateway.
• Arquivos de log ativos rotacionam em logging.maxFileBytes (padrão: 100 MB), mantendo até cinco arquivos numerados e continuando a gravar em um novo arquivo ativo.
• O caminho e o nível do arquivo de log podem ser configurados via ~/.openclaw/openclaw.json:
  • logging.file
  • logging.level

O formato do arquivo é um objeto JSON por linha.

Os caminhos de código de conversa, voz em tempo real e sala gerenciada usam o logger de arquivo compartilhado para registros de ciclo de vida limitados. Esses registros são destinados à depuração operacional e à exportação de logs OTLP; texto de transcrição, payloads de áudio, IDs de turno, IDs de chamada e IDs de itens de provedor não são copiados para o registro de log.

A aba Logs da Control UI acompanha esse arquivo via Gateway (logs.tail). A CLI pode fazer o mesmo:

openclaw logs --follow

Detalhado vs. níveis de log

• Logs em arquivo são controlados exclusivamente por logging.level.
• --verbose afeta apenas a verbosidade do console (e o estilo de log WS); ele não aumenta o nível de log do arquivo.
• Para capturar detalhes exclusivos do modo detalhado em logs em arquivo, defina logging.level como debug ou trace.
• O logging em trace também inclui resumos de temporização de diagnóstico para caminhos críticos selecionados, como a preparação da fábrica de ferramentas de Plugin. Consulte /tools/plugin#slow-plugin-tool-setup.

# Captura do console

A CLI captura console.log/info/warn/error/debug/trace e os grava em logs em arquivo, enquanto ainda imprime em stdout/stderr.

Você pode ajustar a verbosidade do console independentemente via:

• logging.consoleLevel (padrão info)
• logging.consoleStyle (pretty | compact | json)

# Redação

O OpenClaw pode mascarar tokens sensíveis antes que a saída de log ou transcrição saia do processo. Essa política de redação de logging é aplicada aos coletores de texto de console, log em arquivo, registro de log OTLP e transcrição de sessão, de modo que valores secretos correspondentes sejam mascarados antes que linhas JSONL ou mensagens sejam gravadas em disco.

• logging.redactSensitive: off | tools (padrão: tools)
• logging.redactPatterns: array de strings regex (substitui os padrões)
  • Use strings regex brutas (auto gi) ou /pattern/flags se precisar de flags personalizadas.
  • Correspondências são mascaradas mantendo os primeiros 6 + últimos 4 caracteres (comprimento >= 18), caso contrário ***.
  • Os padrões cobrem atribuições de chaves comuns, flags da CLI, campos JSON, cabeçalhos bearer, blocos PEM, prefixos populares de tokens e nomes de campos de credenciais de pagamento, como número de cartão, CVC/CVV, token de pagamento compartilhado e credencial de pagamento.

Alguns limites de segurança sempre fazem redação, independentemente de logging.redactSensitive. Isso inclui eventos de chamada de ferramenta da Control UI, saída da ferramenta sessions_history, exportações de suporte de diagnóstico, observações de erro de provedor, exibição de comando de aprovação de exec e logs do protocolo WebSocket do Gateway. Essas superfícies ainda podem usar logging.redactPatterns como padrões adicionais, mas redactSensitive: "off" não faz com que emitam segredos brutos.

# Logs WebSocket do Gateway

O Gateway imprime logs do protocolo WebSocket em dois modos:

• Modo normal (sem --verbose): apenas resultados RPC "interessantes" são impressos:
  • erros (ok=false)
  • chamadas lentas (limite padrão: >= 50ms)
  • erros de análise
• Modo detalhado (--verbose): imprime todo o tráfego de solicitação/resposta WS.

# Estilo de log WS

openclaw gateway oferece suporte a uma alternância de estilo por Gateway:

• --ws-log auto (padrão): o modo normal é otimizado; o modo detalhado usa saída compacta
• --ws-log compact: saída compacta (solicitação/resposta pareadas) quando detalhado
• --ws-log full: saída completa por frame quando detalhado
• --compact: alias para --ws-log compact

Exemplos:

# otimizado (apenas erros/lentas)
openclaw gateway

# mostrar todo o tráfego WS (pareado)
openclaw gateway --verbose --ws-log compact

# mostrar todo o tráfego WS (metadados completos)
openclaw gateway --verbose --ws-log full

# Formatação do console (logging de subsistema)

O formatador de console é ciente de TTY e imprime linhas consistentes e prefixadas. Loggers de subsistema mantêm a saída agrupada e fácil de examinar.

Comportamento:

• Prefixos de subsistema em cada linha (por exemplo, [gateway], [canvas], [tailscale])
• Cores de subsistema (estáveis por subsistema) além de coloração por nível
• Cor quando a saída é um TTY ou o ambiente parece um terminal avançado (TERM/COLORTERM/TERM_PROGRAM), respeita NO_COLOR
• Prefixos de subsistema encurtados: remove gateway/ + channels/ iniciais, mantém os últimos 2 segmentos (por exemplo, whatsapp/outbound)
• Sub-loggers por subsistema (prefixo automático + campo estruturado { subsystem })
• logRaw() para saída QR/UX (sem prefixo, sem formatação)
• Estilos de console (por exemplo, pretty | compact | json)
• Nível de log do console separado do nível de log em arquivo (o arquivo mantém todos os detalhes quando logging.level é definido como debug/trace)
• Corpos de mensagens do WhatsApp são registrados em debug (use --verbose para vê-los)

Isso mantém os logs em arquivo existentes estáveis enquanto torna a saída interativa fácil de examinar.

# Relacionado

• Logging
• Exportação OpenTelemetry
• Exportação de diagnóstico