PR #80488: fix(auth): resolve per-model api override in provider hook refs

• Repository: openclaw/openclaw
• Author: huveewomg
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/80488

Description (problem / solution / changelog)

Summary

• Problem: When a model within a custom provider overrides api (e.g., api: "ollama" under a provider with api: "openai-completions"), the auth resolution path fails with "No API provider registered for api: ollama" because resolveProviderHookRefs only reads the provider-level providerConfig.api, not the model's effective api.
• Why it matters: Per-model api overrides are accepted by the config schema and respected by the streaming path (ensureCustomApiRegistered in provider-stream.ts), but the auth path doesn't follow — making the feature partially broken. This blocks a common use case: a local router/proxy with multiple backends behind a single provider, where some models need a different transport protocol.
• What changed: Added an optional modelApi parameter to resolveProviderHookRefs that takes precedence over providerConfig.api via ?? fallback. Threaded it through resolveProviderSyntheticAuthWithPlugin, shouldDeferProviderSyntheticProfileAuthWithPlugin, resolveProviderSyntheticRuntimeAuth, resolveSyntheticLocalProviderAuth, and resolveApiKeyForProvider.
• What did NOT change (scope boundary): No changes to streaming, model resolution, provider discovery, or plugin registration. All new parameters are optional — existing callers are unaffected. No config schema changes.

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 #80487
• Related #57099, #57811, #63218
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: Per-model api: "ollama" override within a non-ollama provider fails with "No API provider registered for api: ollama".
• Real environment tested: OpenClaw 2026.5.6 Docker, custom provider routing through a local LLM proxy with mixed openai-completions and ollama models.
• Exact steps or command run after this patch:
  1. Configure a provider with api: "openai-completions" as default
  2. Add a model with api: "ollama" and baseUrl pointing to a local Ollama instance
  3. Send a chat message using that model
• Evidence after fix: Code-level verification only — the fix adds modelApi to resolveProviderHookRefs so "ollama" appears in the provider refs when a model overrides api. Unable to build and run a patched OpenClaw locally (@openclaw/fs-safe build toolchain not available on contributor environment).
• Observed result after fix: Not yet verified at runtime. Requesting maintainer guidance on testing, or verification via CI.
• What was not tested: Runtime behavior with a patched build. The fix is based on code path analysis — confirmed the exact line where model-level api is dropped (provider-runtime.ts:103).
• Before evidence: "No API provider registered for api: ollama" confirmed on OpenClaw 2026.5.6 when using per-model api: "ollama" override within a provider configured with api: "openai-completions".

Root Cause

• Root cause: resolveProviderHookRefs reads providerConfig.api which is the provider-level field. When a model overrides api, the override is resolved at the model level but never passed to the hook resolution function. The Ollama plugin's hooks (synthetic auth, stream creation) are only discovered when "ollama" appears in the provider refs — which it doesn't when the provider itself uses "openai-completions".
• Missing detection / guardrail: No test covers the case where a model-level api override differs from the provider-level api. The existing synthetic-auth-discovery tests only cover provider-level api configurations.
• Contributing context: #63218 fixed multi-instance Ollama routing (multiple providers each with api: "ollama"), but that fix operates at the provider level. Per-model overrides are a distinct code path that wasn't addressed.

Regression Test Plan

• 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/model-auth.test.ts
• Scenario the test should lock in: resolveApiKeyForProvider with a custom provider using api: "openai-completions" at provider level and modelApi: "ollama" passed as override — should resolve via the Ollama plugin's synthetic auth, not fail with "No API provider registered".
• Why this is the smallest reliable guardrail: Tests the exact junction point where provider-level and model-level api diverge in the auth resolution chain.
• Existing test that already covers this: None — existing tests in model-auth.test.ts only cover provider-level api: "ollama" configurations.
• If no new test is added, why not: Contributor does not have the full build toolchain for @openclaw/fs-safe to run tests locally. Happy to add the test if a maintainer can advise on the local test setup, or if a maintainer prefers to add it during review.

User-visible / Behavior Changes

Models with per-model api overrides (e.g., api: "ollama" within an openai-completions provider) now correctly resolve authentication through the overridden API's plugin hooks. Previously these models failed immediately with "No API provider registered".

Diagram

Before:
  model.api = "ollama" (override)
    → resolveProviderHookRefs(provider, providerConfig)
    → reads providerConfig.api = "openai-completions"
    → refs = ["my-router", "openai-completions"]
    → ollama plugin NOT found → auth fails

After:
  model.api = "ollama" (override)
    → resolveProviderHookRefs(provider, providerConfig, modelApi="ollama")
    → reads modelApi ?? providerConfig.api = "ollama"
    → refs = ["my-router", "ollama"]
    → ollama plugin FOUND → synthetic auth resolves

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No — same auth resolution logic, just broader discovery scope
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Linux (Docker)
• Runtime/container: OpenClaw 2026.5.6
• Model/provider: Custom provider with api: "openai-completions", model override api: "ollama"
• Integration/channel: Telegram (group chat)
• Relevant config (redacted):

{
  models: {
    providers: {
      "my-router": {
        baseUrl: "http://localhost:8080/v1",
        api: "openai-completions",
        models: [
          { id: "my-router/cloud-model", name: "Cloud Model" },
          { id: "my-router/local-llama", name: "Local Llama", api: "ollama", baseUrl: "http://localhost:11434" }
        ]
      }
    }
  }
}

Steps

1. Set primary model to my-router/local-llama
2. Send a chat message
3. Observe auth resolution

Expected

• Model resolves synthetic Ollama auth and responds

Actual (before fix)

• "No API provider registered for api: ollama"

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers

Before: Error: No API provider registered for api: ollama on every request to the model with api: "ollama" override. Confirmed on OpenClaw 2026.5.6.

After: Not yet verified at runtime — code-level analysis only. CI should validate.

Human Verification

• Verified scenarios: Code path analysis — traced resolveProviderHookRefs → resolveProviderSyntheticAuthWithPlugin → resolveApiKeyForProvider and confirmed the model-level api is never included in hook refs without this fix. Verified existing callers are unaffected (all new params are optional with ?? fallback).
• Edge cases checked (code-level): Provider with no api field (defaults) — modelApi ?? undefined falls through, no change. Provider with api: "ollama" at provider level — modelApi ?? "ollama" produces same result. Model without api override — modelApi not passed, existing behavior preserved.
• What you did not verify: Runtime behavior with a patched build. Could not run tests locally due to missing @openclaw/fs-safe build toolchain. Relying on CI for validation.

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 — all new parameters are optional
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: A model-level api override could cause the auth resolver to discover an unexpected plugin if the api string matches a plugin the user didn't intend.
  • Mitigation: The modelApi parameter is only used when explicitly passed by the caller — existing code paths without modelApi behave identically. The ?? fallback ensures provider-level api is still the default.

Changed files

• src/agents/model-auth.test.ts (modified, +37/-0)
• src/agents/model-auth.ts (modified, +5/-1)
• src/plugins/provider-runtime.ts (modified, +6/-4)