Skip to content

docs(providers): add Azure OpenAI setup page and directory entry#110299

Open
misbahsy wants to merge 1 commit into
openclaw:mainfrom
misbahsy:docs/azure-openai-provider
Open

docs(providers): add Azure OpenAI setup page and directory entry#110299
misbahsy wants to merge 1 commit into
openclaw:mainfrom
misbahsy:docs/azure-openai-provider

Conversation

@misbahsy

@misbahsy misbahsy commented Jul 18, 2026

Copy link
Copy Markdown

What Problem This Solves

Azure OpenAI chat/Responses is supported by the core azure-openai-responses
model API, but it is effectively undiscoverable in the docs. The provider
directory (docs/providers/index.md) only lists Azure Speech, so a new user
who has an Azure OpenAI key reasonably concludes chat/Responses is not
supported. The only mention of the setup path lived as a passing reference on
the OpenAI page that pointed readers into the unrelated "Server-side compaction"
accordion instead of a real walkthrough.

Why This Change Was Made

Adds a dedicated Azure OpenAI provider page documenting the direct
API-key azure-openai-responses path (v1 vs classic endpoint, deployment name
as model id, AZURE_OPENAI_API_VERSION default, onboarding host recognition,
manual config, and verify commands). It also:

  • adds Azure OpenAI to the provider directory (docs/providers/index.md),
  • repoints the OpenAI page's Azure note to the new page instead of the
    compaction accordion,
  • adds a nav entry and a /providers/azure-openai-responses -> /providers/azure-openai
    redirect in docs.json.

Non-goals: this page does not change any runtime behavior and does not duplicate
the existing OpenAI-page section on Azure image endpoints, nor the Microsoft
Foundry plugin (Entra ID / Foundry discovery) — it routes to both. Reported
reliability issues are listed as open, user-reported, and not maintainer-confirmed
so readers can weigh them without the docs asserting unverified behavior.

User Impact

Users with an Azure OpenAI resource can now find a single page that walks them
through configuring chat/Responses, understand the v1 vs classic endpoint
choice, know that the model id must be the Azure deployment name, and see the
open reported caveats before relying on the path in production.

Evidence

Documentation-only change (141 insertions across 4 files). Claims in the page
were derived from and cross-checked against current core source:

  • Model API registered: src/config/types.models.ts (azure-openai-responses).
  • Transport + defaults: src/agents/openai-responses-transport.ts
    (DEFAULT_AZURE_OPENAI_API_VERSION = "preview", AZURE_OPENAI_API_VERSION,
    AZURE_OPENAI_DEPLOYMENT_NAME_MAP, v1 vs classic via
    isOpenAICompatibleAzureResponsesBaseUrl, deployment-name-as-model).
  • Onboarding host recognition: src/commands/onboard-custom-config.ts
    (*.openai.azure.com, *.services.ai.azure.com).
  • Verify commands: --provider / --probe --probe-provider in
    src/cli/models-cli.ts.
  • Cross-link anchor #azure-openai-endpoints exists on the OpenAI page.

Links are root-relative with no .md suffix and the directory entry is
alphabetically ordered per the docs guide.

Related (open, user-reported): #79570, #80926, #102907

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation size: XS labels Jul 18, 2026
@clawsweeper clawsweeper Bot added rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. labels Jul 18, 2026
@clawsweeper

clawsweeper Bot commented Jul 18, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed July 17, 2026, 9:45 PM ET / July 18, 2026, 01:45 UTC.

Summary
The branch adds an Azure OpenAI provider setup page, provider-directory entry, docs navigation entry, legacy URL redirect, and an OpenAI-page cross-link to the new guide.

PR surface: Docs +138. Total +138 across 4 files.

Reproducibility: not applicable. the PR changes documentation only. The remaining verification is that the documented commands and configuration map accurately to current runtime behavior and that the docs build accepts the page.

Review metrics: none identified.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🌊 off-meta tidepool
Patch quality: 🦐 gold shrimp
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • Rebase or refresh against current main, then resolve and rerun the failing check-docs job.
  • Verify the published setup details against the current Azure transport, onboarding, and model CLI contracts before requesting another review.

Risk before merge

  • [P1] The failed documentation check leaves the published navigation and page validation unresolved; refresh the branch against current main and inspect the failing job before merge.
  • [P1] The new page documents provider configuration and endpoint behavior, so each setup claim should be checked against the current Azure transport and onboarding contracts before publication.

Maintainer options:

  1. Decide the mitigation before merge
    Keep one dedicated Azure OpenAI guide for the existing direct API-key route, but land it only after the docs check passes and the endpoint, deployment-name, environment-variable, and verification instructions are confirmed against current main.
  2. Pause or close
    Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

  • [P2] The only known blocker is an unresolved documentation-check failure; its output must be inspected before a concrete, safe repair can be scoped.

Security
Cleared: The supplied diff is documentation-only and introduces no dependency, workflow, permission, secret-handling, or executable supply-chain change.

Review details

Best possible solution:

Keep one dedicated Azure OpenAI guide for the existing direct API-key route, but land it only after the docs check passes and the endpoint, deployment-name, environment-variable, and verification instructions are confirmed against current main.

Do we have a high-confidence way to reproduce the issue?

Not applicable: the PR changes documentation only. The remaining verification is that the documented commands and configuration map accurately to current runtime behavior and that the docs build accepts the page.

Is this the best way to solve the issue?

Unclear: a dedicated provider page is a plausible maintainable solution to the discoverability gap, but the current environment could not verify the page’s detailed instructions against the current source or diagnose the failing docs check.

AGENTS.md: unclear because the file could not be read completely.

Codex review notes: model internal, reasoning high; reviewed against 75e4103c5738.

Label changes

Label changes:

  • add P3: This is a small documentation discoverability improvement for an existing provider path, with no runtime change in the branch.
  • add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
  • add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Label justifications:

  • P3: This is a small documentation discoverability improvement for an existing provider path, with no runtime change in the branch.
  • rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Evidence reviewed

PR surface:

Docs +138. Total +138 across 4 files.

View PR surface stats
Area Files Added Removed Net
Source 0 0 0 0
Tests 0 0 0 0
Docs 4 141 3 +138
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 4 141 3 +138

What I checked:

Likely related people:

  • unresolved: The environment prevented the required source and git-history inspection, so no current-main feature-history owner can be identified without guessing from the PR author. (role: ownership unresolved; confidence: low; files: docs/providers/azure-openai.md, src/agents/openai-responses-transport.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@BradGroux BradGroux mentioned this pull request Jul 18, 2026
Draft
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

docs Improvements or additions to documentation P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. size: XS status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@misbahsy