Skip to main content

​
Overview

The Logs API provides access to structured log files from OpenClaw agents, gateway processes, and Mission Control itself. Logs are automatically discovered from the configured logs directory and parsed into a unified format.
Logs are read from the filesystem at $LOGS_DIR (configured in environment). Multiple log formats are supported including JSON, pipe-delimited, and journal formats.

​
Get Recent Logs

​
GET /api/logs?action=recent

Retrieve recent log entries with optional filtering.

​
Query Parameters

​
action
string
default:"recent"
Action to perform: recent, sources, or tail
​
limit
integer
default:"100"
Number of log entries to return (max 200)
​
level
string
Filter by log level: info, warn, error, debug
​
source
string
Filter by log source (e.g., gateway, automation/monitor, agent name)
​
session
string
Filter by session ID (for gateway logs)
​
search
string
Search term to filter messages (case-insensitive)

​
Response

​
logs
array
Array of log entries
​
id
string
Unique log entry identifier
​
timestamp
integer
Unix timestamp (milliseconds)
​
level
string
Log level: info, warn, error, debug
​
source
string
Log source (file name or agent identifier)
​
session
string
Session ID (if applicable)
​
message
string
Log message
​
data
object
Additional structured data (if available)
curl -X GET "https://your-instance.com/api/logs?level=error&limit=50" \
  -H "Cookie: mc-session=your-session-token"

​
Response Example

{
  "logs": [
    {
      "id": "gateway-1709823456789-a3c9f2",
      "timestamp": 1709823456789,
      "level": "error",
      "source": "gateway",
      "session": "session-42",
      "message": "Model request failed: timeout after 30s",
      "data": {
        "model": "gpt-4",
        "retries": 3
      }
    },
    {
      "id": "automation/monitor-1709823123456-b4d1a8",
      "timestamp": 1709823123456,
      "level": "info",
      "source": "automation/monitor",
      "message": "Consistency check completed"
    },
    {
      "id": "DataAnalyst-1709822987654-c2e5f9",
      "timestamp": 1709822987654,
      "level": "warn",
      "source": "DataAnalyst",
      "message": "Large dataset detected, processing may take longer"
    }
  ]
}

​
List Available Sources

​
GET /api/logs?action=sources

Discover all available log sources. 
curl -X GET "https://your-instance.com/api/logs?action=sources" \
  -H "Cookie: mc-session=your-session-token"

​
Response Example

{
  "sources": [
    "gateway",
    "automation/monitor",
    "automation/scheduler",
    "DataAnalyst",
    "CodeReviewer"
  ]
}

​
Tail Logs (Real-Time)

​
GET /api/logs?action=tail

Get new logs since a specific timestamp for real-time monitoring.

​
Query Parameters

​
action
string
required
Set to tail
​
since
integer
required
Unix timestamp (milliseconds). Returns only logs after this time.
​
source
string
Filter by specific source
​
limit
integer
default:"100"
Maximum entries to return
curl -X GET "https://your-instance.com/api/logs?action=tail&since=1709823000000" \
  -H "Cookie: mc-session=your-session-token"

​
Add Custom Log Entry

​
POST /api/logs

Create a custom log entry (requires operator role).

​
Request Body

​
action
string
required
Set to add
​
message
string
required
Log message
​
level
string
default:"info"
Log level: info, warn, error, debug
​
source
string
default:"mission-control"
Custom source identifier
​
session
string
Session ID to associate with log
curl -X POST "https://your-instance.com/api/logs" \
  -H "Cookie: mc-session=your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "add",
    "message": "Custom deployment started",
    "level": "info",
    "source": "deployment-script"
  }'

​
Response

{
  "success": true,
  "entry": {
    "id": "custom-1709823456789-d3f4g5",
    "timestamp": 1709823456789,
    "level": "info",
    "source": "deployment-script",
    "message": "Custom deployment started",
    "data": null
  }
}

​
Log Format Detection

The Logs API automatically parses multiple log formats:

​
JSON Format

{"timestamp":1709823456789,"level":"info","message":"Task completed","data":{...}}

​
Pipe-Delimited Format

2026-03-07T14:30:56+01:00|INFO|Consistency check completed
2026-03-07T14:30:57+01:00|ERROR|Connection failed

​
Gateway Journal Format

2026-03-07T14:30:56+01:00 hostname openclaw[12345]: Model request completed

​
Simple Text with ISO Timestamp

2026-03-07T14:30:56.789Z [INFO] Processing started
2026-03-07T14:30:57.123Z [ERROR] Failed to connect

​
Use Cases

​
Monitor Errors Across All Sources

const response = await fetch('/api/logs?level=error&limit=100');
const { logs } = await response.json();

const errorsBySource = logs.reduce((acc, log) => {
  acc[log.source] = (acc[log.source] || 0) + 1;
  return acc;
}, {});

console.log('Errors by source:', errorsBySource);

​
Track Gateway Session Issues

const sessionId = 'session-42';
const response = await fetch(
  `/api/logs?source=gateway&session=${sessionId}&level=warn`
);
const { logs } = await response.json();

​
Search for Specific Events

const response = await fetch(
  '/api/logs?search=timeout&limit=50'
);
const { logs } = await response.json();

​
Error Responses

​
error
string
Error message
Status CodeDescription
400Bad request - Invalid parameters
401Unauthorized - Invalid or missing session
403Forbidden - Insufficient permissions (operator required for POST)
429Rate limited
500Internal server error