🔌 ClawBoard

Your AI Dashboard for OpenClaw

ClawBoard is a comprehensive web-based dashboard for managing and monitoring your OpenClaw AI agent. It provides a beautiful, modern interface for task management, project tracking, journal entries, conversation history, and real-time agent monitoring.

**Repository: github.com/Wadera/clawboard

✨ Features

• 📋 Task Board — Kanban-style task management with drag-and-drop, subtasks, priorities, and dependencies
• 🗂️ Project Management — Organize tasks into projects with links, notebooks, environments, and resources
• 📝 Journal — Daily journal entries with mood tracking, multi-entry per day, and navigation
• 💬 Sessions — Browse and search through all agent conversation transcripts
• 🤖 Real-time Agent Status — Monitor your OpenClaw agent's activity, connections, and health
• 📊 Statistics — Visual insights into task completion, project progress, and agent activity
• 🔌 Plugin System — Extend your dashboard with Docker-based plugins (journals, monitors, blogs, etc.)
• 🎨 Fully Customizable — Theme colors, branding, feature toggles, custom avatars
• 🔐 Secure — Password-protected with JWT authentication
• 🐳 Docker-Ready — Complete Docker Compose setup with health checks
• 🔄 Real-time Updates — WebSocket integration for live dashboard updates

🖼️ Screenshots

Screenshots coming soon! After deployment, we'll add visual examples of the dashboard in action.

Dashboard Overview

Placeholder for main dashboard screenshot

Task Board

Placeholder for Kanban board screenshot

Projects

Placeholder for project management screenshot

Agent Status

Placeholder for agent monitoring screenshot

🚀 Quick Start

Get ClawBoard running in 5 minutes:

# 1. Clone repository
git clone https://github.com/Wadera/clawboard.git
cd ClawBoard

# 2. Run setup script (generates .env with password hash)
./setup.sh

# 3. Start services
docker compose up -d

# 4. Access dashboard
open http://localhost:8080/dashboard/

Prerequisites:

• Docker & Docker Compose
• OpenClaw installed and running
• 2GB RAM, 1 CPU core

What the setup script does:

• Creates .env from .env.example
• Generates bcrypt password hash for dashboard login
• Sets up database credentials and JWT secret
• Configures OpenClaw integration paths
• Creates data and backup directories

🧠 OpenClaw Workspace Integration

ClawBoard automatically reads and displays your bot's workspace files, giving you direct visibility into your agent's personality, memory, and configuration.

What Gets Loaded

The following files from your OpenClaw workspace are accessible in the dashboard:

• SOUL.md — Your bot's personality, identity, and core values
• HEARTBEAT.md — Heartbeat monitoring configuration and tasks
• AGENTS.md — Agent behavior, memory rules, and conventions
• USER.md — Information about the human the bot serves
• memory/YYYY-MM-DD.md — Daily memory logs
• memory/*.md — Additional memory files

How It Works

The workspace is mounted read-only into the ClawBoard backend container:

volumes:
  - ${OPENCLAW_WORKSPACE:-~/.openclaw/workspace}:/workspace:ro

Configuration in .env:

# Path to your bot's workspace directory
OPENCLAW_WORKSPACE=~/.openclaw/workspace

Dashboard Features

When workspace files are loaded, you'll see:

• Workspace Files Widget — Browse and view workspace files directly in the dashboard
• Bot Personality Card — Displays bot name and identity from SOUL.md
• Memory Timeline — Navigate through daily memory logs
• Quick File Access — Jump to any workspace file with one click

Verification

To verify the workspace integration is working:

1. Log into the dashboard at http://localhost:8080/dashboard/
2. Look for the "Workspace Files" widget on the main dashboard
3. Click on any file (e.g., SOUL.md) to view its contents
4. If files don't appear, check:
   • .env has correct OPENCLAW_WORKSPACE path
   • The path exists and contains the expected files
   • Docker container has been restarted after .env changes

Troubleshooting

Files not showing up?

# Check if workspace path is correct
ls -la ~/.openclaw/workspace

# Verify .env configuration
grep OPENCLAW_WORKSPACE .env

# Restart containers to pick up changes
docker compose restart clawboard-backend

Permission issues?

The workspace is mounted read-only, so ClawBoard cannot modify your files. If you need to edit them, use your preferred editor on the host system.

📚 Documentation

Documentation lives in docs/:

• Getting Started — 5-minute quick start guide
• Plugin Development — Build your own plugins
• Example Plugin — Minimal hello-world plugin to learn from
• Project Overview — Architecture deep dive
• Deployment Guide — Production deployment (Traefik, Nginx, Docker)
• Database Guide — Schema, backup, restore
• Contributing — How to contribute

🏗️ Architecture

┌─────────────────────────────────────────┐
│         ClawBoard Frontend              │
│      React + TypeScript + Vite          │
│         Port: 8080 → 80                 │
└────────────┬────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────┐
│         ClawBoard Backend               │
│      Node.js + Express + TypeScript     │
│         Port: 3001 (internal)           │
└──────┬──────────────────────────────────┘
       │
       ├──────────► OpenClaw Gateway
       │            (WebSocket: ws://host.docker.internal:18789)
       │
       └──────────► PostgreSQL 16
                    (Internal only)

Components:

• Frontend: Static React app served by nginx
• Backend: REST API + WebSocket gateway + Plugin proxy
• Database: PostgreSQL for persistent storage
• OpenClaw: Read-only integration for session data
• Plugins: Docker containers loaded on startup (optional)

🛠️ Tech Stack

Frontend

• React 18
• TypeScript
• Vite
• CSS (no framework)

Backend

• Node.js 18+
• Express.js
• TypeScript
• PostgreSQL (node-postgres)
• WebSocket (ws)

Infrastructure

• Docker & Docker Compose
• PostgreSQL 16
• Nginx (frontend serving)
• Traefik / Nginx (optional reverse proxy)

📦 Installation

Prerequisites

# Check Docker
docker --version
docker compose version

# Check OpenClaw
openclaw status

Option 1: Quick Setup (Recommended)

./setup.sh
docker compose up -d

The setup script will guide you through configuration interactively.

Option 2: Manual Setup

# 1. Create .env
cp .env.example .env
nano .env
# Set POSTGRES_PASSWORD, JWT_SECRET, LOGIN_PASSWORD, OPENCLAW_DIR

# 2. Create config
cp clawboard.config.example.json clawboard.config.json
nano clawboard.config.json
# Customize bot name, colors, features

# 3. Start services
docker compose up -d

# 4. Check status
docker compose ps

Option 3: Development Setup

# Start dev stack with hot reload
docker compose -f docker-compose.dev.yml up

🖥️ CLI Tool

ClawBoard includes a command-line tool for managing tasks, projects, tools, and journals.

Setup

# Make executable and add to PATH
chmod +x cli/clawboard
export PATH="$(pwd)/cli:$PATH"

# Or create a symlink
ln -s "$(pwd)/cli/clawboard" /usr/local/bin/clawboard

# Configure API URL (default: http://localhost:8080/api)
export CLAWBOARD_API_URL="http://localhost:8080/api"

Authentication

# Login (stores token in ~/.config/clawboard/token.json)
clawboard login

# Or use environment variables
export CLAWBOARD_PASSWORD="your-dashboard-password"

Quick Start

clawboard list                          # List all tasks
clawboard create "My first task"        # Create a task
clawboard projects                      # List projects
clawboard tools list                    # List tools
clawboard tools generate-md --slim      # Generate TOOLS.md
clawboard journal list                  # List journal entries
clawboard status                        # Dashboard overview

TOOLS.md Bootstrapping

After deploying ClawBoard, bootstrap the tool registry so your bot knows how to use the dashboard:

# 1. Login to the CLI
clawboard login

# 2. Add your tools (or import from a template)
clawboard tools list

# 3. Generate TOOLS.md for your bot's workspace
clawboard tools generate-md --slim -o /path/to/bot/workspace/TOOLS.md

The generated TOOLS.md gives your OpenClaw bot context about available tools and how to use them.

⚙️ Configuration

Environment Variables (.env)

# Database
POSTGRES_PASSWORD=your-secure-password

# Authentication
JWT_SECRET=your-random-hex-string
LOGIN_PASSWORD=your-dashboard-password

# OpenClaw Integration
OPENCLAW_DIR=~/.openclaw
OPENCLAW_GATEWAY_URL=ws://host.docker.internal:18789

# Deployment
FRONTEND_PORT=8082
DOMAIN=localhost

Dashboard Configuration (clawboard.config.json)

{
  "bot": {
    "name": "ClawBot",
    "displayName": "My ClawBoard",
    "emoji": "🤖"
  },
  "branding": {
    "primaryColor": "#6366f1",
    "accentColor": "#8b5cf6",
    "sidebarTitle": "ClawBoard"
  },
  "features": {
    "taskBoard": true,
    "projects": true,
    "journal": true,
    "botStatus": true,
    "stats": true
  }
}

See Getting Started for complete reference.

🔌 Plugins

ClawBoard V2 supports a plugin system where each plugin runs as its own Docker container. Plugins can add sidebar items, API endpoints, and full UI pages to your dashboard.

Quick Plugin Setup

# 1. Create clawboard.plugins.json (or copy the example)
cp clawboard.plugins.example.json clawboard.plugins.json

# 2. Add your plugin entries
# 3. Start with plugins
docker compose up -d

Creating a Plugin

See the full Plugin Development Guide.

Every plugin needs:

1. A plugin.json manifest at its root
2. A /health endpoint
3. A Dockerfile
4. An entry in clawboard.plugins.json

No Plugins? No Problem

ClawBoard works perfectly without any plugins. The plugin system is completely optional — if clawboard.plugins.json is empty or missing, ClawBoard runs in core-only mode.

🔐 Security

ClawBoard follows security best practices:

• ✅ Password-protected with JWT authentication
• ✅ Non-root Docker containers (UID 1002)
• ✅ Read-only OpenClaw mounts
• ✅ Environment variable secrets (no hardcoded passwords)
• ✅ HTTPS support (via Traefik/Nginx)
• ✅ Complete audit logging
• ✅ CORS protection
• ✅ Rate limiting (configurable)

Default credentials:

• Login password: Set in .env (LOGIN_PASSWORD)
• Database: Internal only (not exposed to host)

📊 Database

ClawBoard uses PostgreSQL 16 for data storage:

# Create backup
./database/backup.sh

# Restore from backup
./database/restore.sh

# Direct database access
docker compose exec clawboard-db psql -U clawboard -d clawboard

Tables:

• tasks — Kanban tasks
• projects — Project organization
• journal_entries — Daily journal
• bot_status — Agent status updates
• audit_log — Complete audit trail

See Database Guide for schema and management.

🔄 Updates

# 1. Backup first!
./database/backup.sh

# 2. Pull latest changes
git pull origin main

# 3. Rebuild containers
docker compose build

# 4. Restart services
docker compose up -d

# 5. Verify
docker compose ps

🔌 OpenClaw Gateway Connection

ClawBoard connects to your OpenClaw agent via the Gateway WebSocket. This is how it reads sessions, monitors agent status, and sends control commands.

How It Works

1. OpenClaw Gateway runs on your host machine (default port: 18789)
2. ClawBoard backend (inside Docker) connects to it via WebSocket
3. The extra_hosts Docker setting maps host.docker.internal → your host machine
4. Session data and config files are mounted read-only into the container

Required Mounts

The backend container needs access to these OpenClaw files:

Host Path	Container Path	Purpose
~/.openclaw/agents/main/sessions/	/clawdbot/sessions/	Session transcripts & sessions.json
~/.openclaw/openclaw.json	/clawdbot/clawdbot.json	OpenClaw configuration
~/.openclaw/workspace/	/workspace/	Bot workspace (SOUL.md, memory/, etc.)

Required Environment Variables

Variable	Default	Purpose
OPENCLAW_DIR	~/.openclaw	Host path to OpenClaw data directory
OPENCLAW_GATEWAY_URL	ws://host.docker.internal:18789	Gateway WebSocket URL
OPENCLAW_WORKSPACE	~/.openclaw/workspace	Bot workspace directory

Note: Inside the container, these are mapped to CLAWDBOT_* env vars that the backend reads. The docker-compose.yml handles this mapping automatically.

Verifying the Connection

# 1. Check OpenClaw gateway is running
openclaw gateway status

# 2. Check the backend can reach it
docker compose logs clawboard-backend | grep -i gateway

# 3. Look for "Gateway connected" in logs
docker compose logs clawboard-backend | grep -i "connected"

✅ Functional Tests

After deployment, verify that everything works:

# 1. Check all containers are healthy
docker compose ps

# Expected: All containers show "healthy" or "Up"

# 2. Test API health endpoint
curl http://localhost:8080/api/health

# Expected: {"status":"ok","timestamp":"..."}

# 3. Test login
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"password":"your-password"}'

# Expected: {"token":"...","user":{...}}

# 4. Access dashboard in browser
open http://localhost:8080/dashboard/

# Expected: Login page loads, successful login redirects to dashboard

Troubleshooting:

• API 502 Bad Gateway: Backend container not healthy. Check: docker compose logs clawboard-backend
• Login fails: Password hash mismatch. Regenerate: ./setup.sh (reconfigure)
• Dashboard blank: Check browser console for API errors. Verify /api/ proxy in nginx

🐛 Troubleshooting

"Gateway Disconnected" in Dashboard

This means the backend can't reach the OpenClaw gateway. Check:

# 1. Is OpenClaw gateway running?
openclaw gateway status
# If not: openclaw gateway start

# 2. Is the WebSocket URL correct in .env?
grep OPENCLAW_GATEWAY_URL .env
# Should be: ws://host.docker.internal:18789

# 3. Can the container reach the host?
docker compose exec clawboard-backend sh -c "wget -qO- http://host.docker.internal:18789 || echo 'Cannot reach gateway'"

# 4. Check backend logs for connection errors
docker compose logs clawboard-backend | grep -i "gateway\|websocket\|error"

# 5. Restart the backend
docker compose restart clawboard-backend

Common causes:

• OpenClaw gateway not running → openclaw gateway start
• Wrong port in .env → default is 18789
• Docker networking issue → ensure extra_hosts is in docker-compose.yml
• Firewall blocking localhost connections → check iptables/firewalld rules

Dashboard Won't Load

# Check containers
docker compose ps

# View logs
docker compose logs -f

# Restart
docker compose restart

Blank Pages or Missing Features

# Rebuild frontend with latest config
docker compose build clawboard-frontend
docker compose up -d clawboard-frontend

# Check clawboard.config.json has features enabled
cat clawboard.config.json | grep -A 20 '"features"'

Database Issues

# Check database logs
docker compose logs clawboard-db

# Restart database
docker compose restart clawboard-db

See DEPLOYMENT.md for more deployment and troubleshooting guidance.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md.

See CONTRIBUTING.md for the full guide, including how to maintain a private fork (upstream/downstream workflow).

Ways to contribute:

• 🐛 Report bugs
• ✨ Suggest features
• 📝 Improve documentation
• 💻 Submit code
• 🎨 Design improvements

Development setup:

git clone https://github.com/yourusername/clawboard.git
cd clawboard
docker compose -f docker-compose.dev.yml up

👩‍💻 Authors

Who	Role	Contact
Paulina Stopa	Creator & Architect	pstopa@skyday.eu
Nim 🌀	AI Co-Creator & Lead Engineer	nim@skyday.eu

Yes, an AI co-wrote this dashboard. The future is collaborative. ✨

📝 License

ClawBoard is open-source software licensed under the MIT License.

🙏 Acknowledgments

ClawBoard is built with:

• React — UI framework
• Express.js — Backend framework
• PostgreSQL — Database
• Docker — Containerization
• OpenClaw — AI agent framework

Special thanks to the open-source community!

📧 Contact

• Email: pstopa@skyday.eu
• Repository: ClawBoard on GitHub
• Wiki: Documentation

🗺️ Roadmap

V2.0.0 (Current):

• ✅ Plugin system (Docker-based, config-driven)
• ✅ Multi-entry journal (multiple entries per day)
• ✅ Mobile UX improvements
• ✅ Backend stability (OOM fixes, debounced watchers)
• ✅ Upstream/downstream fork workflow

Planned:

• 🌍 Multi-language support
• 🔔 Notification system
• 👥 Multi-user collaboration
• 📱 Mobile app
• 📊 Advanced analytics
• 🎨 Theme marketplace
• 🔌 Plugin marketplace & registry

---

Built with ❤️ for the OpenClaw community

Get Started | Documentation | Contributing