openclaw - 💡(How to fix) Fix feat: configurable CommandLane.Nested concurrency — unblock parallel hook/cron/sessions_send execution [1 participants]

Summary

The CommandLane.Nested lane is hardcoded to maxConcurrent: 1 with no configuration surface. All webhook hook sessions (/hooks/agent), cron isolated agent runs, and sessions_send inter-agent calls route through this lane, meaning only one can execute at a time across the entire gateway.

This creates severe serialization bottlenecks for any deployment using webhooks or cron jobs at scale — queue backlogs grow linearly with the number of concurrent events, and sessions_send calls from cron/hook context deadlock because the caller holds the single Nested slot while the target session waits for it.

Root Cause

applyGatewayLaneConcurrency() configures concurrency for Main, Cron, and Subagent lanes but omits Nested entirely:

function applyGatewayLaneConcurrency(cfg) {
  setCommandLaneConcurrency(CommandLane.Cron, cfg.cron?.maxConcurrentRuns ?? 1);
  setCommandLaneConcurrency(CommandLane.Main, resolveAgentMaxConcurrent(cfg));
  setCommandLaneConcurrency(CommandLane.Subagent, resolveSubagentMaxConcurrent(cfg));
  // Missing: setCommandLaneConcurrency(CommandLane.Nested, ???);
}

Additionally, resolveNestedAgentLane() routes cron and hook work to CommandLane.Nested regardless of the lane parameter sent by the caller. Even when a webhook connector sends lane: "main", the gateway's normalizeAgentPayload() extracts only 11 fields and drops the lane field, so hook sessions always fall back to Nested.

Steps to Reproduce

# Create multiple cron jobs that fire simultaneously
for i in 1 2 3 4 5 6 7 8; do
  openclaw cron create \
    --name "test-lane-$i" \
    --cron "30 18 * * *" \
    --agent main \
    --session isolated \
    --message "Write a short response." \
    --no-deliver --exact --timeout-seconds 120
done

# Trigger all at once
for id in $(openclaw cron list | grep "test-lane" | awk '{print $1}'); do
  openclaw cron run "$id" &
done
wait

All 8 jobs serialize through Nested lane — total wall time ~120s instead of ~15s.

For sessions_send deadlock: have a cron job call sessions_send to another session. The target can never execute because the caller holds the only Nested slot.

Suggested Fix

Make nested lane concurrency configurable, consistent with existing lane config patterns:

{
  "agents": {
    "defaults": {
      "nestedMaxConcurrent": 8
    }
  }
}

And in applyGatewayLaneConcurrency():

setCommandLaneConcurrency(
    CommandLane.Nested,
    cfg.agents?.defaults?.nestedMaxConcurrent ?? 4
);

Session-level serialization (enqueueSession) already prevents concurrent access to the same session, so increasing nested lane concurrency is safe for independent jobs.

Also: normalizeAgentPayload() should preserve the lane field from webhook payloads so callers can target the intended lane.

Workaround

Patching the bundled JS to add the missing setCommandLaneConcurrency(CommandLane.Nested, N) call. Must be re-applied after every update.

Related Issues

• #52682 — cron isolated agent runs serialize on nested lane
• #52271 — sessions_send from cron/heartbeat deadlocks on nested lane
• #55516 — hooks.maxConcurrentRuns config request
• #14214 — original nested lane maxConcurrent: 1 report (closed)
• #22167 — configurable nested lane concurrency feature request (closed)
• #45165 — sessions_send nested lane serialization

Environment

• OpenClaw: latest (2026.3.x)
• OS: Ubuntu 24.04 ARM64
• Node.js: v22.22.x