From b145862a4255441a19edf66029b2ce3edc2f15c4 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Thu, 23 Apr 2026 12:49:52 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@bc01cbb8a2ac894fc5dea9e49419312160b5b5b5 --- .openclaw-sync/source.json | 4 +- docs/cli/status.md | 1 + docs/providers/openai.md | 128 +++++++++++++++++++++++++++++++++ docs/tools/image-generation.md | 4 ++ docs/tools/slash-commands.md | 3 +- 5 files changed, 137 insertions(+), 3 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index c54263b25..9fdc1d47f 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "57f28285be43a2d6a68cbfa5d8a3ca16720b3ac9", - "syncedAt": "2026-04-23T09:04:10.440Z" + "sha": "bc01cbb8a2ac894fc5dea9e49419312160b5b5b5", + "syncedAt": "2026-04-23T12:49:51.488Z" } diff --git a/docs/cli/status.md b/docs/cli/status.md index 17dc7c186..db69b8589 100644 --- a/docs/cli/status.md +++ b/docs/cli/status.md @@ -21,6 +21,7 @@ Notes: - `--deep` runs live probes (WhatsApp Web + Telegram + Discord + Slack + Signal). - `--usage` prints normalized provider usage windows as `X% left`. +- Session status output now separates `Runtime:` from `Runner:`. `Runtime` is the execution path and sandbox state (`direct`, `docker/*`), while `Runner` tells you whether the session is using embedded Pi, a CLI-backed provider, or an ACP harness backend such as `codex (acp/acpx)`. - MiniMax's raw `usage_percent` / `usagePercent` fields are remaining quota, so OpenClaw inverts them before display; count-based fields win when present. `model_remains` responses prefer the chat-model entry, derive the window label from timestamps when needed, and include the model name in the plan label. - When the current session snapshot is sparse, `/status` can backfill token and cache counters from the most recent transcript usage log. Existing nonzero live values still win over transcript fallback values. - Transcript fallback can also recover the active runtime model label when the live session entry is missing it. If that transcript model differs from the selected model, status resolves the context window against the recovered runtime model instead of the selected one. diff --git a/docs/providers/openai.md b/docs/providers/openai.md index e3c9a1891..c4efcfb63 100644 --- a/docs/providers/openai.md +++ b/docs/providers/openai.md @@ -393,6 +393,134 @@ Legacy `plugins.entries.openai.config.personality` is still read as a compatibil +## Azure OpenAI endpoints + +The bundled `openai` provider can target an Azure OpenAI resource for image +generation by overriding the base URL. On the image-generation path, OpenClaw +detects Azure hostnames on `models.providers.openai.baseUrl` and switches to +Azure's request shape automatically. + + +Realtime voice uses a separate configuration path +(`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`) +and is not affected by `models.providers.openai.baseUrl`. See the **Realtime +voice** accordion under [Voice and speech](#voice-and-speech) for its Azure +settings. + + +Use Azure OpenAI when: + +- You already have an Azure OpenAI subscription, quota, or enterprise agreement +- You need regional data residency or compliance controls Azure provides +- You want to keep traffic inside an existing Azure tenancy + +### Configuration + +For Azure image generation through the bundled `openai` provider, point +`models.providers.openai.baseUrl` at your Azure resource and set `apiKey` to +the Azure OpenAI key (not an OpenAI Platform key): + +```json5 +{ + models: { + providers: { + openai: { + baseUrl: "https://.openai.azure.com", + apiKey: "", + }, + }, + }, +} +``` + +OpenClaw recognizes these Azure host suffixes for the Azure image-generation +route: + +- `*.openai.azure.com` +- `*.services.ai.azure.com` +- `*.cognitiveservices.azure.com` + +For image-generation requests on a recognized Azure host, OpenClaw: + +- Sends the `api-key` header instead of `Authorization: Bearer` +- Uses deployment-scoped paths (`/openai/deployments/{deployment}/...`) +- Appends `?api-version=...` to each request + +Other base URLs (public OpenAI, OpenAI-compatible proxies) keep the standard +OpenAI image request shape. + + +Azure routing for the `openai` provider's image-generation path requires +OpenClaw 2026.4.22 or later. Earlier versions treat any custom +`openai.baseUrl` like the public OpenAI endpoint and will fail against Azure +image deployments. + + +### API version + +Set `AZURE_OPENAI_API_VERSION` to pin a specific Azure preview or GA version +for the Azure image-generation path: + +```bash +export AZURE_OPENAI_API_VERSION="2024-12-01-preview" +``` + +The default is `2024-12-01-preview` when the variable is unset. + +### Model names are deployment names + +Azure OpenAI binds models to deployments. For Azure image-generation requests +routed through the bundled `openai` provider, the `model` field in OpenClaw +must be the **Azure deployment name** you configured in the Azure portal, not +the public OpenAI model id. + +If you create a deployment called `gpt-image-2-prod` that serves `gpt-image-2`: + +``` +/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1 +``` + +The same deployment-name rule applies to image-generation calls routed through +the bundled `openai` provider. + +### Regional availability + +Azure image generation is currently available only in a subset of regions +(for example `eastus2`, `swedencentral`, `polandcentral`, `westus3`, +`uaenorth`). Check Microsoft's current region list before creating a +deployment, and confirm the specific model is offered in your region. + +### Parameter differences + +Azure OpenAI and public OpenAI do not always accept the same image parameters. +Azure may reject options that public OpenAI allows (for example certain +`background` values on `gpt-image-2`) or expose them only on specific model +versions. These differences come from Azure and the underlying model, not +OpenClaw. If an Azure request fails with a validation error, check the +parameter set supported by your specific deployment and API version in the +Azure portal. + + +Azure OpenAI uses native transport and compat behavior but does not receive +OpenClaw's hidden attribution headers. See the **Native vs OpenAI-compatible +routes** accordion under [Advanced configuration](#advanced-configuration) +for details. + + + +For a separate Azure OpenAI Responses provider (distinct from the `openai` +provider), see the `azure-openai-responses/*` model refs in the +[Server-side compaction](#server-side-compaction-responses-api) accordion. + + + +Azure chat and Responses traffic need Azure-specific provider/API config in +addition to a base URL override. If you want Azure model calls beyond image +generation, use the onboarding flow or a provider config that sets the +appropriate Azure API/auth shape rather than assuming `openai.baseUrl` alone +is enough. + + ## Advanced configuration diff --git a/docs/tools/image-generation.md b/docs/tools/image-generation.md index 4b7a0789b..a09842f9f 100644 --- a/docs/tools/image-generation.md +++ b/docs/tools/image-generation.md @@ -160,6 +160,10 @@ Edit with multiple references: /tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024 ``` +To route OpenAI image generation through an Azure OpenAI deployment instead +of `api.openai.com`, see [Azure OpenAI endpoints](/providers/openai#azure-openai-endpoints) +in the OpenAI provider docs. + MiniMax image generation is available through both bundled MiniMax auth paths: - `minimax/image-01` for API-key setups diff --git a/docs/tools/slash-commands.md b/docs/tools/slash-commands.md index 0b9bd0e92..738d19218 100644 --- a/docs/tools/slash-commands.md +++ b/docs/tools/slash-commands.md @@ -108,7 +108,7 @@ Built-in commands available today: - `/help` shows the short help summary. - `/commands` shows the generated command catalog. - `/tools [compact|verbose]` shows what the current agent can use right now. -- `/status` shows runtime status, including provider usage/quota when available. +- `/status` shows runtime status, including `Runtime`/`Runner` labels and provider usage/quota when available. - `/tasks` lists active/recent background tasks for the current session. - `/context [list|detail|json]` explains how context is assembled. - `/export-session [path]` exports the current session to HTML. Alias: `/export`. @@ -229,6 +229,7 @@ of treating `/tools` as a static catalog. - **Provider usage/quota** (example: “Claude 80% left”) shows up in `/status` for the current model provider when usage tracking is enabled. OpenClaw normalizes provider windows to `% left`; for MiniMax, remaining-only percent fields are inverted before display, and `model_remains` responses prefer the chat-model entry plus a model-tagged plan label. - **Token/cache lines** in `/status` can fall back to the latest transcript usage entry when the live session snapshot is sparse. Existing nonzero live values still win, and transcript fallback can also recover the active runtime model label plus a larger prompt-oriented total when stored totals are missing or smaller. +- **Runtime vs runner:** `/status` reports `Runtime` for the effective execution path and sandbox state, and `Runner` for who is actually running the session: embedded Pi, a CLI-backed provider, or an ACP harness/backend. - **Per-response tokens/cost** is controlled by `/usage off|tokens|full` (appended to normal replies). - `/model status` is about **models/auth/endpoints**, not usage.