# Sub-Agents Mastery: Parallel Workflows That Actually Work

Canonical: https://clawdocx.com/docs/sub-agents-mastery
Author: Sam Okafor
Difficulty: INTERMEDIATE
Published: 2026-02-01
Updated: 2026-02-01

> Learn when and how to use sub-agents for complex tasks. Fan-out patterns, monitoring, error handling, and real-world examples.

# Sub-Agents Mastery: Parallel Workflows That Actually Work

Sub-agents let you break complex tasks into parallel workflows. Instead of doing everything sequentially, you spawn multiple agents to work simultaneously—then combine their results.

## What Are Sub-Agents?

A **sub-agent** is a separate OpenClaw session spawned to handle a specific task. Your main agent delegates work to sub-agents, monitors their progress, and combines their outputs.

**When to use sub-agents:**
- Research requiring multiple sources simultaneously
- Code reviews across multiple files
- Content generation (bulk blog posts, variations)
- Multi-step tasks that can run in parallel
- Tasks requiring different models or thinking levels

**When NOT to use sub-agents:**
- Simple sequential tasks (overhead isn't worth it)
- Tasks requiring shared state throughout
- Quick one-off queries

---

## The Three Types of Sub-Agents

### 1. sessions_spawn (Built-in)

OpenClaw's native sub-agent spawning via the `sessions_spawn` tool.

```javascript
// Spawn a research sub-agent
const result = await sessions_spawn({
  task: "Research the latest React Server Components best practices. Find 5 authoritative sources and summarize key points.",
  agentId: "anthropic/claude-sonnet-4-6",
  timeoutSeconds: 300,
  cleanup: "delete" // or "keep"
});
```

**Pros:** Built-in, simple, auto-announces results
**Cons:** Limited control, one-shot (no steering mid-task)

### 2. Claude Code / Codex Agents

Spawn Claude Code or Codex for coding-heavy tasks.

```javascript
// Spawn Claude Code for a coding task
const result = await sessions_spawn({
  task: "Implement a Redis caching layer for the user service. Write the code, tests, and documentation.",
  agentId: "openai-codex/gpt-5.3-codex",
  timeoutSeconds: 600,
  thinking: "high"
});
```

**Pros:** Specialized for coding, can work on large codebases
**Cons:** Higher cost, longer runtime

### 3. Coding-Agent Skill

Use the `coding-agent` skill to delegate coding tasks with more control.

```bash
# From within a skill
openclaw agent spawn \
  --skill coding-agent \
  --task "Refactor the authentication module" \
  --model codex53 \
  --dir /tmp/refactor-task
```

**Pros:** Skill-based, reusable, can chain multiple
**Cons:** Requires skill installation

---

## Fan-Out Patterns

### Pattern 1: Parallel Research

Spawn multiple sub-agents to research different aspects simultaneously.

```javascript
// Research a topic from multiple angles
const researchTasks = [
  "Research technical implementation of edge functions",
  "Research pricing and cost considerations for edge deployment", 
  "Research security implications of edge computing",
  "Find case studies of companies using edge functions successfully"
];

const results = await Promise.all(
  researchTasks.map(task => sessions_spawn({
    task,
    agentId: "anthropic/claude-sonnet-4-6",
    timeoutSeconds: 300
  }))
);

// Combine results into comprehensive report
const report = synthesizeResearch(results);
```

**Use case:** Due diligence, technology evaluation, competitive analysis

### Pattern 2: Multi-File Code Review

Review different aspects of a PR in parallel.

```javascript
// Review different aspects of a codebase
const reviewTasks = [
  { aspect: "security", focus: "auth, injection vulnerabilities, secrets" },
  { aspect: "performance", focus: "n+1 queries, caching, big O" },
  { aspect: "style", focus: "naming, consistency, comments" },
  { aspect: "testing", focus: "coverage, edge cases, mocks" }
];

const reviews = await Promise.all(
  reviewTasks.map(({ aspect, focus }) => sessions_spawn({
    task: `Review this PR for ${aspect} issues. Focus on: ${focus}. Provide specific line-by-line feedback.`,
    agentId: "openai-codex/gpt-5.3-codex",
    timeoutSeconds: 400
  }))
);

// Aggregate into single comprehensive review
const finalReview = aggregateReviews(reviews);
```

**Use case:** Thorough PR reviews without waiting hours

### Pattern 3: Bulk Content Generation

Generate multiple content pieces simultaneously.

```javascript
// Generate blog post variations
const topics = [
  "OpenClaw for beginners",
  "Advanced OpenClaw workflows",
  "OpenClaw vs ChatGPT",
  "Building skills for OpenClaw"
];

const posts = await Promise.all(
  topics.map(topic => sessions_spawn({
    task: `Write a 1000-word blog post about "${topic}". Include introduction, 3 main sections with examples, and conclusion.`,
    agentId: "anthropic/claude-sonnet-4-6",
    timeoutSeconds: 600
  }))
);
```

**Use case:** Content marketing, documentation, variations testing

---

## Error Handling

Sub-agents can fail. Handle it gracefully:

```javascript
async function spawnWithFallback(task, primaryModel, fallbackModel) {
  try {
    return await sessions_spawn({
      task,
      agentId: primaryModel,
      timeoutSeconds: 300
    });
  } catch (error) {
    console.log(`Primary agent failed: ${error.message}. Trying fallback...`);
    
    return await sessions_spawn({
      task,
      agentId: fallbackModel,
      timeoutSeconds: 300
    });
  }
}

// Usage
const result = await spawnWithFallback(
  "Complex research task...",
  "anthropic/claude-opus-4-6",
  "anthropic/claude-sonnet-4-6"
);
```

**Strategies:**
- Retry with same model
- Fallback to cheaper model
- Fallback to sequential (no sub-agent)
- Queue for later retry

---

## Monitoring and Steering

### Check Sub-Agent Status

```javascript
// List running sub-agents
const activeAgents = await subagents({ action: "list" });

// Check specific agent
const status = await subagents({ 
  action: "poll", 
  target: "agent-session-key",
  timeout: 30000 
});
```

### Kill a Stuck Agent

```javascript
// If an agent is taking too long
await subagents({ 
  action: "kill", 
  target: "agent-session-key" 
});
```

### Send Mid-Task Instructions

```javascript
// Steer an agent mid-task (if supported)
await subagents({
  action: "steer",
  target: "agent-session-key",
  message: "Focus more on security aspects, less on performance"
});
```

---

## Cost Optimization

Sub-agents can get expensive. Optimize with these strategies:

### 1. Right-Size Your Models

```javascript
// Don't use Opus for simple tasks
const modelMap = {
  "research": "anthropic/claude-sonnet-4-6",
  "coding": "openai-codex/gpt-5.3-codex",
  "summarization": "anthropic/claude-haiku-4",
  "creative": "anthropic/claude-sonnet-4-6"
};

const result = await sessions_spawn({
  task,
  agentId: modelMap[taskType],
  timeoutSeconds: 300
});
```

### 2. Set Aggressive Timeouts

```javascript
// Don't let agents run forever
const result = await sessions_spawn({
  task: "Quick research...",
  agentId: "anthropic/claude-sonnet-4-6",
  timeoutSeconds: 120 // 2 minutes max
});
```

### 3. Use Cleanup: Delete

```javascript
// Clean up sessions to save resources
const result = await sessions_spawn({
  task,
  agentId: "anthropic/claude-sonnet-4-6",
  cleanup: "delete" // Remove session after completion
});
```

### 4. Batch Small Tasks

```javascript
// Instead of 10 tiny sub-agents, batch them
const result = await sessions_spawn({
  task: "Process these 10 small tasks in sequence: [list tasks]",
  agentId: "anthropic/claude-haiku-4", // Use cheap model
  timeoutSeconds: 300
});
```

---

## Real-World Example: Competitive Analysis

Here's a complete workflow for competitive analysis:

```javascript
// Step 1: Spawn parallel research agents
const competitors = ["CompetitorA", "CompetitorB", "CompetitorC"];

const researchResults = await Promise.all(
  competitors.map(competitor => sessions_spawn({
    task: `Research ${competitor}. Find: pricing, key features, customer reviews (positive and negative), recent news/updates, target market. Provide structured report.`,
    agentId: "anthropic/claude-sonnet-4-6",
    timeoutSeconds: 400
  }))
);

// Step 2: Spawn analysis agent to compare
const comparison = await sessions_spawn({
  task: `Compare these three competitors: ${JSON.stringify(researchResults)}. Create a feature matrix, identify their strengths/weaknesses, and recommend our positioning strategy.`,
  agentId: "anthropic/claude-opus-4-6",
  timeoutSeconds: 300
});

// Step 3: Spawn content agent to create deliverable
const presentation = await sessions_spawn({
  task: `Create a competitive analysis slide deck based on: ${comparison}. Include title slide, competitor overview slides, feature comparison table, and strategic recommendations.`,
  agentId: "anthropic/claude-sonnet-4-6",
  timeoutSeconds: 400
});

// Total time: ~15 minutes instead of 2+ hours sequentially
// Cost: ~$2-3 vs $5-8 if done as one long Opus session
```

---

## Common Mistakes

**Mistake 1: Over-parallelizing**
```javascript
// BAD: Spawning 50 sub-agents
const results = await Promise.all(
  items.map(item => sessions_spawn({ task: item })) // 50 agents!
);
// Result: Rate limits, high costs, confusion

// GOOD: Batch into reasonable groups
const batches = chunk(items, 5);
for (const batch of batches) {
  const results = await Promise.all(
    batch.map(item => sessions_spawn({ task: item }))
  );
  await processBatch(results);
}
```

**Mistake 2: Not handling failures**
```javascript
// BAD: Assuming all succeed
const results = await Promise.all(tasks.map(t => sessions_spawn(t)));

// GOOD: Graceful degradation
const results = await Promise.allSettled(tasks.map(t => sessions_spawn(t)));
const successful = results.filter(r => r.status === "fulfilled");
```

**Mistake 3: Wrong model for the task**
```javascript
// BAD: Using Opus for simple summarization
sessions_spawn({ agentId: "anthropic/claude-opus-4-6", task: "Summarize this paragraph" });

// GOOD: Use appropriate model
sessions_spawn({ agentId: "anthropic/claude-haiku-4", task: "Summarize this paragraph" });
```

---

## Sub-Agent Skill Template

Want to build a reusable sub-agent workflow? Use this SKILL.md template:

```markdown
# Multi-Reviewer Skill

## Overview
Spawn parallel code review sub-agents for comprehensive PR analysis.

## Tools
- sessions_spawn
- github

## Workflow
1. Fetch PR diff using GitHub skill
2. Spawn 4 review sub-agents (security, performance, style, tests)
3. Collect all reviews
4. Aggregate into final review comment
5. Post to GitHub

## Configuration
Set REVIEW_ASPECTS in your SOUL.md or environment.
```

---

## What's Next?

- **Cost Optimization Guide** — keep sub-agent bills under control
- **Workflow Recipes** — more copy-paste sub-agent patterns
- **Building Custom Skills** — package your sub-agent workflows as reusable skills

Start with simple parallel research tasks, then move to more complex orchestration. The key is starting small and adding complexity only when you need it.