Issue Station
Sign In
Tools hereToolbox

openclaw - 💡(How to fix) Fix docs: subagent model priority order mismatch between docs and implementation [1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#75934•Fetched 2026-05-03 04:44:11
View on GitHub
Comments
1
Participants
2
Timeline
2
Reactions
2
Author
kikibriankikibrian
Participants
clawsweeper[bot]clawsweeper[bot]kikibriankikibrian
Timeline (top)
closed ×1commented ×1

The documented subagent model priority in docs/tools/subagents.md does not match the actual implementation in resolveSubagentConfiguredModelSelection.

Root Cause

The documented subagent model priority in docs/tools/subagents.md does not match the actual implementation in resolveSubagentConfiguredModelSelection.

RAW_BUFFERClick to expand / collapse

Description

The documented subagent model priority in docs/tools/subagents.md does not match the actual implementation in resolveSubagentConfiguredModelSelection.

Priority Order

Docs state (docs/tools/subagents.md):

Model: inherits the caller unless you set agents.defaults.subagents.model (or per-agent agents.list[].subagents.model); an explicit sessions_spawn.model still wins.

Docs imply:

  1. sessions_spawn.model (explicit override)
  2. agents.defaults.subagents.model or agents.list[N].subagents.model
  3. inherits the caller (default fallback)

Actual code (model-selection-sqz--Abu.js → resolveSubagentConfiguredModelSelection):

  1. sessions_spawn.model ✅
  2. agents.list[N].subagents.model ✅
  3. agents.list[N].model ← UNDOCUMENTED - per-agent main model checked before global subagent default
  4. agents.defaults.subagents.model ← actually overridden by step 3
  5. agents.defaults.model ← not "inherit from caller", no parent lookup exists
  6. hardcoded fallback

Issue A: Undocumented agents.list[N].model precedence

If a user sets agents.defaults.subagents.model expecting it to control all subagents, the per-agent model value silently overrides it at step 3. This is not documented.

Issue B: "Inherits the caller" is not implemented

The docs state subagents inherit the caller's model. There is no code path that consults the parent/caller session's model when resolving a subagent's model. The fallback goes to agents.defaults.model or hardcoded default.

Suggested fix

Either:

  • (a) Update docs to match the actual 6-level precedence, including the undocumented step 3
  • (b) Add an explicit "inherit from caller" fallback step to the code
  • (c) Both: fix the code to match docs, then update docs

Relevant code locations

  • dist/model-selection-sqz--Abu.js: resolveSubagentSpawnModelSelection (line ~153)
  • dist/model-selection-sqz--Abu.js: resolveSubagentConfiguredModelSelection (line ~137)
  • docs/tools/subagents.md (line ~136)

Environment

  • Version: 2026.4.29

extent analysis

TL;DR

Update the documentation in docs/tools/subagents.md to reflect the actual 6-level precedence used in resolveSubagentConfiguredModelSelection, or modify the code to match the documented behavior.

Guidance

  • Review the current implementation in resolveSubagentConfiguredModelSelection to understand the actual precedence order.
  • Compare this with the documented order in docs/tools/subagents.md to identify discrepancies.
  • Consider updating the documentation to match the actual behavior, or modify the code to implement the "inherit from caller" fallback as described in the documentation.
  • Verify the changes by testing the model selection with different configurations to ensure the behavior matches the updated documentation.

Example

No code snippet is provided as the issue is focused on documentation and behavior discrepancies rather than a specific code error.

Notes

The fix may involve updating the documentation, modifying the code, or both, depending on the desired behavior. The version 2026.4.29 is mentioned, but without further context, it's unclear if this is relevant to the fix.

Recommendation

Apply workaround: Update the documentation to reflect the actual behavior, as this is a more straightforward change that can be implemented immediately, while modifying the code to match the documented behavior may require additional testing and validation.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#authentication issue#prompt issue#agent setup#task chaining#parallel task

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - 💡(How to fix) Fix docs: subagent model priority order mismatch between docs and implementation [1 comments, 2 participants]