Microsoft Foundry

通过 Microsoft Foundry 使用 Claude Code：创建资源与部署、三种 Azure 认证方式、固定模型版本、RBAC 与排障。

本页讲通过 Microsoft Foundry 配置 Claude Code，包括设置、配置和排障。

前置条件

有权访问 Microsoft Foundry 的 Azure 订阅
创建 Microsoft Foundry 资源和部署的 RBAC 权限
已安装并配置的 Azure CLI（可选，只有在你没有其他获取凭据的机制时才需要）

向多个用户部署时，推广前先固定模型版本。

设置

1. 创建 Microsoft Foundry 资源

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

打开 Microsoft Foundry 门户
创建新资源，记下资源名
为 Claude 模型创建部署，记下你给每个部署起的部署名（第 4 步要把这些名字设为模型变量）：Claude Opus、Claude Sonnet、Claude Haiku

配置部署时，你还要选择它的托管选项，它决定推理在 Azure 还是 Anthropic 基础设施上运行。

2. 配置 Azure 凭据

Claude Code 支持三种 Microsoft Foundry 认证方式，选最适合你安全要求的：

选项 A：API Key 认证：在 Microsoft Foundry 门户里导航到你的资源，进入 Endpoints and keys，复制 API Key，然后设置环境变量：

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 令牌认证：Claude Code 在每个请求上把 ANTHROPIC_FOUNDRY_AUTH_TOKEN 的值作为 Authorization: Bearer 头发送。适用于另一个进程（如宿主应用或登录脚本）已经为你获取了访问令牌的情况。把变量设为 Microsoft Entra ID 为你的资源签发的 bearer 令牌。ANTHROPIC_FOUNDRY_AUTH_TOKEN 优先于 ANTHROPIC_FOUNDRY_API_KEY 和默认凭据链。

使用 Microsoft Foundry 时，/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 这类别名会解析为 Claude Code 对 Microsoft Foundry 的内置默认值，它可能落后于最新发布，也可能尚未在你的账号里可用。

把模型变量设置为与你在第 1 步创建的部署名匹配。没有 ANTHROPIC_DEFAULT_OPUS_MODEL 时，Microsoft Foundry 上的 opus 别名解析为 Opus 4.6，把它设为更新的 Opus 模型 ID（如 Opus 4.8）：

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 部署。提示缓存自动启用；想请求 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 变量，并在第一个提示时连接到你的 Azure 资源。与 Amazon Bedrock 和 Google Cloud 的 Agent Platform 不同，Microsoft Foundry 没有交互式设置向导。想验证你的设置，在 Claude Code 里运行 /status：API provider 一行显示 Microsoft Foundry，以及你配置的资源名或基础 URL。

Azure RBAC 配置

Azure AI User 和 Cognitive Services User 默认角色包含调用 Claude 模型所需的全部权限。想要更严格的权限，创建一个包含下面内容的自定义角色：

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

排障

如果收到错误「Failed to get token from azureADTokenProvider: ChainedTokenCredential authentication failed」：在环境里配置 Entra ID，或设置 ANTHROPIC_FOUNDRY_API_KEY
如果在第一个提示时请求反复出现连接错误：检查 ANTHROPIC_FOUNDRY_RESOURCE 是否设置为你的实际资源名，而不是占位符。Claude Code 用这个值构建端点 URL，所以错误的名字会指向一个不存在的主机