---
read_when:
    - Alterando a saída ou os formatos de log
    - Depuração da saída da CLI ou do Gateway
summary: Superfícies de registro, registros em arquivo, estilos de registro WS e formatação do console
title: Registro em log do Gateway
x-i18n:
    generated_at: "2026-05-06T17:56:11Z"
    model: gpt-5.5
    provider: openai
    source_hash: 16bce5763754d13f855a46777b4c3cc7a7c966e35e0cd08a15f359fd22623bcb
    source_path: gateway/logging.md
    workflow: 16
---

# Logging

Para uma visão geral voltada ao usuário (CLI + Control UI + configuração), consulte [/logging](/pt-BR/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:

```text
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:

```bash
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](/pt-BR/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:

```bash
# 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](/pt-BR/logging)
- [Exportação OpenTelemetry](/pt-BR/gateway/opentelemetry)
- [Exportação de diagnóstico](/pt-BR/gateway/diagnostics)