——
OpenClaw 修复 Azure OpenAI 图像生成：3 步配置指南
OpenClaw 最新版本已正式支持 Azure OpenAI Service 的图像生成功能，解决了此前仅支持标准 OpenAI 端点的限制。本文将详细介绍该修复的技术背景、配置方法及验证步骤，帮助开发者无缝集成企业级 AI 图像生成能力。
—
问题背景：为什么需要 Azure OpenAI 支持？
在之前的版本中，OpenClaw 的图像生成模块（image-generation-provider）仅兼容标准 OpenAI API 端点（api.openai.com）。对于使用 Azure OpenAI Service 的企业用户而言，这造成了以下障碍：
- 合规要求：企业数据需留在 Azure 云环境内
- 网络策略：内部网络可能限制对外部 API 的直接访问
- 统一计费：希望集中使用 Azure 订阅管理 AI 服务成本
GitHub Issue #70487 记录了这一需求，而 PR #70570 现已完成修复。
—
技术实现：核心改动解析
端点适配机制
修复后的代码通过检测配置中的 baseURL 参数，自动识别 Azure OpenAI 端点格式：
// 标准 OpenAI 端点
const openAIConfig = {
baseURL: 'https://api.openai.com/v1',
apiKey: process.env.OPENAI_API_KEY
};
// Azure OpenAI 端点（新增支持）
const azureConfig = {
baseURL: 'https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}',
apiKey: process.env.AZURE_OPENAI_API_KEY,
defaultHeaders: {
'api-key': process.env.AZURE_OPENAI_API_KEY // Azure 使用 header 认证
}
};
关键差异处理
| 特性 | 标准 OpenAI | Azure OpenAI |
|:—|:—|:—|
| 认证方式 | Authorization: Bearer {key} | api-key: {key} header |
| 端点格式 | /v1/images/generations | /images/generations?api-version=2024-02-01 |
| 模型指定 | model: "dall-e-3" | 通过 deployment ID 隐式指定 |
—
配置指南：3 步完成集成
第一步：获取 Azure OpenAI 凭证
登录 Azure 门户，完成以下操作：
1. 创建 Azure OpenAI 资源
2. 在 模型部署 中部署 dall-e-3 模型（记录 deployment ID）
3. 复制 密钥和终结点 中的 API 密钥和终结点 URL
第二步：配置 OpenClaw 环境变量
在项目根目录创建或修改 .env 文件：
Azure OpenAI 图像生成配置
AZURE_OPENAI_API_KEY=your-azure-api-key-here
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_DALLE_DEPLOYMENT=dall-e-3-deployment-name
第三步：验证安装
执行官方提供的验证命令：
1. 安装依赖（使用锁定文件确保版本一致）
pnpm install --frozen-lockfile
2. 检查变更文件
pnpm check:changed
3. 运行图像生成模块测试
pnpm test extensions/openai/image-generation-provider.test.ts
预期输出应包含 ✅ 通过的测试用例，确认 Azure 端点响应正常。
—
代码示例：在 Agent 中调用图像生成
以下是在 OpenClaw Agent 配置中使用修复后功能的完整示例：
// agent.config.ts
import { createImageGenerationTool } from '@openclaw/tools';
export default {
tools: [
createImageGenerationTool({
// 自动检测 Azure 端点
provider: 'openai',
baseURL: process.env.AZURE_OPENAI_ENDPOINT + '/openai/deployments/' +
process.env.AZURE_OPENAI_DALLE_DEPLOYMENT,
apiKey: process.env.AZURE_OPENAI_API_KEY,
// Azure 需要显式设置 header 认证
defaultHeaders: {
'api-key': process.env.AZURE_OPENAI_API_KEY
}
})
]
};
调用示例：
// 在 Agent 执行流程中
const result = await agent.execute({
task: '生成一张未来城市的赛博朋克风格图像',
options: {
size: '1024x1024',
quality: 'hd',
style: 'vivid'
}
});
// 返回：{ url: "https://..." }
—
常见问题（FAQ）
Q1: 如何区分应该使用标准 OpenAI 还是 Azure OpenAI？
A: 根据您的部署环境决定：
- 个人开发/测试：标准 OpenAI API 更简单，按量计费
- 企业生产：Azure OpenAI 提供 SLA 保障、私有网络支持（Private Endpoint）和区域数据驻留合规
Q2: 配置后提示 “401 Unauthorized” 怎么办？
A: Azure OpenAI 使用 api-key header 而非 Authorization header。请检查：
1. 环境变量 AZURE_OPENAI_API_KEY 是否正确设置
2. 配置中是否包含 defaultHeaders: { 'api-key': ... }
3. 密钥是否来自 Azure 门户的 密钥和终结点 页面（非 OpenAI 官网）
Q3: 支持哪些 DALL-E 模型版本？
A: 当前修复验证支持：
- DALL-E 3（推荐）：最高质量，支持 1024×1024/1792×1024/1024×1792
- DALL-E 2：仅支持 1024×1024，成本较低
Azure 部署时需确保模型版本为 dall-e-3 或 dall-e-2，与代码中的 model 参数一致。
Q4: 该修复是否影响现有的标准 OpenAI 配置？
A: 完全向后兼容。现有使用标准 OpenAI 端点的配置无需任何修改。修复通过智能检测 baseURL 格式自动适配，两种模式可共存于同一项目。
Q5: 如何贡献更多 Azure OpenAI 功能的改进？
A: 欢迎参与 OpenClaw 开源社区：
1. Fork 仓库并创建功能分支
2. 参考本次修复的提交 62262d4 了解代码规范
3. 提交 PR 前运行 pnpm check:changed 和完整测试套件
—
总结与下一步
本次更新使 OpenClaw 的图像生成能力覆盖更广泛的部署场景，关键收益包括：
| 收益 | 说明 |
|:—|:—|
| 企业合规 | 满足数据驻留和网络安全策略 |
| 成本优化 | 统一 Azure 订阅计费，可能享受企业协议折扣 |
| 架构灵活 | 同一套 Agent 代码适配多种 OpenAI 部署模式 |
建议下一步行动：
1. 升级至包含此修复的 OpenClaw 最新版本
2. 参考 OpenClaw 图像生成文档 完成配置迁移
3. 探索结合 Azure AI Content Safety 实现生成内容审核
—
相关阅读
—
参考来源
| 来源 | 链接 |
|:—|:—|
| 本次修复的 GitHub Commit | https://github.com/openclaw/openclaw/commit/62262d493bd80dfad587a838a7dc591c053f6c98 |
| 原始 Issue #70487 | https://github.com/openclaw/openclaw/issues/70487 |
| 合并 PR #70570 | https://github.com/openclaw/openclaw/pull/70570 |
| Azure OpenAI 图像生成 REST API 文档 | https://learn.microsoft.com/azure/ai-services/openai/reference#image-generation |
| OpenClaw 官方文档 | https://docs.openclaw.dev |
—
本文基于 OpenClaw 开源项目 commit 62262d4 撰写，感谢贡献者 zhang-guiping 和 Tak Hoffman 的技术实现。
