Admin Guide

Overview

The OpenClaw Project Dashboard is an operations-first task management system with a Win11-style desktop shell UI. It integrates with the OpenClaw agent runtime for bidirectional agent communication.

Server Management

Start

node task-server.js

Restart

bash scripts/restart-task-server.sh

Health Check

bash scripts/dashboard-health.sh check

Validate API

node scripts/dashboard-validation.js

Database Management

Apply a Migration

bash scripts/apply-workflow-migration.sh schema/migrations/001_add_workflow_runs.sql

Check Database Connection

PGPASSWORD=$POSTGRES_PASSWORD psql -h $POSTGRES_HOST -U $POSTGRES_USER -d $POSTGRES_DB -c "SELECT 1;"

Reset (Destructive)

psql -U postgres -d mission_control -f schema/openclaw-dashboard.sql

Snapshots & Restore (backup)

Full-state backup as JSON artifacts in storage/snapshots/ (docs/briefs/snapshot-restore.md; no new DB tables — the registry is the directory listing). Artifacts are secret-free by construction: settings carry config-source keys only, and a deny-regex pass redacts secret-looking values anywhere in the payload.

# Create (requires PostgreSQL)
curl -X POST http://localhost:3876/api/snapshots -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"name":"pre-maintenance"}'

# List / download
curl http://localhost:3876/api/snapshots -H "Authorization: Bearer $TOKEN"
curl -OJ http://localhost:3876/api/snapshots/<snapshot_id>/download -H "Authorization: Bearer $TOKEN"

# Dry-run diff preview (nothing written), then apply merge or replace
curl -X POST http://localhost:3876/api/restore/preview -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"snapshot_id":"<id>"}'
curl -X POST http://localhost:3876/api/restore/apply -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"snapshot_id":"<id>","mode":"merge","restoreId":"<uuid>"}'

Notes: restore requests over RESTORE_MAX_BYTES (default 100 MB) are rejected 413 before parsing. Apply is checkpointed per table — re-POST with the same restoreId to resume after a partial failure; a completed apply replays as {duplicate:true} doing nothing. Replace mode deletes rows absent from the artifact — take a fresh snapshot first (that IS the rollback move). Without PostgreSQL, create/preview/apply answer 503 {available:false} while list/download keep working from disk.

Cron Job Management

Install Cron Jobs

Cron definitions are in crontab/ files. Install with:

cat crontab/*.cron | crontab -

Monitor Cron

The cron-manager-server (port 3878) provides an API. Since the 2026-08 security fixes it requires a bearer token and only accepts loopback Host headers (see SECURITY-AUDIT-2026-08.md F2/F3):

curl -H "Authorization: Bearer $DASHBOARD_AUTH_TOKEN" \
     http://127.0.0.1:3878/api/cron-admin/jobs

Keepalive Servers

The cron-manager and memory-api servers auto-restart every 2 minutes via keepalive crons. They log health checks to /tmp/cron-manager-restart.log and /tmp/memory-api-restart.log.

Agent Integration

Agent Reporting

Agents report work to the Kanban board via agent_reporter.py:

# Create task
python3 scripts/agent_reporter.py task create -t "Task title" -p "Project" --auto-claim

# Complete task
python3 scripts/agent_reporter.py task complete -i <task-id>

Agent Heartbeat

Agents send heartbeats via:

python3 scripts/agent_reporter.py heartbeat

The dashboard displays live agent status in the Agents view.

Gateway Sync

The gateway sync runs every 30 seconds, pulling OpenClaw agent status into the dashboard. Enable via:

# Already configured in crontab
* * * * * node /path/to/sync-gateway-status.mjs >> /path/to/logs/sync-gateway-status.log 2>&1

Troubleshooting

Server won’t start

# Check if port is in use
ss -tlnp | grep 3876

# Check database connection
PGPASSWORD=postgres psql -h 127.0.0.1 -U postgres -d mission_control -c "SELECT 1;"

# Check logs
node task-server.js 2>&1 | head -20

Blank page in browser

1. Check server is running: curl http://localhost:3876/api/health
2. Check browser console for JS errors
3. Clear browser cache and hard refresh

Cron jobs showing stale

1. Verify crontab is installed: crontab -l | grep cron-manager
2. Check keepalive log: tail -20 /tmp/cron-manager-restart.log
3. Run heartbeat guard: python3 scripts/heartbeat_cron_guard.py --json

Widget panel not loading

1. Check IndexedDB availability in browser
2. Clear site data: DevTools → Application → Clear storage
3. Hard refresh the page

Customization

CSS Theme

The Win11 theme uses CSS variables. Edit src/styles/win11-theme.css:

:root {
  --win11-accent: #0078d4;
  --win11-bg: #202020;
  /* ... */
}

Add a Custom View

See DEVELOPER_GUIDE.md → “Adding a New View”

Security

• All credentials via environment variables (.env)
• Dashboard API auth is single-operator bearer token mode via DASHBOARD_AUTH_TOKEN
• /api/health and /api/auth/self are public; other /api/* routes require the bearer token when configured
• Full login/session/RBAC auth is deferred until a multi-operator requirement exists
• Secret scanning pipeline in src/security/
• No hardcoded credentials in codebase
• CORS headers configured per-origin
• See docs/auth-reference.md for the current auth contract
• See .env.example for all configurable settings

Support

• Issues: https://github.com/pgedeon/openclaw-project-webos/issues