#8361: docs: Add subagent configuration and allowlist guide
docs
stale
This documentation guides users on how to configure the policy in to resolve the error. It provides clear examples for allowing all or specific agents. This was based on a real-world use case during a security audit.
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
Adds a new documentation page describing how to resolve the `sessions_spawn` “agentId is not allowed” forbidden error by configuring sub-agent spawning permissions in the OpenClaw config.
The guide introduces an allowlist concept with examples for allowing any sub-agent vs restricting to specific agent ids, plus a short troubleshooting section. This overlaps with (and should align to) the existing `/tools/subagents` documentation, which already defines the `agents.list[].subagents.allowAgents` semantics used by `sessions_spawn`.
<h3>Confidence Score: 3/5</h3>
- Mostly safe to merge, but the examples contain at least one copy/paste-breaking snippet and likely schema drift with existing docs.
- This PR only adds documentation, so runtime impact is low; however, the guide is intended to fix a real error and currently includes an invalid JSON example and introduces `allowAny` semantics that conflict with the existing documented schema (`allowAgents: ["*"]`). Those issues could cause user confusion and failed configuration changes.
- docs/concepts/subagent-configuration.md
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
**Context used:**
- Context from `dashboard` - CLAUDE.md ([source](https://app.greptile.com/review/custom-context?memory=fd949e91-5c3a-4ab5-90a1-cbe184fd6ce8))
- Context from `dashboard` - AGENTS.md ([source](https://app.greptile.com/review/custom-context?memory=0d0c8278-ef8e-4d6c-ab21-f5527e322f13))
<!-- /greptile_comment -->
Most Similar PRs
#12808: docs(subagents): clarify allowAgents is per-agent only
by JBrady · 2026-02-09
86.4%
#15852: fix: pass agentId when resolving IRC session paths
by MisterGuy420 · 2026-02-14
79.8%
#7252: docs: align config examples and tool docs with current runtime
by nice-and-precise · 2026-02-02
78.5%
#13833: Cursor/cloud agent 1770777372587 3zom0
by zhch158 · 2026-02-11
77.4%
#19560: docs: refactor agent workspace default location & bootstrap configu...
by ashinkuniyil · 2026-02-17
77.4%
#20072: feat(sessions_spawn): add sessionKey param to reuse sub-agent sessions
by Be1Human · 2026-02-18
77.2%
#9829: Fix MCP transport reconnect and SSE header handling
by mabengda · 2026-02-05
76.2%
#16362: Update session-pruning.md - updated agents.defaults config std
by elliottb · 2026-02-14
76.0%
#10514: Security: harden AGENTS.md with gateway, prompt injection, and supp...
by catpilothq · 2026-02-06
75.5%
#14734: test(agents): guard against stale allowAgents in existing sessions
by davidahmann · 2026-02-12
75.5%