stack/docker/openclaw-instances

Mosaic Agent Fleet — Setup Guide

Prerequisites

• Docker Swarm initialized on target host
• Mosaic Stack running (Postgres, Valkey on mosaic-stack_internal network)

1. Configure Environment Variables

Copy and fill in each agent's .env file:

cd docker/openclaw-instances

# Required for each agent:
# ZAI_API_KEY         — Your Z.ai API key (or other LLM provider key)
# OPENCLAW_GATEWAY_TOKEN — Unique bearer token per agent

# Generate unique tokens:
for agent in main projects research operations; do
  echo "OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)"
done

Optional: Local Ollama

If you have an Ollama instance, add to any agent's .env:

OLLAMA_BASE_URL=http://your-ollama-host:11434
OLLAMA_MODEL=cogito  # or any model you have pulled

The entrypoint script will automatically inject the Ollama provider at startup.

Optional: Override Default Model

OPENCLAW_MODEL=anthropic/claude-sonnet-4-6

2. Populate Config Volumes

Each agent needs its .json.template file in its config volume:

# Create config directories and copy templates
for agent in main projects research operations; do
  mkdir -p /var/lib/docker/volumes/mosaic-agents_mosaic-${agent}-config/_data/
  cp openclaw-instances/mosaic-${agent}.json.template \
     /var/lib/docker/volumes/mosaic-agents_mosaic-${agent}-config/_data/openclaw.json.template
  cp openclaw-instances/entrypoint.sh \
     /var/lib/docker/volumes/mosaic-agents_mosaic-${agent}-config/_data/entrypoint.sh
done

3. Deploy

docker stack deploy -c docker/openclaw-compose.yml mosaic-agents
docker stack services mosaic-agents

4. First-Time Auth (if needed)

For providers requiring OAuth (e.g., Anthropic):

docker exec -it $(docker ps -q -f name=mosaic-main) openclaw auth

Follow the device-code flow in your browser. Tokens persist in the state volume.

You can also use the Mosaic WebUI terminal (xterm.js) for this.

5. Verify

# Check health
curl http://localhost:18789/health

# Test chat completions endpoint
curl http://localhost:18789/v1/chat/completions \
  -H "Authorization: Bearer YOUR_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"openclaw:main","messages":[{"role":"user","content":"hello"}]}'

Environment Variable Reference

Variable	Required	Description
ZAI_API_KEY	Yes*	Z.ai API key (*or other provider key)
OPENCLAW_GATEWAY_TOKEN	Yes	Bearer token for this agent (unique per instance)
OPENCLAW_MODEL	No	Override default model (default: zai/glm-5)
OLLAMA_BASE_URL	No	Ollama endpoint (e.g., http://10.1.1.42:11434)
OLLAMA_MODEL	No	Ollama model name (default: cogito)