stack/docker/OPENCLAW-FLEET.md

Mosaic Agent Fleet

Multi-agent deployment for Mosaic Stack using OpenClaw containers on Docker Swarm.

Architecture

Each agent runs as an isolated OpenClaw Gateway instance with its own:

• Workspace — persistent volume for agent files and memory
• State — persistent volume for auth tokens and sessions
• Config — template rendered at startup from environment variables

Agents communicate with the Mosaic API via the OpenAI-compatible /v1/chat/completions endpoint. The Mosaic WebUI routes chat requests to agents through the OpenClawGatewayModule.

Default Agent Roles

Agent	Role	Description
mosaic-main	Orchestrator	User-facing gateway, routes to other agents
mosaic-projects	Developer	Implementation, coding, PRs
mosaic-research	Research	Web search, analysis, discovery
mosaic-operations	Operations	Monitoring, health checks, alerts

Models and providers are configured per-deployment via environment variables and the Mosaic Settings UI — not hardcoded in these files. See the Setup Guide for env var reference.

Prerequisites

• Docker Swarm initialized on target host
• Mosaic Stack running (mosaic-stack_internal network available)
• At least one LLM provider API key (Z.ai, OpenAI, Anthropic, etc.)

Quick Start

1. Configure — Fill in docker/openclaw-instances/*.env files
2. Deploy — docker stack deploy -c docker/openclaw-compose.yml mosaic-agents
3. Auth — If needed, run openclaw auth inside a container (or via Mosaic terminal)
4. Verify — docker stack services mosaic-agents

See openclaw-instances/README.md for detailed setup.

Future: Onboarding Wizard

Model assignments, provider configuration, and agent customization will be managed through the Mosaic WebUI onboarding wizard and Settings pages (MS22-P4). Until then, use environment variables per the README.