Real-Time Monitoring - Mission Control

Overview

Mission Control provides real-time visibility into agent activity through three complementary systems: Activity Feed, Live Sessions, and Log Viewer. Updates arrive via WebSocket (gateway) and Server-Sent Events (database changes) with smart polling fallback.

Real-time monitoring requires either a connected gateway (WebSocket) or an active SSE stream. Both pause polling to reduce server load.

Activity Feed

The Activity Feed is a chronological stream of all system events.

Accessing the Feed

Open Activity Panel

Click Activity in the left navigation rail.

View Live Stream

Events appear instantly as they occur. A pulsing green indicator shows live status.

Filter Events

Use the filter bar to narrow by activity type, actor, or limit.

Event Types

The feed tracks 9+ event types:

Task Events
Agent Events
Communication Events
System Events

task_created — New task added
task_updated — Task status or details changed
task_deleted — Task removed
assignment — Task assigned to agent

Activity Card Structure

Each activity displays:

Icon — Color-coded symbol for event type (e.g., + for created, ~ for updated)
Actor — Who triggered the event (agent name or “system”)
Description — Human-readable event summary
Entity Details — Task title, agent name, or related object info
Timestamp — Relative time (“5m ago”, “2h ago”)
Additional Data — Expandable JSON details (click “Show details”)

Filtering

Narrow the feed using filter controls:

By Activity Type

Select from dropdown:

All Types
task_created
agent_status_change
comment_added
etc.

By Actor

Filter to specific agent or user:

All Actors
researcher-01
system
admin

By Limit

Control result count:

25 items
50 items (default)
100 items
200 items

Live vs. Paused Mode

Toggle auto-refresh with the Live/Paused button:

Live 🟢 — Updates every 30 seconds + instant SSE delivery
Paused ⚫ — Manual refresh only

When SSE is connected, “Live” mode pauses polling and relies entirely on event stream. Notifications arrive within ~50ms.

Live Sessions

Track active agent sessions in real-time (gateway-connected agents only).

Session Attributes

Field	Description
Key	Unique session identifier
Kind	Session type (e.g., “clawd”, “agent”, “cli”)
Age	Time since session started (e.g., “2h”, “5m”)
Model	LLM model in use (normalized, e.g., “sonnet-4”)
Tokens	Usage (e.g., “12.5K/35K”)
Active	Boolean indicator (active if updated within last hour)
Message Count	Number of messages exchanged
Cost	Estimated cost in USD

Viewing Sessions

Sessions appear in the Sessions panel (if gateway is connected) or can be queried via API:

curl http://localhost:3000/api/sessions \
  -H "x-api-key: your-api-key"

Response:

{
  "sessions": [
    {
      "id": "session-abc123",
      "key": "clawd-researcher-01",
      "kind": "clawd",
      "age": "2h",
      "model": "sonnet-4",
      "tokens": "12500/35000",
      "active": true,
      "startTime": 1735689600000,
      "lastActivity": 1735696800000,
      "messageCount": 47,
      "cost": 0.0875
    }
  ]
}

Log Viewer

Stream logs from agents and gateway in real-time.

Accessing Logs

Open Log Viewer

Navigate to Logs in the side panel.

View Stream

Logs auto-scroll as new entries arrive.

Filter

Use level filters (info/warn/error) or search bar.

Log Levels

Debug

Verbose diagnostic messages

Info

Normal operational events

Warn

Potential issues requiring attention

Error

Failures and exceptions

Log Structure

Each log entry includes:

{
  "id": "log-1735696800-abc123",
  "timestamp": 1735696800000,
  "level": "info",
  "source": "agent",
  "session": "clawd-researcher-01",
  "message": "Task #42 completed successfully",
  "data": {"taskId": 42, "duration": 320}
}

Searching Logs

Use the Log Viewer search bar or query via API:

# Search by text
curl http://localhost:3000/api/logs?search=error \
  -H "x-api-key: your-api-key"

# Filter by level
curl http://localhost:3000/api/logs?level=error \
  -H "x-api-key: your-api-key"

# Filter by source
curl http://localhost:3000/api/logs?source=gateway \
  -H "x-api-key: your-api-key"

WebSocket Connection

Mission Control connects to the OpenClaw gateway via WebSocket.

Connection Flow

Challenge-Response Handshake

Client connects to ws://gateway:18789
Server sends connect.challenge with nonce
Client signs payload with Ed25519 device identity
Server validates signature and returns device token

Authenticated Session

WebSocket connection authenticated. Client can subscribe to events.

Heartbeat Monitoring

Client sends ping every 30 seconds. Server responds with pong. RTT tracked.

Connection Status

View connection state in the header bar:

🟢 Connected — Gateway online, receiving events
🟡 Connecting — Handshake in progress
🔴 Disconnected — Offline or connection failed
⚠️ Reconnecting — Attempting reconnection (exponential backoff)

Manual Reconnect

If connection drops:

Check gateway status (is it running?)
Verify OPENCLAW_GATEWAY_HOST and OPENCLAW_GATEWAY_PORT in .env
Click Reconnect in the connection status widget

If handshake fails with “origin not allowed”, add your Mission Control URL to gateway.controlUi.allowedOrigins in the gateway’s openclaw.json.

Server-Sent Events (SSE)

Mission Control uses SSE to stream database change events to all connected clients.

Event Types

agent.created
agent.updated
agent.deleted
task.created
task.updated
task.deleted
comment.added
notification.created

SSE Connection

Clients automatically connect to /api/events on page load:

const eventSource = new EventSource('/api/events')

eventSource.addEventListener('task.updated', (e) => {
  const task = JSON.parse(e.data)
  console.log('Task updated:', task)
})

Connection Indicator

The SSE connection status appears in the Activity Feed:

🟢 SSE Connected — Live event stream active
🔴 SSE Disconnected — Falling back to polling

Smart Polling

When neither WebSocket nor SSE is available, Mission Control uses intelligent polling:

Polling Behavior

Tab Visible
Tab Hidden
WebSocket Connected
SSE Connected

Poll every 30 seconds (configurable per component)
Fire immediate refresh on visibility change
Reset backoff multiplier

Pause polling (events via SSE)
Configurable with pauseWhenSseConnected: true

Implementation

Components use the useSmartPoll hook:

import { useSmartPoll } from '@/lib/use-smart-poll'

function MyPanel() {
  const fetchData = async () => {
    const response = await fetch('/api/data')
    const data = await response.json()
    setData(data)
  }

  // Poll every 30s, pause when SSE is connected
  useSmartPoll(fetchData, 30000, { 
    pauseWhenSseConnected: true 
  })
}

Heartbeat System

Mission Control tracks agent liveness via periodic heartbeats.

Agent Heartbeat

Agents send heartbeats every 60-300 seconds (configurable):

curl -X POST http://localhost:3000/api/agents/{id}/heartbeat \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "status": "idle",
    "last_activity": "Completed task #42"
  }'

Automatic Timeout

The background scheduler runs every 5 minutes:

Query agents with status != 'offline' and last_seen < threshold
Mark stale agents as offline
Log activity: “Agent marked offline (no heartbeat for 10m)”
Create notification for operator

Configure Timeout

Adjust in Settings → General:

{
  "general.agent_heartbeat_timeout": 600
}

Value in seconds (default: 600 = 10 minutes).

WebSocket Heartbeat

Gateway connections send ping/pong every 30 seconds:

Ping sent — Client sends {type: "req", method: "ping", id: "ping-1"}
Pong received — Server responds with {type: "res", id: "ping-1", ok: true}
RTT calculated — Round-trip time displayed in connection status
Missed pongs — After 3 missed pongs (90s), force reconnect

Notifications

Real-time notifications appear in the Notifications panel:

Notification Types

Info — General system messages
Warn — Potential issues (e.g., agent offline)
Error — Critical failures (e.g., deployment failed)
Heartbeat — Agent liveness alerts

Viewing Notifications

Open Panel

Click Notifications in the side rail.

Review Items

Unread notifications appear bold.

Mark Read

Click a notification to mark it read.

Clear All

Click Clear All to dismiss all notifications.

API Access

# Get notifications for current user
curl http://localhost:3000/api/notifications \
  -H "x-api-key: your-api-key"

# Mark as read
curl -X PUT http://localhost:3000/api/notifications/{id} \
  -H "Content-Type: application/json" \
  -d '{"read": true}'

Performance Metrics

Connection Latency

WebSocket RTT displayed in connection status widget:

< 50ms — Excellent
50-100ms — Good
100-200ms — Fair
> 200ms — Check network or gateway load

Event Delivery

WebSocket — Near-instant (< 10ms after gateway receives event)
SSE — Fast (< 50ms after database write)
Polling — Delayed (up to 30s depending on interval)

Troubleshooting

Activity Feed Not Updating

Check SSE connection status (green indicator)
Verify browser dev tools for SSE errors
Confirm Live mode is enabled
Try clicking Refresh manually

WebSocket Connection Failed

Verify gateway is running: ps aux | grep gateway
Check gateway port: OPENCLAW_GATEWAY_PORT in .env
Test gateway directly: wscat -c ws://localhost:18789
Check allowedOrigins in gateway openclaw.json

Logs Not Appearing

Confirm gateway is connected (green status)
Check log level filters (remove any filters)
Verify agents are sending logs (check gateway logs)
Try /api/logs endpoint directly to rule out UI issue

Next Steps

Cost Tracking

Monitor token usage and costs with per-model breakdowns

Background Automation

Configure automated tasks and monitoring rules

Get Started

Core Features

Integrations

Deployment

Advanced

Documentation Index

​Overview

​Activity Feed

​Accessing the Feed

​Event Types

​Activity Card Structure

​Filtering

​Live vs. Paused Mode

​Live Sessions

​Session Attributes

​Viewing Sessions

​Log Viewer

​Accessing Logs

​Log Levels

Debug

Info

Warn

Error

​Log Structure

​Searching Logs

​WebSocket Connection

​Connection Flow

​Connection Status

​Manual Reconnect

​Server-Sent Events (SSE)

​Event Types

​SSE Connection

​Connection Indicator

​Smart Polling

​Polling Behavior

​Implementation

​Heartbeat System

​Agent Heartbeat

​Automatic Timeout

​WebSocket Heartbeat

​Notifications

​Notification Types

​Viewing Notifications

​API Access

​Performance Metrics

​Connection Latency

​Event Delivery

​Troubleshooting

​Next Steps

Cost Tracking

Background Automation

Build docs developers (and LLMs) love

Overview

Activity Feed

Accessing the Feed

Event Types

Activity Card Structure

Filtering

Live vs. Paused Mode

Live Sessions

Session Attributes

Viewing Sessions

Log Viewer

Accessing Logs

Log Levels

Log Structure

Searching Logs

WebSocket Connection

Connection Flow

Connection Status

Manual Reconnect

Server-Sent Events (SSE)

Event Types

SSE Connection

Connection Indicator

Smart Polling

Polling Behavior

Implementation

Heartbeat System

Agent Heartbeat

Automatic Timeout

WebSocket Heartbeat

Notifications

Notification Types

Viewing Notifications

API Access

Performance Metrics

Connection Latency

Event Delivery

Troubleshooting

Next Steps