openclaw - 💡(How to fix) Fix feat: expose hooks.maxConcurrentRuns config for parallel webhook agent execution [1 participants]

Problem

All hook-dispatched agent runs (action: "agent" in hooks.mappings) serialize on a shared "nested" global lane with maxConcurrent: 1. Even when each webhook event has a unique sessionKey (via transform overrides), only one hook agent can execute at a time — the rest queue behind it.

This is a significant bottleneck for webhook-driven agentic workflows where multiple events (e.g., GitHub project board status changes for different issues) arrive close together. In our case, planning issue A blocks coding issue B blocks reviewing issue C, even though they are completely independent.

Root Cause

dispatchAgentHook → runCronIsolatedAgentTurn(lane: "cron") → runEmbeddedPiAgent(lane: resolveNestedAgentLane("cron")) → global lane resolves to "nested".

The "nested" lane is created by getLaneState() with the default maxConcurrent: 1 and is never configured via setCommandLaneConcurrency.

Meanwhile, the "cron", "main", and "subagent" lanes all have config knobs:

// gateway-cli startup
setCommandLaneConcurrency(CommandLane.Cron, cfg.cron?.maxConcurrentRuns ?? 1);
setCommandLaneConcurrency(CommandLane.Main, resolveAgentMaxConcurrent(cfg));
setCommandLaneConcurrency(CommandLane.Subagent, resolveSubagentMaxConcurrent(cfg));
// CommandLane.Nested — not configured, defaults to 1

Proposed Fix

Add a config knob for the nested lane concurrency, following the same pattern as cron.maxConcurrentRuns:

setCommandLaneConcurrency(CommandLane.Nested, cfg.hooks?.maxConcurrentRuns ?? 1);

And add the corresponding schema entry:

hooks.maxConcurrentRuns:
  type: number
  default: 1
  help: "Maximum number of hook-dispatched agent runs that can execute concurrently on the nested lane."

This is a one-line fix in the gateway startup path (plus the schema definition), backward-compatible (defaults to 1), and follows the existing pattern.

Current Workaround

We wrote a custom gateway:startup internal hook that imports setCommandLaneConcurrency from the dist bundle and calls it manually:

import { ed as setCommandLaneConcurrency } from "openclaw/dist/pi-embedded-BaSvmUpW.js";
setCommandLaneConcurrency("nested", 3);

This works but is fragile — the hashed filename and minified export alias change between releases.

Environment

• OpenClaw 2026.3.24
• Webhook-driven agentic workflow with 3 hook mappings (planning, coding, review)
• Dynamic session keys via transform overrides (confirmed working — sessions are separate, but execution still serializes)

Impact

Any user running webhook-driven agent workflows with multiple concurrent events hits this bottleneck. The session-level isolation works correctly, but the global nested lane prevents actual parallel execution.