Mission Control

Auto-refreshes every 5 seconds (configurable in HTML).

System Architecture

Components

1. Data Collector (_collect_data.py)

   • Location: ~/.openclaw/workspace/scripts/_collect_data.py
   • Queries: gateway status, agent states, cron jobs, Sentinel alerts
   • Output: dashboard_data.json (workspace root)
   • Run mode: Background daemon via dashboard_refresh.sh

2. Dashboard Server (serve.js)

   • Location: ~/.openclaw/workspace/serve.js
   • Port: 8787
   • Serves: dashboard.html + dashboard_data.json
   • LaunchAgent: ~/Library/LaunchAgents/ai.openclaw.dashboard.plist

3. Dashboard HTML (dashboard.html)

   • Location: ~/.openclaw/workspace/dashboard.html
   • Auto-refresh: Polls dashboard_data.json every 5s
   • Panels: Gateway, Agents, Cron Jobs, Security (Sentinel)

4. Refresh Daemon (dashboard_refresh.sh)

   • Location: ~/.openclaw/workspace/scripts/dashboard_refresh.sh
   • Runs: _collect_data.py every 5 seconds
   • Managed by: LaunchAgent (auto-restart on crash)

Data Flow

┌─────────────────────┐
│  LaunchAgent        │ ← Starts on boot
│  (dashboard.plist)  │
└──────────┬──────────┘
           │
           ├─→ serve.js (port 8787)
           │   └─→ Serves dashboard.html
           │
           └─→ dashboard_refresh.sh
               └─→ _collect_data.py (every 5s)
                   └─→ dashboard_data.json

Quick Commands

Check Dashboard Status

# Is the server running?
lsof -ti:8787

# Check LaunchAgent status
launchctl list | grep ai.openclaw.dashboard

# View collector logs (if logging enabled)
cat ~/.openclaw/workspace/scripts/dashboard_collector.log

Manual Data Collection

cd "~/.openclaw/workspace"
python3 scripts/_collect_data.py
cat dashboard_data.json | jq .

Restart Dashboard

# Restart LaunchAgent
launchctl unload ~/Library/LaunchAgents/ai.openclaw.dashboard.plist
launchctl load ~/Library/LaunchAgents/ai.openclaw.dashboard.plist

View in Browser

open http://127.0.0.1:8787/

Extending the Dashboard

Add a New Data Section

1. Edit _collect_data.py:

   # Add new collector function
   def collect_new_section():
       return {
           "status": "ok",
           "your_data": "here"
       }
   
   # Add to main data dict
   data["newSection"] = collect_new_section()
   

2. Update dashboard.html:

   <!-- Add new panel -->
   <div class="panel">
       <h2>New Section</h2>
       <div id="new-section-content"></div>
   </div>
   
   <!-- Add render function -->
   <script>
   function renderNewSection(data) {
       const container = document.getElementById('new-section-content');
       container.innerHTML = `<p>${data.newSection.status}</p>`;
   }
   
   // Call from updateDashboard()
   renderNewSection(data);
   </script>
   

3. Test:

   python3 scripts/_collect_data.py
   # Check dashboard at http://127.0.0.1:8787/
   

Add a New Panel

Panels are defined in dashboard.html. Structure:

<div class="panel">
    <h2>Panel Title</h2>
    <div class="metric">
        <span class="label">Metric Name:</span>
        <span class="value" id="metric-id">Value</span>
    </div>
</div>

Use CSS classes for status indicators:

• .status-ok → Green
• .status-warning → Yellow
• .status-error → Red

Change Refresh Interval

Dashboard refresh (browser): Edit dashboard.html, find setInterval, change 5000 (5s):

setInterval(fetchData, 5000); // milliseconds

Data collector refresh (backend): Edit scripts/dashboard_refresh.sh, change sleep 5:

while true; do
    python3 "$SCRIPT_DIR/_collect_data.py"
    sleep 5  # seconds
done

Then restart LaunchAgent.

Data Schema Reference

Current dashboard_data.json structure:

{
  "timestamp": "2026-03-07T15:20:30Z",
  "gateway": {
    "reachable": true,
    "version": "2026.3.2",
    "uptime": "2d 14h 22m"
  },
  "agents": [
    {
      "id": "main",
      "name": "Sherlock",
      "model": "anthropic/claude-opus-4-6",
      "contextPercent": 23.4,
      "lastActiveAgeMs": 120000
    }
  ],
  "cronJobs": [
    {
      "id": "morning-briefing",
      "label": "Morning Briefing",
      "schedule": "0 8 * * *",
      "enabled": true,
      "lastRunTime": "2026-03-07T08:00:00Z",
      "consecutiveErrors": 0
    }
  ],
  "security": {
    "sentinelActive": true,
    "pendingAlerts": 0,
    "lastCheckAgeMs": 300000
  }
}

Monitoring Best Practices

1. Context Thresholds:

   • <30%: Normal
   • 30-50%: Watch
   • 50-60%: Prepare to flush

   • 60%: Stuck (alert needed)

2. Cron Job Health:

   • consecutiveErrors > 2: Investigate
   • lastRunTime > schedule interval: Missed runs

3. Sentinel Alerts:

   • pendingAlerts > 0: Unprocessed threats

4. Gateway:

   • reachable: false: Core system down

Troubleshooting

Dashboard won't load:

# Check server is running
lsof -ti:8787

# Check LaunchAgent
launchctl list | grep dashboard

# Restart
launchctl unload ~/Library/LaunchAgents/ai.openclaw.dashboard.plist
launchctl load ~/Library/LaunchAgents/ai.openclaw.dashboard.plist

Data not updating:

# Check refresh script is running
ps aux | grep dashboard_refresh.sh

# Check data file is being written
ls -lh ~/.openclaw/workspace/dashboard_data.json

# Manual collection test
python3 ~/.openclaw/workspace/scripts/_collect_data.py

Stale data:

• Check timestamp field in dashboard_data.json
• Verify collector isn't crashing (check _collect_data.py for errors)
• Ensure gateway is reachable from collector

Notes

• Dashboard server runs on localhost only (not exposed to network)
• Data collection uses OpenClaw gateway API (requires gateway running)
• Auto-starts on boot via LaunchAgent
• Refresh rate tunable (default: 5s backend + 5s frontend)
• Lightweight: ~1-2% CPU, <50MB RAM