A Control Center for OpenClaw Agents

Keep your AI agents organized and accountable. ClawController gives you visibility into what your OpenClaw agents are doing, assigns them structured work, and tracks their progress — so you're not just hoping they're on task.

The problem: You've got multiple OpenClaw agents running, but how do you know what they're actually working on? Are they stuck? Did they finish? What's next?

The solution: ClawController provides a visual dashboard where you can:

• See all your agents and their current status at a glance
• Assign structured tasks with clear deliverables
• Track progress through a defined workflow
• Route work to the right agent automatically
• Review completed work before closing tasks

• Features
• Screenshots
• Quick Start
• Architecture
• Configuration
• Creating Agents
• Task Workflow
• Auto-Assignment Rules
• Recurring Tasks
• API Reference
• OpenClaw Integration
• Customization
• Contributing

Running multiple OpenClaw agents is powerful, but it can get chaotic:

• Agents work in isolated sessions — you lose track of who's doing what
• No central place to see progress across all agents
• Work gets duplicated or dropped
• Hard to review output before it ships

ClawController fixes this by giving you one place to manage the work, not the agents themselves. OpenClaw handles the AI. ClawController handles the workflow.

Manage your AI team with kanban boards, agent status monitoring, and real-time activity feeds.

Coordinate trading agents with specialized workflows and market-focused task management.

Run a creative agency with writer, designer, and specialist agents working in parallel.

• Node.js 18+ (for frontend)
• Python 3.10+ (for backend)

# Clone the repository
git clone https://github.com/mdonan90/ClawController.git
cd ClawController

# Backend setup
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Frontend setup
cd ../frontend
npm install

Option 1: Use the start script

./start.sh

Option 2: Manual start

# Terminal 1 - Backend
cd backend
source venv/bin/activate
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

# Terminal 2 - Frontend
cd frontend
npm run dev -- --port 5001 --host 0.0.0.0

Access the dashboard: http://localhost:5001

./stop.sh

Once the dashboard is running, create your first agent:

# Create a simple developer agent
curl -X POST http://localhost:8000/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "dev",
    "name": "Dev Agent", 
    "role": "developer",
    "description": "Handles coding tasks and technical work",
    "avatar": "💻",
    "status": "idle"
  }'

Verify: Refresh your dashboard at http://localhost:5001 and you should see "Dev Agent 💻" in the sidebar.

Next Steps: See Creating Agents for AI-assisted agent creation and advanced configuration.

ClawController/
├── backend/
│   ├── main.py          # FastAPI application + all endpoints
│   ├── models.py        # SQLAlchemy models (Task, Agent, etc.)
│   ├── database.py      # Database connection setup
│   └── requirements.txt # Python dependencies
├── frontend/
│   ├── src/
│   │   ├── App.jsx      # Main React component
│   │   ├── components/  # UI components (Header, Kanban, etc.)
│   │   └── store/       # Zustand state management
│   └── package.json     # Node dependencies
├── start.sh             # Start both services
└── stop.sh              # Stop both services

• Frontend: React 18 + Vite + Tailwind CSS + Zustand
• Backend: FastAPI + SQLite + SQLAlchemy
• Real-time: WebSockets for live updates

Create a .env file in the backend directory (optional):

# Database path (default: ./data/mission_control.db)
DATABASE_URL=sqlite:///./data/mission_control.db

# OpenClaw config path for live agent status
OPENCLAW_CONFIG_PATH=~/.openclaw/config.yaml

Edit frontend/src/App.jsx to change the API URL:

const API_BASE = 'http://localhost:8000/api';

For production, point this to your backend URL.

ClawController can generate agent configurations from natural language descriptions:

Step 1: Describe Your Agent

1. Click + New Agent
2. Describe what you want: "A market research analyst that understands long term macro while providing micro guidance"
3. Or click a template: Backend Dev, Sales Agent, Researcher
4. Click Generate Config

Step 2: Review & Customize

The system generates:

• Agent ID & Name — auto-suggested based on your description
• Emoji — visual identifier
• Model — recommended model (Sonnet, Opus, Haiku, etc.)
• SOUL.md — personality, competencies, and behavior guidelines
• TOOLS.md — available tools and integrations

You can edit any field, refine the SOUL.md, or click ← Refine to adjust your description. When ready, click Create Agent.

Complete Example - Lead Agent:

curl -X POST http://localhost:8000/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "main",
    "name": "Project Lead",
    "role": "LEAD",
    "description": "Primary orchestrator and task reviewer",
    "avatar": "👤",
    "status": "STANDBY",
    "workspace": "/Users/mike/projects"
  }'

Expected Response:

{
  "id": "main",
  "name": "Project Lead",
  "role": "LEAD",
  "description": "Primary orchestrator and task reviewer",
  "avatar": "👤",
  "status": "STANDBY"
}

Important: Set exactly one agent with "role": "LEAD" — this agent will:

• Receive task completion notifications
• Be the default reviewer for tasks in REVIEW status
• Coordinate work across your agent team

Simple Developer Agent:

curl -X POST http://localhost:8000/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "dev", 
    "name": "Dev Agent",
    "role": "INT",
    "avatar": "💻",
    "status": "IDLE"
  }'

Role Guidelines:

• One LEAD required — handles task reviews and team coordination
• Multiple INT agents — your main workforce for most tasks
• SPC agents — specialists for domain-specific work

Status Updates: Agent status is automatically detected from OpenClaw session activity and task assignments.

INBOX → ASSIGNED → IN_PROGRESS → REVIEW → DONE

Tasks can be created from multiple surfaces:

• Dashboard: Click the + New Task button
• Discord: Message your OpenClaw agent with a task description
• Telegram: Send tasks via your connected Telegram bot
• Squad Chat: Use the built-in chat to create and assign tasks

Via API:

curl -X POST http://localhost:8000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Build login page",
    "description": "Create a responsive login form with OAuth support",
    "priority": "high",
    "tags": ["coding", "frontend"],
    "assignee_id": "dev"
  }'

Agents should log their progress:

curl -X POST http://localhost:8000/api/tasks/{task_id}/activity \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "dev",
    "message": "Started working on the login form layout"
  }'

Activity keywords that trigger status changes:

• → IN_PROGRESS: Any activity on an ASSIGNED task
• → REVIEW: "completed", "done", "finished", "ready for review"

Configure automatic task routing based on tags.

Edit backend/main.py:

# Auto-assignment rules: tag -> agent_id
ASSIGNMENT_RULES = {
    "coding": "dev",
    "frontend": "dev",
    "backend": "dev",
    "trading": "trader",
    "analysis": "analyst",
    "marketing": "brand",
    "writing": "writer",
    "design": "designer",
    "support": "support",
}

1. When a task is created with tags, the system checks each tag against the rules
2. First matching rule wins
3. Task is automatically assigned to that agent
4. Status changes from INBOX to ASSIGNED

# This task will auto-assign to "dev" because of the "coding" tag
curl -X POST http://localhost:8000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fix authentication bug",
    "tags": ["coding", "urgent"]
  }'

Schedule tasks that repeat on a schedule.

Via UI: Tasks panel → Recurring Tasks tab → + New Recurring Task

Via API:

curl -X POST http://localhost:8000/api/recurring-tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Daily standup summary",
    "description": "Compile and post daily progress report",
    "schedule": "0 9 * * 1-5",
    "assignee_id": "lead",
    "tags": ["daily", "reporting"],
    "enabled": true
  }'

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sun=0)
│ │ │ │ │
* * * * *

Examples:

• 0 9 * * 1-5 — 9 AM, Monday-Friday
• 0 */2 * * * — Every 2 hours
• 0 0 1 * * — First day of each month at midnight

• Pause: PATCH /api/recurring-tasks/{id} with {"enabled": false}
• View runs: GET /api/recurring-tasks/{id}/runs
• Delete: DELETE /api/recurring-tasks/{id}

Connect to ws://localhost:8000/ws for real-time updates:

const ws = new WebSocket('ws://localhost:8000/ws');
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // Handle: task_created, task_updated, agent_status, chat_message, etc.
};

ClawController is built for OpenClaw. Here's how they connect:

ClawController reads your OpenClaw config to show real agent status:

# In backend/main.py
OPENCLAW_CONFIG_PATH = os.path.expanduser("~/.openclaw/config.yaml")

Agents defined in your OpenClaw config appear automatically with live status indicators.

When you @mention an agent in Squad Chat, ClawController routes the message via:

openclaw agent --agent {agent_id} --message "{your message}"

This wakes the agent in its own session and delivers your message.

Important: Your agents need instructions to use ClawController correctly. Add the following to each agent's TOOLS.md or AGENTS.md:

## ClawController Integration

**API Base:** `http://localhost:8000/api`

### When assigned a task:
1. Check for tasks: `GET /api/tasks?assignee_id={your_id}&status=ASSIGNED`
2. Log progress as you work (every significant step)
3. When finished, post activity with "completed" or "done"
4. Wait for human approval

### Logging Activity (REQUIRED while working)
curl -X POST http://localhost:8000/api/tasks/{TASK_ID}/activity \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "YOUR_AGENT_ID", "message": "What you did"}'

### Task Lifecycle
- ASSIGNED → Task given to you
- IN_PROGRESS → Auto-triggers on first activity log
- REVIEW → Say "completed" in activity to trigger
- DONE → Human approves (never set this yourself)

### Key Rules
- Always log activity — progress is tracked via activity logs
- Don't skip REVIEW — humans approve before DONE
- Use descriptive updates — helps humans understand progress

A complete template is available at AGENT_INSTRUCTIONS.md in the repo.

The "Cyber Claw" theme uses Tailwind CSS. Edit frontend/tailwind.config.js:

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#F97316',  // Orange accent
        background: '#09090B',  // Near black
        surface: '#18181B',  // Card backgrounds
      }
    }
  }
}

Edit backend/models.py:

class TaskStatus(str, Enum):
    INBOX = "INBOX"
    ASSIGNED = "ASSIGNED"
    IN_PROGRESS = "IN_PROGRESS"
    BLOCKED = "BLOCKED"  # Add new status
    REVIEW = "REVIEW"
    DONE = "DONE"

Then update the frontend kanban columns in App.jsx.

Edit backend/models.py:

class AgentRole(str, Enum):
    LEAD = "lead"
    DEVELOPER = "developer"
    ANALYST = "analyst"
    SPECIALIST = "specialist"
    SUPPORT = "support"
    CREATIVE = "creative"  # Add new role

Add to backend/main.py:

@app.get("/api/custom-endpoint")
def custom_endpoint(db: Session = Depends(get_db)):
    # Your logic here
    return {"status": "ok"}

# Build frontend
cd frontend
npm run build

# Serve with nginx or copy dist/ to your static host

• Backend: Run with gunicorn + uvicorn workers
• Frontend: Serve from CDN or nginx
• Database: SQLite works for small teams; PostgreSQL for scale

Problem: Error: listen EADDRINUSE: address already in use :::8000 or :::5001

Solution:

# Find processes using the ports
lsof -i :8000  # Backend port
lsof -i :5001  # Frontend port

# Kill processes if needed
kill -9 <PID>

# Or use different ports
uvicorn main:app --port 8001  # Backend
npm run dev -- --port 5002   # Frontend

Problem: Dashboard shows "Connection Failed" when accessing remotely

Solution:

# Backend: Allow all origins (development only)
uvicorn main:app --host 0.0.0.0 --port 8000

# Frontend: Enable network access
npm run dev -- --host 0.0.0.0 --port 5001

# Access via: http://YOUR_IP:5001

Problem: Dashboard loads but agent sidebar is empty

Solutions:

1. Create your first agent:

   curl -X POST http://localhost:8000/api/agents \
     -H "Content-Type: application/json" \
     -d '{"id": "dev", "name": "Dev Agent", "role": "developer", "avatar": "💻", "status": "idle"}'

2. Import from OpenClaw config:

   • Click "Import from OpenClaw" in Agent Management
   • Requires ~/.openclaw/openclaw.json with configured agents

3. Check OpenClaw integration:

   # Verify config exists
   ls ~/.openclaw/openclaw.json
   
   # Check API endpoint
   curl http://localhost:8000/api/openclaw/status

Problem: Tasks/agents not persisting or database errors

Solutions:

1. Check database file:

   # Default location
   ls backend/data/mission_control.db
   
   # Create directory if missing
   mkdir -p backend/data

2. Reset database:

   rm backend/data/mission_control.db
   # Restart backend - database will recreate automatically

3. Permissions:

   chmod 755 backend/data
   chmod 644 backend/data/mission_control.db

Problem: Dashboard shows "Connection Failed" or no real-time updates

Solutions:

1. Check backend is running:

   curl http://localhost:8000/api/stats

2. Verify WebSocket endpoint:

   # Should show upgrade response
   curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
        http://localhost:8000/ws

3. Browser console errors:

   • Open DevTools → Console
   • Look for WebSocket connection errors
   • Common cause: backend not running or wrong port

Problem: Agents stuck in "OFFLINE" or status doesn't change

Solutions:

1. Check OpenClaw session files:

   # Verify session directory exists
   ls ~/.openclaw/agents/AGENT_ID/sessions/
   
   # Check recent activity
   find ~/.openclaw/agents/*/sessions -name "*.jsonl" -newermt "1 hour ago"

2. Manual status update:

   curl -X PATCH "http://localhost:8000/api/agents/AGENT_ID/status?status=WORKING"

3. Refresh agents list:

   • Click the refresh button in agent sidebar
   • Or restart the backend to rescan OpenClaw config

Problem: Dashboard slow or unresponsive

Solutions:

1. Check task count:

   curl http://localhost:8000/api/stats

2. Clear old tasks:

   # Archive completed tasks older than 30 days
   curl -X DELETE "http://localhost:8000/api/tasks/cleanup?days=30"

3. Database optimization:

   # SQLite vacuum (requires stopping backend)
   sqlite3 backend/data/mission_control.db "VACUUM;"

Enable debug mode:

# Backend with debug logging
uvicorn main:app --log-level debug --reload

# Check API health
curl http://localhost:8000/api/stats
curl http://localhost:8000/api/agents
curl http://localhost:8000/api/tasks

Common API errors:

• 422 Validation Error → Check request body format
• 404 Not Found → Verify agent/task ID exists
• 500 Internal Error → Check backend logs

1. Check backend logs for error messages
2. Check browser console for frontend errors
3. Verify all services running with ps aux | grep uvicorn
4. Test API directly with curl commands above

Still having issues? Check the GitHub Issues or create a new one with:

• Your OS and versions (Python, Node.js)
• Full error message
• Steps to reproduce

Contributions welcome!

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

# Run with hot reload
cd backend && uvicorn main:app --reload
cd frontend && npm run dev

• Python: Follow PEP 8
• JavaScript: ESLint + Prettier

MIT License - see LICENSE for details.

OpenClaw is an open-source AI agent framework that lets you run persistent AI assistants with memory, tools, and multi-channel access (Discord, Telegram, etc.).

ClawController adds the missing piece: structured task management so your agents work on what matters, not whatever they feel like.

Built for the OpenClaw community.

Author: Mike O'Nan (@mdonan90)