Multi-Agent Orchestration

Why One Agent Isn't Enough

Meet Your Two-Agent Team

OpenClaw excels at browser tasks, automation, computer use, and always-on operations. Claude Code excels at code generation, system building, and complex reasoning. Together they cover every axis of autonomous work.

🔸

OpenClaw Agent

Always-on executor. Runs cron jobs, automated feeds, browser tasks, and computer use. Lives inside OpenClaw with full GUI access. Dispatches work to Claude Code when code needs to be built.

🔵

Claude Code Agent

Session-based builder. Generates code, deploys edge functions, writes migrations, runs tests. Picks up dispatched work from the queue automatically. Reports results back to the dashboard.

The Core Architecture

Autonomous Dispatch Pipeline

OpenClaw creates a queue item. The poller picks it up. An 8-phase handler orchestrates everything. The dashboard animates in real time. Telegram sends alerts to your phone. You don't touch a thing.

1. CONTEXT

2. PLAN

3. TASK BOARD

4. BUILD

5. VALIDATE

6. HEAL

7. REPORT

8. CLOSE

OpenClaw dispatches a build task → pending_tasks table (Supabase queue) → Queue Poller picks up (every 30 seconds) → Claims the item → 8-Phase Handler activates: Phase 1: CONTEXT — Claim + read requirements (5%) Phase 2: PLAN — Analyze approach (12%) Phase 3: TASK BOARD — Create Kanban task + assign (20%) Phase 4: BUILD — Launch agent + heartbeat (25-90%) Phase 5: VALIDATE — Verify results (75%) Phase 6: HEAL — Self-healing on failure Phase 7: REPORT — Generate build summary (90%) Phase 8: CLOSE — Move task to done (100%) → Dashboard shows everything live → Telegram alerts every ~6 minutes → Build History records result

Architecture Decisions

Why It Works This Way

Handler Drives the Phases

The handler posts all 8 phase transitions, not the dispatched agent. Dispatched Claude sessions can't be trusted to make API calls — they're sandboxed. So the handler orchestrates everything: phase dots, Telegram alerts, Build History, Kanban tasks.

Heartbeats Prevent Stale Badges

A background task posts work_progress to the database every 3 minutes. The dashboard knows the agent is alive. No heartbeat for 10 minutes = STALE badge. 15 minutes = FAILED. This prevents ghost runs.

Dispatch Brief Standard

Every dispatch must include 4 sections: Task (what to build), Requirements (detailed spec), Environment (working dir, env vars, dependencies), and Deliverables (expected outputs including README.md). No guessing. No ambiguity.

Agent Comms for Coordination

OpenClaw and Claude Code message each other directly via the agent_comms system. Message types: comment, question, status_request, status_response, directive. Thread-based with reply support. Session-start hooks auto-check for unread messages.

Orchestration Patterns

Four Ways Agents Work Together

Queue Dispatch

OpenClaw creates a pending_tasks item. Claude Code auto-picks it up. The 8-phase pipeline handles everything. This is the production pattern — it runs when you're not at your desk.

PRIMARY PATTERN

Sequential Handoff

OpenClaw completes task A, then hands off to Claude Code for task B via agent_comms. One finishes before the other starts. Good for dependent tasks.

Parallel Execution

Both agents work on different parts simultaneously. OpenClaw handles research while Claude Code builds. Results merge on the dashboard. Maximum throughput.

Escalation

OpenClaw tries a task, hits a wall, escalates to Claude Code via queue dispatch with context about what failed. The more capable agent takes over with full history.

Dashboard Visibility

Command Center — 3 Live Panels

The Command Center page has three panels that update in real time via Supabase real-time subscriptions. No refresh needed.

🔴

Autonomous Assignment

Live phase animation with 8 dots that light up green as each phase completes. Progress bar fills from 0% to 100%. Shows current action text, elapsed time, and stale/failed detection. When idle, panel is empty. When a build fires, it comes alive.

Build History

Every completed build shows as a row with 8 green dots (one per phase). Displays duration, turn count, and outcome. Your audit trail for every autonomous build.

Run History

Timeline view of every autonomous run. Click a row to see the full phase-by-phase breakdown with timestamps, actions, and results.

The Prompt

Multi-Agent Dispatch Setup

This prompt sets up the queue dispatch protocol, agent communication, and the 8-phase pipeline handler. Give this to your Claude Code agent so it knows how to pick up dispatched work and report results.

multi-agent-dispatch.md

# Multi-Agent Dispatch Protocol ## Agent Identity You are a Claude Code agent operating alongside an OpenClaw agent. You pick up dispatched work from the queue, build autonomously, and report results to the ClawBuddy dashboard. ## Session Startup Every session, before doing anything else: 1. Check the queue for pending work: {"request_type": "queue", "action": "list", "status": "pending", "limit": 5} 2. Check for agent messages: {"request_type": "agent_comms", "action": "check", "agent_name": "<agent_name>"} 3. If queue items exist, claim the top one: {"request_type": "queue", "action": "claim", "item_id": "<item_id>"} ## The 8-Phase Pipeline When building a dispatched task, follow these phases in order: ### Phase 1: CONTEXT (5%) - Read the dispatch brief (payload.prompt) - Understand requirements, environment, deliverables - Log: "Claimed: <task_title>. Reading requirements." ### Phase 2: PLAN (12%) - Analyze the approach - Identify files to create/modify - Log: "Planning: <approach summary>" ### Phase 3: TASK BOARD (20%) - Create a Kanban task on ClawBuddy - Assign yourself + the owner - Move task to "doing" - Log: "Task created and assigned on Kanban board." ### Phase 4: BUILD (25-90%) - Execute the build - Post heartbeat every 3 minutes (work_progress events) - Log at every major step ### Phase 5: VALIDATE (75%) - Verify the build works - Run tests if applicable - Check for errors - Log: "Validating build results." ### Phase 6: HEAL (reserved) - If validation fails, attempt self-healing - Fix errors and re-validate - Log: "Healing: <what failed and how it was fixed>" ### Phase 7: REPORT (90%) - Generate build summary insight - Create HTML report if substantial output - Log: "Report generated." ### Phase 8: CLOSE (100%) - Move Kanban task to "done" - Complete the queue item - Post final status - Log: "Build complete. Task moved to done." ## Dispatch Brief Standard Every dispatch you receive should include: ### Task What to build (one sentence) ### Requirements Detailed spec — UI, features, behavior ### Environment - Working directory - Env vars needed - Dependencies ### Deliverables 1. Working app 2. README.md (always) 3. Dashboard tasks + logs 4. Final report ## Agent Communication Send messages to other agents: {"request_type": "agent_comms", "action": "send", "from_agent": "<agent_name>", "to_agent": "<openclaw_agent_name>", "message_type": "status_response", "message": "Build complete. Dashboard updated."} Reply to threads: {"request_type": "agent_comms", "action": "reply", "message_id": "<id>", "from_agent": "<agent_name>", "message": "Acknowledged. Starting build."} ## Heartbeat Contract During active work, post progress every 3 minutes: {"request_type": "log", "action": "create", "category": "observation", "message": "Progress: Building component X", "data": {"event_type": "work_progress", "run_id": "<uuid>", "phase": "BUILD", "percent_complete": 45, "current_action": "Building component X"}} ## Queue Completion When done: {"request_type": "queue", "action": "complete", "item_id": "<item_id>", "result": {"status": "completed", "summary": "Built X with Y features"}} On failure: {"request_type": "queue", "action": "fail", "item_id": "<item_id>", "error": "Description of what failed"}

The difference

Most AI setups are chatbots. This is a structured build system with queue-based dispatch, handler-driven phases, heartbeat monitoring, and a dashboard that shows you everything in real time. OpenClaw dispatches. Claude Code builds. The Command Center tracks every phase. Telegram keeps you updated. You don't have to be there for any of it.

Rework Dispatch

When Something Breaks — Rework Template

Don't start from scratch. Use this structured rework dispatch to give the executor agent full context.

Canonical Rework Dispatch Shape

{
  "request_type": "queue",
  "action": "create",
  "task_type": "build",
  "action_name": "Fix: <describe what broke>",
  "priority": "high",
  "payload": {
    "prompt": "## Task\n<One sentence: what to fix>\n\n## Current State (Broken)\n<What's failing, error messages, screenshots>\n\n## Requirements\n<What the fixed version should do>\n\n## Environment\n- Working directory: /path/to/app/\n- Existing codebase — read README.md first\n- Error log: <paste or reference>\n\n## Deliverables\n1. Fixed feature, passing validation\n2. Updated README.md\n3. ClawBuddy logs showing fix\n4. HTML report with before/after",
    "dispatcher": "<openclaw_agent_name>",
    "task_title": "Fix: <describe what broke>",
    "max_turns": 100
  }
}