Skip to content

ACP runtime ignores per-agent model.primary override #87381

Closed

Description

@xiaoxuesheng123467

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"

  1. Main agent calls sessions_spawn(agentId: "claude3", runtime: "acp", task: "...") without explicit model
  2. modelOverride = undefined (tool args only)
  3. spawnAcpDirect({ model: undefined })
  4. runtimeOptions = void 0 (all three fields falsy)
  5. ACP Manager: requestedModel = undefined
  6. runtime.ensureSession({ ... }) — no model field included
  7. AcpxRuntime: sessionOptions: input.sessionOptions = undefined
  8. AcpxManager: input.sessionOptions?.model = undefined
  9. applyRequestedModelIfAdvertised receives no model → returns false
  10. 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)

Activity

  1. WarrenJones commented on May 27, 2026

    @WarrenJones
  2. clawsweeper commented on May 27, 2026

    @clawsweeper
    Contributor

    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:

    • I did not run a live ACP launch in this read-only review; the current-main failure is source-reproducible from OpenClaw's spawn path and the acpx package contract.
    • The fix should preserve explicit sessions_spawn.model precedence and existing Codex ACP command-normalization behavior while adding the missing configured-model fallback.

    Codex review notes: model gpt-5.5, reasoning high; reviewed against bb46b79d3c14.

    Label changes

    Label changes:

    • add P2: This is a normal-priority runtime routing bug with a clear source path and limited blast radius to ACP session model selection.
    • add impact:auth-provider: The issue is about configured model choice/provider routing being ignored for ACP runtime sessions.
    • add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
    • add clawsweeper:source-repro: Current issue advisory state selects this label.
    • add clawsweeper:queueable-fix: Current issue advisory state selects this label.
    • add 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:

    • node scripts/run-vitest.mjs src/agents/acp-spawn.test.ts
    • node scripts/run-vitest.mjs extensions/acpx/src/runtime.test.ts
    • node scripts/run-vitest.mjs src/acp/control-plane/manager.test.ts
    • node scripts/run-vitest.mjs src/agents/openclaw-tools.subagents.sessions-spawn.model.test.ts

    What I checked:

    • Repository policy read: Root AGENTS.md was read fully before review, and scoped ACP/agent guidance was read for the touched paths. (AGENTS.md:1, bb46b79d3c14)
    • ACP sessions_spawn only reads explicit model input: The tool normalizes only params.model, then passes that value to spawnAcpDirect; no target agent config model is resolved on the ACP path. (src/agents/tools/sessions-spawn-tool.ts:297, bb46b79d3c14)
    • ACP spawn runtime options are built only from params.model: initializeAcpSpawnRuntime creates runtimeOptions.model only when params.model is present, and the caller passes model: params.model, so a configured per-agent primary is not applied. (src/agents/acp-spawn.ts:984, bb46b79d3c14)
    • Existing model selection contract already supports target agent primary: The native subagent selection helper falls back through target agent subagents.model and then target agent model before default model, and the tests cover target agent primary winning over global default. (src/agents/model-selection.ts:323, bb46b79d3c14)
    • Docs define per-agent model as strict primary config: The agent configuration docs say agents.list[].model string or object form sets a strict per-agent primary unless fallbacks are configured. Public docs: docs/gateway/config-agents.md. (docs/gateway/config-agents.md:1109, bb46b79d3c14)
    • OpenClaw manager forwards model if runtimeOptions contains one: A resolved runtimeOptions.model is validated and forwarded as model to runtime.ensureSession, so the missing piece is before or inside the ACP runtime adapter. (src/acp/control-plane/manager.core.ts:332, bb46b79d3c14)

    Likely related people:

    • Onur Solmaz: Introduced the ACP thread-bound agents surface and later refactored OpenClaw to consume the acpx runtime library. (role: ACP feature history owner; confidence: high; commits: a7d56e3554d0, 154a7edb7cad; files: src/agents/acp-spawn.ts, extensions/acpx/src/runtime.ts, src/acp/control-plane/manager.core.ts)
    • Peter Steinberger: Recent commits touched model-selection helpers and the current main refactor that internalized the OpenClaw agent runtime. (role: recent adjacent owner; confidence: medium; commits: 310d2db31241, 7b36fa76726a, bb46b79d3c14; files: src/agents/model-selection.ts, src/agents/subagent-spawn-plan.ts, src/agents/acp-spawn.ts)
    • Bob: Recently carried ACP recovery and reset hardening that touched the same ACP control-plane/runtime area. (role: recent ACP hardening contributor; confidence: medium; commits: f6124f3e17a9; files: extensions/acpx/src/runtime.ts, src/acp/control-plane/manager.core.ts)
    • Pavan Kumar Gondhi: Current shallow blame attributes the reviewed ACP spawn/runtime files to the recent side-effecting command wrapper fix, but the grafted history makes this weaker than the feature-history signals. (role: recent adjacent contributor; confidence: low; commits: 8e41c118fa80; files: src/agents/acp-spawn.ts, extensions/acpx/src/runtime.ts, src/acp/control-plane/manager.core.ts)
    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.
  3. added
    P2Normal backlog priority with limited blast radius.
    impact:auth-providerAuth, provider routing, model choice, or SecretRef resolution may break.
    issue-rating: 🦞 diamond lobsterVery strong issue quality with high-confidence source-level or clear reproduction.
    clawsweeper:source-reproClawSweeper found a high-confidence source-level issue reproduction.
    clawsweeper:queueable-fixClawSweeper marked this issue as an existing queue_fix_pr work candidate.
    clawsweeper:fix-shape-clearClawSweeper found a clear likely implementation shape for this issue.
    on May 27, 2026
  4. xiaoxuesheng123467 commented on May 27, 2026

    @xiaoxuesheng123467
    Author

    Additional finding: root cause also involves Claude Code's ANTHROPIC_MODEL env var

    After 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.json sets ANTHROPIC_MODEL to the default model (mimo-v2.5-pro), which locks the Claude Code process into that model at startup. The ACP runtime's setSessionModel call 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

    • Agent claude3 config: "model": {"primary": "xiaomi/mimo-v2.5"}
    • Claude Code settings.json: ANTHROPIC_MODEL=mimo-v2.5-pro
    • ACP spawn resolves model correctly to xiaomi/mimo-v2.5 (with our fix)
    • applyRequestedModelIfAdvertised calls setSessionModel("mimo-v2.5")
    • Claude Code process rejects or ignores the switch, stays on mimo-v2.5-pro
    • Error: model (mimo-v2.5-pro) may not exist or you may not have access

    Workaround

    Change ANTHROPIC_MODEL in ~/.claude/settings.json to 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 on setSessionModel to switch.

    Fixes applied locally

    1. dist/acp-spawn-*.js (~line 1100): Auto-resolve agent model from config when params.model is undefined
    2. dist/runtime-*.js (~line 6120): Map input.model to sessionOptions.model in AcpxRuntime.ensureSession
    3. ~/.claude/settings.json: Changed ANTHROPIC_MODEL from mimo-v2.5-pro to mimo-v2.5

    Fixes 1 and 2 address the ACP runtime bug. Fix 3 is a workaround for the setSessionModel not reliably overriding the startup model.

    Suggestion

    The ACP runtime should pass the configured per-agent model as a --model flag when spawning the Claude Code process (or set ANTHROPIC_MODEL per-session), rather than relying solely on setSessionModel after startup. This would make the per-agent model override robust regardless of the user's global settings.json.

  5. steipete commented on Jun 1, 2026

    @steipete
    Contributor

    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.model to the delegate session initialization. Focused proof: src/agents/acp-spawn.test.ts plus extensions/acpx/src/runtime.test.ts.

  6. locked as resolved and limited conversation to collaborators on Jun 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Normal backlog priority with limited blast radius.clawsweeper:fix-shape-clearClawSweeper found a clear likely implementation shape for this issue.clawsweeper:queueable-fixClawSweeper marked this issue as an existing queue_fix_pr work candidate.clawsweeper:source-reproClawSweeper found a high-confidence source-level issue reproduction.impact:auth-providerAuth, provider routing, model choice, or SecretRef resolution may break.issue-rating: 🦞 diamond lobsterVery strong issue quality with high-confidence source-level or clear reproduction.

    Type

    No type

    Fields

    Priority

    None yet

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions