Summary

• Problem: provider media/image/audio HTTP paths were still rebuilding baseUrl, private-network allowance, default auth headers, and attribution/header precedence independently.
• Why it matters: phase 1 and phase 2 centralized request policy and model-path request shaping, but non-model HTTP paths were still a duplication hotspot for future proxy/custom-header/auth/TLS work.
• What changed: added resolveProviderHttpRequestConfig to the provider HTTP seam and migrated OpenAI-compatible audio, Deepgram audio, Gemini media-understanding, Gemini image generation, and Moonshot video to use it.
• What did NOT change (scope boundary): response parsing and provider-specific payload bodies stay provider-owned; stream wrapper consolidation is not part of this PR.

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 #
• Related refactor(providers): add internal request config seam #59454
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: provider HTTP call sites evolved separate request-building logic after model-path request shaping was centralized, so default auth/header/baseUrl behavior could drift by capability and provider.
• Missing detection / guardrail: there was no shared seam test locking caller-header precedence plus default-header application across non-model HTTP paths.
• Prior context (git blame, prior PR, issue, or refactor if known): this is the next phase after refactor(providers): add internal request config seam #59454, which introduced the internal request-config seam for model resolution.
• Why this regressed now: it is older duplication, not a fresh regression from refactor(providers): add internal request config seam #59454. That PR made the remaining gap more obvious because model and non-model request shaping no longer matched structurally.
• If unknown, what was ruled out: N/A

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/media-understanding/shared.test.ts plus existing provider tests for OpenAI audio, Deepgram, Moonshot, and Gemini media/image paths.
• Scenario the test should lock in: caller headers win over defaults; default auth headers are still injected when absent; explicit custom base URLs continue to enable private-network fetches for provider-owned endpoints.
• Why this is the smallest reliable guardrail: the shared helper is now the merge point, and the provider tests prove the migrated call sites still emit the expected requests.
• Existing test that already covers this (if any): provider-specific request-shape tests existed, but they did not lock in the shared merge contract.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• Providers that use the shared HTTP seam now resolve default auth headers, attribution headers, and explicit custom baseUrl handling through one path instead of per-provider merge logic.
• Explicit caller header overrides remain preserved.

Diagram (if applicable)

Before:
[provider http path] -> [manual baseUrl/auth/header merge] -> [POST]
[another provider path] -> [slightly different manual merge] -> [POST]

After:
[provider http path] -> [resolveProviderHttpRequestConfig] -> [provider payload + POST]

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22 / pnpm
• Model/provider: OpenAI-compatible audio, Deepgram, Google Gemini, Moonshot
• Integration/channel (if any): N/A
• Relevant config (redacted): default provider config plus explicit custom baseUrl in scoped tests

Steps

1. Run the affected media/image/audio providers with and without explicit header overrides.
2. Inspect the emitted request headers and URL construction.
3. Verify the shared helper preserves explicit headers and still injects defaults when absent.

Expected

• Provider requests keep existing payload shapes while sharing one header/baseUrl/private-network merge path.

Actual

• The migrated providers now use the shared helper and the targeted tests/build/check all pass.

Evidence

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

Human Verification (required)

• Verified scenarios: OpenAI audio attribution/auth override behavior, Deepgram auth/content-type defaults, Gemini media/image auth + baseUrl handling, Moonshot video request shaping, shared helper precedence tests.
• Edge cases checked: explicit auth/header override, fallback base URL without private-network enablement, custom configured base URL with provider-owned private-network allowance.
• What you did not verify: full pnpm test and live provider credentials.

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)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: the new helper is exported through openclaw/plugin-sdk/provider-http, so future changes to it become SDK-surface changes.
  • Mitigation: keep it narrow, additive, and covered by shared seam tests plus existing provider request-shape tests.
• Risk: migrating more providers later could accidentally over-generalize request shaping.
  • Mitigation: this PR centralizes only common transport/header/baseUrl behavior and leaves payload construction/provider response parsing local.