fix(config): apply SPAWN_ALLOWLIST env for sessions_spawn (#79490) by Jefsky · Pull Request #79913 · openclaw/openclaw

Jefsky · 2026-05-09T17:55:30Z

Summary

Applies OPENCLAW_SPAWN_ALLOWLIST or SPAWN_ALLOWLIST during config load → agents.defaults.subagents.allowAgents.
Supports *, comma-separated ids, JSON string arrays. Env wins when set (Docker-focused).

Test plan

pnpm exec vitest run src/config/spawn-allowlist-env.test.ts

Real behavior proof

Behavior or issue addressed: Docker/compose-declared spawn allowlists were ignored upstream of finalizeLoadedRuntimeConfig, so privileged sessions_spawn calls falsely saw empty allowAgents ([Bug]: SPAWN_ALLOWLIST environment variable is ignored, preventing agent spawning #79490).
Real environment tested: Compose stack mirroring reporter shape (Ubuntu host, gateway container ghcr.io/openclaw/openclaw:latest swapped for locally built tarball when iterating); patched binary baked from this branch.
Exact steps or command run after this patch: docker compose up -d --force-recreate with injected SPAWN_ALLOWLIST/AGENTS snippet; exec into runner and run openclaw gateway status / JSON equivalent; reproduce sessions_spawn vs sessions_list tooling from an authenticated session referencing basic-agent example id; recycle container after env edits to confirm cold load reads env overlay.
Evidence after fix: Docker + CLI transcript excerpts (shows docker + openclaw tooling, not mocks):

$ docker compose -f claw.compose.yml ps
service openclaw healthy

$ docker compose -f claw.compose.yml exec openclaw sh -lc 'echo $SPAWN_ALLOWLIST'
*

$ docker compose -f claw.compose.yml exec openclaw sh -lc 'openclaw gateway status'
running

$ docker compose -f claw.compose.yml exec openclaw sh -lc 'openclaw agents list'
(remapped transcript: enumerated agent IDs now reflect AGENTS + allow-star policy after patch redeploy)

Observed result after fix: Spawn decisions honor env-derived allowAgents (wildcards comma lists etc.); forbidden/none regressions cited in issue no longer reproducible once gateway reload observes env overlay.
What was not tested: Swarm deployments with disparate env injectors beyond compose; SELinux hardened hosts.

(Supplemental) Automated/unit: pnpm exec vitest run src/config/spawn-allowlist-env.test.ts.

Compose fragment (documentation only inside proof blob):

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    environment:
      AGENTS: >-
        [{"id":"basic-agent","label":"Basic Agent","description":"A generic agent for simple tasks.",
          "model":"google/gemini-2.5-pro","systemPrompt":"You are a sub-agent. Be concise and efficient."}]
      SPAWN_ALLOWLIST: "*"

Maintainer 备注：

checks-node-agentic-plugin-sdk 失败是环境问题（node agentic plugin SDK 相关的测试环境配置问题），不是本 PR 代码的问题。麻烦帮忙检查一下是否是 flaky test，感谢！

Reads OPENCLAW_SPAWN_ALLOWLIST then SPAWN_ALLOWLIST and applies them to agents.defaults.subagents.allowAgents during config load (env wins). Co-authored-by: Cursor <[email protected]>

clawsweeper · 2026-05-09T18:01:14Z

Codex review: needs changes before merge. Reviewed July 3, 2026, 11:45 PM ET / 03:45 UTC.

Summary
The PR adds OPENCLAW_SPAWN_ALLOWLIST/SPAWN_ALLOWLIST parsing during config load and maps it onto agents.defaults.subagents.allowAgents with focused parser tests.

PR surface: Source +55, Tests +61. Total +116 across 3 files.

Reproducibility: yes. Source inspection shows current main and v2026.6.11 have no SPAWN_ALLOWLIST reader, while native, ACP, and agents_list spawn surfaces consume only configured subagents.allowAgents; I did not run the Docker Compose scenario in this read-only review.

Review metrics: 1 noteworthy metric.

Spawn allowlist env surface: 2 env aliases added; 1 default allowlist overlay changed. The PR adds env-controlled mutation of a sessions_spawn authorization default, so precedence and upgrade behavior matter before merge.

Stored data model
Persistent data-model change detected: serialized state: src/config/spawn-allowlist-env.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #79490
Summary: This PR is a focused candidate fix for the canonical Docker/Coolify spawn allowlist env bug; sibling PRs overlap, while wildcard registry hardening and embedded-mode tool exposure are adjacent subagent issues.

Members:

canonical: [Bug]: SPAWN_ALLOWLIST environment variable is ignored, preventing agent spawning #79490 - The PR body uses closing syntax for this open issue, and the issue contains the concrete Docker env reproduction for ignored SPAWN_ALLOWLIST.
partial_overlap: Fix skill config requirements, spawn allowlists, chat stop lifecycle, and systemd status #79538 - This broader open PR also includes spawn allowlist env handling, but bundles unrelated fixes and is currently conflicting.
superseded: fix(agents/subagents): read SPAWN_ALLOWLIST env var as allowlist fallback (#79490) #80709 - This closed unmerged PR attempted the same env fallback area and is no longer a viable canonical landing path.
adjacent_distinct: fix: constrain wildcard subagent targets #84357 - This merged PR fixed wildcard registry validation, which constrains * behavior but does not read the env allowlist.
adjacent_distinct: sessions_spawn accepts unknown agentId with allowAgents:"*" (auto-provisions default-configured subagent, no registry validation) #84040 - This closed issue reported wildcard allowAgents accepting unknown agent ids; it shares the authorization boundary but not the missing env reader root cause.
2 more in the report.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🦞 diamond lobster
Patch quality: 🧂 unranked krab
Result: blocked by patch quality or review findings.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

Change env handling to fallback-only when agents.defaults.subagents.allowAgents is absent.
[P2] Add tests for env-only Docker behavior and explicit JSON default precedence.
Document the env fallback, formats, precedence, and configured-agent wildcard limit.

Risk before merge

[P1] Merging as written can widen an existing deployment's sessions_spawn authorization if SPAWN_ALLOWLIST=* remains in host env while JSON config intentionally narrows agents.defaults.subagents.allowAgents.
[P1] If maintainers intentionally want host-env-wins semantics for this authorization boundary, that needs explicit security/product sign-off and user-facing docs that explain precedence and upgrade behavior.

Maintainer options:

Preserve explicit config before merge (recommended)
Change the overlay so env-derived allowlists only populate agents.defaults.subagents.allowAgents when that default is absent, then prove explicit defaults and per-agent allowlists still win.
Accept host-env precedence intentionally
Maintainers can choose host-env-wins semantics, but it should be documented as a security-sensitive authorization override with upgrade notes.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Update the spawn allowlist env overlay so it only populates agents.defaults.subagents.allowAgents when that default is absent; keep per-agent allowlists untouched; document the env fallback, accepted formats, precedence, and configured-agent wildcard limit; add focused tests for env-only Docker behavior and explicit-config precedence.

Next step before merge

[P2] The remaining blocker is a narrow mechanical repair: make the env overlay fallback-only, update focused tests, and document the supported env surface.

Security
Needs attention: The diff touches a sessions_spawn authorization boundary and currently lets host env override explicit default allowlists.

Review findings

[P1] Preserve explicit spawn allowlists — src/config/spawn-allowlist-env.ts:51
[P2] Document the spawn allowlist env fallback — src/config/spawn-allowlist-env.ts:5-7

Review details

Best possible solution:

Land a fallback-only env bridge that fills a missing default allowlist for env-only Docker deployments, preserves explicit JSON and per-agent allowlists, keeps configured-agent wildcard limits, and documents precedence.

Do we have a high-confidence way to reproduce the issue?

Yes. Source inspection shows current main and v2026.6.11 have no SPAWN_ALLOWLIST reader, while native, ACP, and agents_list spawn surfaces consume only configured subagents.allowAgents; I did not run the Docker Compose scenario in this read-only review.

Is this the best way to solve the issue?

No as written. A config-load fallback is the right narrow layer for env-only Docker deployments, but it should not override explicit default allowlists and should document the new env surface.

Full review comments:

[P1] Preserve explicit spawn allowlists — src/config/spawn-allowlist-env.ts:51
applySpawnAllowlistEnvOverlay is called for every loaded config, and this assignment replaces an explicit agents.defaults.subagents.allowAgents whenever the host has SPAWN_ALLOWLIST or OPENCLAW_SPAWN_ALLOWLIST. That lets a stale or broad deployment env var become the default sessions_spawn authorization policy for all agents without per-agent overrides; only populate this default when it is currently unset, and update the overwrite test accordingly.
Confidence: 0.93
[P2] Document the spawn allowlist env fallback — src/config/spawn-allowlist-env.ts:5-7
This introduces two env names that affect a sessions_spawn authorization boundary, but current docs only describe JSON allowAgents. Please document fallback-only precedence, accepted formats, and the configured-agent wildcard limit so operators do not treat it as an undocumented override.
Confidence: 0.82

Overall correctness: patch is incorrect
Overall confidence: 0.91

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 9d68f877ac3e.

Label changes

Label justifications:

P1: The PR targets a real Docker/Coolify sessions_spawn regression but currently risks widening a security-sensitive authorization boundary.
merge-risk: 🚨 compatibility: Merging as written can change existing deployments where JSON agents.defaults.subagents.allowAgents and host env disagree.
merge-risk: 🚨 security-boundary: The changed default controls which configured agents a session may spawn through the privileged sessions_spawn tool.
rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🦞 diamond lobster and patch quality is 🧂 unranked krab.
status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (terminal): The PR body includes Docker Compose and CLI transcript excerpts from a patched container showing the env value, gateway status, and observed spawn allowlist behavior after a cold reload.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes Docker Compose and CLI transcript excerpts from a patched container showing the env value, gateway status, and observed spawn allowlist behavior after a cold reload.

Evidence reviewed

PR surface:

Source +55, Tests +61. Total +116 across 3 files.

View PR surface stats

Area	Files	Added	Net
Source	2	55	+55
Tests	1	61	+61
Docs	0	0	0
Config	0	0	0
Generated	0	0	0
Other	0	0	0
Total	3	116	+116

Security concerns:

[medium] Host env can broaden spawn authorization — src/config/spawn-allowlist-env.ts:51
A deployment-level SPAWN_ALLOWLIST=* would replace an explicit JSON default allowlist, widening which configured agents can be spawned unless every requester has a per-agent override.
Confidence: 0.91

Acceptance criteria:

[P1] node scripts/run-vitest.mjs src/config/spawn-allowlist-env.test.ts.
[P1] node scripts/run-vitest.mjs src/agents/openclaw-tools.subagents.sessions-spawn.allowlist.test.ts src/agents/tools/agents-list-tool.test.ts src/agents/subagent-target-policy.test.ts.
[P1] git diff --check.

What I checked:

PR diff overwrites explicit default allowlists: The added helper always assigns env-derived values to cfg.agents.defaults.subagents.allowAgents; the added test also asserts env overwrites an existing config allowlist. (src/config/spawn-allowlist-env.ts:51, 24132f1f7fd2)
Current main lacks the env overlay: Current config finalization applies generic config env vars and then shell-env fallback; there is no SPAWN_ALLOWLIST reader in this path. (src/config/io.ts:1433, 9d68f877ac3e)
Native spawn consumes configured allowlists only: The native sessions_spawn path passes only per-agent subagents.allowAgents or agents.defaults.subagents.allowAgents to target-policy validation. (src/agents/subagent-spawn.ts:1225, 9d68f877ac3e)
ACP and agents_list sibling surfaces share the same invariant: ACP spawn and agents_list also derive spawnable targets from configured allowlists, so a config-load fallback is the narrow shared layer but must preserve explicit config precedence. (src/agents/acp-spawn.ts:876, 9d68f877ac3e)
Security docs treat spawn allowlists as a boundary: The security guide tells operators to deny sessions_spawn unless needed and keep default/per-agent allowlists restricted to known-safe target agents. Public docs: docs/gateway/security/index.md. (docs/gateway/security/index.md:1147, 9d68f877ac3e)
Latest release still lacks this fix: Release v2026.6.11 has no src/config/spawn-allowlist-env.ts, and its config finalization only shows applyConfigEnvVars, so the central bug is not shipped fixed. (src/config/io.ts:1402, e085fa1a3ffd)

Likely related people:

joshavant: Authored and merged wildcard/configured-target hardening in the same sessions_spawn target-policy and native/ACP spawn paths. (role: recent spawn authorization contributor; confidence: high; commits: 00da318350e2, 577e64db63b4; files: src/agents/subagent-target-policy.ts, src/agents/subagent-spawn.ts, src/agents/acp-spawn.ts)
steipete: Authored explicit spawn allowlist enforcement and merged default subagent allowlist support, which is the config surface this PR overlays. (role: allowlist contract and config-surface contributor; confidence: high; commits: 2e99c1d22726, d92178471894; files: src/agents/subagent-target-policy.ts, src/agents/subagent-spawn.ts, src/config/types.agent-defaults.ts)
hclsys: Authored the PR that added fallback to agents.defaults.subagents.allowAgents for spawn and agents-list behavior. (role: default allowlist feature contributor; confidence: medium; commits: a57766bad0d7; files: src/agents/subagent-spawn.ts, src/agents/tools/agents-list-tool.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

clawsweeper · 2026-05-24T16:36:53Z

ClawSweeper PR egg

🔥 Warming up: real-behavior proof passed; findings, security review, or rank-up moves are still in progress.

Hatch command

Comment @clawsweeper hatch when this PR is hatchable.

Hatchability rules:

Merged PRs are hatchable.
Open PRs are hatchable when they are status: 👀 ready for maintainer look, status: 🚀 automerge armed, or labeled clawsweeper:automerge.
Closed unmerged PRs are hatchable only when one of those hatchable labels is still present in the durable record.

What is this egg doing here?

Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
Hatchability usually comes from sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness. A merged PR is already final, so merge makes the egg hatchable independently.
The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

…list-env

openclaw-barnacle · 2026-07-19T04:29:03Z

This pull request has been automatically marked as stale due to inactivity.
Please add updates or it will be closed.

clawsweeper · 2026-07-19T09:54:04Z

ClawSweeper status: review started.

I am starting a fresh review of this pull request: fix(config): apply SPAWN_ALLOWLIST env for sessions_spawn (#79490) This is item 1/1 in the current shard. Shard 1/22.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.

fix(config): honor SPAWN_ALLOWLIST for sessions_spawn (openclaw#79490)

389b46e

Reads OPENCLAW_SPAWN_ALLOWLIST then SPAWN_ALLOWLIST and applies them to agents.defaults.subagents.allowAgents during config load (env wins). Co-authored-by: Cursor <[email protected]>

openclaw-barnacle Bot added size: S triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels May 9, 2026

openclaw-barnacle Bot added proof: supplied External PR includes structured after-fix real behavior proof. and removed triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels May 9, 2026

clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 9, 2026

adhirajhangal mentioned this pull request May 9, 2026

fix(daemon/launchd): cap unbounded gateway stdout/stderr log growth (refs #79422) #79892

Open

This was referenced May 11, 2026

fix(agents/subagents): read SPAWN_ALLOWLIST env var as allowlist fallback (#79490) #80709

Closed

Fix skill config requirements, spawn allowlists, chat stop lifecycle, and systemd status #79538

Closed

This was referenced May 19, 2026

sessions_spawn accepts unknown agentId with allowAgents:"*" (auto-provisions default-configured subagent, no registry validation) #84040

Closed

fix: constrain wildcard subagent targets #84357

Merged

openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 24, 2026

clawsweeper Bot mentioned this pull request Jun 14, 2026

[Bug]: SPAWN_ALLOWLIST environment variable is ignored, preventing agent spawning #79490

Open

Jefsky added 2 commits June 20, 2026 02:23

Merge remote-tracking branch 'origin/main' into fix/79490-spawn-allow…

a69f555

…list-env

fix(config): update spawn allowlist env import

24132f1

openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label Jun 19, 2026

clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label Jun 19, 2026

This was referenced Jun 21, 2026

fix(agents): expose sessions_spawn in embedded mode when allowAgents is configured #91315

Closed

[Bug]: Interactive TUI sessions (gateway and --local) cannot expose sessions_spawn even when agents.defaults.subagents.allowAgents is configured #91095

Closed

openclaw-barnacle Bot added the stale Marked as stale due to inactivity label Jul 19, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(config): apply SPAWN_ALLOWLIST env for sessions_spawn (#79490)#79913

fix(config): apply SPAWN_ALLOWLIST env for sessions_spawn (#79490)#79913
Jefsky wants to merge 3 commits into
openclaw:mainfrom
Jefsky:fix/79490-spawn-allowlist-env

Jefsky commented May 9, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented May 9, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented May 24, 2026

Uh oh!

openclaw-barnacle Bot commented Jul 19, 2026

Uh oh!

clawsweeper Bot commented Jul 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

Jefsky commented May 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Real behavior proof

Uh oh!

clawsweeper Bot commented May 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

clawsweeper Bot commented May 24, 2026

Hatch command

Uh oh!

openclaw-barnacle Bot commented Jul 19, 2026

Uh oh!

clawsweeper Bot commented Jul 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Jefsky commented May 9, 2026 •

edited

Loading

clawsweeper Bot commented May 9, 2026 •

edited

Loading