Reading Real-Time Logs

Overview

Real-time logs provide visibility into your agent's activity, helping you debug issues, monitor performance, and understand user interactions.

Accessing Logs

1. Navigate to your instance details page
2. Click the "Logs" tab in the navigation
3. Logs will stream in real-time as your agent runs

Log Levels

Logs are categorized by severity level:

• INFO: Normal operations and events
• WARNING: Potential issues that don't stop execution
• ERROR: Critical issues that prevent operation
• DEBUG: Detailed information for troubleshooting

Understanding Log Entries

Each log entry contains:

• Timestamp: When the event occurred (UTC)
• Level: Severity (INFO, WARNING, ERROR, DEBUG)
• Source: Component that generated the log
• Message: Description of the event

Example Log Entry

[2026-02-11 14:32:15 UTC] INFO [OpenClaw] Agent started successfully [2026-02-11 14:32:16 UTC] INFO [Telegram] Connected to bot @myagent_bot [2026-02-11 14:32:45 UTC] INFO [AI] Processing message from user 12345 [2026-02-11 14:32:47 UTC] INFO [AI] Response generated (245 tokens)

Common Log Patterns

Startup Sequence

[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

Errors

[ERROR] Failed to connect to Telegram: invalid bot token [ERROR] AI API error: quota exceeded [ERROR] Authentication failed: invalid API key

Filtering and Searching Logs

Filter by Level

Use the level filter dropdown to show only specific log types:

• All logs (default)
• Errors only
• Warnings and errors
• Info and above

Search Logs

Use the search box to find specific events:

• Search by user ID
• Search by error message
• Search by timestamp
• Search by component name

Log Retention

Logs are retained for 30 days from creation. After 30 days, they are automatically deleted to save storage.

To preserve logs long-term:

• Copy important log entries manually
• Take screenshots of error messages
• Export logs before the 30-day window (export feature coming soon)

Using Logs for Troubleshooting

Diagnosing Startup Failures

1. Look for the first ERROR message
2. Check if environment variables loaded correctly
3. Verify API connections were established
4. Note any authentication failures

Tracking Message Failures

1. Search for the user ID or message timestamp
2. Look for ERROR entries in the message flow
3. Check AI provider response codes
4. Verify the complete request/response cycle

Monitoring Performance

1. Check timestamps between request and response
2. Look for slow API calls (>10 seconds)
3. Monitor token usage in AI responses
4. Track message throughput during peak times

Real-Time vs Historical Logs

Real-Time Mode

• Shows logs as they occur
• Auto-scrolls to newest entries
• Best for monitoring active instances
• Click "Pause" to stop auto-scroll

Historical Mode

• View logs from past 30 days
• Select date range to view
• Search and filter old logs
• Best for investigating past issues

Best Practices

• Check logs after starting: Verify successful initialization
• Monitor regularly: Review logs weekly for warnings
• Screenshot errors: Save error messages for support tickets
• Use filters: Focus on relevant log levels
• Check timestamps: Correlate logs with user reports
• Look for patterns: Recurring errors may indicate config issues

Common Errors and Solutions

"Invalid API key"

Solution: Verify your OPENAI_API_KEY or ANTHROPIC_API_KEY is correct. See API key errors guide.

"Quota exceeded"

Solution: Check your AI provider billing and increase usage limits. See pricing and billing.

"Connection timeout"

Solution: Network issue with AI provider or messaging platform. Check connection issues guide.

"Bot token invalid"

Solution: Verify your TELEGRAM_BOT_TOKEN or DISCORD_BOT_TOKEN. See Telegram setup guide.

Log Privacy and Security

Important notes about log privacy:

• API keys are never logged: Secrets are redacted in logs
• User messages may appear: Be aware of sensitive data
• Logs are encrypted at rest: Stored securely on AWS
• Only you can access: Logs are isolated per instance
• Auto-deleted after 30 days: Reduces data retention

Next Steps

• Learn about starting and stopping instances
• Understand troubleshooting instance failures
• Read about updating environment variables