Logs API

Access system logs from OpenClaw agents and gateway processes

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

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

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

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

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 Code	Description
400	Bad request - Invalid parameters
401	Unauthorized - Invalid or missing session
403	Forbidden - Insufficient permissions (operator required for POST)
429	Rate limited
500	Internal server error