# OpenClaw Agent Fleet

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

## Agent Roster

| Agent             | Service             | Primary Model   | Role                               |
| ----------------- | ------------------- | --------------- | ---------------------------------- |
| jarvis-main       | `jarvis-main`       | `zai/glm-5`     | Orchestrator / user-facing gateway |
| jarvis-projects   | `jarvis-projects`   | `zai/glm-5`     | Development and coding tasks       |
| jarvis-research   | `jarvis-research`   | `zai/glm-5`     | Research and web search            |
| jarvis-operations | `jarvis-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/jarvis-main.env`
- `docker/openclaw-instances/jarvis-projects.env`
- `docker/openclaw-instances/jarvis-research.env`
- `docker/openclaw-instances/jarvis-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 jarvis
```

### 4. Verify service status

```bash
docker stack services jarvis
docker service logs jarvis-jarvis-main --tail 100
docker service logs jarvis-jarvis-projects --tail 100
docker service logs jarvis-jarvis-research --tail 100
docker service logs jarvis-jarvis-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=jarvis-jarvis-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 jarvis` | Deploy/update fleet    |
| `docker stack services jarvis`                              | List services in stack |
| `docker service logs jarvis-<service>`                      | View service logs      |
| `docker service update --force jarvis-<service>`            | Restart rolling update |
| `docker service scale jarvis-<service>=N`                   | Scale a service        |
| `docker stack rm jarvis`                                    | 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.