Summary

Describe the problem and fix in 2–5 bullets:

• Problem: Azure OpenAI /chat/completions calls returned 404 because api-version wasn’t being appended correctly.
• Why it matters: Azure endpoints require api-version; without it, web chat and embedded runs fail.
• What changed: Added models.providers.*.apiVersion, captured it in onboarding, and injected api-version at request time for Azure chat completions.
• What did NOT change (scope boundary): Inline/provider entries without baseUrl now surface as “Unknown model” instead of failing later at request time.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• 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 #

User-visible / Behavior Changes

• New config field: models.providers.*.apiVersion for OpenAI‑compatible chat completions.
• Onboard now prompts for API version for Azure endpoints and supports --custom-api-version.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (Yes)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:
  • Adds a query parameter to Azure /chat/completions requests only; no new endpoints.

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22 + pnpm
• Model/provider: Azure OpenAI (OpenAI‑compatible)
• Integration/channel (if any): Web Control UI
• Relevant config (redacted):
  • models.providers.custom-*.baseUrl: https://<resource>.cognitiveservices.azure.com/openai/deployments/o1
  • models.providers.custom-*.apiVersion: 2025-01-01-preview

  "models": {
    "mode": "merge",
    "providers": {
      "custom-hyh-m7yee95k-eastus2-cognitiveservices-azure-com": {
        "baseUrl": "https://hyh-m7yee95k-eastus2.cognitiveservices.azure.com/openai/deployments/o1",
        "apiKey": "xxxxx",
        "apiVersion": "2025-01-01-preview",
        "api": "openai-completions",
        "models": [
          {
            "id": "o1",
            "name": "o1 (Custom Provider)",
            "reasoning": false,
            "input": [
              "text"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 16000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },

Steps

1. Configure Azure OpenAI custom provider with apiVersion.
2. Start gateway and send a message from Web Control UI.
3. Observe request includes api-version and succeeds.

Expected

• Chat completion succeeds without 404.

Actual

• 404 from Azure when api-version missing.

Evidence

Attach at least one:

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

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: Azure OpenAI chat via Web UI succeeds with api-version.
• Edge cases checked: None.
• What you did not verify: Non‑Azure providers; non‑chat completion endpoints.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (Yes)
• Migration needed? (No)
• If yes, exact upgrade steps:
  • Add models.providers.*.apiVersion only for Azure OpenAI providers that require it.

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: Remove models.providers.*.apiVersion or revert the code.
• Files/config to restore: ~/.openclaw/openclaw.json provider block.
• Known bad symptoms reviewers should watch for: Azure chat completions returning 404.

Risks and Mitigations

• Risk: API version injected on Azure hosts could be incorrect if misconfigured.
  • Mitigation: apiVersion is opt‑in and only applied for configured Azure hosts and /chat/completions paths.