From 8d7a1be7f5e666aaa653e20323d6d55e4d7d7810 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Sun, 1 Mar 2026 08:06:15 -0600 Subject: [PATCH] fix(docker): strip hardcoded model/provider assumptions from fleet doc Model choices and provider prereqs belong in onboarding/settings, not static documentation. --- docker/OPENCLAW-FLEET.md | 115 +++++++++++++-------------------------- 1 file changed, 37 insertions(+), 78 deletions(-) diff --git a/docker/OPENCLAW-FLEET.md b/docker/OPENCLAW-FLEET.md index ebc0564..78b643f 100644 --- a/docker/OPENCLAW-FLEET.md +++ b/docker/OPENCLAW-FLEET.md @@ -1,90 +1,49 @@ -# OpenClaw Agent Fleet +# Mosaic Agent Fleet -OpenClaw multi-agent deployment for Mosaic Stack using Docker Swarm and Portainer. +Multi-agent deployment for Mosaic Stack using OpenClaw containers on Docker Swarm. -## Agent Roster +## Architecture -| Agent | Service | Primary Model | Role | -| ----------------- | ------------------- | --------------- | ---------------------------------- | -| mosaic-main | `mosaic-main` | `zai/glm-5` | Orchestrator / user-facing gateway | -| mosaic-projects | `mosaic-projects` | `zai/glm-5` | Development and coding tasks | -| mosaic-research | `mosaic-research` | `zai/glm-5` | Research and web search | -| mosaic-operations | `mosaic-operations` | `ollama/cogito` | Monitoring, health checks, alerts | +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](openclaw-instances/README.md) for env var reference. ## Prerequisites -1. Docker Swarm initialized on the target host -2. Existing Docker network `mosaic-stack_internal` (external swarm network) -3. Z.ai API access key (`ZAI_API_KEY`) -4. Ollama reachable at `10.1.1.42:11434` for the `cogito` model +- 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 each agent env file +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` -Set values in: +See [openclaw-instances/README.md](openclaw-instances/README.md) for detailed setup. -- `docker/openclaw-instances/mosaic-main.env` -- `docker/openclaw-instances/mosaic-projects.env` -- `docker/openclaw-instances/mosaic-research.env` -- `docker/openclaw-instances/mosaic-operations.env` +## Future: Onboarding Wizard -Required variables: - -- `OPENCLAW_CONFIG_PATH=/config/openclaw.json` -- `ZAI_API_KEY=` -- `OPENCLAW_GATEWAY_TOKEN=` - -### 2. Generate unique gateway tokens - -Generate one token per service: - -```bash -openssl rand -hex 32 -``` - -### 3. Deploy the fleet - -From repo root: - -```bash -docker stack deploy -c docker/openclaw-compose.yml mosaic -``` - -### 4. Verify service status - -```bash -docker stack services mosaic -docker service logs mosaic-mosaic-main --tail 100 -docker service logs mosaic-mosaic-projects --tail 100 -docker service logs mosaic-mosaic-research --tail 100 -docker service logs mosaic-mosaic-operations --tail 100 -``` - -### 5. First-time auth (if required) - -Exec into a container and run OpenClaw auth device flow: - -```bash -docker exec -it $(docker ps -q -f name=mosaic-mosaic-main) sh -openclaw auth -``` - -You can also complete this in the Mosaic WebUI terminal (xterm.js). - -## Management Commands - -| Command | Description | -| ----------------------------------------------------------- | ---------------------- | -| `docker stack deploy -c docker/openclaw-compose.yml mosaic` | Deploy/update fleet | -| `docker stack services mosaic` | List services in stack | -| `docker service logs mosaic-` | View service logs | -| `docker service update --force mosaic-` | Restart rolling update | -| `docker service scale mosaic-=N` | Scale a service | -| `docker stack rm mosaic` | Remove fleet | - -## Notes - -- Each service stores persistent local OpenClaw state in `/home/node/.openclaw`. -- Each service mounts a read-only per-agent JSON config at `/config/openclaw.json`. -- `chatCompletions` endpoint is enabled in each agent config for Mosaic API usage. +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.