PR #73042: fix(nvidia): add NVIDIA_API_KEY marker to provider catalog output

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

Description (problem / solution / changelog)

Fixes #73013

Summary

• Problem: buildNvidiaProvider() in extensions/nvidia/provider-catalog.ts returns a ModelProviderConfig without an apiKey field. When that config is persisted to ~/.openclaw/agents/<id>/agent/models.json, pi-coding-agent's validateConfig() rejects the entry because non-built-in providers with custom models must declare apiKey. The whole models.json then fails validation, silently dropping every other custom provider entry in the same file (codex, xai, github-copilot, etc.) and falling through to built-in models only.
• Why it matters: A single missing field on one bundled plugin silently disables every custom provider a user has registered. There is no warn/error log — the file just stops loading. Reporter discovered this only by direct ModelRegistry.find('nvidia', ...) probing.
• What changed: Added apiKey: "NVIDIA_API_KEY" to the object returned by buildNvidiaProvider(). This is the bare env-var name; OpenClaw's resolveUsableCustomProviderApiKey already recognizes that form and resolves to process.env.NVIDIA_API_KEY at infer time. Same pattern already used by extensions/codex/provider-catalog.ts:68 (apiKey: CODEX_APP_SERVER_AUTH_MARKER). Added a regression test asserting the field is present.
• What did NOT change (scope boundary): Auth manifest (already declares envVar: "NVIDIA_API_KEY" in extensions/nvidia/index.ts:21). Model definitions, baseUrl, api, contextWindow, costs. Other provider plugins (the same omission may exist elsewhere — left for follow-up issues so this PR stays focused). Did not change resolveUsableCustomProviderApiKey or the validation contract — the fix conforms to existing behavior.

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 #73013
• Related #
• This PR fixes a bug or regression

Root Cause

• Root cause: When catalog.buildProvider is called and its result is persisted to models.json, downstream consumers (pi-coding-agent's validateConfig()) require apiKey for any non-built-in provider that declares custom models. buildNvidiaProvider() omitted that field, so the persisted entry failed validation. The validation failure isn't local to NVIDIA — it throws synchronously, which causes the entire models.json parse to fail, silently dropping every other custom provider entry in the same file.
• Missing detection / guardrail: extensions/nvidia/provider-catalog.test.ts only asserted baseUrl, api, and the model id list. It did not assert the presence of apiKey, so the missing field never tripped a test.
• Contributing context (if known): Several other provider plugins already include apiKey in their buildProvider output — codex uses CODEX_APP_SERVER_AUTH_MARKER, anthropic uses an actual credential value in provider-discovery.ts. The convention exists; nvidia just missed it.

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: extensions/nvidia/provider-catalog.test.ts
• Scenario the test should lock in: buildNvidiaProvider().apiKey === "NVIDIA_API_KEY" — explicit assertion that the env-var marker is present and exactly matches the env-var name declared in the auth manifest.
• Why this is the smallest reliable guardrail: buildNvidiaProvider is a pure function with no I/O. Asserting one field is enough; the wider validation contract is covered by pi-coding-agent's own tests.
• Existing test that already covers this (if any): None — the existing builds the bundled NVIDIA provider defaults test asserts baseUrl, api, and model ids, but never reads apiKey.
• If no new test is added, why not: N/A — 1 new test added.

User-visible / Behavior Changes

• A user who has registered other custom providers (codex, xai, github-copilot, etc.) in ~/.openclaw/agents/<id>/agent/models.json will no longer have those entries silently dropped because of NVIDIA's missing field.
• For users who only configured NVIDIA: nvidia/nemotron-3-super-120b-a12b and the other three NVIDIA models now appear configured (instead of configured,missing) when NVIDIA_API_KEY is set in the env.
• No defaults removed or renamed.

Diagram

models.json validation chain

Before:
[user sets NVIDIA_API_KEY, runs `openclaw models list`]
  -> models.json contains nvidia entry without apiKey
  -> pi-coding-agent validateConfig() throws
  -> models.json fails to load entirely
  -> codex/xai/copilot/... all silently dropped
  -> registry falls through to built-in models only
  -> nvidia/* shows as `configured,missing`

After:
[user sets NVIDIA_API_KEY, runs `openclaw models list`]
  -> models.json contains nvidia entry with apiKey: "NVIDIA_API_KEY"
  -> pi-coding-agent validateConfig() accepts the entry
  -> models.json loads successfully; all custom providers stay registered
  -> resolveUsableCustomProviderApiKey() resolves "NVIDIA_API_KEY" to process.env at infer time
  -> nvidia/* shows as `configured`

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No (the field is the env-var name, not the secret value; existing resolveUsableCustomProviderApiKey reads the actual secret from process.env at infer time)
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: Linux (any)
• Runtime/container: Node 22.14+
• Model/provider: nvidia/nemotron-3-super-120b-a12b (NVIDIA NIM)
• Integration/channel (if any): N/A — provider plugin
• Relevant config (redacted): NVIDIA_API_KEY env var set; one or more custom providers registered in ~/.openclaw/agents/<id>/agent/models.json

Steps

1. Set NVIDIA_API_KEY env var.
2. Have at least one other custom provider entry in ~/.openclaw/agents/<id>/agent/models.json alongside the bundled nvidia entry.
3. Run openclaw models list.

Expected

• nvidia/nemotron-3-super-120b-a12b row tagged configured.
• All other custom providers in the same models.json continue to load.

Actual (before fix)

• nvidia/nemotron-3-super-120b-a12b row tagged configured,missing.
• ModelRegistry.find('nvidia', 'nemotron-3-super-120b-a12b') returns null.
• All other custom providers in the same file silently disappear.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

$ pnpm test extensions/nvidia
 Test Files  2 passed (2)
      Tests  3 passed (3)   # 2 existing + 1 new (apiKey marker assertion)

pnpm check:changed is green: conflict markers, typecheck, lint, runtime import cycles all pass.

Human Verification (required)

• Verified scenarios:
  • Targeted vitest run for extensions/nvidia (3/3 pass locally on Node 22).
  • Full pnpm check:changed gate (all lanes green).
  • Cross-checked the convention by reading extensions/codex/provider-catalog.ts:68 (apiKey: CODEX_APP_SERVER_AUTH_MARKER) — the new apiKey: "NVIDIA_API_KEY" field follows the same shape and matches the auth manifest's declared envVar exactly.
  • Confirmed extensions/nvidia/index.ts:21 declares envVar: "NVIDIA_API_KEY", so the marker string in buildNvidiaProvider is consistent with the auth method.
• Edge cases checked:
  • No other place writes to NVIDIA's persisted models.json (grep confirms buildNvidiaProvider is the only producer).
  • Test still asserts the bundled defaults (baseUrl, api, model ids) so we haven't regressed coverage of the rest of the config shape.
• What you did not verify:
  • Live end-to-end against a real NVIDIA API key (openclaw models list against an actual environment with NVIDIA_API_KEY set and pi-coding-agent loaded). I do not have a NIM subscription. The fix is mechanical and matches an existing convention, and the unit test locks in the field shape; the live path (resolveUsableCustomProviderApiKey reading process.env.NVIDIA_API_KEY) is already covered by other plugins that use bare env-var markers.
  • The same field omission may exist on other provider plugins. The reporter notes "the same fix likely applies to any other plugin whose provider id matches the model id prefix." I scoped this PR to NVIDIA only; auditing the rest is a separate task.

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.

(Both will be checked once review activity lands. Currently no bot review conversations on this PR.)

Compatibility / Migration

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

Risks and Mitigations

• Risk: apiKey: "NVIDIA_API_KEY" is a marker value, not a real secret; if resolveUsableCustomProviderApiKey were ever changed to require a literal secret (instead of resolving env-var names), this entry would break.
  • Mitigation: codex already uses the same bare-marker convention (CODEX_APP_SERVER_AUTH_MARKER), so any such future change would have to handle that case generically. We follow an established pattern.
• Risk: writing the env-var name into a file might look confusing to users who inspect models.json directly.
  • Mitigation: the value is a documented marker, not a credential. The file's existing style (codex's marker) sets the precedent. A docs improvement covering this convention would be a separate PR.
• Risk: the same omission likely exists on other plugins (the reporter flagged this).
  • Mitigation: scoped to NVIDIA in this PR per the original issue. If a maintainer wants a sweep, that's a separate refactor — happy to follow up if asked.

Changed files

• extensions/nvidia/provider-catalog.test.ts (modified, +6/-0)
• extensions/nvidia/provider-catalog.ts (modified, +12/-4)