# OpenClaw Agent Fleet

OpenClaw multi-agent deployment for Mosaic Stack using Docker Swarm and Portainer.

## Agent Roster

| 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  |

## 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

## Quick Start

### 1. Configure each agent env file

Set values in:

- `docker/openclaw-instances/mosaic-main.env`
- `docker/openclaw-instances/mosaic-projects.env`
- `docker/openclaw-instances/mosaic-research.env`
- `docker/openclaw-instances/mosaic-operations.env`

Required variables:

- `OPENCLAW_CONFIG_PATH=/config/openclaw.json`
- `ZAI_API_KEY=<your-zai-api-key>`
- `OPENCLAW_GATEWAY_TOKEN=<unique-token-per-agent>`

### 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-<service>`                      | View service logs      |
| `docker service update --force mosaic-<service>`            | Restart rolling update |
| `docker service scale mosaic-<service>=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.