145 lines
3.4 KiB
Markdown
145 lines
3.4 KiB
Markdown
---
|
||
summary: "Logging overview: file logs, console output, CLI tailing, and the Control UI"
|
||
read_when:
|
||
- You need a beginner-friendly overview of logging
|
||
- You want to configure log levels or formats
|
||
- You are troubleshooting and need to find logs quickly
|
||
---
|
||
|
||
# Logging
|
||
|
||
Clawdbot logs in two places:
|
||
|
||
- **File logs** (JSON lines) written by the Gateway.
|
||
- **Console output** shown in terminals and the Control UI.
|
||
|
||
This page explains where logs live, how to read them, and how to configure log
|
||
levels and formats.
|
||
|
||
## Where logs live
|
||
|
||
By default, the Gateway writes a rolling log file under:
|
||
|
||
`/tmp/clawdbot/clawdbot-YYYY-MM-DD.log`
|
||
|
||
You can override this in `~/.clawdbot/clawdbot.json`:
|
||
|
||
```json
|
||
{
|
||
"logging": {
|
||
"file": "/path/to/clawdbot.log"
|
||
}
|
||
}
|
||
```
|
||
|
||
## How to read logs
|
||
|
||
### CLI: live tail (recommended)
|
||
|
||
Use the CLI to tail the gateway log file via RPC:
|
||
|
||
```bash
|
||
clawdbot logs --follow
|
||
```
|
||
|
||
Output modes:
|
||
|
||
- **TTY sessions**: pretty, colorized, structured log lines.
|
||
- **Non-TTY sessions**: plain text.
|
||
- `--json`: line-delimited JSON (one log event per line).
|
||
- `--plain`: force plain text in TTY sessions.
|
||
- `--no-color`: disable ANSI colors.
|
||
|
||
In JSON mode, the CLI emits `type`-tagged objects:
|
||
|
||
- `meta`: stream metadata (file, cursor, size)
|
||
- `log`: parsed log entry
|
||
- `notice`: truncation / rotation hints
|
||
- `raw`: unparsed log line
|
||
|
||
If the Gateway is unreachable, the CLI prints a short hint to run:
|
||
|
||
```bash
|
||
clawdbot doctor
|
||
```
|
||
|
||
### Control UI (web)
|
||
|
||
The Control UI’s **Logs** tab tails the same file using `logs.tail`.
|
||
See [/web/control-ui](/web/control-ui) for how to open it.
|
||
|
||
### Provider-only logs
|
||
|
||
To filter provider activity (WhatsApp/Telegram/etc), use:
|
||
|
||
```bash
|
||
clawdbot providers logs --provider whatsapp
|
||
```
|
||
|
||
## Log formats
|
||
|
||
### File logs (JSONL)
|
||
|
||
Each line in the log file is a JSON object. The CLI and Control UI parse these
|
||
entries to render structured output (time, level, subsystem, message).
|
||
|
||
### Console output
|
||
|
||
Console logs are **TTY-aware** and formatted for readability:
|
||
|
||
- Subsystem prefixes (e.g. `gateway/providers/whatsapp`)
|
||
- Level coloring (info/warn/error)
|
||
- Optional compact or JSON mode
|
||
|
||
Console formatting is controlled by `logging.consoleStyle`.
|
||
|
||
## Configuring logging
|
||
|
||
All logging configuration lives under `logging` in `~/.clawdbot/clawdbot.json`.
|
||
|
||
```json
|
||
{
|
||
"logging": {
|
||
"level": "info",
|
||
"file": "/tmp/clawdbot/clawdbot-YYYY-MM-DD.log",
|
||
"consoleLevel": "info",
|
||
"consoleStyle": "pretty",
|
||
"redactSensitive": "tools",
|
||
"redactPatterns": [
|
||
"sk-.*"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### Log levels
|
||
|
||
- `logging.level`: **file logs** (JSONL) level.
|
||
- `logging.consoleLevel`: **console** verbosity level.
|
||
|
||
`--verbose` only affects console output; it does not change file log levels.
|
||
|
||
### Console styles
|
||
|
||
`logging.consoleStyle`:
|
||
|
||
- `pretty`: human-friendly, colored, with timestamps.
|
||
- `compact`: tighter output (best for long sessions).
|
||
- `json`: JSON per line (for log processors).
|
||
|
||
### Redaction
|
||
|
||
Tool summaries can redact sensitive tokens before they hit the console:
|
||
|
||
- `logging.redactSensitive`: `off` | `tools` (default: `tools`)
|
||
- `logging.redactPatterns`: list of regex strings to override the default set
|
||
|
||
Redaction affects **console output only** and does not alter file logs.
|
||
|
||
## Troubleshooting tips
|
||
|
||
- **Gateway not reachable?** Run `clawdbot doctor` first.
|
||
- **Logs empty?** Check that the Gateway is running and writing to the file path
|
||
in `logging.file`.
|
||
- **Need more detail?** Set `logging.level` to `debug` or `trace` and retry.
|