What does `allowAgents: ["*"]` mean?

Setting `allowAgents` to `["*"]` in your `agents.defaults.subagents` configuration means that any agent ID is permitted to be spawned as a sub-agent. You can also specify a list of specific agent IDs, like `["agent1", "agent2"]`, to restrict sub-agent spawning to only those listed.

My config validates, but `sessions_spawn` still fails. What else could it be?

If your config validates successfully, the issue might be that the `sessions_spawn` tool itself is not enabled in your `tools.allow` list, or there's a separate permissions issue with the specific agent trying to spawn. Double-check that `sessions_spawn` is explicitly allowed in your agent's configuration and that the agent has the necessary permissions to create sub-agents.

Which OpenClaw versions are affected?

The issue seems to affect versions around OpenClaw 2026.2.3-1 and later, as indicated in GitHub issue #10031. Users have reported it persists in later patch releases as well. Updating your schema is the key regardless of the minor version.

Fix OpenClaw `sessions_spawn` Blocked by Config Schema Mismatch

TL;DR — Quick Fix

Your OpenClaw config schema is missing the `allowAgents` field in `agents.defaults.subagents`, causing `sessions_spawn` to fail. Add this field to your schema.

Run Diagnostics

Next Step

Fix now, then reduce repeat incidents

If this issue keeps coming back, validate your setup in Doctor first, then harden your config.

Open Doctor Harden Config

Error Signal

agentId is not allowed for sessions_spawn (allowed: none)

What's Happening

The sessions_spawn tool in OpenClaw is failing because your configuration schema doesn't recognize the allowAgents key within agents.defaults.subagents. The runtime code expects this key to control which sub-agents can be spawned, but the schema validation rejects it as an unknown field. This breaks all multi-agent functionality that relies on spawning.

The Fix

Update your OpenClaw configuration schema definition to include allowAgents within the agents.defaults.subagents section. The allowAgents field should be an array of strings, where each string is an allowed agent ID. Use ["*"] to allow any agent ID.

Here's how your schema should look:

{
  "agents": {
    "defaults": {
      "subagents": {
        "maxConcurrent": 8,
        "allowAgents": ["*"] // Or specific agent IDs like ["agent1", "agent2"]
      }
    }
  }
}

This addition tells the schema validator that allowAgents is a valid field, resolving the mismatch. Ensure your gateway or relevant service picks up this updated schema.

Why This Occurs

This problem happens when the runtime code for sessions_spawn has been updated to use a new configuration option (allowAgents), but the corresponding JSON schema used for validation hasn't been updated to match. The runtime logic reads the allowAgents value to check permissions, but the validator rejects the configuration before it even gets to that logic because the schema is out of date. The schema and runtime are out of sync.

Prevention

Always ensure your configuration schema files are up-to-date with the version of OpenClaw you are running. Keep an eye on release notes for new configuration options. Regularly run validation checks against your configuration files using the schema to catch these discrepancies early. If you are managing your own schema, integrate it into your CI/CD pipeline to automatically validate configurations before deployment.

Last Updated: March 2026

Did this guide solve your problem?