OpenClaw Microsoft Foundry 模型供应商插件接入 Azure AI Foundry 部署、MAI 图像生成与 Entra ID 认证【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawOpenClaw 通过openclaw/microsoft-foundry插件将 Microsoft FoundryAzure AI Foundry接入其模型体系覆盖文本推理与 MAI 图像生成两大能力。本文以 Microsoft Foundry 插件参考文档 为核心骨架结合插件源码逐层拆解其部署发现、API 路由、双认证模型与图像生成约束读完即可在 OpenClaw 中完成 Foundry 部署的接入与排障。插件概览分发、Surface 与激活Microsoft Foundry 插件随 OpenClaw 内置分发无需单独安装插件包名为openclaw/microsoft-foundry当前版本可从 package.json 查看。插件入口通过 index.ts 的definePluginEntry注册两类能力Providermicrosoft-foundry负责聊天模型接入api.registerProviderImage-generation providermicrosoft-foundry负责 MAI 图像生成api.registerImageGenerationProvider。从插件元数据 openclaw.plugin.json 可以看到它归类为models类别、默认启用enabledByDefault: true并在contracts.imageGenerationProviders中声明了microsoft-foundry合约。其activation.onStartup为false即插件按需加载而非启动即占用资源。环境要求与两种认证方式使用本插件需要满足以下前提来自参考文档 Requirements 一节拥有带部署deployment的 Microsoft Foundry 或 Azure AI Foundry 资源API Key 认证通过环境变量AZURE_OPENAI_API_KEY或已配置的 provider API keyEntra ID 认证需安装 Azure CLI 并先执行az loginOpenClaw 通过az account get-access-token自动刷新运行时令牌。源码层面provider.ts 明确声明了envVars: [AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT]并注册了两种认证方法entraIdAuthMethod与apiKeyAuthMethod定义于 auth.ts。Entra IDaz login认证流程Entra ID 走custom类型的认证向导wizard完整流程在 auth.ts 中实现检查az是否可用isAzCliInstalled不可用直接报错提示安装 Azure CLI检测已登录账户az account show若未登录通过az login --use-device-code发起设备码登录支持--tenant回退与--allow-no-subscriptions列出可用订阅az account list --all仅保留Enabled状态单选自动采用、多选由用户挑选、无订阅时退化为租户级认证用户确认后从订阅中发现 Foundry 资源az cognitiveservices account list并列出部署az cognitiveservices account deployment list见 onboard.ts对非图像模型执行连接测试testFoundryConnection写出认证结果profilemicrosoft-foundry:entra凭据标记为__entra_id_dynamic__动态令牌占位并携带订阅、租户、端点、模型元数据。API Key 认证API Key 走api_key类型向导auth.ts优先读取命令行选项azureOpenaiApiKey与环境变量AZURE_OPENAI_API_KEY再引导用户输入端点与模型选择最终写出 profilemicrosoft-foundry:default。运行时令牌刷新机制Entra ID 的动态令牌由 runtime.ts 负责刷新通过az account get-access-token获取令牌默认 resource 为认知服务作用域https://cognitiveservices.azure.comAnthropic 消息 API 使用https://ai.azure.com/.default见 shared.ts令牌在进程内按scope:subscriptionId:tenantId缓存getFoundryTokenCacheKey缓存上限 128 条过期自动剔除距离过期不足 5 分钟TOKEN_REFRESH_MARGIN_MS即触发异步刷新刷新请求按缓存键去重合并令牌缺失或expiresOn无法解析时回退生命周期为 55 分钟。聊天模型部署发现、API 路由与能力解析聊天部署的模型引用格式为microsoft-foundry/deployment-name部署名直接作为模型 ref。接入时onboarding 通过 Azure CLI 发现 Foundry 资源与部署再把所选部署名写入模型配置对应models.providers.microsoft-foundry.models[].id。OpenAI 兼容 API/openai/v1与 API 形态选择OpenClaw 使用 Foundry 的/openai/v1端点对接 OpenAI 兼容的聊天 API具体形态由模型家族自动决定参考文档与 shared.ts 的usesFoundryResponsesByDefault模型家族默认 API 形态GPTgpt-*、o1/o3/o4、computer-use-preview、DeepSeek-V4openai-responsesMAI-DS-R1 及其他 chat-completion 部署openai-completions除非显式配置支持的 API其中openai-responses形态有两点值得注意的实现细节Foundry 的 Responses 端点不支持持久化store因此插件在 provider.ts 中通过wrapStreamFn注入replayResponsesItemIds: true让加密推理回放encrypted reasoning replay能对照原始 item id 校验openai-completions形态下若显式保留推理能力maxTokensField会映射为max_completion_tokens见 shared.ts 的requiresFoundryMaxCompletionTokens。模型能力自动解析插件在onModelSelected、normalizeResolvedModel等钩子中调用resolveFoundryModelCapabilitiesshared.ts按模型名自动补全以下元数据并写回模型配置API 形态Claude 部署 →anthropic-messages否则按家族规则选择推理能力Claude 思考、reasoning_effort支持、推理内容reasoning content三类判定thinkingLevelMap把 OpenClaw 的思考档位off/minimal/low/medium/high/xhigh/max映射为 Foundry 支持的 effort例如gpt-5系映射minimal/low/medium/highgpt-5.1-codex-max额外支持xhigh输入模态Claude、GPT、o*、computer-use-preview自动标记为支持图像输入[text, image]上下文窗口与最大输出如gpt-5.4*系为 1,050,000/128,000 tokensclaude-opus-4-5等为 200,000/64,000MAI-DS-R1 为 163,840/163,840canonicalModelIdmergeFoundryCanonicalModelParams会把模型名写入params.canonicalModelId供后续线协议与思考映射使用。关于 MAI-DS-R1MAI-DS-R1 通过**推理内容reasoning content**而非reasoning_effort被识别为具备推理能力其上下文窗口与输出 token 元数据均为163,840 tokens参考文档 shared.ts。Claude 部署走 Anthropic Messages 形态Anthropic Claude 部署在 Microsoft Foundry 中使用的是Anthropic Messages API 形态而非 OpenAI 兼容的/openai/v1。参考文档明确给出两种接入姿势临时方案在原生 Anthropic 运行时落地前将其配置为自定义的anthropic-messagesprovider关键参数当 Foundry 部署名与 Claude 模型 ID 不一致时必须在模型条目上设置params.canonicalModelId这样 OpenClaw 才能应用模型专属的线协议、正确映射/think off并安全保留签名思考signed thinking。源码佐证buildFoundryProviderBaseUrlshared.ts对 Anthropic 形态拼接.../anthropic端点对 OpenAI 形态拼接.../openai/v1resolveThinkingProfileprovider.ts对claude-mythos-preview等预览模型强制adaptive思考档位并移除off。MAI 图像生成插件在image_generate能力上注册microsoft-foundry当前支持的 Microsoft AI 图像模型为MAI-Image-2.5-FlashMAI-Image-2.5MAI-Image-2eMAI-Image-2源码中isFoundryMaiImageModel还额外识别mai-image-2-efficient见 shared.ts。为什么没有默认图像模型MAI API 要求请求的model字段必须是你的部署名因此插件不声明默认图像模型需要用户用已部署的 MAI 图像部署名作为模型 ref。参考文档给出的配置示例agent.config.json5{ agents: { defaults: { mediaModels: { image: { primary: microsoft-foundry/deployment-name, timeoutMs: 600000, }, }, }, }, }其中timeoutMs对应图像生成操作超时源码中的默认值为 600,000ms10 分钟见 image-generation-provider.ts。生成与编辑端点纯提示词生成prompt-only调用POST {endpoint}/mai/v1/images/generations参考图编辑reference-image edits调用POST {endpoint}/mai/v1/images/edits且仅限MAI-Image-2.5-Flash与MAI-Image-2.5部署。纯提示词生成允许在只配置 Foundry 端点的情况下使用自定义部署名但图像编辑若使用自定义部署名则必须通过 onboarding 选择部署或提供模型元数据以便 OpenClaw 校验该部署确实由MAI-Image-2.5-Flash/MAI-Image-2.5支撑源码ensureMaiImageModel与isMaiImageEditModel见 image-generation-provider.ts。MAI 图像约束参考文档列出的硬性约束均可从 image-generation-provider.ts 的常量与校验函数得到印证输出每次请求一张 PNG 图像MAI_IMAGE_MAX_RESULTS 1尺寸默认1024x1024宽和高都必须 ≥ 768 px总像素宽 × 高 ≤ 1,048,576编辑输入一张 PNG 或 JPEG 图像MAI_IMAGE_UPLOAD_MIME_TYPES仅接受 jpeg/jpg/png以 multipart 表单上传不支持共享提示shared hintsaspectRatio、resolution、quality、background以及非 PNG 的outputFormat等提示不会发送给 Microsoft Foundry。图像请求的鉴权与文本模型一致API Key 走api-key头Entra ID 则先经prepareFoundryRuntimeAuth刷新令牌后使用Authorization: Bearer头见 image-generation-provider.ts。典型接入配置文本推理模型接入后的 provider 配置大致如下由 onboarding 自动生成也可手工维护{ models: { providers: { microsoft-foundry: { baseUrl: https://your-resource.services.ai.azure.com/openai/v1, api: openai-completions, // 或 openai-responses / anthropic-messages models: [ { id: my-gpt-deployment, name: gpt-5.4, api: openai-responses, baseUrl: https://your-resource.services.ai.azure.com/openai/v1, reasoning: true, thinkingLevelMap: { off: none, minimal: minimal, low: low, medium: medium, high: high }, params: { canonicalModelId: gpt-5.4 }, contextWindow: 1050000, maxTokens: 128000, }, ], }, }, }, }选择模型后onModelSelected会自动补齐上述name、api、baseUrl、reasoning、thinkingLevelMap、params.canonicalModelId、input、contextWindow、maxTokens等字段并同步绑定认证 profile 与插件 allowlist见 provider.ts。图像模型图像模型按前文配置示例在agents.defaults.mediaModels.image.primary中填入microsoft-foundry/deployment-name即可。故障排查参考文档给出了三个高频问题及其解法报错原因与解法az: command not foundAzure CLI 未安装或不在 PATH。安装 Azure CLI或改用 API Key 认证Microsoft Foundry endpoint missing for MAI image generation未配置端点。通过 onboarding 选择 Foundry 部署或在models.providers.microsoft-foundry.baseUrl中补充端点supports MAI image deployments only所选图像模型指向非 MAI 部署。请为image_generate使用已部署的 MAI 图像模型对应源码实现resolveConfiguredEndpoint会依次从运行时准备的 baseUrl、provider 配置的baseUrl、环境变量AZURE_OPENAI_ENDPOINT中提取端点缺失时抛出该错误image-generation-provider.tsensureMaiImageModel对非 MAI 部署抛出supports MAI image deployments only错误。此外cli.ts 还针对 Azure CLI 常见失败做了错误归一化未登录提示运行az login --use-device-code、订阅不可达提示检查订阅/租户权限、AADSTS*错误提示重跑设备码登录并确认租户帮助用户快速定位认证层面的问题。深入阅读插件参考文档docs/plugins/reference/microsoft-foundry.md插件入口与注册extensions/microsoft-foundry/index.tsProvider 主实现extensions/microsoft-foundry/provider.ts模型能力与 API 路由解析extensions/microsoft-foundry/shared.ts两种认证方法extensions/microsoft-foundry/auth.tsEntra ID 令牌刷新extensions/microsoft-foundry/runtime.tsAzure CLI 封装extensions/microsoft-foundry/cli.tsMAI 图像生成实现extensions/microsoft-foundry/image-generation-provider.tsonboarding 资源/部署发现extensions/microsoft-foundry/onboard.ts插件元数据extensions/microsoft-foundry/openclaw.plugin.json【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考