Principle:Openclaw Openclaw Log Inspection
Log Inspection
Log Inspection is the principle of providing structured, real-time access to gateway log output for debugging, monitoring, and operational awareness. In a long-running AI agent gateway, logs are the primary diagnostic artifact, and the ability to stream, filter, and format them is essential for effective operations.
Motivation
The OpenClaw gateway runs as a background service (via launchd on macOS, systemd on Linux, or as a standalone process). Operators need to inspect what the gateway is doing without attaching a debugger or manually navigating log files. Log inspection bridges the gap between the running gateway and the operator's terminal, offering both one-shot tail and continuous follow modes.
Core Concepts
Structured Log Format
OpenClaw writes logs as newline-delimited JSON (NDJSON). Each log line is a JSON object containing metadata fields such as:
- time -- ISO 8601 timestamp of the log event.
- level -- Severity level (trace, debug, info, warn, error, fatal).
- subsystem -- The subsystem that produced the log (e.g., "gateway", "telegram", "whatsapp").
- module -- A more specific code module identifier.
- message -- The human-readable log message.
This structured format enables both machine parsing (for JSON output mode) and human-friendly rendering (with colorized, time-condensed pretty output).
Log Levels
The logging system uses a hierarchical level scheme:
| Level | Purpose |
|---|---|
| trace | Very fine-grained diagnostic output, typically disabled. |
| debug | Internal state transitions and decision points. |
| info | Normal operational events (message received, response sent). |
| warn | Recoverable issues that may require attention. |
| error | Failures that prevented an operation from completing. |
| fatal | Unrecoverable errors that cause process termination. |
The file logger and console logger can be configured to different minimum levels, allowing verbose file logging for post-mortem analysis while keeping terminal output clean.
Dual-Output Architecture
Log functions in OpenClaw write to two destinations simultaneously:
- File logger -- A rolling JSON log file under
/tmp/openclaw/, rotated daily with automatic pruning of files older than 24 hours. - Console output -- Styled terminal output using the runtime environment's
log/errormethods, with ANSI color coding based on severity.
This dual-output approach ensures that logs are always persisted for later inspection while providing immediate feedback in interactive sessions.
Subsystem Routing
Log messages can be prefixed with a subsystem identifier (e.g., "telegram: message received"). The logging layer automatically parses this prefix and routes the message to a subsystem-specific logger, enabling per-subsystem log filtering and labeling.
Remote Log Tailing
The gateway exposes a logs.tail RPC method that allows the CLI to fetch log lines without direct file access. This is critical for remote gateway configurations where the operator does not have filesystem access to the gateway host. The RPC returns paginated log content with cursor-based positioning for efficient follow mode.
Design Principles
- Never block on logging -- All log transport operations are wrapped in try/catch to ensure that a logging failure never crashes the application.
- Structured first, pretty second -- Logs are stored as structured JSON; human-friendly formatting is applied only at the rendering layer.
- Cursor-based streaming -- Follow mode uses a file cursor to efficiently resume from where the last read left off, avoiding re-reading entire log files.
- Broken pipe safety -- The log CLI detects broken output pipes (e.g., when piped to
head) and exits gracefully instead of crashing.
Relationship to Other Concepts
Log Inspection is a read-only diagnostic capability that complements Health Monitoring (which provides a structured health snapshot) and Diagnostic Repair (which may reference log output when diagnosing problems).