openclaw-spawner

---
name: openclaw-spawner
description: >
  Enables an Openclaw agent to spawn sub-agents (child Openclaw instances) when a task is too
  large, complex, or parallel to handle alone. Use this skill whenever an Openclaw agent needs
  to delegate work to another Openclaw agent, break a large task into concurrent sub-tasks,
  or hand off a portion of work mid-execution. Triggers include: task requires parallel execution,
  a sub-task is clearly separable from the main task, the agent detects it cannot complete the
  work alone within time/context limits, or the user asks to "spawn", "delegate", "parallelize",
  or "split" work across agents. Always use this skill — not ad-hoc improvisation — when spawning
  is needed.
env: >
  Provider API key env var — which one depends on the model= argument passed at call time.
  Common ones: ANTHROPIC_API_KEY (Anthropic), OPENAI_API_KEY (OpenAI), GEMINI_API_KEY (Gemini),
  GROQ_API_KEY (Groq), MISTRAL_API_KEY (Mistral). Ollama requires no key.
  Full list: https://docs.litellm.ai/docs/providers
security: >
  CREDENTIAL: Set the provider-specific API key env var for your chosen model. Never embed keys in payloads or snapshots.
  FILESYSTEM: Passing file-access tools to children grants them read/write access to arbitrary paths — only pass tools you trust.
  DATA EXPOSURE: progress_so_far is sent to the provider API and visible to the child agent — sanitize snapshots and strip secrets before spawning.
  TOOLS: Tools must be in OpenAI function-call format — LiteLLM translates them per provider automatically.
---

# Openclaw Spawner

Allows an Openclaw agent to spawn child Openclaw agents, passing them exactly the context they
need to carry out their piece of work and report results back.

**Helper script:** `scripts/spawn_openclaw.py` — copy this into your project and import from it.
It contains `spawn_openclaw()`, `spawn_openclaw_async()`, `is_error()`, and `read_result()`.

**Multi-provider:** Uses [LiteLLM](https://docs.litellm.ai/docs/providers) — pass any supported
model string via the `model=` argument. Default is `"anthropic/claude-opus-4-6"`.

**Requires:** `litellm` Python package (`pip install litellm`) and the API key env var for
your chosen provider (e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`).

**Tool format:** OpenAI function-call format. LiteLLM translates to each provider's native
format automatically.

---

## Security Notes

> **Credential:** `spawn_openclaw.py` uses LiteLLM to call your chosen provider.
> Set the matching API key env var (e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`).
> Never put keys in a payload or snapshot.

> **Tool format:** Tools must be in OpenAI function-call format. LiteLLM translates
> them to each provider's native format automatically.

> **Filesystem access:** Passing `tools=` to a child agent grants that child whatever
> capabilities those tools carry. File-access tools allow children to read and write arbitrary
> paths. Only supply tools you would trust the parent to use directly. When in doubt, omit
> `tools=` — the child will return results in its summary text.

> **Snapshot sanitization:** `progress_so_far` is sent to the Anthropic API and injected
> into the child's context. Before spawning, review snapshots and strip any secrets,
> credentials, personal data, or other sensitive information.

---

## When to Spawn

Spawn a child agent when **any** of these are true:

- The remaining task has a clearly separable sub-task that can run independently.
- Two or more subtasks can proceed in parallel, saving wall-clock time.
- The current agent's context window is approaching its limit and a fresh context would help.
- A sub-task requires different tools, permissions, or specialization.
- The user explicitly asks to spawn / delegate / parallelize.

**Do not** spawn for trivial one-step tasks; keep it in the current agent.

---

## Spawn Depth Limit

`MAX_DEPTH = 3` (configurable in `scripts/spawn_openclaw.py`).

| Depth | Role |
|---|---|
| 0 | Root / parent agent |
| 1 | Direct child (default spawn) |
| 2 | Grandchild (only if child's `sub_task` explicitly permits spawning) |
| 3+ | **Blocked** — raises `ValueError` |

Always pass `depth=<current_depth + 1>` when calling `spawn_openclaw()` from inside a child.

---

## Spawn Payload Schema

Every spawn call must include these three fields:

```json
{
  "main_task_title": "<short human-readable title of the overall parent task>",
  "progress_so_far": "<markdown summary of what has already been done, decisions made, artefacts produced, and anything the sub-agent must know to avoid redoing work>",
  "sub_task": "<clear, self-contained description of exactly what this child agent must do, including expected output format and where/how to return results>"
}
```

### Field Guidelines

| Field | Rules |
|---|---|
| `main_task_title` | ≤ 10 words. Stable across all children of the same parent. |
| `progress_so_far` | Include: steps completed, key decisions, files written, variables/state the child needs. Exclude: raw data the child doesn't need. Keep it dense but readable. |
| `sub_task` | Must be self-contained. Assume the child has zero memory of the parent conversation. Include: what to do, inputs, expected output format, where to put results (file path, return value, etc.). |

---

## Step-by-Step Spawning Protocol

### 1 — Decide to Spawn

Confirm the sub-task is genuinely separable. If in doubt, handle it yourself.

### 2 — Freeze Parent State

Before spawning, write a progress snapshot. This becomes `progress_so_far` for the child
**and** serves as the parent's own checkpoint in case it needs to resume.

> **Sanitize before spawning.** `progress_so_far` is sent to the Anthropic API and
> injected into the child's context. Remove any secrets, API keys, passwords, tokens,
> or personal data before including them in the snapshot.

```
## Progress Snapshot — <main_task_title>
**Completed:**
- <step 1>
- <step 2>

**Artifacts produced:**
- <file or output name>: <one-line description>

**Decisions made:**
- <decision>: <rationale>

**Pending (what the child will handle):**
- <sub-task description>
```

### 3 — Build the Spawn Payload

Fill in the three required fields from the snapshot above.

### 4 — Spawn the Openclaw Sub-Instance

Import from `scripts/spawn_openclaw.py`:

> **Important:** Without `tools=`, the child is a pure language model — it can reason and
> produce text but **cannot read or write files**. If the sub_task requires file I/O, pass the
> appropriate tool definitions (e.g. Anthropic computer-use tools, custom file tools).
> When tools are omitted, collect the child's result from the `summary` string directly
> rather than calling `read_result()`.

```python
from spawn_openclaw import spawn_openclaw, is_error, read_result

# my_tools = [...]  # OpenAI function-call format tools if the child needs file I/O

payload = {
    "main_task_title": "Refactor authentication module",
    "progress_so_far": (
        "## Progress Snapshot\n"
        "**Completed:**\n- Audited existing auth flow\n- Identified 3 outdated JWT helpers\n\n"
        "**Artifacts produced:**\n- `/tmp/audit_report.md`: full list of issues\n\n"
        "**Decisions made:**\n- Use PyJWT 2.x API; drop legacy HS256 fallback\n\n"
        "**Pending (child handles):**\n- Rewrite auth/jwt_helpers.py per audit report"
    ),
    "sub_task": (
        "Rewrite `/src/auth/jwt_helpers.py` using PyJWT 2.x. "
        "Read `/tmp/audit_report.md` for issues to fix. "
        "Write the rewritten file to `/tmp/jwt_helpers_new.py` and a "
        "one-paragraph summary to `/tmp/jwt_helpers_changes.md`."
    ),
}

try:
    # Swap model= to use any LiteLLM-supported provider:
    # "openai/gpt-4o", "gemini/gemini-2.0-flash", "groq/llama-3.3-70b-versatile", etc.
    summary = spawn_openclaw(payload, depth=1, model="anthropic/claude-opus-4-6", tools=my_tools)
except (ValueError, FileNotFoundError) as exc:
    raise  # bad depth, missing payload key, or SKILL.md not found — fix the call

if is_error(summary):
    print("Child failed:", summary)
else:
    result = read_result("/tmp/jwt_helpers_changes.md")
    if result is None:
        print("WARNING: child did not write expected result file.")
```

If `SKILL.md` is not adjacent to `spawn_openclaw.py`, pass the path explicitly:

```python
import pathlib
summary = spawn_openclaw(payload, depth=1, skill_path=pathlib.Path("/your/path/to/SKILL.md"))
```

### 5 — Await and Integrate Results

1. Check `is_error(summary)` — handle failures before reading files.
2. Use `read_result(path)` to safely read child output; treat `None` as child failure.
3. Merge into parent progress snapshot.
4. Continue with the next step of the parent task — or spawn another child if needed.

---

## Spawning Strategies

| Strategy | When to use | Parent blocks? |
|---|---|---|
| **Sequential** | Child output is needed for next parent step | Yes, until child done |
| **Parallel-gather** | Multiple independent children; parent needs all before continuing | Yes, until all done |
| **Fire-and-forget** | Child works on a separable track; parent has its own work now | No — merge later |

---

### Strategy A — Sequential

Use `spawn_openclaw(payload, depth=1)` as shown in Step 4. Read result, check for errors, continue.

---

### Strategy B — Parallel Gather

```python
import asyncio
from spawn_openclaw import spawn_openclaw_async, is_error, read_result

async def main():
    payloads = [
        {
            "main_task_title": "Generate market research report",
            "progress_so_far": "Outline approved. Three sections assigned in parallel.",
            "sub_task": "Write 'Competitive Landscape' (600 words). Save to /tmp/section_competitive.md."
        },
        {
            "main_task_title": "Generate market research report",
            "progress_so_far": "Outline approved. Three sections assigned in parallel.",
            "sub_task": "Write 'Customer Segments' (600 words). Save to /tmp/section_customers.md."
        },
        {
            "main_task_title": "Generate market research report",
            "progress_so_far": "Outline approved. Three sections assigned in parallel.",
            "sub_task": "Write 'Market Trends' (600 words). Save to /tmp/section_trends.md."
        },
    ]

    summaries = await asyncio.gather(
        *[spawn_openclaw_async(p, depth=1, model="openai/gpt-4o", tools=my_tools) for p in payloads],
        return_exceptions=True,
    )

    result_paths = [
        "/tmp/section_competitive.md",
        "/tmp/section_customers.md",
        "/tmp/section_trends.md",
    ]

    for summary, path in zip(summaries, result_paths):
        if isinstance(summary, BaseException):
            print(f"Child raised exception for {path}: {summary}")
            continue
        if is_error(summary):
            print(f"Child failed for {path}:", summary)
            continue
        content = read_result(path)
        if content is None:
            print(f"WARNING: no result file at {path}")
        else:
            print(f"Merging {path} ({len(content)} chars)")
            # merge content into parent output ...
```

---

### Strategy C — Fire-and-Forget

The parent delegates a sub-task and **immediately continues its own work**.
The child writes results to a known file path. The parent checks at a planned **merge point**.

```
Parent:  ──[spawn child]──────────────────────────[merge point]──▶ continue
Child:            └──[work independently]──[write result file]──▶ done
```

```python
import asyncio
from spawn_openclaw import spawn_openclaw_async, is_error, read_result

async def main():
    child_result_path = "/tmp/child_analysis.md"
    payload = {
        "main_task_title": "Refactor authentication module",
        "progress_so_far": (
            "Audit complete. Parent is now rewriting core auth logic. "
            "Child is assigned to analyse test coverage gaps in parallel."
        ),
        "sub_task": (
            f"Read `/tmp/audit_report.md`. Identify which functions lack test coverage. "
            f"Write a markdown report of gaps to `{child_result_path}`. "
            f"Include function name, file, and suggested test cases for each gap."
        ),
    }

    # Spawn — returns immediately, child runs in background
    child_task = asyncio.create_task(
        spawn_openclaw_async(payload, depth=1, model="anthropic/claude-opus-4-6", tools=my_tools)
    )

    # Parent does its OWN work right now
    await do_parent_work()

    # Merge point — collect child
    try:
        summary = await child_task
    except (ValueError, FileNotFoundError) as exc:
        print("Child raised configuration error:", exc)
        return
    if is_error(summary):
        print("Child failed:", summary)
    else:
        content = read_result(child_result_path)
        if content is None:
            print("WARNING: child did not write expected result file.")
        else:
            await integrate_child_output(content)


async def do_parent_work():
    pass  # replace with actual parent steps

async def integrate_child_output(text: str):
    print(f"Merging {len(text)} chars from child...")
```

#### Rules for fire-and-forget

1. **Always specify `result_path` in `sub_task`** — it is the only rendezvous.
2. **Plan your merge point before spawning** — know exactly when the parent will need the child's output.
3. **Use `read_result()`** — returns `None` safely on any filesystem error (missing file, permission denied, etc.).
4. **One result file per child** — if a child produces multiple artefacts, have it write a manifest JSON listing them all.
5. **Don't fire-and-forget if parent needs the result immediately** — use Sequential instead.

---

## Error Handling

**What raises vs. what returns an error string:**

| Situation | Behaviour |
|---|---|
| Anthropic API error (network, rate limit, etc.) | Returns JSON error string — never raises |
| Empty or non-text API response | Returns JSON error string — never raises |
| `depth >= MAX_DEPTH` | **Raises `ValueError`** — programmer error, fix your call |
| Missing required payload key (`main_task_title`, `progress_so_far`, `sub_task`) | **Raises `ValueError`** — fix your payload |
| Non-JSON-serializable value in payload | **Raises `ValueError`** — fix your payload |
| SKILL.md not found | **Raises `FileNotFoundError`** — fix your path config |

Always check with `is_error()` after a successful call. Wrap the call itself in try/except if you need to handle the two programmer-error exceptions gracefully:

```python
try:
    summary = spawn_openclaw(payload, depth=1)
except (ValueError, FileNotFoundError) as exc:
    print("Configuration error:", exc)
    raise  # or handle

if is_error(summary):
    import json
    err = json.loads(summary)
    print("Runtime error:", err["error"])
    print("Partial results at:", err.get("partial_results"))  # may be None
    # decide: retry, fallback, abort parent
else:
    # success — read result files
    result = read_result("/tmp/some_output.md")
    if result is not None:
        # merge result ...
        pass
    else:
        print("WARNING: child did not write expected result file.")
```

---

## Anti-Patterns to Avoid

| Anti-Pattern | Why It's Bad | Fix |
|---|---|---|
| Sending the full conversation history as `progress_so_far` | Wastes tokens; child gets confused | Summarize: only what the child needs |
| Including secrets in `progress_so_far` | Snapshot is sent to Anthropic API and visible to child | Strip API keys, passwords, tokens, and personal data before spawning |
| Passing overly-permissive tools to children | Children gain filesystem or network access beyond what their sub_task needs | Scope tools to minimum required capability; omit tools= if the task only needs text output |
| Vague `sub_task` like "handle the rest" | Child doesn't know what to do | Be explicit: inputs, steps, output location |
| Spawning for a 2-line task | Overhead > benefit | Do it in the parent |
| Not writing a progress snapshot before spawning | Parent loses state if it crashes | Always freeze state first |
| Omitting `tools=` when sub_task requires file I/O | Child is a pure LM — it cannot read or write files; `read_result()` always returns `None` | Pass tool definitions or collect results from the summary string instead |
| Ignoring `is_error()` on child summary | Silent failures; parent merges nothing | Always check before reading result files |
| Fire-and-forget with no result file | No rendezvous; parent can't collect output | Always specify `result_path` in `sub_task` |
| Awaiting fire-and-forget child immediately after spawn | Defeats the purpose | Put `await child_task` at the merge point |
| Omitting `depth=` when spawning from inside a child | Depth check never triggers; runaway trees | Always pass `depth=current_depth + 1` |
| Child spawning further children without explicit permission | Runaway tree; hard to debug | Only spawn if `sub_task` explicitly says so |

---

## Quick Reference Card

```
SPAWN CHECKLIST
───────────────────────────────────────────
[ ] Sub-task is genuinely separable?
[ ] depth= will stay within MAX_DEPTH (default 3)?
[ ] Progress snapshot written (parent state frozen)?
[ ] main_task_title: ≤ 10 words, stable
[ ] progress_so_far: dense summary, no raw dumps
[ ] sub_task: self-contained, explicit result_path

STRATEGY SELECTION
[ ] Parent needs result before next step?        → Sequential (A)
[ ] Multiple children, all needed before merge?  → Parallel-gather (B)
[ ] Parent has its own work to do right now?     → Fire-and-forget (C)

AFTER EVERY SPAWN
[ ] is_error(summary) checked?
[ ] read_result(path) used (handles missing files safely)?
[ ] None result handled — don't merge silently?

FIRE-AND-FORGET EXTRAS
[ ] result_path agreed before spawning?
[ ] merge point placed after parent's own work?
```