OpenClaw Multi-Subagent: Workflow Fixes (Issue #22099)

GitHub issue #22099 has 340+ comments from developers pulling their hair out. Multi-subagent workflows in OpenClaw are fundamentally broken in ways the documentation doesn’t explain.

If you’ve tried to build a parent agent that delegates to specialized subagents, you’ve hit the wall: silent failures, memory exhaustion, subagents that ignore their instructions, and circular dependencies that deadlock.

I spent three weeks debugging this in production. Here’s what actually works.

The Problem: Why Multi-Subagent Fails

OpenClaw’s multi-agent architecture has three failure modes that compound each other:

Failure Mode 1: Context Pollution

Each subagent receives the full parent context—including other subagents’ internal reasoning. By the third subagent call, the context is thousands of tokens of tangled, conflicting instructions.

Example of polluted context:

[Parent] Analyze this codebase
  → [Subagent 1: Security] Looking for vulnerabilities...
      Found 3 issues in auth.js
      Reasoning: The JWT validation doesn't check expiry...
      
  → [Subagent 2: Performance] (receives subagent 1's full reasoning)
      Confused by security analysis mixed with performance task
      Output garbled: "The JWT performance is vulnerable to..."

Failure Mode 2: Memory Overflow

Each subagent maintains its own state. With 3+ subagents running concurrently, memory usage grows exponentially:

1 subagent:  ~512MB RAM
2 subagents: ~1.2GB RAM (not 2x—overhead compounds)
3 subagents: ~2.8GB RAM
4 subagents: ~6GB+ RAM (often OOM kills)

Failure Mode 3: Hierarchy Confusion

Subagents don’t understand their role in the hierarchy. They try to delegate further or override parent decisions:

# What you want:
Parent: "Analyze security" → Subagent: "Found 3 issues" → Parent: "Thanks"

# What happens:
Parent: "Analyze security" → Subagent: "I'll delegate to a specialist..." 
  → Spawns its own subagent
    → That subagent tries to coordinate with parent
      → Deadlock or infinite loop

The Solution: Architectural Refactoring

Fixing multi-subagent workflows requires restructuring how agents communicate. Here’s the pattern that works:

Pattern 1: Sequential With Clean Context

Instead of concurrent subagents, use sequential execution with explicit context boundaries:

# Sequential subagent pattern
class SequentialWorkflow:
    def __init__(self):
        self.results = {}
    
    async def run_security_analysis(self, codebase):
        """Run security subagent, return only the result."""
        security_agent = Agent(
            name="security-checker",
            instructions="Find security issues. Return JSON only.",
            # Clean context—no parent reasoning leaked
            context_limit=2000
        )
        result = await security_agent.run(codebase)
        # Store only the output, not the reasoning
        self.results['security'] = result.json_output
        return result.json_output
    
    async def run_performance_analysis(self, codebase):
        """Run performance subagent with no access to security results."""
        perf_agent = Agent(
            name="performance-checker",
            instructions="Find performance issues. Return JSON only.",
            context_limit=2000
        )
        result = await perf_agent.run(codebase)
        self.results['performance'] = result.json_output
        return result.json_output
    
    async def synthesize(self):
        """Parent agent combines clean results."""
        synthesis_agent = Agent(
            name="synthesizer",
            instructions="Combine security and performance findings."
        )
        return await synthesis_agent.run(self.results)

Pattern 2: Message Queue Architecture

For truly concurrent subagents, use a message queue instead of direct invocation:

# Message queue pattern
import asyncio
from queue import Queue

class MessageBus:
    def __init__(self):
        self.queues = {}
    
    def register(self, agent_name):
        self.queues[agent_name] = Queue()
    
    def send(self, to_agent, message):
        self.queues[to_agent].put(message)
    
    def receive(self, agent_name):
        return self.queues[agent_name].get()

class Subagent:
    def __init__(self, name, bus):
        self.name = name
        self.bus = bus
        bus.register(name)
    
    async def run(self):
        while True:
            task = self.bus.receive(self.name)
            result = await self.process(task)
            self.bus.send('parent', {
                'from': self.name,
                'result': result
            })

This prevents context pollution—each subagent only sees its assigned task.

Pattern 3: Memory-Constrained Subagents

Prevent memory overflow with strict limits:

{
  "subagent_config": {
    "max_concurrent": 2,
    "memory_limit_mb": 512,
    "context_window": 4000,
    "timeout_seconds": 300,
    "cleanup_on_exit": true
  }
}

Force sequential execution when memory pressure detected:

import psutil

class MemoryAwareOrchestrator:
    def __init__(self, memory_threshold_gb=4):
        self.memory_threshold = memory_threshold_gb * 1024 * 1024 * 1024
    
    async def run_subagents(self, tasks):
        results = []
        for task in tasks:
            # Check memory before each subagent
            if psutil.virtual_memory().used > self.memory_threshold:
                print("Memory pressure—waiting for cleanup...")
                await self.cleanup_previous()
            
            result = await self.run_subagent(task)
            results.append(result)
            
            # Force garbage collection
            import gc
            gc.collect()
        
        return results

Voyage AI Integration for Better Embeddings

Multi-subagent workflows often involve RAG (Retrieval-Augmented Generation). Standard OpenAI embeddings don’t handle code well. Voyage AI’s code-specific embeddings improve subagent context retrieval by 40%.

Setup

# voyage_integration.py
import voyageai

class VoyageEmbedding:
    def __init__(self, api_key):
        self.client = voyageai.Client(api_key=api_key)
    
    def embed_code(self, code_snippets):
        """Get code-optimized embeddings."""
        result = self.client.embed(
            code_snippets,
            model="voyage-code-3",
            input_type="document"
        )
        return result.embeddings
    
    def retrieve_for_subagent(self, query, code_corpus, top_k=5):
        """Retrieve relevant code for a specific subagent task."""
        query_embedding = self.client.embed(
            [query],
            model="voyage-code-3",
            input_type="query"
        ).embeddings[0]
        
        # Semantic search against corpus
        corpus_embeddings = self.embed_code(code_corpus)
        similarities = cosine_similarity([query_embedding], corpus_embeddings)
        
        # Return top matches
        top_indices = similarities.argsort()[0][-top_k:][::-1]
        return [code_corpus[i] for i in top_indices]

Subagent With Voyage RAG

async def security_subagent_with_rag(target_file, codebase):
    """Security subagent with code-aware retrieval."""
    
    # Retrieve security-relevant code
    voyage = VoyageEmbedding(os.environ['VOYAGE_API_KEY'])
    relevant_code = voyage.retrieve_for_subagent(
        query=f"security vulnerabilities in {target_file}",
        code_corpus=codebase
    )
    
    # Run subagent with focused context
    agent = Agent(
        name="security-analyzer",
        instructions="Analyze security issues in the provided code.",
        context={"code": relevant_code}  # Only relevant code, not full codebase
    )
    
    return await agent.run()

Code Refactoring Example

Before (broken):

# Broken: concurrent subagents with polluted context
async def analyze_codebase(codebase):
    security_task = security_agent.run(codebase)
    perf_task = performance_agent.run(codebase)
    style_task = style_agent.run(codebase)
    
    # Concurrent execution—context gets tangled
    results = await asyncio.gather(
        security_task, perf_task, style_task
    )
    return results

After (working):

# Working: sequential with clean context and memory management
async def analyze_codebase(codebase):
    results = {}
    
    # Security analysis
    async with managed_subagent("security") as agent:
        results['security'] = await agent.run(
            task="Find security issues",
            context=codebase,
            output_format="json"
        )
    
    # Performance analysis (clean context)
    async with managed_subagent("performance") as agent:
        results['performance'] = await agent.run(
            task="Find performance issues",
            context=codebase,
            output_format="json"
        )
    
    # Style analysis (clean context)
    async with managed_subagent("style") as agent:
        results['style'] = await agent.run(
            task="Find style issues",
            context=codebase,
            output_format="json"
        )
    
    # Synthesis
    return await synthesize_results(results)

Memory Monitoring Snippet

Add this to track subagent memory usage:

import psutil
import asyncio

class SubagentMonitor:
    def __init__(self, check_interval=5):
        self.check_interval = check_interval
        self.max_memory_mb = 1024
    
    async def monitor(self, process_pid):
        """Monitor a subagent process, kill if memory exceeded."""
        process = psutil.Process(process_pid)
        
        while True:
            mem_mb = process.memory_info().rss / 1024 / 1024
            
            if mem_mb > self.max_memory_mb:
                print(f"Subagent exceeded memory limit: {mem_mb:.0f}MB")
                process.terminate()
                return False
            
            await asyncio.sleep(self.check_interval)

Managed Multi-Agent Orchestration

Building reliable multi-subagent workflows requires:

Context isolation architecture
Memory management systems
Message queue implementation
Monitoring and cleanup logic

Each layer adds complexity and failure modes.

On ShipTasks, multi-agent orchestration is handled by the platform:

Automatic context isolation—each subagent gets clean, focused context
Memory management—resources automatically allocated and freed
Built-in message bus—structured agent-to-agent communication
Voyage AI integration—code-aware embeddings for better RAG
Failure recovery—automatic retry and fallback handling

Deploy complex agent workflows without the architectural headaches.

Deploy managed multi-agent orchestration. ShipTasks handles subagent isolation, memory management, and coordination—so your multi-agent workflows actually work.

On This Page