Logging System

OpenClaw uses a structured logging framework that supports subsystem layering, sensitive data redaction, and diagnostic event recording.

Source Location

src/logging/
├── logger.ts            # Core logger implementation
├── subsystem.ts         # Subsystem loggers
├── console.ts           # Console output formatting
├── diagnostic.ts        # Diagnostic event logging
├── redact.ts            # Sensitive data redaction
└── *.test.ts            # Tests

src/logger.ts            # Top-level logging configuration

Logging Architecture

Subsystem Logging

Source: src/logging/subsystem.ts

Logs are layered by subsystem, with each module having its own logger:

// Subsystem logging (simplified)
// Each module creates a subsystem logger
// Supports hierarchical naming (e.g., "gateway.auth", "agent.tools")
// Verbosity controlled per subsystem

Subsystem examples:

Subsystem	Description
gateway	Gateway core
gateway.auth	Authentication module
gateway.methods	Method dispatch
agent	Agent runtime
agent.tools	Tool execution
channels.telegram	Telegram channel
channels.discord	Discord channel
plugins	Plugin system

Console Capture

Source: src/logging.ts

enableConsoleCapture() intercepts all console.* calls and converts them to structured log entries:

// src/logging.ts (simplified)
function enableConsoleCapture(): void {
  // Intercept console.log, console.error, etc.
  // Convert to structured log entries
  // Preserve original stdout/stderr behavior
}

This ensures that even when third-party libraries use console.log(), the output is captured as structured log records.

Sensitive Data Redaction

Source: src/logging/redact.ts

Sensitive data in logs is automatically redacted:

// Redaction rules (simplified)
// - API tokens → "***"
// - Phone numbers → "***1234"
// - Email addresses → "u***@example.com"
// - Passwords → "[REDACTED]"

Redaction is applied automatically before log output, ensuring sensitive information never leaks into log files.

Diagnostic Logging

Source: src/logging/diagnostic.ts

Diagnostic events track system behavior and performance:

// Diagnostic events
// - Operation timing
// - Error traces with context
// - Performance metrics
// - System state snapshots

Verbose Levels

Log detail is controlled through verbose levels:

Level	Output
0	Errors and warnings only
1	Basic operation information
2	Detailed operation information
3	Debug-level output

WebSocket Logging

Source: src/gateway/ws-log.ts

The Gateway's WebSocket communication has a dedicated logging module:

// WebSocket logging (simplified)
// - Connection events (connect, disconnect, error)
// - Method calls (request, response)
// - Event emissions
// - Payload sizes and timing

Summary

• Structured logging framework with subsystem layering and hierarchical naming
• Console Capture intercepts all console.* calls
• Automatic redaction prevents sensitive data (tokens, passwords, phone numbers) from leaking
• Diagnostic events track system behavior and performance
• Verbose levels (0-3) control log detail
• WebSocket communication has dedicated logging