How to Read and Interpret Logs

Overview

Logs are essential for understanding what your agent is doing and diagnosing problems. This guide helps you interpret common log patterns.

For accessing logs, see Reading Real-Time Logs.

Log Entry Anatomy

Typical log entry format:

[2026-02-11 14:32:15 UTC] INFO [Component] Message

Components:

Timestamp: When event occurred (UTC)
Level: Severity (DEBUG, INFO, WARNING, ERROR)
Component: Which part of system logged (OpenClaw, Telegram, AI)
Message: Description of event

Understanding Log Levels

DEBUG

Detailed information for troubleshooting
Usually can be ignored unless debugging specific issue
Example: "Received webhook payload: {...}"

INFO

Normal operational messages
Confirms things are working correctly
Example: "Message processed successfully"

WARNING

Something unexpected but not critical
System continues but may need attention
Example: "Rate limit approaching, slowing requests"

ERROR

Something failed
Requires investigation and action
Example: "Failed to send message: invalid token"

Common Log Patterns

Successful Startup

[INFO] Container starting... [INFO] Environment variables loaded [INFO] Connecting to Telegram API... [INFO] Bot connected: @your_bot [INFO] AI provider initialized: OpenAI GPT-4 [INFO] Agent ready to receive messages

Message Processing

[INFO] New message from user 12345: "Hello" [INFO] Sending to AI model: gpt-4 [INFO] AI response received (120 tokens) [INFO] Sent reply to user 12345

API Authentication Error

[ERROR] AI API authentication failed [ERROR] Invalid API key provided [ERROR] Response: {"error": "invalid_api_key"}

Rate Limiting

[WARNING] Rate limit reached for user 12345 [INFO] Request queued for retry in 60 seconds [INFO] Retry successful

Diagnosing Startup Failures

Look for these patterns:

API Key Issues

[ERROR] Failed to initialize AI provider [ERROR] Authentication failed: invalid API key

Solution: Check OPENAI_API_KEY or ANTHROPIC_API_KEY. See API key errors guide.

Bot Token Issues

[ERROR] Telegram connection failed [ERROR] Invalid bot token

Solution: Verify TELEGRAM_BOT_TOKEN with @BotFather.

Configuration Errors

[ERROR] Missing required environment variable: OPENAI_API_KEY [ERROR] Invalid value for MAX_TOKENS: "abc"

Solution: Check environment variables for typos and correct data types.

Tracking Message Flow

Follow a message through the system:

Receipt: [INFO] New message from user 12345
Processing: [INFO] Sending to AI model: gpt-4
AI Response: [INFO] AI response received (120 tokens)
Reply: [INFO] Sent reply to user 12345

If any step fails, you'll see an ERROR at that point.

Performance Analysis

Look at timestamps to measure performance:

[14:32:45] New message from user 12345 [14:32:47] AI response received (245 tokens) [14:32:48] Sent reply to user 12345

This shows: 2 seconds to get AI response, 1 second total latency. Normal range is 1-10 seconds depending on model.

Error Patterns to Watch For

Repeated Errors

Same error multiple times = systemic issue:

[ERROR] Failed to connect to AI provider (x20)

Action: Check provider status page, verify API key.

Intermittent Errors

Occasional errors = temporary issue or rate limiting:

[ERROR] Connection timeout [INFO] Retry successful

Action: Usually auto-resolves. Monitor if frequency increases.

Cascade Failures

One error leading to many:

[ERROR] AI API key invalid [ERROR] Failed to process message [ERROR] Failed to send error notification [ERROR] Log upload failed

Action: Fix root cause (first error) - others will resolve.

Using Logs for Support

When contacting support, include:

Instance name and subdomain
Timestamp of issue
Screenshot or copy of error logs
Context: what you were trying to do
What you've already tried

Log Retention

Logs retained for 30 days
After 30 days, automatically deleted
Screenshot or copy important errors for later reference

Advanced: Log Correlation

To trace a specific user's journey:

Search logs for user ID
Review all entries in chronological order
Note timing between events
Identify where process broke down

Quick Reference: Error Codes

401: Authentication failed (check API key)
429: Rate limit exceeded (slow down requests)
500: Provider internal error (wait and retry)
502/503: Service temporarily unavailable
Timeout: Request took too long (check network/model speed)