Bug: sessions_spawn blocked by config schema mismatch

Version: OpenClaw 2026.2.3-1 (d84eb46)
Platform: macOS (Homebrew installation)
Severity: High - Blocks core multi-agent functionality

Description

The sessions_spawn tool is completely blocked due to a mismatch between the runtime code and config schema. The code expects agents.defaults.subagents.allowAgents but the config validation rejects this key as unrecognized.

Error message:

agentId is not allowed for sessions_spawn (allowed: none)

Expected Behavior

Agents should be able to spawn sub-agents when configured with:

{
  "agents": {
    "defaults": {
      "subagents": {
        "maxConcurrent": 8,
        "allowAgents": ["*"]
      }
    }
  }
}

Where:

• "allowAgents": ["*"] = Allow spawning any agent ID
• "allowAgents": ["agent1", "agent2"] = Allow specific agent IDs only

Actual Behavior

1. Agent attempts to use sessions_spawn tool
2. Receives error: agentId is not allowed for sessions_spawn (allowed: none)
3. Attempting to configure allowAgents fails with schema validation error
4. Multi-agent workflows are completely blocked

Root Cause

Runtime code expects allowAgents:

Location: /opt/homebrew/lib/node_modules/openclaw/dist/loader-BAZoAqqR.js

const allowAgents = resolveAgentConfig(cfg, requesterAgentId)?.subagents?.allowAgents ?? [];
const allowAny = allowAgents.some((value) => value.trim() === "*");
const allowSet = new Set(
  allowAgents
    .filter((value) => value.trim() && value.trim() !== "*")
    .map((value) => normalizeAgentId(value).toLowerCase())
);
if (!allowAny && !allowSet.has(normalizedTargetId)) {
  return jsonResult({
    error: `agentId is not allowed for sessions_spawn (allowed: ${
      allowAny ? "*" : allowSet.size > 0 ? Array.from(allowSet).join(", ") : "none"
    })`
  });
}

Config schema rejects allowAgents:

$ openclaw config set agents.defaults.subagents.allowAgents '["*"]'
Error: Config validation failed: agents.defaults.subagents: Unrecognized key: "allowAgents"

Current schema only allows maxConcurrent:

$ openclaw config get agents.defaults.subagents
{
  "maxConcurrent": 8
}

Steps to Reproduce

1. Install OpenClaw 2026.2.3-1
2. Set up an agent
3. Attempt to use sessions_spawn in agent code
4. Observe error: agentId is not allowed for sessions_spawn (allowed: none)
5. Try to configure allowAgents:

   openclaw config set agents.defaults.subagents.allowAgents '["*"]'

6. Observe config validation error

Attempted Workarounds

❌ CLI Config Command

openclaw config set agents.defaults.subagents.allowAgents '["*"]'

Result: Config validation failed: Unrecognized key: "allowAgents"

❌ Manual JSON Edit

Edited ~/.openclaw/openclaw.json to add:

"subagents": {
  "maxConcurrent": 8,
  "allowAgents": ["*"]
}

Result: Gateway refuses to start:

Invalid config at ~/.openclaw/openclaw.json:
- agents.defaults.subagents: Unrecognized key: "allowAgents"

Impact

High Priority - This completely blocks a core OpenClaw feature:

• ❌ Cannot spawn specialized sub-agents
• ❌ Multi-agent workflows impossible
• ❌ Cannot replicate documented patterns (e.g., @pbteja1998's multi-agent setup)
• ❌ Severely limits autonomous agent productivity

Affected Users:

• Anyone trying to use sessions_spawn tool
• Users building multi-agent architectures
• Developers following autonomous agent patterns

Environment

OpenClaw Version: 2026.2.3-1 (d84eb46)
Installation: Homebrew (/opt/homebrew/lib/node_modules/openclaw)
OS: macOS
Agent: main (Scout)
Node.js: (from Homebrew)

Proposed Fix

Option 1: Update Config Schema (Recommended)

Add allowAgents as a recognized key in the config schema:

// In config schema definition
subagents: {
  maxConcurrent?: number;
  allowAgents?: string[];  // ← ADD THIS
}

Option 2: Update Runtime Code

If allowAgents is deprecated, update runtime to use the correct config path that the schema supports.

Option 3: Documentation

If there's an alternative way to enable sessions_spawn, please document it clearly.

Questions

1. Is allowAgents the intended configuration key?
2. What is the proper way to enable sessions_spawn?
3. Is this feature still under active development?
4. Will the schema be updated in an upcoming release?
5. Is there a workaround we're missing?

Additional Context

From the agent's analysis:

"The error points to a system-level policy. To enable sessions_spawn, the allowAgents list needs to be updated in the core configuration file."

Related Examples:
Other users have successfully created multi-agent setups (e.g., @pbteja1998's Jarvis/Shuri/Vision architecture), suggesting this feature should work when properly configured.

Source Code Reference:
The error originates from multiple files:

• /opt/homebrew/lib/node_modules/openclaw/dist/loader-BAZoAqqR.js
• /opt/homebrew/lib/node_modules/openclaw/dist/extensionAPI.js
• /opt/homebrew/lib/node_modules/openclaw/dist/reply-DpTyb3Hh.js

All check for allowAgents but the config schema doesn't recognize it.

Current Config

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "google/gemini-2.5-pro"
      },
      "workspace": "/Users/ashok/.openclaw/workspace",
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  }
}

Labels

bug, config, high-priority, multi-agent, sessions, schema-mismatch