跳转至

Azure 端点

Azure OpenAI 端点

内置的 openai provider 可以通过覆盖基础 URL 将图像生成定向到 Azure OpenAI 资源。在图像生成路径上,OpenClaw 会检测 models.providers.openai.baseUrl 中的 Azure 主机名,并自动切换到 Azure 的请求格式。

Note

实时语音使用单独的配置路径(plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint),不受 models.providers.openai.baseUrl 的影响。其 Azure 设置请参阅 语音和言语 下的 实时语音 折叠面板。

在以下情况下使用 Azure OpenAI:

  • 你已经拥有 Azure OpenAI 订阅、配额或企业协议
  • 你需要 Azure 提供的区域数据驻留或合规控制
  • 你希望将流量保留在现有 Azure 租户内

配置

对于通过内置 openai provider 进行的 Azure 图像生成,请将 models.providers.openai.baseUrl 指向你的 Azure 资源,并将 apiKey 设置为 Azure OpenAI 密钥(不是 OpenAI Platform 密钥):

{
  models: {
    providers: {
      openai: {
        baseUrl: "https://<your-resource>.openai.azure.com",
        apiKey: "<azure-openai-api-key>",
      },
    },
  },
}

OpenClaw 会识别以下用于 Azure 图像生成路由的 Azure 主机后缀:

  • *.openai.azure.com
  • *.services.ai.azure.com
  • *.cognitiveservices.azure.com

对于在可识别 Azure 主机上发出的图像生成请求,OpenClaw 会:

  • 发送 api-key 头,而不是 Authorization: Bearer
  • 使用部署作用域路径(/openai/deployments/{deployment}/...)
  • 在每个请求中追加 ?api-version=...
  • 对 Azure 图像生成调用使用 600 秒的默认请求超时。每次调用的 timeoutMs 值仍会覆盖此默认值。

其他基础 URL(公共 OpenAI、OpenAI 兼容代理)保持标准的 OpenAI 图像请求格式。

Note

openai provider 的图像生成路径的 Azure 路由需要 OpenClaw 2026.4.22 或更高版本。较早版本会将任何自定义 openai.baseUrl 视为公共 OpenAI 端点,并在 Azure 图像部署上失败。

API 版本

设置 AZURE_OPENAI_API_VERSION 以将 Azure 图像生成路径固定到特定的 Azure 预览版或 GA 版本:

export AZURE_OPENAI_API_VERSION="2024-12-01-preview"

当该变量未设置时,默认值为 2024-12-01-preview。

模型名称即部署名称

Azure OpenAI 将模型绑定到部署。对于通过内置 openai provider 路由的 Azure 图像生成请求,OpenClaw 中的 model 字段必须是你在 Azure 门户中配置的 Azure 部署名称,而不是公共 OpenAI 模型 ID。

如果你创建了一个名为 gpt-image-2-prod 的部署,该部署提供 gpt-image-2:

/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1

相同的部署名称规则适用于所有通过内置 openai provider 路由的图像生成调用。

区域可用性

Azure 图像生成目前仅在部分区域可用(例如 eastus2、swedencentral、polandcentral、westus3、uaenorth)。在创建部署之前,请查阅 Microsoft 当前的区域列表,并确认你的区域提供该特定模型。

参数差异

Azure OpenAI 和公共 OpenAI 并不总是接受相同的图像参数。Azure 可能会拒绝公共 OpenAI 允许的选项(例如 gpt-image-2 上的某些 background 值),或者仅在特定模型版本上公开这些选项。这些差异来自 Azure 和底层模型,而非 OpenClaw。如果 Azure 请求因验证错误而失败,请在 Azure 门户中检查你的特定部署和 API 版本支持的参数集。

Note

Azure OpenAI 使用原生传输和兼容行为,但不会接收 OpenClaw 的隐藏归属标头——请参阅 高级配置 下的 原生路由与 OpenAI 兼容路由 折叠面板。

对于 Azure 上的聊天或 Responses 流量(图像生成之外),请使用入门流程或专用的 Azure provider 配置;仅设置 openai.baseUrl 不会自动采用 Azure 的 API/认证格式。存在一个单独的 azure-openai-responses/* provider;请参阅 服务端压缩折叠面板。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw