Concurrency & Limits

+15 Mana ✨
OpenClaw Concurrency Limits(DOCUMENTATION)OpenClaw Rate Limiting(DOCUMENTATION)

Introduction

Multi-agent orchestration comes with hard constraints that you must understand to build reliable systems. OpenClaw enforces limits on concurrent runs, active children per session, session lifetime, and tool availability for sub-agents. This lesson covers every limit and explains the reasoning behind each constraint.

Key Concepts

  • 8 Concurrent Sub-Agent Runs: The maximum number of spawned sessions executing simultaneously across the entire Gateway
  • 5 Active Children Per Session: The maximum number of child sessions a single parent can have running at once
  • 60-Minute Auto-Archival: Idle sub-agent sessions are automatically archived after 60 minutes of inactivity
  • Tool Restrictions: Sub-agents have access to a subset of tools compared to the parent agent
  • Rate Limit Awareness: Each sub-agent turn counts against your API provider's rate limits

Real World Context

A DevOps team sets up an orchestrator that spawns 10 workers to audit 10 microservices simultaneously. The first 8 workers start executing, but workers 9 and 10 are queued because the Gateway's concurrent limit is 8. Meanwhile, the team discovers that some workers cannot access the SSH tool because it is restricted for sub-agents. Understanding these limits upfront would have saved them debugging time.

Deep Dive

Concurrent Run Limit

The Gateway allows a maximum of 8 sub-agent sessions running at the same time:

json
{
  "agents": {
    "defaults": {
      "maxConcurrentSubAgents": 8
    }
  }
}

If you spawn a 9th session while 8 are running, it enters a queue and starts when a slot becomes available. This limit prevents resource exhaustion and ensures fair API usage across all agents.

Active Children Per Session

A single parent session can have at most 5 active children:

json
{
  "limits": {
    "maxActiveChildrenPerSession": 5
  }
}

This means if your coordinator tries to spawn a 6th worker, the spawn call will block until one of the existing 5 children completes. Design your task decomposition to work within this limit, or stagger spawns by waiting for some workers to finish before spawning more.

Auto-Archival

Sub-agent sessions that sit idle for 60 minutes are automatically archived:

json
{
  "sessions": {
    "subAgentIdleTimeoutMinutes": 60
  }
}

An archived session's state is preserved but the session is no longer active. If the parent tries to interact with an archived child, it receives an error. This prevents resource leaks from abandoned sub-agent sessions.

Tool Restrictions for Sub-Agents

Sub-agents do not automatically inherit all parent tools. Certain tools are restricted by default:

json
{
  "agents": {
    "subAgentToolRestrictions": {
      "denied": ["ssh-executor", "database-admin", "sessions_spawn"],
      "allowed": ["code-analyzer", "file-reader", "web-search"]
    }
  }
}

Notice that sessions_spawn itself is in the denied list for depth-2 workers (since they cannot spawn further children). Powerful tools like SSH and database admin are also restricted by default to prevent sub-agents from performing dangerous operations unsupervised.

Rate Limit Considerations

Each sub-agent turn counts against your API provider's rate limits:

bash
# 8 concurrent sub-agents, each making 1 API call per second
# = 8 requests/second against your rate limit
# If your limit is 10 req/s, only 2 req/s remain for interactive use

This calculation shows why the concurrent limit matters. High sub-agent concurrency can starve interactive sessions of API capacity. Monitor your rate limit usage and adjust concurrency accordingly.

Common Pitfalls

  • Ignoring the 5-child limit during orchestration: Designing a coordinator that needs 10 parallel workers will fail at the 6th spawn. Plan for batching.
  • Not accounting for sub-agent API usage in rate limits: Sub-agents share the same rate limits as your interactive sessions.
  • Letting idle sub-agents accumulate: Without monitoring, idle sessions consume memory until the 60-minute archival kicks in.

Best Practices

  • Design task decomposition to fit within 5 concurrent children per coordinator to avoid queuing delays.
  • Monitor rate limit consumption when running multiple sub-agents to prevent starving interactive sessions.
  • Set appropriate runTimeoutSeconds on all spawns to prevent sessions from running longer than necessary.

Summary

  • Maximum 8 concurrent sub-agent sessions across the entire Gateway
  • Maximum 5 active children per parent session
  • Idle sub-agent sessions are auto-archived after 60 minutes
  • Sub-agents have restricted tool access compared to parent agents
  • All sub-agent turns count against your API provider's rate limits
✓ Completed