System Help

Architecture, processes, and API reference

← Portal

Architecture Overview

This system runs on a Mac Mini (Apple Silicon, 48GB). OpenClaw agent orchestrates everything. Each app is a standalone Node.js or Python server. The portal (port 5190) ties them together.

Running Processes

Service Port What it does Managed by
OpenClaw 18789 Main agent runtime — model routing, skills, session management launchd
Portal Auth 5190 Login portal + app proxy + heartbeat alerts launchd (com.portal.auth)
Mission Control 5173 Agent monitoring dashboard — costs, model health, events, graph heartbeat
Cost Guard 7720 Budget enforcement + model proxy — all paid model calls route here launchd (com.cost-guard.api)
Market Research 8095 Stock ticker scanning, AI research, opportunity scoring heartbeat
YouTube Synopsis 5182 Channel monitoring, transcript extraction, AI synopsis generation launchd (com.ys-ui)
Document Finder 8093 Gmail invoice/receipt/attachment scanner & classifier heartbeat
X Briefing (GX) 5181 Grok-powered X/Twitter post summarization & briefing heartbeat
Video Analysis 5191 Standalone video transcript + ticker extraction API heartbeat
Filing System 8091/8092 Document management & search (backend + frontend) heartbeat
MUE API 7710 Model Usage Engine — model pricing, sync, fallback chains heartbeat
Prediction Market 5183 Prediction market arbitrage scanner manual

Heartbeat Monitor

The heartbeat monitor at projects/heartbeat-monitor/heartbeat.sh runs every 60 seconds via launchd. It checks each service four ways:

  1. Port listening — is the TCP port open?
  2. Health endpoint — does the HTTP health check respond?
  3. CLOSE_WAIT count — more than 20 stuck connections triggers a restart
  4. CPU spike — sustained >80% CPU for 2+ checks triggers a restart

After 2 consecutive failures, the service is force-killed and restarted. Alerts are sent via Telegram. Caddy (TLS proxy on port 443) is also monitored.

Cost Guard Proxy

POST /api/proxy/chat at localhost:7720 is the mandatory gateway for all paid model calls. Every app routes through it:

  1. Estimates cost based on model + token count
  2. Checks budget against the app's configured limit
  3. Returns 402 Payment Required if budget is exceeded (hard block)
  4. Can reroute to a cheaper model when thresholds are near
  5. Logs every call with real token counts and cost to MC dashboard

Supported backends: ollama/gemma3:12b (free), ollama/glm-4.7-flash (free), openai/gpt-4o-mini (paid), xai/grok-4.3 (paid). Any app that calls a model directly (bypassing the proxy) will have a budget hole — the proxy is the only gate.

Model Routing (Agent)

The OpenClaw agent (me) uses the configured fallback chain in openclaw.json:

deepseek/deepseek-v4-flash → xai/grok-4.3 → zai/glm-5.1 → ollama/glm-4.7-flash

Every agent call is logged in ~/.openclaw/agents/*/sessions/*.jsonl with model, tokens, cache hits, and cost. MC's costs_db.py parses these on startup to build the dashboard. Pricing is auto-discovered from the MUE database on every seed — no manual table to maintain.

Quick Reference

Endpoint Description
/mc/ Mission Control dashboard
/cogu/ Cost Guard panel (spend chart, budget thresholds)
/cogu/api/status Cost Guard raw API status (JSON)
/api/sparkline 7-day spend sparkline data (JSON)
/mr/ Market Research dashboard
/ys/ YouTube Synopsis dashboard
/df/ Document Finder dashboard
/gx/ X Briefing dashboard
/fs/ Filing System