My OpenClaw agent won’t spawn sub-agents

You asked your agent to delegate a task, and nothing happened. No spawned session, no result, sometimes not even an error. Sub-agent spawning fails silently in OpenClaw, and it breaks for a small set of very specific reasons. This article covers how to find which one you have and fix it.

Run this first

Before anything else, get a complete picture of what your agent can see and what the config actually says. This check covers the three most common causes in one pass.

Run openclaw status and show me the full output. Then read my openclaw.json and show me: (1) whether sessions_spawn appears in the available tools list, (2) the complete agents section of my config including any allowAgents settings, and (3) whether there is an acp section anywhere in the config. If any of these are missing or look unusual, tell me exactly what is wrong and which of the four sub-agent failure causes below is most likely.

Match what you see to the four causes below. Each one has a fix you can apply from chat.

Cause 1: allowAgents is missing or in the wrong place

The allowAgents setting controls which agent definitions a given agent is allowed to use when spawning sub-agents. Without it, the agent will not attempt a spawn regardless of what you ask it to do. No error is logged. It simply does not try.

The placement requirement is strict and not clearly documented as of March 2026. allowAgents must be inside a specific agent entry in agents.list. If you put it under agents.defaults, the gateway will fail to start with a schema validation error. If you omit it entirely, spawning is silently blocked.

Read my openclaw.json and check the agents section carefully. Is allowAgents present? If so, is it under agents.defaults or inside an agent entry in agents.list? Show me the full JSON structure of my agents config so I can see exactly where allowAgents is placed. If it is missing entirely or in the wrong location, fix it now: move it inside the agent entry in agents.list and restart the gateway.

The correct structure looks like this. allowAgents sits inside the agent object in agents.list, not at the agents.defaults level:

{
  "agents": {
    "defaults": {
      "model": "deepseek/deepseek-chat",
      "contextTokens": 200000
    },
    "list": [
      {
        "id": "main",
        "allowAgents": ["main"],
        "model": "deepseek/deepseek-chat"
      }
    ]
  }
}

Setting allowAgents: ["main"] on an agent allows it to spawn sub-agents that run using the same main agent definition. If you have multiple agent definitions and set different allowAgents arrays on each, each agent can only spawn the specific definitions listed in its own array. There is no inheritance between agent definitions. To spawn sub-agents using a different agent definition, add that agent’s ID to the array and create a matching entry in agents.list.

Cause 2: sessions_spawn not in the available tools list

The sessions_spawn tool is what the agent actually calls to create a sub-agent session. If it is not in the available tools list, the agent has no mechanism to spawn anything. This can happen if the agent has a restricted tool policy that omits it, if a plugin is filtering the tool list, or if you are on an OpenClaw version older than 2026.2.0 where the tool name differed.

Show me the complete list of available tools for my current agent. Is sessions_spawn listed? If not, check my openclaw.json for any tool restrictions or allowlists under the agents section. Also check whether any installed plugin has a configuration that could be filtering or blocking tools. Tell me exactly what is preventing sessions_spawn from appearing and how to fix it.

If sessions_spawn is blocked by a tool allowlist, add it to the list for that agent. If a plugin is filtering it out, check the plugin’s config for a tools.block or tools.allow setting and update it.

Cause 3: The model does not construct sub-agent tool calls reliably

Sub-agent spawning requires the model to correctly construct a sessions_spawn tool call with the right schema. Not all models do this reliably. Smaller local models frequently drop required parameters, pass the wrong types, or produce the tool call as plain text description rather than an actual structured call. The result is silence: the agent appears to acknowledge the request but no sub-agent appears.

As of March 2026, the community has identified the following patterns: DeepSeek v3 handles single-step sub-agent spawns correctly but occasionally fails on complex nested orchestration; phi4 and llama3.1:8b will attempt the call but frequently malform the task parameter in ways that fail at the gateway level without returning an error to the model.

What model am I currently using? Try a test sub-agent spawn right now. Spawn a sub-agent with this exact task: “Reply with the single word WORKING.” Tell me whether the spawn succeeded, what the sub-agent responded, and whether you had any difficulty constructing the tool call. If it failed, show me the exact error.

If the test fails with a schema error or produces no output, the issue is the model. Switch to DeepSeek v3 (deepseek/deepseek-chat) or Sonnet (anthropic/claude-sonnet-4-6) for the session and run the test again.

Override the model for this session to deepseek/deepseek-chat and run the sub-agent test again: spawn a sub-agent with task “Reply with the single word WORKING.” Did the spawn succeed? If yes, the original model was the problem and I need to configure a more capable model for any workflows that use sub-agents. Tell me how to set deepseek/deepseek-chat as my default model in openclaw.json.

Cause 4: ACP harness misconfiguration (runtime: “acp”)

If you are using runtime: "acp" in your sessions_spawn calls to run coding agents like Codex or Claude Code as sub-agents, there are requirements beyond the base allowAgents setting. The ACP harness requires an agentId parameter pointing to a valid ACP agent entry, and the acp.allowedAgents list in your config must include that agent ID. Missing either will cause the spawn to fail with a different error than the standard sub-agent flow.

I am trying to spawn a sub-agent using runtime: “acp”. Read my openclaw.json and check: (1) Is there an acp section in my config? (2) Does it have an allowedAgents list? (3) Is the agentId I am using in the sessions_spawn call present in that list? Show me the full acp section and tell me what is missing or wrong.

If the acp section is missing entirely, you need to configure it before ACP sub-agent spawning will work. The minimum required structure is:

{
  "acp": {
    "defaultAgent": "main",
    "allowedAgents": ["main", "your-coding-agent-id"]
  }
}

Verifying sub-agent spawning works end to end

After applying any fix, run a full end-to-end test before relying on sub-agents in a real workflow. The test below confirms that spawning, execution, and result return are all working correctly.

Run a full sub-agent test. Do the following in order: (1) Spawn a sub-agent with task “Count to three and reply with the three numbers separated by commas.” (2) Wait for the result and show me the sub-agent’s response. (3) Spawn a second sub-agent with task “Read the file at /home/node/.openclaw/workspace/HEARTBEAT.md and summarize it in one sentence. If the file does not exist, reply with NOT FOUND.” (4) Show me both results and confirm that sub-agent spawning is working correctly end to end.

If both tests return correct results, sub-agent spawning is fully operational. If the first succeeds but the second fails, the issue is likely a permissions or workspace access problem specific to file operations in sub-agents, not a spawning problem. If both fail, the fix did not take effect and you need to restart the gateway and recheck the config.

Common mistakes that cause silent failures after the fix

These are the patterns that send operators back to this article after thinking they already fixed the problem.

Restarting the session instead of the gateway. Config changes in openclaw.json are read at gateway startup, not at session start. Starting a new chat does not pick up the change. You must restart the gateway process for allowAgents changes to take effect.

Setting allowAgents to an empty array. "allowAgents": [] is valid JSON but blocks all spawning. It is equivalent to not setting it at all. The value must contain at least one agent ID string.

Spawning with a model that is not in your providers list. If the model parameter in your sessions_spawn call points to a provider or model that is not configured in models.providers, the sub-agent will fail to initialize. The error appears in the gateway log but is not returned to the calling agent. Check that any model specified in the spawn call is present and has a valid API key.

Check my openclaw.json for any common sub-agent config mistakes: (1) Is allowAgents set to an empty array anywhere? (2) Are all models I use in sessions_spawn calls present in models.providers with valid API keys? (3) Was the gateway restarted after the most recent config change, or is the running config possibly stale? Report any issues you find.

Frequently asked questions

The model described the tool call in plain text instead of making an actual structured call. This is a model reliability issue and is most common with smaller local models. The agent is narrating what it would do rather than doing it. Switch to a more capable model for orchestration tasks and run the test spawn command above.

Yes. The model parameter in sessions_spawn sets the model for that specific sub-agent session independently of the calling agent’s model. This is the recommended pattern: use DeepSeek v3 or Sonnet for orchestration, route sub-agents to local models like phi4 for the delegated tasks themselves.

OpenClaw does not enforce a hard cap on concurrent sub-agents as of March 2026, but each sub-agent consumes memory and API tokens. On a 1GB VPS running a local model, two to three concurrent sub-agents is typically the practical limit before you see performance degradation. On a 4GB instance with API model routing, ten or more concurrent sub-agents is feasible for light tasks.

No. Sub-agents are isolated sessions. They do not inherit the calling agent’s skills, memory, or context. If you need a sub-agent to use a specific skill, it must be installed at the agent level in the config using an agent definition that includes that skill. See the related article on sub-agent skill access for the full setup.

Yes, if the sub-agent’s agent definition also has allowAgents configured. There is no depth limit enforced by OpenClaw, but recursive spawning without a termination condition will run until you hit a token or cost limit. Always include a stopping condition in any agent that is allowed to spawn sub-agents.

The default sub-agent timeout is 30 seconds. Long tasks (web research, multi-step file operations, code generation) frequently exceed this. Set runTimeoutSeconds in the sessions_spawn call to a higher value. For tasks with no predictable runtime, set it to 0 (no timeout). Monitor cost when doing this on API models.

Yes. The gateway log records spawn attempts, failures, and sub-agent session IDs. Ask your agent to read the last 50 lines of the gateway log and filter for spawn-related entries. Failed spawns log the reason at the ERROR level, which is the fastest way to diagnose a spawn problem that is not covered by the four causes above.

What allowAgents actually controls

The allowAgents setting is a security boundary, not just a feature toggle. When you set allowAgents: ["main"] on an agent, you are explicitly telling OpenClaw: this agent is permitted to create new sessions running under the main agent definition. Without this explicit permission, the gateway blocks the spawn attempt before it reaches the model. The model never even attempts the tool call.

This design is intentional. An agent with unrestricted spawning ability could, in theory, create hundreds of sub-agents that consume API tokens at scale. The allowlist prevents runaway costs from misconfigured automation. It also prevents a compromised or manipulated agent from escalating its own capabilities by spawning agents with different permissions.

The boundary works at the agent definition level, not the session level. If you have two agent definitions in agents.list (for example, main and worker), an agent running as main can only spawn sub-agents using the definitions listed in its allowAgents array. It cannot spawn a worker unless "worker" is in that array. This matters when you are building specialized sub-agent workflows where different agent definitions have different tool access or model assignments.

Show me all agent definitions in my openclaw.json agents.list. For each one, show me: the agent ID, the model assigned to it, what allowAgents is set to, and whether it has any tool restrictions. I want a complete picture of my agent topology so I can understand which agents can spawn which others.

Using the gateway log to debug spawn failures

When sub-agent spawning fails, the gateway log is the most reliable source of truth. The gateway records spawn attempts at the DEBUG level and failures at the ERROR level. If your agent appears to be trying to spawn but nothing appears in your session list, the log will tell you exactly why the spawn was rejected. If the log shows no spawn attempt at all, the model never called the sessions_spawn tool. This is Cause 3 (model reliability), not a config problem. The fix is a more capable primary model, not a config change.

Read the last 100 lines of the OpenClaw gateway log and show me any entries related to sub-agent spawning, sessions_spawn calls, or allowAgents errors. The log is typically at /var/log/openclaw/gateway.log or accessible via journalctl -u openclaw –no-pager -n 100. If you cannot find the log, try running: journalctl -u openclaw -n 100 –no-pager and show me the output.

Common error patterns in the log and what they mean:

• “allowAgents not configured for agent main”: The allowAgents field is missing from the agent entry. Add it as described in Cause 1 above.
• “agent id not in allowAgents”: The agent ID specified in the sessions_spawn call is not in the allowAgents array. Add it.
• “sessions_spawn: tool not available”: The tool is not in the agent’s tool list. Check for tool restrictions in the agent config.
• “schema validation error”: The sessions_spawn call from the model had missing or wrong-type parameters. This is a model reliability issue. Switch to a more capable model.
• “ACP agent id not in allowedAgents”: ACP-specific error. The agentId in the runtime: “acp” call is not in acp.allowedAgents. Add it.

Thread-bound sub-agents and when to use them

When you spawn a sub-agent on Discord, you have the option to make it thread-bound by setting thread: true in the sessions_spawn call. Thread-bound sub-agents create a new Discord thread and post their output there, keeping the conversation organized when multiple sub-agents are running on the same channel. Non-thread-bound sub-agents return their output to the calling session.

Thread-bound sessions use mode: "session" and are persistent: they stay open until explicitly closed. This is the recommended pattern for coding agent workflows where you want to review and continue the work across multiple turns. Non-thread-bound sub-agents use mode: "run" by default and terminate when the task completes.

I want to spawn a sub-agent that creates a Discord thread and posts its work there. What does the correct sessions_spawn call look like for a thread-bound sub-agent on Discord? Show me the exact parameters I need, including thread: true, mode: “session”, and any other required fields. Then spawn a test thread-bound sub-agent with task “Say hello and confirm you are running in a thread.”

Cost management for sub-agent workflows

Each sub-agent session is a separate API call stream. If you are using paid API models (DeepSeek, Sonnet, Opus), every sub-agent runs up its own token bill independently of the calling session. A workflow that spawns five sub-agents doing research tasks can cost five to ten times as much as a single session doing the same work sequentially. Before building multi-agent workflows, understand the cost model.

Three practices that keep sub-agent costs manageable:

Route sub-agents to local models for the actual work. The calling agent (orchestrator) needs a capable model to construct the sessions_spawn call correctly. The sub-agents doing the delegated tasks often do not. If a sub-agent is summarizing a file, running a script, or formatting output, phi4 or llama3.1:8b will handle it for zero API cost. Set the model parameter in sessions_spawn to a local model for those tasks.

Set runTimeoutSeconds explicitly. The default timeout is 30 seconds. If a sub-agent hits a long task and exceeds the timeout, it terminates without returning a result. The calling agent may retry, doubling the cost. Set a timeout that matches the expected task duration and build in a retry limit so runaway costs do not accumulate silently.

Use sessions_yield when orchestrating multiple sub-agents. If you spawn several sub-agents and then poll for their results in a loop, each poll turn costs tokens. The sessions_yield pattern ends the calling session’s turn and waits for push notification when sub-agents complete. It is the cost-efficient alternative to polling and is the recommended pattern for any workflow that spawns more than one sub-agent at a time.

I want to set up a sub-agent workflow that uses local models for the delegated tasks to minimize API cost. Show me the correct sessions_spawn call to spawn a sub-agent using ollama/phi4:latest as its model. Then estimate the cost difference between running a 5-sub-agent research workflow entirely on deepseek/deepseek-chat versus running the orchestrator on deepseek/deepseek-chat and the 5 sub-agents on ollama/phi4:latest.

sessions_spawn parameter reference

Understanding the full parameter set for sessions_spawn helps you build more reliable sub-agent workflows and diagnose failures faster. These are the parameters that matter most in practice.

task (required): The prompt the sub-agent receives. Write this as a complete, self-contained instruction. Sub-agents do not inherit context from the calling session, so the task must include everything the sub-agent needs to know. If the task references a file, include the full path. If it needs to know a URL, include the URL. Vague tasks produce vague results.

runtime: Defaults to "subagent". Use "acp" for coding agents (Codex, Claude Code). The runtime determines which spawning pathway the gateway uses and which config sections are checked for permissions.

mode: "run" (default) for one-shot tasks that terminate on completion. "session" for persistent sessions that stay open for continued interaction. Use "session" with thread: true for coding agent workflows.

model: Overrides the model for the sub-agent session. If omitted, the sub-agent uses the model specified in its agent definition in agents.list. Explicitly setting this is the recommended practice for cost control.

agentId: Required when using runtime: "acp". Must match an ID in acp.allowedAgents. For standard sub-agents, the agent definition used is determined by allowAgents in the calling agent’s config.

runTimeoutSeconds: Maximum runtime in seconds before the sub-agent session is terminated. Set to 0 for no timeout. Defaults to 30 seconds if not specified. Always set this explicitly for any task with a known duration.

streamTo: Set to "parent" to stream the sub-agent’s output to the calling session in real time instead of waiting for completion. Useful for long tasks where you want visibility into progress. Has a small additional cost in tokens due to streaming overhead.

Show me the exact sessions_spawn call I would use to: spawn a sub-agent using ollama/phi4:latest, with a 5-minute timeout, running a one-shot task. The task is: “Read /home/node/.openclaw/workspace/HEARTBEAT.md and return its full contents. If the file does not exist, return NOT FOUND.” Include all required parameters in the tool call.

Common multi-agent patterns that work in OpenClaw

Once spawning is working, these are the patterns operators use most often in production. Each one solves a real workflow problem.

Research and synthesize. Spawn three to five sub-agents, each with a different search query or data source. The calling agent waits for all results, then synthesizes them into a single output. This parallelizes research that would otherwise take multiple sequential turns.

Generate and review. Spawn a sub-agent to generate a draft (article, code, plan). The calling agent receives the draft and either publishes it directly or reviews it before passing back for revision. Separates generation from review, which reduces context pollution in both agents.

Triage and route. A lightweight calling agent (cheap model, low timeout) reads inbound messages or tasks and routes each one to a specialized sub-agent based on content. The routing agent itself does minimal work. The sub-agents do the heavy lifting. Total cost is lower than running everything through a single high-capability model.

Checkpoint and continue. For tasks that exceed context limits, spawn a sub-agent, have it work until it produces a checkpoint file, terminate it, then spawn a new sub-agent starting from the checkpoint. Effectively provides unlimited context for long-running tasks without the cost of a very large context window.

I want to set up a research-and-synthesize workflow. Spawn three sub-agents in parallel, each searching for a different angle on the topic “OpenClaw security best practices in 2026.” Use ollama/phi4:latest for each sub-agent to minimize cost. Set a 3-minute timeout on each. Once all three complete, synthesize their findings into a single summary of no more than 300 words.

Pre-launch checklist for sub-agent workflows

Before deploying a sub-agent workflow into production use, run through this checklist. Each item represents a failure mode that has been reported in the OpenClaw community as of March 2026.

• allowAgents is in agents.list, not agents.defaults: Verify the placement before every new deploy. This is the most common mistake and it fails silently.
• sessions_spawn is in the available tools list: Run the diagnostic blockquote above to confirm. Do not assume it is there because it worked before a gateway restart or plugin update.
• The orchestrating agent’s model can construct sessions_spawn calls: Run the test spawn (single word “WORKING”) before deploying the real workflow. If the test fails, the real workflow will fail the same way.
• runTimeoutSeconds is set explicitly on every spawn call: No sub-agent should rely on the 30-second default. Set it to match the task. If the task duration is unknown, set it to 0 and monitor the first run.
• Sub-agent tasks are self-contained: Each task should include every piece of information the sub-agent needs. No implicit context from the calling session is available inside the sub-agent.
• Cost is estimated before running: Know which models your sub-agents will use and roughly how many tokens each task will consume. Surprise API bills from multi-agent workflows are a real and common problem.
• The gateway was restarted after the last config change: Config changes are not live until the gateway restarts. If you changed allowAgents or any agent definition today, confirm the restart happened.

Run a pre-launch check for my sub-agent setup. Check all of the following and report pass or fail for each: (1) allowAgents is present and placed inside agents.list (not agents.defaults). (2) sessions_spawn is in the available tools list. (3) The current model has successfully constructed a sessions_spawn tool call in this session. (4) The gateway was restarted after the most recent config change. Summarize what is ready and what still needs to be fixed.

What to do after spawning works

Once the test spawn is passing and sub-agents are appearing in your sessions list, the next step is to build the workflow you actually wanted. A few things that will save you debugging time as you do that:

Use sessions_list to monitor active sub-agents after every spawn. Ask your agent to list running sessions and show you their status after spawning. This confirms the sub-agent is actually running and not silently failing post-spawn. A sub-agent that fails during initialization may not produce any output to the calling session, so checking the sessions list is the only way to know whether it started at all.

Use sessions_history to retrieve what a sub-agent did. If a sub-agent completes but you want to review its work, ask your agent to fetch the session history for that sub-agent’s session key. You get the full turn-by-turn log of what it did and what it produced.

Use subagents(action=kill) if something goes wrong mid-run. If a sub-agent is looping, consuming tokens, or stuck, your calling agent can kill it by session key. This is faster and cheaper than waiting for the timeout to expire. The kill takes effect immediately and the token consumption stops as soon as the gateway processes the request, which is typically within one second on a local install.

Show me the sessions list for this workspace. List any active or recently completed sub-agent sessions, including their session key, current status, the model they are running, and the first line of their last message. If there are any sessions that appear stuck or have been running longer than 10 minutes without producing output, flag them explicitly and ask me whether I want to kill them or let them continue.

Keep Reading: