Claude Code trên Microsoft Foundry

Microsoft Foundry là một provider bên thứ ba khác mà Claude Code hỗ trợ, bên cạnh Amazon Bedrock và Google Cloud’s Agent Platform.

Yêu cầu trước khi bắt đầu

• Azure subscription có quyền truy cập Microsoft Foundry.
• Quyền RBAC để tạo resource và deployment trên Microsoft Foundry.
• Azure CLI đã cài đặt (tùy chọn - chỉ cần nếu bạn không có cách khác để lấy credentials).

Chú ý

Nếu triển khai cho nhiều người dùng, pin phiên bản model trước khi rollout.

Thiết lập

1. Tạo resource Microsoft Foundry

1. Vào Microsoft Foundry portal, tạo resource mới, ghi lại tên resource.
2. Tạo deployment cho các model Claude (Opus, Sonnet, Haiku), ghi lại tên deployment cho từng model - bạn sẽ dùng các tên này ở bước 4.

Khi cấu hình một deployment, bạn cũng chọn hosting option (chạy trên Azure hay trên hạ tầng Anthropic), quyết định inference chạy ở đâu.

2. Cấu hình credentials Azure

Claude Code hỗ trợ ba cách xác thực với Microsoft Foundry:

Cách A: API key

Vào resource trong Microsoft Foundry portal → mục Endpoints and keys → copy API Key:

export ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key

Cách B: Microsoft Entra ID

Khi không đặt ANTHROPIC_FOUNDRY_API_KEY lẫn ANTHROPIC_FOUNDRY_AUTH_TOKEN, Claude Code tự dùng default credential chain của Azure SDK. Cách phổ biến ở local là:

az login

Cách C: Bearer token (yêu cầu Claude Code v2.1.203 trở lên)

Claude Code gửi giá trị ANTHROPIC_FOUNDRY_AUTH_TOKEN trên mỗi request dưới dạng header Authorization: Bearer. Dùng cách này khi một tiến trình khác (host application hoặc script đăng nhập) đã lấy sẵn access token cho bạn:

export ANTHROPIC_FOUNDRY_AUTH_TOKEN=your-entra-access-token

ANTHROPIC_FOUNDRY_AUTH_TOKEN có độ ưu tiên cao hơn ANTHROPIC_FOUNDRY_API_KEY và cao hơn default credential chain.

Ghi chú

Khi dùng Microsoft Foundry, lệnh /logout không khả dụng vì xác thực do Azure credentials quản lý.

3. Cấu hình Claude Code

# Bật tích hợp Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1

# Tên resource Azure (thay {resource} bằng tên resource của bạn)
export ANTHROPIC_FOUNDRY_RESOURCE={resource}
# Hoặc cung cấp base URL đầy đủ:
# export ANTHROPIC_FOUNDRY_BASE_URL=https://{resource}.services.ai.azure.com/anthropic

4. Pin phiên bản model

Chú ý

Pin phiên bản model cụ thể cho mọi deployment. Không pin, alias sonnet/opus sẽ trỏ tới default tích hợp sẵn của Claude Code cho Microsoft Foundry, có thể chậm hơn bản mới nhất và chưa chắc khả dụng trong tài khoản của bạn. Microsoft Foundry không có kiểm tra model lúc khởi động, nên request sẽ lỗi thẳng khi default không khả dụng. Khi tạo Azure deployment, chọn phiên bản model cụ thể thay vì “auto-update to latest”.

Đặt các biến model khớp với tên deployment đã tạo ở bước 1:

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'

Tác vụ nền (như đặt tiêu đề session) dùng model small/fast, thường là Haiku. Trên Microsoft Foundry, Claude Code mặc định dùng primary model cho việc này vì không phải tài khoản nào cũng có deployment Haiku. Để dùng Haiku cho tác vụ nền, đặt ANTHROPIC_DEFAULT_HAIKU_MODEL thành deployment Haiku khả dụng trong tài khoản bạn.

Prompt caching được bật tự động. Để yêu cầu TTL cache 1 giờ thay vì mặc định 5 phút (tính phí cao hơn cho cache write):

export ENABLE_PROMPT_CACHING_1H=1

5. Chạy Claude Code

claude

Claude Code đọc CLAUDE_CODE_USE_FOUNDRY và các biến khác từ môi trường, kết nối tới Azure resource ngay ở prompt đầu tiên. Khác với Amazon Bedrock và Google Cloud’s Agent Platform, Microsoft Foundry không có wizard thiết lập tương tác - các biến môi trường ở bước 3 và 4 là đường duy nhất để cấu hình.

Xác minh bằng /status: dòng API provider hiển thị Microsoft Foundry, kèm tên resource hoặc base URL đã cấu hình.

Cấu hình Azure RBAC

Các role mặc định Azure AI User và Cognitive Services User đã bao gồm mọi quyền cần thiết để gọi model Claude.

Để hạn chế hơn, tạo custom role với:

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

Xử lý sự cố

Lỗi “Failed to get token from azureADTokenProvider: ChainedTokenCredential authentication failed”: cấu hình Entra ID trong môi trường, hoặc đặt ANTHROPIC_FOUNDRY_API_KEY.

Request lỗi kết nối liên tục ở prompt đầu tiên: kiểm tra ANTHROPIC_FOUNDRY_RESOURCE đã đặt đúng tên resource thật, không phải placeholder. Claude Code dựng endpoint URL từ giá trị này, nên tên sai sẽ trỏ tới host không tồn tại.

Nguồn

Dịch và biên soạn từ Claude Code on Microsoft Foundry.