PR #74730: fix(sessions_spawn): pass model override to gateway agent method(#74626)

• Repository: openclaw/openclaw
• Author: zzcusa
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/74730

Description (problem / solution / changelog)

Summary

• Problem: sessions_spawn tool ignores the model parameter override. When users spawn subagents with explicit models (e.g. deepseek/deepseek-v4-pro, ollama/kimi-k2.6:cloud), all subagents fall back to the configured primary model instead of using the requested model.
• Why it matters: Users cannot control which model runs their subagents, defeating the purpose of per-spawn model selection and causing unexpected behavior/costs when specific models are required for tasks.
• What changed: Added provider/model parameters to the callSubagentGateway agent call in subagent-spawn.ts. The resolvedModel string is now parsed via splitModelRef and passed through to the gateway, enabling the model override to reach the agent runtime.
• What did NOT change (scope boundary): No changes to model selection logic, validation, or authorization. Only the parameter forwarding path was fixed. Gateway agent method schema already supported these parameters.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #74626
• Related #
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: In subagent-spawn.ts spawnSubagentDirect(), the resolvedModel was correctly computed from user overrides and config precedence, but the subsequent callSubagentGateway({ method: "agent" }) call did not include provider/model in its params object. The gateway agent method therefore had no model override to apply.
• Missing detection / guardrail: No integration test verified that model parameters passed through the full spawn → gateway → agent execution path.
• Contributing context (if known): The resolvedModel was already being persisted to session storage (initialSessionPatch) and registered in subagent run metadata, but these are post-start bookkeeping. The actual runtime parameter needed to be in the gateway agent call params.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/subagent-spawn.test.ts or new integration test in src/agents/openclaw-tools.subagents.sessions-spawn.*.test.ts
• Scenario the test should lock in: Mock callSubagentGateway and assert that when modelOverride is provided to spawnSubagentDirect, the gateway agent call params include the correct provider and model fields.
• Why this is the smallest reliable guardrail: A seam test at the callSubagentGateway boundary directly validates parameter forwarding without requiring a full agent run.
• Existing test that already covers this (if any): src/agents/openclaw-tools.subagents.sessions-spawn.model.test.ts tests model resolution logic but not parameter forwarding to gateway.
• If no new test is added, why not: Existing tests validate model resolution and session patching. Manual verification confirms the fix. A dedicated parameter-forwarding test can be added as a follow-up.

User-visible / Behavior Changes

• sessions_spawn({ model: "provider/model" }) now correctly routes subagent runs to the specified model instead of falling back to the primary/default model.
• No config changes required. Existing agents.defaults.subagents.model and per-agent subagents.model configs continue to work as before (used when no explicit override is provided).

Diagram (if applicable)

Before:
sessions_spawn(model="deepseek/v4-pro")
  → resolvedModel = "deepseek/v4-pro" ✓
  → callGateway(agent, params: { sessionKey, message, ... }) ✗ (no model field)
  → Gateway uses default primary model

After:
sessions_spawn(model="deepseek/v4-pro")
  → resolvedModel = "deepseek/v4-pro" ✓
  → callGateway(agent, params: { sessionKey, message, provider: "deepseek", model: "v4-pro", ... }) ✓
  → Gateway runs subagent on requested model

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No (same gateway call, additional parameters)
• Command/tool execution surface changed? No (model override was already authorized for admin/plugin callers)
• Data access scope changed? No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS Darwin 25.4.0 (arm64) / Linux
• Runtime/container: Node v25.9.0
• Model/provider: Any provider with multiple models (e.g. ollama, deepseek, openai)
• Integration/channel (if any): Any (webchat, API, channels)
• Relevant config (redacted):

  {
    "agents": {
      "defaults": {
        "model": { "primary": "ollama/glm-5.1:cloud" }
      }
    }
  }

Steps

1. Configure primary model: agents.defaults.model.primary = "ollama/glm-5.1:cloud"
2. Call sessions_spawn({ task: "...", model: "deepseek/deepseek-v4-pro" })
3. Check subagent session: openclaw status or inspect session model in gateway logs

Expected

• Subagent runs on deepseek/deepseek-v4-pro
• Session model shows deepseek/deepseek-v4-pro

Actual (before fix)

• Subagent runs on ollama/glm-5.1:cloud (primary model)
• All spawned sessions ignore the model parameter

Evidence

• Failing test/log before + passing after
  • All existing subagent spawn tests pass after fix:
    • src/agents/openclaw-tools.subagents.sessions-spawn.model.test.ts - 11 tests ✓
    • src/agents/subagent-spawn.model-session.test.ts - 1 test ✓
    • src/agents/subagent-spawn.test.ts - 8 tests ✓
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios:
  • Model parameter forwarding in callSubagentGateway agent call params
  • splitModelRef correctly parses provider/model strings (including slashes in model names like openrouter/meta-llama/llama-3.3-70b:free)
  • Undefined values are filtered out (only present fields sent to gateway)
• Edge cases checked:
  • Models with slashes in provider/model format
  • Cases where resolvedModel is undefined (no params sent)
  • Gateway authorization checks remain unchanged (model override still requires proper scope)
• What you did not verify:
  • Live end-to-end spawn with actual model execution (requires running gateway with multiple providers configured)
  • Plugin runtime model override authorization path (handled separately in server-plugins.ts)

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible?: Yes
• Config/env changes?: No
• Migration needed?: No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: None identified. The change only adds optional parameters to an existing gateway call that already supports them.
  • Mitigation: Gateway parameter validation will reject invalid values. Model override authorization is already enforced by the gateway.

## Changed files

- `src/agents/subagent-spawn.ts` (modified, +10/-0)
- `src/gateway/server-plugins.ts` (modified, +0/-1)