< Return_To_Databank()
OPENCLAW
Mar 02, 2026

Multi-Agent Workforce: The Complete WSL 2 & Docker Deployment Guide

Author: YAER_SYSID: n6mb01sl

OpenClaw Multi-Agent Workforce Setup Guide

Why Docker + WSL?

Running OpenClaw inside Docker containers on WSL 2 provides a strong layer of isolation between the agents and your host operating system. Each agent runs in its own sandboxed container with no direct access to your Windows filesystem, network services, or personal data beyond what you explicitly mount. If an agent misbehaves or is compromised, the blast radius is limited to that container alone — your host machine and other agents remain unaffected. WSL 2 adds a further boundary by running a real Linux kernel in a lightweight VM, meaning Docker's Linux containers execute natively without the overhead and security quirks of Hyper-V translation layers.

Table of Contents

Multiple Agents vs. Sub-Agents

There is an important distinction between running multiple independent agents (as this guide sets up) and using sub-agents within a single agent. Sub-agents share the same configuration, Telegram bot token, model providers, and context — they are essentially worker threads that a single parent agent spawns to handle tasks concurrently. Multiple independent agents, on the other hand, each have their own identity, their own Telegram bot, their own configuration, and their own isolated container. This means they can serve different users or groups, use different model backends, and operate completely independently of one another. Choose sub-agents when you need one bot to multitask; choose multiple agents when you need truly separate bots with separate identities and isolation boundaries.

1. Prerequisites

Before starting, ensure you have the following installed on your Windows machine:

  • Docker Desktop: Ensure "Use the WSL 2 based engine" is checked in Settings.
  • WSL 2 (Ubuntu): Your terminal environment.
  • Two Telegram Bot Tokens: One for each agent (Alpha and Beta).

2. Directory Structure

Open your WSL terminal and create a dedicated folder for your "workforce". Organizing your files correctly is crucial for data persistence.

mkdir -p ~/openclaw-workforce/agent-1/config
mkdir -p ~/openclaw-workforce/agent-2/config
cd ~/openclaw-workforce

3. Creating the Environment Files

A. The OpenClaw Dockerfile

Create a file named Dockerfile in ~/openclaw-workforce/. This builds a Node 22 environment compatible with OpenClaw's latest requirements.

# Use Node.js 22 to avoid version conflicts
FROM node:22-bookworm

ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y \
    curl bash sudo git python3 python3-pip build-essential \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Install OpenClaw via the official script
RUN curl -fsSL https://openclaw.ai/install.sh | bash -s -- --yes || true

# Ensure global CLI access
RUN npm install -g openclaw

# Run the gateway in the foreground
CMD ["openclaw", "gateway", "run"]

B. The Unified docker-compose.yml

This file allows you to launch all agents with one command. It handles the port mapping (18789 for Alpha, 18790 for Beta).

services:
  # Agent Alpha
  oc-alpha:
    build: .
    container_name: oc_alpha
    environment:
      - OPENCLAW_GATEWAY_CUSTOM_BIND_HOST=0.0.0.0
    command: ["openclaw", "gateway", "run", "--port", "18789", "--bind", "custom"]
    ports:
      - "18789:18789"
    volumes:
      - ./agent-1/config:/root/.openclaw
    restart: unless-stopped

  # Agent Beta
  oc-beta:
    build: .
    container_name: oc_beta
    environment:
      - OPENCLAW_GATEWAY_CUSTOM_BIND_HOST=0.0.0.0
    command: ["openclaw", "gateway", "run", "--port", "18789", "--bind", "custom"]
    ports:
      - "18790:18789"
    volumes:
      - ./agent-2/config:/root/.openclaw
    restart: unless-stopped

4. Solving Permission Issues (Access Denied)

Docker often creates configuration files with "root" ownership, preventing you from editing them in WSL. You must take ownership back to your user (e.g., neilb).

# Replace $USER with your WSL username if necessary
sudo chown -R $USER:$USER ~/openclaw-workforce/agent-1
sudo chown -R $USER:$USER ~/openclaw-workforce/agent-2
chmod -R 755 ~/openclaw-workforce/agent-1
chmod -R 755 ~/openclaw-workforce/agent-2

5. Initial Onboarding & Setup

Launch the Containers

docker compose up -d --build

Initialize Alpha Agent

You must run the onboard process inside the container to set your Telegram token:

docker exec -it oc_alpha openclaw onboard
  • Gateway Port: 18789
  • Telegram Token: Enter your first Bot Token.

Initialize Beta Agent

Repeat for the second agent:

docker exec -it oc_beta openclaw onboard
  • Gateway Port: 18789 (Internal port remains the same).
  • Telegram Token: Enter your second Bot Token.

6. Dashboard Connection & Security

A. Fixing "Gateway Token Mismatch"

Each agent generates a unique token. If the Dashboard shows an authentication error, retrieve the token from the container:

docker exec oc_alpha cat /root/.openclaw/openclaw.json | grep token

Copy the string and paste it into the Gateway Token field on your Dashboard (http://localhost:18789).

B. Fixing "Pairing Required"

OpenClaw requires manual approval for new browser connections. If you see this red error on the Dashboard, run:

docker exec oc_alpha openclaw devices approve --all
docker exec oc_beta openclaw devices approve --all

7. Maintenance & Troubleshooting (Tips)

Q: Access Denied A: Run the chown and chmod commands from Step 4.

Q: Bot not responding in groups A: Run docker exec oc_alpha openclaw config set channels.telegram.groupPolicy open.

Q: Connection Error A: Ensure OPENCLAW_GATEWAY_CUSTOM_BIND_HOST is set to 0.0.0.0 in the yml file.

Q: Rate Limited A: Restart the container (docker compose restart) to reset the login attempt counter.

Automatic Startup

Because we used restart: unless-stopped in the docker-compose.yml, your agents will automatically start whenever your computer boots up, provided Docker Desktop is running.

8. Scaling Up: Adding More Agents

To seamlessly add more OpenClaw Agents in the future without causing any disruptions, the core strategy relies on Isolation and Templating. Think of it like adding production lines in a factory: as long as each line has unique entry/exit points (ports) and independent storage (directories), they can operate entirely independently.

A. The "Three Unique" Rule for Core Isolation

Whenever you add a new Agent (e.g., oc-gamma), you must ensure these three settings are strictly unique:

  1. Unique Host Port: Alpha uses 18789, Beta uses 18790, so the new Agent should use 18791.
  2. Unique Volume Path: Each Agent must have its own independent configuration folder (e.g., ./agent-3/config), or else configuration conflicts and data corruption will occur.
  3. Unique Container Name: Define a different container_name in your docker-compose.yml (e.g., oc_gamma) so you can execute commands targeting it specifically.

B. The Expansion Template

Simply copy and paste this template at the bottom of your existing docker-compose.yml and update the lines marked with FIXME:

  # --- New Agent Template ---
  oc-gamma: # FIXME: Change service name (e.g. oc-gamma, oc-delta)
    build: .
    container_name: oc_gamma # FIXME: Change container name
    environment:
      - OPENCLAW_GATEWAY_CUSTOM_BIND_HOST=0.0.0.0
    command: ["openclaw", "gateway", "run", "--port", "18789", "--bind", "custom"]
    ports:
      - "18791:18789" # FIXME: Change the left-side host port (e.g. 18791, 18792)
    volumes:
      - ./agent-3/config:/root/.openclaw # FIXME: Change the left-side volume path
    depends_on:
      - codex-proxy
    restart: unless-stopped

C. Adding Without Disruption

Once you update the .yml file, do not restart the entire workforce. You only need to target the new service:

  • Start Only the New Service:

    docker compose up -d oc-gamma

    Docker will automatically recognize that Alpha and Beta are already running and will strictly launch only the new Gamma container.

  • Initialize the New Agent Separately:

    docker exec -it oc_gamma openclaw onboard

    This operates without affecting the runtime state of Alpha or Beta.

  • Approve Device Pairing Separately: Access http://localhost:18791, then execute:

    docker exec oc_gamma openclaw devices approve --all

D. Advanced: Using Environment Variables (.env)

If you plan to scale beyond 10 agents, we highly recommend establishing a .env file to centrally manage your ports.

Example .env file:

PORT_ALPHA=18789
PORT_BETA=18790
PORT_GAMMA=18791

Example docker-compose.yml reference:

    ports:
      - "${PORT_GAMMA}:18789"

9. Advanced Maintenance Tips

  • Hot Updates: If you just need to add a model to one specific Agent, update its config JSON file and run docker compose restart [service-name]. Other Agents will remain online.
  • Log Isolation: If you want to check the new Agent for errors without mixing logs, use docker logs -f oc_gamma.
  • Shared Proxies: All Agents can share the same codex-proxy or ollama service/container. This is the power of a "unified" architecture—the Proxy acts as a central utility plant, and Agents simply tap into it.
END OF TRANSMISSION.[< />]