要在 Microsoft Foundry 上使用 Claude Code，必须通过环境变量配置认证和资源，并手动固定模型版本以避免部署不匹配报错。关键步骤包括：在 Azure 门户创建资源并部署 Claude 模型、设置 ANTHROPIC_FOUNDRY_API_KEY 或使用 Azure CLI 登录进行 Entra ID 认证、通过 CLAUDE_CODE_USE_FOUNDRY 等变量启用集成，最后用 ANTHROPIC_DEFAULT_*_MODEL 变量固定每个模型版本。

Claude Code Microsoft Foundry 集成：Azure 部署与认证配置 #

Deploying Claude Code across your organization? Talk to sales about enterprise plans, SSO, and centralized billing. View plans | Contact sales

前提条件 #

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

如果要将 Claude Code 部署给多个用户，务必在固定模型版本的同时锁定具体版本号，以免 Anthropic 发布新模型时因版本不匹配导致调用失败。

设置步骤 #

1. 创建 Microsoft Foundry 资源 #

首先在 Azure 中创建一个 Claude 资源：

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

注意：使用 Microsoft Foundry 时，/login 和 /logout 命令被禁用，因为认证已通过 Azure 凭据处理。

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. 固定模型版本 #

必须为每个部署固定具体的模型版本。 如果使用模型别名（sonnet、opus、haiku）而不固定版本，当 Anthropic 发布新版本时，Claude Code 可能尝试使用尚未在你账户中部署的模型版本，导致现有用户报错。在 Azure 中创建部署时，应选择具体版本号而非“自动更新到最新”。

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

如果不设置 ANTHROPIC_DEFAULT_OPUS_MODEL，Foundry 上的 opus 别名默认解析为 Opus 4.6。要使用最新模型，设置以下变量：

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

后台任务（如会话标题生成）默认使用小/快模型（通常为 Haiku 类模型）。由于并非所有账户都有 Haiku 部署，Foundry 上 Claude Code 默认将后台任务指向主模型。要使用 Haiku 处理后台任务，按上方所示将 ANTHROPIC_DEFAULT_HAIKU_MODEL 设置为账户中可用的 Haiku 部署。

当前和旧版模型 ID 请参见 Models overview。完整环境变量列表参见模型配置。

提示缓存自动启用。如果希望使用 1 小时缓存 TTL 而非默认的 5 分钟，设置以下变量（注意 1 小时 TTL 的缓存写入按更高费率计费）：

export ENABLE_PROMPT_CACHING_1H=1

5. 运行 Claude Code #

环境变量设置完成后，在项目目录中启动 Claude Code：

claude

Claude Code 从环境变量中读取 CLAUDE_CODE_USE_FOUNDRY 和其他 Foundry 变量，在首次提示时连接到你的 Azure 资源。与 Bedrock 和 Vertex AI 不同，Foundry 没有交互式设置向导，因此步骤 3 和 4 中的环境变量是唯一的配置途径。

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 改用 API Key 认证。

相关资源 #

• Microsoft Foundry 文档
• Microsoft Foundry 模型
• Microsoft Foundry 定价

常见问题 #

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

与 Bedrock/Vertex AI 不同，Foundry 没有模型版本降级机制。当 Anthropic 发布新版本模型但 Foundry 部署尚未更新时，使用别名（如 sonnet）会直接导致调用失败。固定具体版本号（如 claude-sonnet-4-6）可以确保用户始终访问稳定的已部署版本。

API Key 和 Entra ID 认证怎么选？ #

API Key 适合快速上手和测试场景，配置简单。Entra ID 认证更适合生产环境——无需管理 API Key，可利用 Azure 原生的身份和权限体系（如 MFA、条件访问）。如果遇到 ChainedTokenCredential authentication failed 错误，可切换为 API Key 或配置 Entra ID 凭据。

提示缓存自动启用后，如何延长缓存时间？ #

提示缓存默认启用，TTL 为 5 分钟。设置 ENABLE_PROMPT_CACHING_1H=1 环境变量可将缓存 TTL 延长至 1 小时（注意：1 小时 TTL 的缓存写入按更高费率计费）。