# View Logs and Debug

Troubleshoot issues with system logs and diagnostic tools.

## Accessing Logs

Navigate to **Logs** in the sidebar.

## Log Interface

```
┌─────────────────────────────────────┐
│ Logs                         🔍 🔧  │
├─────────────────────────────────────┤
│ Filter: [All ▼] Search: [      ]   │
├─────────────────────────────────────┤
│ [2026-03-05 21:18:32] [INFO]       │
│ Agent started successfully          │
│                                     │
│ [2026-03-05 21:18:35] [DEBUG]      │
│ Connected to Telegram channel       │
│                                     │
│ [2026-03-05 21:19:01] [ERROR]      │
│ Failed to fetch weather data        │
│ Error: API timeout                  │
│                                     │
└─────────────────────────────────────┘
```

## Log Levels

| Level     | Color     | Meaning              |
| --------- | --------- | -------------------- |
| **ERROR** | 🔴 Red    | Failures, exceptions |
| **WARN**  | 🟡 Yellow | Warnings, issues     |
| **INFO**  | 🟢 Green  | Normal operations    |
| **DEBUG** | ⚪ Gray    | Detailed diagnostics |

## Filtering Logs

### By Level

Select minimum level:

* **Error** - Only errors
* **Warning** - Errors + warnings
* **Info** - Standard view
* **Debug** - Everything

### By Component

Filter by source:

```
All
├── Agent Core
├── Channels
│   ├── Telegram
│   └── Discord
├── Skills
├── Cron Jobs
└── API
```

### By Time

* Last 100 entries
* Last hour
* Last 24 hours
* Custom range

### Search

Find specific text:

```
Search: "telegram"
Results: All messages containing "telegram"
```

## Common Log Patterns

### Startup Sequence

```
[INFO] Agent initializing...
[INFO] Loading configuration
[INFO] Connecting to channels
[INFO] Telegram: Connected
[INFO] Discord: Connected
[INFO] Agent ready
```

Normal startup.

### API Errors

```
[ERROR] LLM API call failed
[ERROR] Status: 402
[ERROR] Message: Insufficient balance
[WARN] Retrying in 5 seconds...
```

Agent wallet needs funding.

### Channel Issues

```
[WARN] Telegram webhook failed
[ERROR] Invalid bot token
[INFO] Attempting reconnect...
```

Check channel configuration.

## Debug Tools

Access **Debug** section for advanced diagnostics.

### Health Check

Run system diagnostic:

```bash
Debug → Health Check → Run
```

Checks:

* Disk space
* Memory usage
* Channel connections
* API accessibility

### Test Connections

Verify external services:

```bash
Debug → Test → Telegram
Debug → Test → Discord
Debug → Test → LLM API
```

### Component Status

View real-time status:

```
┌──────────────────┐
│ Component Status │
├──────────────────┤
│ Agent Core  ✅   │
│ Telegram    ✅   │
│ Discord     ⚠️   │
│ Database    ✅   │
└──────────────────┘
```

## Troubleshooting Common Issues

### Agent Not Responding

1. Check **Logs** for errors
2. Run **Health Check**
3. Verify wallet balance
4. Test channel connections

### High Resource Usage

1. Review **Usage** section
2. Check **Logs** for runaway processes
3. Identify loops or heavy tasks
4. Restart agent if needed

### Channel Problems

1. Test connection in Debug
2. Verify tokens are valid
3. Check logs for webhook errors
4. Reconfigure if necessary

### API Failures

1. Check agent wallet balance
2. Verify API keys in Config
3. Test API in Debug
4. Review rate limit status

## Log Retention

Default retention: 30 days

Older logs automatically purged.

To change:

```
Config → LOG_RETENTION_DAYS=30
```

## Exporting Logs

Download for analysis:

```
Logs → Export → Download .log
```

Or copy-paste specific entries.

## SSH Access for Deep Debug

Connect directly to VPS:

```bash
ssh root@{agent-ip}
```

View system logs:

```bash
cat /var/log/agent.log
docker logs agent
tail -f ~/.openclaw/logs/*.log
```

## Best Practices

✅ **Do**:

* Check logs when issues occur
* Set up alerts for errors
* Review logs periodically
* Keep sensitive info out of logs

❌ **Don't**:

* Ignore warning messages
* Log passwords or keys
* Fill disk with verbose logs
* Delete logs before investigating

## Getting Help

When contacting support, provide:

1. Relevant log excerpts
2. Error messages
3. Steps to reproduce
4. Agent ID and timestamp

## FAQ

**Q: Where are logs stored?** A: In agent's file system: `~/.openclaw/logs/`

**Q: Can I increase log verbosity?** A: Yes, set `LOG_LEVEL=debug` in Config

**Q: How long are logs kept?** A: Default 30 days, configurable

**Q: Can I send logs to external service?** A: Use skills or cron jobs to forward

## Next Steps

→ [Configure Channels](/agos/agos-cloud/agent/channels.md) if connection issues


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://agos.gitbook.io/agos/agos-cloud/agent/logs-debug.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.