Claude Code on Microsoft Foundry

Microsoft Foundry 是 Azure 提供的 AI 模型托管服务，支持在企业 Azure 环境中部署和调用 Claude 模型。本文介绍如何配置 Claude Code 使用 Microsoft Foundry，包括创建 Azure 资源和部署、选择 API Key 或 Entra ID 两种认证方式、配置必要环境变量、固定模型版本，以及 RBAC 权限配置。

前提条件

• 有访问 Microsoft Foundry 权限的 Azure 订阅
• 创建 Microsoft Foundry 资源和部署的 RBAC 权限
• 已安装并配置 Azure CLI（可选，仅在使用 Entra ID 认证时需要）

---

设置步骤

1. 创建 Microsoft Foundry 资源

1. 导航到 Microsoft Foundry 门户
2. 创建新资源，记录你的资源名称
3. 为 Claude 模型创建部署：
   • Claude Opus
   • Claude Sonnet
   • Claude Haiku

2. 配置 Azure 凭据

Claude Code 支持两种认证方式，选择适合你安全要求的方式：

选项 A：API Key 认证

1. 在 Microsoft Foundry 门户中导航到你的资源
2. 进入 Endpoints and keys 部分
3. 复制 API Key
4. 设置环境变量：

export ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key

选项 B：Microsoft Entra ID 认证

未设置 ANTHROPIC_FOUNDRY_API_KEY 时，Claude Code 自动使用 Azure SDK 默认凭据链，支持多种本地和远程工作负载的认证方式。

本地环境通常使用 Azure CLI：

az login

3. 配置 Claude Code

设置以下环境变量以启用 Microsoft Foundry：

# 启用 Microsoft Foundry 集成
export CLAUDE_CODE_USE_FOUNDRY=1

# Azure 资源名称（用你的资源名替换 {resource}）
export ANTHROPIC_FOUNDRY_RESOURCE={resource}

# 或者提供完整的基础 URL：
# export ANTHROPIC_FOUNDRY_BASE_URL=https://{resource}.services.ai.azure.com/anthropic

4. 固定模型版本

设置模型变量与步骤 1 中创建的部署名称匹配：

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'

当前和历史模型 ID 参见 Models 概览。完整环境变量列表参见模型配置。

重要：部署到多个用户前必须固定模型版本。不固定时，Claude Code 别名（sonnet、opus、haiku）会指向最新版本——当 Anthropic 发布新模型但用户账户尚未启用时，Foundry 用户会看到错误（Bedrock/Vertex 会降级，Foundry 没有对应的起动检查机制）。

---

Azure RBAC 配置

Azure AI User 和 Cognitive Services User 默认角色包含调用 Claude 模型所需的所有权限。

如需更严格的权限，可创建包含以下内容的自定义角色：

{
  "permissions": [
    {
      "dataActions": [
        "Microsoft.CognitiveServices/accounts/providers/*"
      ]
    }
  ]
}

详细说明参见 Microsoft Foundry RBAC 文档。

---

故障排查

错误 "Failed to get token from azureADTokenProvider: ChainedTokenCredential authentication failed"

在环境中配置 Entra ID，或设置 ANTHROPIC_FOUNDRY_API_KEY。

---

相关资源

• Microsoft Foundry 文档
• Microsoft Foundry 模型
• Microsoft Foundry 价格
• 第三方集成概览

---

常见问题

Q: API Key 认证和 Entra ID 认证应该选哪个？

API Key 适合快速上手和测试场景，配置简单。Entra ID 认证更适合生产环境——无需管理 API Key，使用 Azure 原生的身份和权限体系（支持 MFA、条件访问等安全策略）。

Q: 为什么必须固定模型版本，不能使用别名？

与 Bedrock/Vertex 不同，Foundry 没有"找不到模型时自动降级"的机制。当 Anthropic 发布新版本模型但 Foundry 部署尚未更新时，使用别名会直接报错。固定版本号（如 claude-sonnet-4-6）可确保用户访问稳定。

Q: 部署了多个 Claude 模型，如何指定每个角色使用的模型？

通过 ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL 三个环境变量分别指定，值为你在 Foundry 门户中创建的部署名称。