在 Microsoft Foundry 上使用 Claude Code

了解如何通过 Microsoft Foundry 配置 Claude Code，包括设置、配置和故障排除。

前提条件

在通过 Microsoft Foundry 配置 Claude Code 前，请确保具备：

• 有权访问 Microsoft Foundry 的 Azure 订阅
• 可创建 Microsoft Foundry 资源和部署的 RBAC 权限
• 已安装并配置 Azure CLI（可选；仅在没有其他凭据获取方式时需要）

设置

1. 预配 Microsoft Foundry 资源

首先，在 Azure 中创建 Claude 资源：

1. 前往 Microsoft Foundry 门户
2. 创建新资源，并记下资源名称
3. 为 Claude 模型创建部署：
   • Claude Opus
   • Claude Sonnet
   • Claude Haiku

2. 配置 Azure 凭据

Claude Code 支持三种 Microsoft Foundry 身份验证方式。请选择最符合安全要求的方式。

选项 A：API 密钥身份验证

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，也未设置 ANTHROPIC_FOUNDRY_AUTH_TOKEN，Claude Code 会自动使用 Azure SDK 的默认凭据链。 该凭据链支持以多种方式对本地和远程工作负载进行身份验证。

在本地环境中，通常可以使用 Azure CLI：

az login

选项 C：Bearer Token 身份验证

Claude Code 会在每个请求中发送 ANTHROPIC_FOUNDRY_AUTH_TOKEN 的值，并将其用作 Authorization: Bearer 请求头。如果主机应用或登录脚本等其他进程已经为你取得 access token，请使用此选项。需要 Claude Code v2.1.203 或更高版本。

将该变量设置为 Microsoft Entra ID 为你的资源签发的 bearer token：

export ANTHROPIC_FOUNDRY_AUTH_TOKEN=your-entra-access-token

ANTHROPIC_FOUNDRY_AUTH_TOKEN 的优先级高于 ANTHROPIC_FOUNDRY_API_KEY 和默认凭据链。

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 中创建的部署名称一致。

如果未设置 ANTHROPIC_DEFAULT_OPUS_MODEL，Microsoft Foundry 上的 opus 别名会解析为 Opus 4.6。要使用最新模型，请将其设为 Opus 4.8 ID：

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

生成会话标题等后台任务会使用较小且速度较快的模型，通常是 Haiku 类模型。在 Microsoft Foundry 上，Claude Code 默认对这类任务使用主模型，因为并非所有账号都有 Haiku 部署。要让后台任务使用 Haiku，请像上例一样，将 ANTHROPIC_DEFAULT_HAIKU_MODEL 设为账号中可用的 Haiku 部署。

当前和旧版模型 ID 请参阅模型概述。完整的环境变量列表请参阅模型配置。

Prompt 缓存会自动启用。要请求 1 小时缓存 TTL，而不是默认的 5 分钟，请设置以下变量；写入使用 1 小时 TTL 的缓存会按更高费率计费：

export ENABLE_PROMPT_CACHING_1H=1

5. 运行 Claude Code

设置环境变量后，从项目目录启动 Claude Code：

claude

Claude Code 会从环境中读取 CLAUDE_CODE_USE_FOUNDRY 和其他 Microsoft Foundry 变量，并在发送第一个 Prompt 时连接到 Azure 资源。与 Amazon Bedrock 和 Google Cloud 的 Agent Platform 不同，Microsoft 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。

其他资源

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