.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
A single ZeroClaw agent can do a lot on its own, but some workflows benefit from splitting work across specialized agents. Instead of one agent that tries to handle everything from writing code to scheduling meetings to analyzing logs, you set up sub-agents that each focus on a specific domain and let the main agent delegate tasks to them.
ZeroClaw's delegate system handles this natively. The main agent evaluates incoming requests, decides if a sub-agent would handle it better and routes the task accordingly. The sub-agent works on the task and returns the result to the main agent, which presents it to the user.
This all happens within a single ZeroClaw instance; you don't need multiple VPS deployments.
When multi-agent setups make sense
Before configuring sub-agents, it's worth thinking about when this actually helps. A single agent with the right tools and a good system prompt handles most personal assistant tasks perfectly fine. Where multi-agent starts to pay off is when you have distinct domains that benefit from different system prompts, different tool sets or even different models.
A few patterns that work well: a coding agent that has access to shell tools and a detailed system prompt about your codebase, paired with a writing agent that has web search tools and a prompt tuned for drafting. Or a monitoring agent that runs on cron and checks system metrics, feeding summaries to a main agent that decides when to alert you. Or a research agent using a large cloud model for complex analysis, with a fast local model handling quick answers through the main agent.
If you've used OpenClaw's multi-agent system, the concepts are similar but ZeroClaw's implementation is lighter weight and runs everything in the same process rather than spawning separate services.
Sub-agent configuration
Sub-agents are defined in your config.toml under [agents] sections. Each agent gets its own name, system prompt, tool access and optionally a different AI provider or model:
[agents.coder]
system_prompt = "You are a coding assistant. Focus on writing clean, well-documented code. You have access to shell and file tools."
tools = ["shell", "file", "git"]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
[agents.researcher]
system_prompt = "You are a research assistant. Search the web and summarize findings concisely."
tools = ["web_search", "http"]
provider = "openai"
model = "gpt-4o"The main agent (the default one that receives messages from your channels) delegates to these sub-agents based on the task. ZeroClaw's agent runtime evaluates the request and routes it to the best-matching sub-agent automatically, or you can instruct the main agent to "ask the coder to..." for explicit delegation.
Configurable timeouts
One of the additions in ZeroClaw v0.5.1 is configurable sub-agent timeouts. Before this, a sub-agent that hung on a long API call or an unresponsive tool could block the entire pipeline. Now you can set per-agent timeouts:
[agents.coder]
timeout_seconds = 120
[agents.researcher]
timeout_seconds = 60If a sub-agent doesn't complete within its timeout, the main agent receives a timeout error and can decide what to do: retry, try a different approach, or report the failure to the user. For agents that do heavier work (running tests, building projects), set longer timeouts. For quick-response agents, shorter timeouts prevent the user from waiting when something goes wrong.
Tool isolation between agents
Each sub-agent can have its own tool set. This is both a feature and a security measure. Your researcher agent doesn't need shell access, and your coder agent probably shouldn't be sending emails. By scoping tools per agent, you limit what each one can do.
The tools array in each agent config specifies which tools that agent can use. If a tool isn't listed, the agent can't invoke it. The main agent retains access to all tools by default (unless you restrict it too), which makes sense because it's the coordinator that decides how to route tasks.
If you're concerned about agent tool access from a security perspective, the secrets management guide has broader advice on controlling what your AI agents can access. The principles apply across both OpenClaw and ZeroClaw deployments.
Monitoring agent activity
When multiple agents are running, it helps to see what each one is doing. The zeroclaw status command shows active agents and their current state. If you've enabled the Prometheus metrics endpoint on the gateway, you can track per-agent request counts and latencies:
curl http://127.0.0.1:42617/metrics | grep zeroclaw_requestsThe metrics include labels for agent name and status, so you can build Grafana dashboards that show each sub-agent's activity separately. The production guide covers Prometheus and log collection in more detail.
Multi-agent with local models
Here's where things get interesting on a budget. You can mix cloud and local providers across agents. Use a cheap local model via Ollama for the main agent (handling simple questions and routing), and route complex tasks to sub-agents using cloud providers. This way you only pay API costs for the tasks that genuinely need a larger model.
# Main agent uses local model (free)
default_provider = "ollama"
default_model = "llama3.1:8b"
# Sub-agent uses cloud model (pay per use)
[agents.analyst]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
tools = ["web_search", "file"]The main agent handles the 80% of requests that a local model can deal with, and escalates the 20% that need deeper reasoning to Claude. In practice, this can reduce API costs by 60-80% compared to running everything through a cloud provider.
