Summary

• Problem: src/agents/models-config.plan.ts:60-61 unconditionally awaits resolveImplicitProvidersImpl(...) (the provider-discovery scan) before reading cfg.models?.mode. When the user has set models.mode: "replace" to opt out of discovery, this still runs the full implicit-resolver — wasted work and (in some setups) 70+s of startup latency.
• Why it matters: The documented contract at src/config/schema.help.ts:924 is that models.mode = "replace" uses only the configured providers. Honoring it eliminates the discovery cost for replace-mode users and fixes the timing regression they were filing the issue about.
• What changed: Added a 3-line early-return at the top of resolveProvidersForModelsJsonWithDeps that short-circuits to mergeProviders({ implicit: {}, explicit: explicitProviders }) when cfg.models?.mode === "replace". The injected deps.resolveImplicitProviders seam used by tests is preserved for merge-mode callers.
• What did NOT change (scope boundary): merge/undefined paths are untouched. planOpenClawModelsJsonWithDeps (which also reads cfg.models?.mode at L156) is unchanged — its existing logic short-circuits cleanly on the empty implicit result. No public type changes. No new exports.

Mirrors the sibling short-circuit at src/flows/model-picker.ts:116-118 (loadPickerModelCatalog does the same if (cfg.models?.mode === "replace") return ... before its catalog load).

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

(Closest match: agents config plumbing; no checkbox fits cleanly.)

Linked Issue/PR

• Closes [Bug]: models.mode="replace" still triggers implicit provider discovery and causes large startup delays #66957
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: resolveProvidersForModelsJsonWithDeps ran the implicit provider resolver even when models.mode === "replace", violating the documented contract and adding 70+s of startup latency in replace-mode setups.
• Real environment tested: local clone built and tested on macOS arm64 (Node v24.7.0, pnpm 11.1.0, vitest 4.1.6).
• Exact steps or command run after this patch:

  node scripts/run-vitest.mjs run \
    src/agents/models-config.replace-mode-skip-implicit-discovery.test.ts \
    src/agents/models-config.applies-config-env-vars.test.ts \
    src/agents/models-config.providers.implicit.discovery-scope.test.ts \
    src/agents/models-config.merge.test.ts
  

• Evidence after fix:

   RUN  v4.1.6 /private/tmp/openclaw-triage-20pr/repo
  
   Test Files  2 passed (2)        # new test file (under 2 project lanes)
        Tests  6 passed (6)         # 3 scenarios × 2 lanes
   Test Files  6 passed (6)         # existing models-config tests
        Tests  46 passed (46)
  

  The new test file models-config.replace-mode-skip-implicit-discovery.test.ts has 3 scenarios:
  1. skips implicit discovery when models.mode === 'replace' — DI spy assertion not.toHaveBeenCalled, result contains only explicit providers.
  2. still resolves implicit when models.mode === 'merge' — spy called once, result merges both.
  3. still resolves implicit when models.mode is undefined (defaults to merge) — spy called once.
     Regression: all 46 existing tests across models-config.applies-config-env-vars.test.ts, models-config.providers.implicit.discovery-scope.test.ts, and models-config.merge.test.ts continue to pass — they use mode: undefined or merge, so they enter the same code path as before.
• Observed result after fix: all 52 tests pass. With mode: "replace" and an injected spy, resolveImplicitProviders is never called.
• What was not tested: I did not benchmark the wall-clock startup latency improvement in a real OpenClaw setup against the reporter's specific provider configuration (the issue body cites ~72s of pnpm tsx cold-load time). The new test proves the implicit-resolver call is genuinely skipped; converting that skip into measured-on-host latency win would require a configured agent with provider-discovery providers loaded.
• Before evidence (optional but encouraged): on unpatched main, the new test 1 fails — not.toHaveBeenCalled is violated because resolveImplicitProvidersImpl is awaited unconditionally before the mode is read.

Root Cause (if applicable)

• Root cause: the function reads explicitProviders first, then unconditionally awaits the implicit resolver, then merges. There is no mode check until planOpenClawModelsJsonWithDeps:156 — too late to skip the discovery work.
• Missing detection / guardrail: documented contract at src/config/schema.help.ts:924 ("replace uses only your configured providers") was not enforced anywhere in resolveProvidersForModelsJsonWithDeps. The new test locks the contract via spy assertion.
• Contributing context (if known): PR fix(agents): skip implicit provider discovery when models.mode is replace [AI-assisted] #73557 attempted a similar shape and was closed without merge. The shape used here mirrors the sibling pattern in src/flows/model-picker.ts:116-118, which is the canonical in-repo idiom for replace-mode short-circuits.

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/models-config.replace-mode-skip-implicit-discovery.test.ts (new).
• Scenario the test should lock in: with cfg.models.mode === "replace", the injected resolveImplicitProviders spy must never be called and the result must contain only the explicit-provider entries.
• Why this is the smallest reliable guardrail: uses the same DI seam (deps.resolveImplicitProviders) the codebase already uses for testing the merge path. No new mocking infrastructure required.
• Existing test that already covers this (if any): none — models-config.applies-config-env-vars.test.ts and models-config.providers.implicit.discovery-scope.test.ts exercise the merge/undefined paths only.

User-visible / Behavior Changes

For users with models.mode: "replace":

• Implicit provider discovery no longer runs. This is the documented contract.
• Startup time drops by the cost of the discovery scan (reported as 70+s in some setups; varies by provider count and pnpm tsx cold-load behavior).
• The final models.json contents are identical to what the merge-mode emitter would produce given zero implicit providers — i.e. the providers map is exactly the user's cfg.models.providers.

No change for merge/undefined mode users.

Diagram (if applicable)

N/A

AI Disclosure

This PR was authored with AI assistance (Claude Code, Opus 4.7). The fix shape was selected after a 5-lens design debate (MVD, defensive, pattern-match, performance, DX) — all five lenses converged on the same 3-line early-return mirroring src/flows/model-picker.ts:116-118. The chosen variant is the smallest viable diff that honors the documented contract.