Multi-Agent OpenClaw Setup

Complete guide to setting up specialized subagent instances with OpenClaw — isolated Docker containers with role-specific configurations, shared skills, and separate credential vaults.

Overview

OpenClaw supports spawning isolated agent sessions in sandboxed Docker containers. Each subagent gets:

Dedicated workspace — persistent storage for memory and work products
Shared skills — read-only access to commune skills library
Isolated credentials — separate rbw (Bitwarden) vault with read/write access
Role-specific configuration — custom AGENTS.md, TOOLS.md, SOUL.md

This allows specialized agents (CI triage, research, librarian duties) to run independently while maintaining security boundaries and shared tooling.

Architecture

Agent Roster

Agent	Forgejo User	Workspace	Purpose
main	`agent`	`/root/.openclaw/workspace`	Primary agent, coordination, user interaction
ci-triage	`ci`	`/root/.openclaw/workspace-ci-triage`	CI/CD failure analysis and fixes
research	`researcher`	`/root/.openclaw/workspace-research`	Research tasks, librarian duties, wiki contributions

Container Configuration

Each subagent runs in a Docker container with these mounts:

# ci-triage example
volumes:
  - /root/.openclaw/workspace-ci-triage:/workspace:rw
  - /root/.openclaw/workspace/skills:/workspace/skills:ro
  - /root/.config/rbw-ci-triage:/workspace/.config/rbw:rw

Key principles:

Workspace: Agent-specific directory, read/write
Skills: Shared from main workspace, read-only
RBW config: Agent-specific vault, read/write

File System Layout

/root/.openclaw/
├── workspace/                    # Main agent workspace
│   ├── skills/                   # Shared skills (commune/skills repo)
│   ├── AGENTS.md
│   ├── TOOLS.md
│   └── SOUL.md
├── workspace-ci-triage/          # CI agent workspace
│   ├── AGENTS.md
│   ├── TOOLS.md
│   ├── SOUL.md
│   └── memory/
└── workspace-research/           # Research agent workspace
    ├── AGENTS.md
    ├── TOOLS.md
    ├── SOUL.md
    └── memory/

/root/.config/
├── rbw/                          # Main agent vault
│   ├── config.json
│   └── master_password (mode 600)
├── rbw-ci-triage/                # CI agent vault
│   ├── config.json
│   └── master_password (mode 600)
└── rbw-research/                 # Research agent vault
    ├── config.json
    └── master_password (mode 600)

Configuration Files

Gateway Config (openclaw.json)

{
  "agents": {
    "ci-triage": {
      "forgejo_username": "ci",
      "model": "anthropic/claude-sonnet-4-5",
      "thinking": "low",
      "sandbox": {
        "enabled": true,
        "workspaceRoot": "/root/.openclaw/workspace-ci-triage",
        "mounts": [
          {
            "source": "/root/.openclaw/workspace-ci-triage",
            "target": "/workspace",
            "readonly": false
          },
          {
            "source": "/root/.openclaw/workspace/skills",
            "target": "/workspace/skills",
            "readonly": true
          },
          {
            "source": "/root/.config/rbw-ci-triage",
            "target": "/workspace/.config/rbw",
            "readonly": false
          }
        ],
        "env": {
          "HOME": "/workspace"
        }
      }
    },
    "research": {
      "forgejo_username": "researcher",
      "model": "anthropic/claude-sonnet-4-5",
      "thinking": "low",
      "sandbox": {
        "enabled": true,
        "workspaceRoot": "/root/.openclaw/workspace-research",
        "mounts": [
          {
            "source": "/root/.openclaw/workspace-research",
            "target": "/workspace",
            "readonly": false
          },
          {
            "source": "/root/.openclaw/workspace/skills",
            "target": "/workspace/skills",
            "readonly": true
          },
          {
            "source": "/root/.config/rbw-research",
            "target": "/workspace/.config/rbw",
            "readonly": false
          }
        ],
        "env": {
          "HOME": "/workspace"
        }
      }
    }
  }
}

AGENTS.md Template

Every agent workspace needs an AGENTS.md that includes this critical startup check:

## Session Start
1. **Check your environment:** Run `pwd` — if output is `/workspace`, you MUST use relative paths or absolute paths starting with `/workspace/`. Tool calls with host paths will fail.
2. Read SOUL.md (who you are)
3. Read TOOLS.md (your resources)
4. Read memory/YYYY-MM-DD.md (today + yesterday)
5. Read MEMORY.md for context

Why this matters: Agents inherit context from the main session which references host paths (/root/.openclaw/workspace-*), but inside containers everything is at /workspace. Without this check, agents waste tool calls trying to access non-existent host paths.

Common Issues and Solutions

1. RBW Master Password Permissions

Problem: The master_password file owned by root:root mode 600, but containers run as uid 1000 (sandbox user).

Error:

cat: /workspace/.config/rbw/master_password: Permission denied

Solution: Set correct ownership when creating rbw vaults:

# Create vault directory
mkdir -p /root/.config/rbw-ci-triage
 
# Initialize rbw config
rbw config set base_url https://keys.brads.house
rbw config set email ci@dungeon.church
 
# Create master password file with correct ownership
echo "your-master-password" > /root/.config/rbw-ci-triage/master_password
chown 1000:1000 /root/.config/rbw-ci-triage/master_password
chmod 600 /root/.config/rbw-ci-triage/master_password

Alternative: Use mode 644 if ownership can’t be changed:

chmod 644 /root/.config/rbw-ci-triage/master_password

2. Workspace Write Permissions

Problem: Agent needs write access to workspace for memory files, git operations, etc.

Solution: Ensure workspace directory is owned by uid 1000:

chown -R 1000:1000 /root/.openclaw/workspace-ci-triage

3. Skills Read Access (Path Escape Validation)

Problem: OpenClaw’s read tool validates paths are inside the agent’s workspace root. Skills mounted at /workspace/skills from /root/.openclaw/workspace/skills trigger path escape errors.

Error:

Path escapes sandbox root (~/.openclaw/workspace-research)

Workaround: Use exec cat instead of read for skills:

# ❌ Fails with path escape error
read skills/librarian/SKILL.md
 
# ✅ Works
exec cat skills/librarian/SKILL.md

Future fix options:

Modify read tool to allow read-only shared mounts
Mount skills inside agent workspace (/root/.openclaw/workspace-{agent}/skills)

4. Bash Array Syntax in Skills

Problem: Skills use bash arrays (ROLES=(...)) but exec tool defaults to /bin/sh which doesn’t support them.

Error:

sh: 1: Syntax error: "(" unexpected

Workaround: Explicitly use bash:

# ❌ Fails in sh
ROLES=("editor" "art-historian" "cartographer")
ROLE=${ROLES[$RANDOM % ${#ROLES[@]}]}
 
# ✅ Works with explicit bash
/usr/bin/bash -c 'ROLES=("editor" "art-historian")
ROLE=${ROLES[$RANDOM % ${#ROLES[@]}]}
echo $ROLE'

Future fix: Set bash as default shell in Docker image or make skills POSIX-compatible.

5. .env File Pollution

Problem: Skills that append to ~/.env accumulate entries across sessions in persistent workspaces:

# Before fix
LIBRARIAN_ROLE=editor
LIBRARIAN_ROLE=art-historian
LIBRARIAN_ROLE=editor
LIBRARIAN_ROLE=editor

Solution: Export variables instead of writing to disk:

# ❌ Old approach
with open(Path.home() / ".env", "a") as f:
    f.write(f"LIBRARIAN_ROLE={role}\n")
 
# ✅ New approach
import os
os.environ["LIBRARIAN_ROLE"] = role
print(f"export LIBRARIAN_ROLE={role}")

Then capture and eval in the skill:

ROLE_OUTPUT=$(python3 scripts/select_role.py)
eval "$(echo "$ROLE_OUTPUT" | head -1)"  # Set env var
echo "$ROLE_OUTPUT"

Setting Up a New Subagent

1. Create Workspace Directory

mkdir -p /root/.openclaw/workspace-{agent}
chown -R 1000:1000 /root/.openclaw/workspace-{agent}

2. Create RBW Vault

# Create vault directory
mkdir -p /root/.config/rbw-{agent}
 
# Configure rbw
RBW_CONFIG_DIR=/root/.config/rbw-{agent} rbw config set base_url https://keys.brads.house
RBW_CONFIG_DIR=/root/.config/rbw-{agent} rbw config set email {agent}@dungeon.church
 
# Create master password file
echo "master-password-here" > /root/.config/rbw-{agent}/master_password
chown 1000:1000 /root/.config/rbw-{agent}/master_password
chmod 600 /root/.config/rbw-{agent}/master_password

3. Create Configuration Files

Create AGENTS.md, TOOLS.md, and SOUL.md in the workspace directory. Use existing agents as templates, ensuring:

AGENTS.md includes the pwd check in Session Start
TOOLS.md documents container paths (/workspace/...)
SOUL.md defines the agent’s role and personality

4. Add to Gateway Config

Edit ~/.openclaw/openclaw.json:

{
  "agents": {
    "{agent}": {
      "forgejo_username": "{username}",
      "model": "anthropic/claude-sonnet-4-5",
      "thinking": "low",
      "sandbox": {
        "enabled": true,
        "workspaceRoot": "/root/.openclaw/workspace-{agent}",
        "mounts": [
          {
            "source": "/root/.openclaw/workspace-{agent}",
            "target": "/workspace",
            "readonly": false
          },
          {
            "source": "/root/.openclaw/workspace/skills",
            "target": "/workspace/skills",
            "readonly": true
          },
          {
            "source": "/root/.config/rbw-{agent}",
            "target": "/workspace/.config/rbw",
            "readonly": false
          }
        ],
        "env": {
          "HOME": "/workspace"
        }
      }
    }
  }
}

5. Restart Gateway

openclaw gateway restart

6. Test the Agent

Spawn a test session:

openclaw sessions spawn --agent {agent} --task "Check your environment with pwd, verify skills access with 'ls /workspace/skills', and test rbw with 'rbw unlock < /workspace/.config/rbw/master_password && rbw sync'"

Verify:

✅ pwd returns /workspace
✅ Skills directory is readable
✅ rbw unlocks successfully
✅ Agent can write to workspace

Security Considerations

Credential Isolation

Each agent has its own Vaultwarden vault with unique credentials:

Main agent: Full access to all Brad’s credentials
CI agent: Limited to CI/CD tokens, deployment keys
Research agent: Limited to research APIs, library tokens

Never share master passwords between agents. Each vault is independent.

Workspace Boundaries

Agents cannot access each other’s workspaces due to Docker mount isolation:

ci-triage sees only /workspace (mapped to workspace-ci-triage)
research sees only /workspace (mapped to workspace-research)
Skills are read-only and shared

Skills as Shared Code

Skills mounted read-only prevent agents from modifying shared tooling. Changes to commune/skills require PRs and go through review.

Troubleshooting

Agent can’t write to workspace

Check ownership:

ls -la /root/.openclaw/workspace-{agent}
# Should be 1000:1000

Fix:

chown -R 1000:1000 /root/.openclaw/workspace-{agent}

rbw unlock fails

Check master_password permissions:

ls -la /root/.config/rbw-{agent}/master_password
# Should be: -rw------- 1 1000 1000 or -rw-r--r-- 1 root root

Fix:

chown 1000:1000 /root/.config/rbw-{agent}/master_password
chmod 600 /root/.config/rbw-{agent}/master_password

Tool calls fail with host paths

Check AGENTS.md includes the startup environment check:

1. **Check your environment:** Run `pwd` — if output is `/workspace`...

Verify agent is using container paths in tool calls:

✅ /workspace/skills/librarian/SKILL.md
✅ skills/librarian/SKILL.md (relative)
❌ /root/.openclaw/workspace/skills/librarian/SKILL.md

Skills throw syntax errors

Check for bashisms in skills. Either:

Use explicit bash: /usr/bin/bash -c '...'
Make skills POSIX-compatible (avoid arrays, [[, etc.)

References

OpenClaw documentation: /usr/lib/node_modules/openclaw/docs
Skills repository: commune/skills on git.brads.house
Example agent configs: /root/.openclaw/workspace-{ci-triage,research}/

Multi-Agent Coordination — resilience patterns and provider fallbacks
Agent Skills — skill system architecture
Credential Management — rbw and Vaultwarden patterns

Commune

Explorer

Multi-Agent OpenClaw Setup

Overview

Architecture

Agent Roster

Container Configuration

File System Layout

Configuration Files

Gateway Config (openclaw.json)

AGENTS.md Template

Common Issues and Solutions

1. RBW Master Password Permissions

2. Workspace Write Permissions

3. Skills Read Access (Path Escape Validation)

4. Bash Array Syntax in Skills

5. .env File Pollution

Setting Up a New Subagent

1. Create Workspace Directory

2. Create RBW Vault

3. Create Configuration Files

4. Add to Gateway Config

5. Restart Gateway

6. Test the Agent

Security Considerations

Credential Isolation

Workspace Boundaries

Skills as Shared Code

Troubleshooting

Agent can’t write to workspace

rbw unlock fails

Tool calls fail with host paths

Skills throw syntax errors

References

Graph View

Table of Contents

Backlinks

Commune

Explorer

Multi-Agent OpenClaw Setup

Overview

Architecture

Agent Roster

Container Configuration

File System Layout

Configuration Files

Gateway Config (openclaw.json)

AGENTS.md Template

Common Issues and Solutions

1. RBW Master Password Permissions

2. Workspace Write Permissions

3. Skills Read Access (Path Escape Validation)

4. Bash Array Syntax in Skills

5. .env File Pollution

Setting Up a New Subagent

1. Create Workspace Directory

2. Create RBW Vault

3. Create Configuration Files

4. Add to Gateway Config

5. Restart Gateway

6. Test the Agent

Security Considerations

Credential Isolation

Workspace Boundaries

Skills as Shared Code

Troubleshooting

Agent can’t write to workspace

rbw unlock fails

Tool calls fail with host paths

Skills throw syntax errors

References

Related

Graph View

Table of Contents

Backlinks