Repository navigation
Description
ACP runtime ignores per-agent model.primary override — always falls back to default model
Description
When an agent is configured with a specific model.primary in openclaw.json, the ACP runtime (acpx) does not apply this override at session initialization time. The Claude Code process is launched with the system default model instead.
Expected: Agent claude3 with "model": {"primary": "xiaomi/mimo-v2.5"} should use mimo-v2.5.
Actual: It falls back to the default xiaoimi/mimo-v2.5-pro.
Root Cause
Two compounding bugs in the ACP spawn → AcpxRuntime code path:
Bug 1: ACP spawn does not resolve agent model from config
openclaw-tools reads model only from the sessions_spawn tool call arguments. When the calling agent does not explicitly pass model, it is undefined. The subagent spawn path has resolveSubagentSpawnModelSelection which correctly resolves agent.model.primary from config, but the ACP spawn path has no equivalent.
File: dist/openclaw-tools-*.js (sessions_spawn tool)
// Line ~10678: only reads from tool call args
const modelOverride = normalizeToolModelOverride(readStringParam$1(params, "model"));
// Line ~10724: passes potentially undefined value
model: modelOverride,File: dist/acp-spawn-*.js (line ~821)
// When params.model is falsy, runtimeOptions becomes void 0
runtimeOptions: params.model || params.thinking || params.runTimeoutSeconds ? {
...params.model ? { model: params.model } : {},
// ...
} : void 0,cfg and targetAgentId are both available in the ACP spawn function, so the agent config could be resolved here.
Bug 2: AcpxRuntime.ensureSession drops input.model
Even when a model IS passed through the ACP Session Manager (which correctly extracts requestedModel and passes it as model: requestedModel to runtime.ensureSession()), the AcpxRuntime's ensureSession ignores input.model and passes sessionOptions: input.sessionOptions (always undefined) to the inner AcpxManager.
File: dist/runtime-*.js (line ~6109-6121)
async ensureSession(input) {
// ...
const record = await (await this.getManager()).ensureSession({
sessionKey: sessionName,
agent,
mode: input.mode,
cwd: input.cwd ?? this.options.cwd,
resumeSessionId: input.resumeSessionId,
sessionOptions: input.sessionOptions // <-- ALWAYS undefined
});The AcpRuntimeEnsureInput type has model?: string but no sessionOptions field, so input.sessionOptions is always undefined and input.model is never forwarded.
The inner AcpxManager reads input.sessionOptions?.model which is always undefined, so applyRequestedModelIfAdvertised returns false and the process launches with the default model.
Full trace for agent "claude3"
- Main agent calls
sessions_spawn(agentId: "claude3", runtime: "acp", task: "...")without explicitmodel modelOverride = undefined(tool args only)spawnAcpDirect({ model: undefined })runtimeOptions = void 0(all three fields falsy)- ACP Manager:
requestedModel = undefined runtime.ensureSession({ ... })— nomodelfield included- AcpxRuntime:
sessionOptions: input.sessionOptions=undefined - AcpxManager:
input.sessionOptions?.model=undefined applyRequestedModelIfAdvertisedreceives no model → returnsfalse- Claude Code launched with default model
Proposed fix
Two changes needed:
1. dist/acp-spawn-*.js (~line 1100): Auto-resolve agent model from config when not explicitly provided:
// Before:
model: params.model,
// After:
model: params.model ?? (() => {
const ac = resolveAgentConfig(cfg, targetAgentId);
const m = ac?.model;
return typeof m === "string" ? m : m?.primary;
})(),2. dist/runtime-*.js (~line 6120): Map input.model to sessionOptions.model:
// Before:
sessionOptions: input.sessionOptions
// After:
sessionOptions: input.sessionOptions ?? (input.model ? { model: input.model } : undefined)Environment
- OpenClaw version: 2026.5.26
- Node: v22.22.3
- Platform: macOS (Darwin 25.5.0)
Metadata
Metadata
Assignees
Labels
Type
Fields
Priority
Activity
WarrenJones commentedon May 27, 2026
clawsweeper commentedon May 27, 2026
Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed May 27, 2026, 2:39 PM ET / 18:39 UTC.
Summary
Keep open: current main still does not resolve a target ACP agent's configured primary model when sessions_spawn omits an explicit model, and the acpx dependency contract also requires OpenClaw to map that model into sessionOptions before the delegate can apply it.
Reproducibility: yes. from source inspection: an ACP sessions_spawn without a model passes undefined through the ACP spawn path, and acpx only applies requested models from sessionOptions.model. I did not run a live ACP process in this read-only review.
Next step
This is a narrow, source-reproducible ACP model-routing bug with clear files and regression-test targets.
Review details
Best possible solution:
Resolve the target ACP agent's configured primary model when no explicit spawn model is supplied, then map the resulting model into the acpx sessionOptions contract before session creation.
Do we have a high-confidence way to reproduce the issue?
Yes, from source inspection: an ACP sessions_spawn without a model passes undefined through the ACP spawn path, and acpx only applies requested models from sessionOptions.model. I did not run a live ACP process in this read-only review.
Is this the best way to solve the issue?
Yes, the maintainable fix is to reuse existing configured-model resolution instead of inventing another model policy path, then bridge OpenClaw's model field to acpx sessionOptions.
AGENTS.md: found and applied where relevant.
Remaining risk / open question:
Codex review notes: model gpt-5.5, reasoning high; reviewed against bb46b79d3c14.
Label changes
Label changes:
P2: This is a normal-priority runtime routing bug with a clear source path and limited blast radius to ACP session model selection.impact:auth-provider: The issue is about configured model choice/provider routing being ignored for ACP runtime sessions.issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.clawsweeper:source-repro: Current issue advisory state selects this label.clawsweeper:queueable-fix: Current issue advisory state selects this label.clawsweeper:fix-shape-clear: Current issue advisory state selects this label.Label justifications:
P2: This is a normal-priority runtime routing bug with a clear source path and limited blast radius to ACP session model selection.impact:auth-provider: The issue is about configured model choice/provider routing being ignored for ACP runtime sessions.Evidence reviewed
Acceptance criteria:
What I checked:
AGENTS.md:1, bb46b79d3c14)src/agents/tools/sessions-spawn-tool.ts:297, bb46b79d3c14)src/agents/acp-spawn.ts:984, bb46b79d3c14)src/agents/model-selection.ts:323, bb46b79d3c14)docs/gateway/config-agents.md. (docs/gateway/config-agents.md:1109, bb46b79d3c14)src/acp/control-plane/manager.core.ts:332, bb46b79d3c14)Likely related people:
src/agents/acp-spawn.ts,extensions/acpx/src/runtime.ts,src/acp/control-plane/manager.core.ts)src/agents/model-selection.ts,src/agents/subagent-spawn-plan.ts,src/agents/acp-spawn.ts)extensions/acpx/src/runtime.ts,src/acp/control-plane/manager.core.ts)src/agents/acp-spawn.ts,extensions/acpx/src/runtime.ts,src/acp/control-plane/manager.core.ts)How this review workflow works
@clawsweeper re-reviewcomments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.@clawsweeper re-reviewor@clawsweeper re-runon an open PR or issue to request a fresh review only.@clawsweeper reviewto request a fresh review only.@clawsweeper autofix,@clawsweeper automerge,@clawsweeper fix ci, or@clawsweeper address review.@clawsweeper explainto ask for more context, or@clawsweeper stopto stop active automation.xiaoxuesheng123467 commentedon May 27, 2026
Additional finding: root cause also involves Claude Code's
ANTHROPIC_MODELenv varAfter further investigation, the ACP spawn model resolution bug (described above) is only part of the problem. The other part is that Claude Code's
settings.jsonsetsANTHROPIC_MODELto the default model (mimo-v2.5-pro), which locks the Claude Code process into that model at startup. The ACP runtime'ssetSessionModelcall then tries to switch to the configured per-agent model (mimo-v2.5), but fails because the model switching mechanism doesn't reliably override the startup model.What we observed
claude3config:"model": {"primary": "xiaomi/mimo-v2.5"}settings.json:ANTHROPIC_MODEL=mimo-v2.5-proxiaomi/mimo-v2.5(with our fix)applyRequestedModelIfAdvertisedcallssetSessionModel("mimo-v2.5")mimo-v2.5-promodel (mimo-v2.5-pro) may not exist or you may not have accessWorkaround
Change
ANTHROPIC_MODELin~/.claude/settings.jsonto match the most common agent model (mimo-v2.5), so Claude Code starts with the right default. Agents needing a different model (e.g.mimo-v2.5-pro) rely onsetSessionModelto switch.Fixes applied locally
dist/acp-spawn-*.js(~line 1100): Auto-resolve agent model from config whenparams.modelis undefineddist/runtime-*.js(~line 6120): Mapinput.modeltosessionOptions.modelinAcpxRuntime.ensureSession~/.claude/settings.json: ChangedANTHROPIC_MODELfrommimo-v2.5-protomimo-v2.5Fixes 1 and 2 address the ACP runtime bug. Fix 3 is a workaround for the
setSessionModelnot reliably overriding the startup model.Suggestion
The ACP runtime should pass the configured per-agent model as a
--modelflag when spawning the Claude Code process (or setANTHROPIC_MODELper-session), rather than relying solely onsetSessionModelafter startup. This would make the per-agent model override robust regardless of the user's globalsettings.json.steipete commentedon Jun 1, 2026
Fixed in #88946.
ACP spawn now resolves the target runtime=acp agent's configured primary model and passes it as ACP runtime options, and AcpxRuntime forwards the model through
sessionOptions.modelto the delegate session initialization. Focused proof:src/agents/acp-spawn.test.tsplusextensions/acpx/src/runtime.test.ts.