Langsung ke konten utama

Prasyarat

Sebelum mengonfigurasi Claude Code dengan Microsoft Foundry, pastikan Anda memiliki:
  • Langganan Azure dengan akses ke Microsoft Foundry
  • Izin RBAC untuk membuat sumber daya dan deployment Microsoft Foundry
  • Azure CLI diinstal dan dikonfigurasi (opsional - hanya diperlukan jika Anda tidak memiliki mekanisme lain untuk mendapatkan kredensial)
Jika Anda menerapkan Claude Code ke beberapa pengguna, pin versi model Anda sebelum melakukan peluncuran.

Penyiapan

  1. Sediakan resource Microsoft Foundry

Pertama, buat resource Claude di Azure:
  1. Buka portal Microsoft Foundry
  2. Buat resource baru, dan catat nama resource Anda
  3. Buat deployment untuk model Claude, dan catat nama deployment yang Anda berikan untuk masing-masing; Anda akan menetapkan nama-nama ini sebagai variabel model pada langkah 4:
    • Claude Opus
    • Claude Sonnet
    • Claude Haiku
    Saat Anda mengonfigurasi deployment, Anda juga memilih opsi hosting-nya, yang menentukan apakah inferensi berjalan di infrastruktur Azure atau di infrastruktur Anthropic.

  1. Konfigurasikan kredensial Azure

Claude Code mendukung tiga metode autentikasi untuk Microsoft Foundry. Pilih metode yang paling sesuai dengan persyaratan keamanan Anda:
  • Kunci API: Anda menyalin kunci dari portal Microsoft Foundry dan menetapkannya sebagai ANTHROPIC_FOUNDRY_API_KEY
  • Microsoft Entra ID: Claude Code mendapatkan token melalui rantai kredensial default Azure SDK, misalnya dari sesi az login, sehingga tidak ada kunci API yang perlu disimpan
  • Bearer token: proses lain memperoleh access token Microsoft Entra ID dan Anda meneruskannya di ANTHROPIC_FOUNDRY_AUTH_TOKEN
Saat menggunakan Microsoft Foundry, perintah /logout tidak tersedia karena autentikasi ditangani melalui kredensial Azure.

Menggunakan kunci API

Salin kunci dari portal Microsoft Foundry, lalu tetapkan sebagai environment variable:
  1. Buka resource Anda di portal Microsoft Foundry
  2. Buka bagian Endpoints and keys
  3. Salin API Key
  4. Tetapkan environment variable, dengan mengganti your-azure-api-key dengan kunci yang Anda salin:

Menggunakan Microsoft Entra ID

Biarkan ANTHROPIC_FOUNDRY_API_KEY dan ANTHROPIC_FOUNDRY_AUTH_TOKEN tidak ditetapkan. Claude Code kemudian menggunakan rantai kredensial default Azure SDK. Ini mendukung berbagai metode untuk mengautentikasi workload lokal maupun jarak jauh. Di mesin lokal, masuk dengan Azure CLI:
Untuk peran yang dibutuhkan identitas Anda, lihat Konfigurasi Azure RBAC.

Menggunakan bearer token

Claude Code mengirimkan nilai ANTHROPIC_FOUNDRY_AUTH_TOKEN pada setiap permintaan sebagai header Authorization: Bearer. Gunakan opsi ini ketika proses lain, seperti aplikasi host atau skrip masuk, telah memperoleh access token untuk Anda. Tetapkan variabel ke bearer token yang diterbitkan Microsoft Entra ID untuk resource Anda:
ANTHROPIC_FOUNDRY_AUTH_TOKEN diutamakan daripada ANTHROPIC_FOUNDRY_API_KEY dan daripada rantai kredensial default.

  1. Konfigurasikan Claude Code

Tetapkan environment variable berikut untuk mengaktifkan Microsoft Foundry:
Tetapkan ANTHROPIC_FOUNDRY_RESOURCE hanya ke nama resource, seperti my-resource. Claude Code menolak URL atau nama host saat Anda mengirim pesan.

  1. Sematkan versi model

Sematkan versi model tertentu untuk setiap deployment. Tanpa penyematan, alias model seperti sonnet dan opus di-resolve ke default bawaan Claude Code untuk Microsoft Foundry. Default tersebut dapat tertinggal dari rilis terbaru dan mungkin belum tersedia di akun Anda.Ketika resource Anda tidak memiliki deployment untuk default tersebut, Claude Code beralih ke model yang lebih lama atau permintaan gagal. Peralihan menampilkan pesan yang diawali dengan Switched to <fallback> because <model> is not available. Saat Anda membuat deployment Azure, pilih versi model tertentu alih-alih “auto-update to latest.”
Tetapkan variabel model agar sesuai dengan nama deployment yang Anda buat pada langkah 1. Tanpa ANTHROPIC_DEFAULT_OPUS_MODEL, alias opus di Microsoft Foundry di-resolve ke Opus 4.6. Tetapkan ke ID model Opus yang lebih baru, seperti Opus 4.8:
Tugas latar belakang seperti pembuatan judul sesi menggunakan model kecil/cepat, biasanya model kelas Haiku. Di Microsoft Foundry, Claude Code secara default menggunakan model utama untuk ini karena tidak setiap akun memiliki deployment Haiku. Untuk menggunakan Haiku bagi tugas latar belakang, tetapkan ANTHROPIC_DEFAULT_HAIKU_MODEL ke deployment Haiku yang tersedia di akun Anda, seperti yang ditunjukkan di atas. Untuk ID model saat ini dan lama, lihat Ikhtisar model. Lihat Konfigurasi model untuk daftar lengkap environment variable. Prompt caching diaktifkan secara otomatis. Untuk meminta TTL cache 1 jam alih-alih default 5 menit, tetapkan variabel berikut; penulisan cache dengan TTL 1 jam ditagih dengan tarif yang lebih tinggi:
Untuk menetapkan TTL yang berbeda untuk percakapan utama Anda dan untuk permintaan yang dibuat Claude Code di luar percakapan tersebut, pilih TTL sendiri.

  1. Jalankan Claude Code

Setelah environment variable ditetapkan, jalankan Claude Code dari direktori proyek Anda:
Claude Code membaca CLAUDE_CODE_USE_FOUNDRY dan variabel Microsoft Foundry lainnya dari lingkungan dan terhubung ke resource Azure Anda pada prompt pertama. Tidak seperti Amazon Bedrock dan Agent Platform dari Google Cloud, Microsoft Foundry tidak memiliki wizard penyiapan interaktif, sehingga environment variable pada langkah 3 dan 4 adalah satu-satunya jalur konfigurasi. Untuk memverifikasi penyiapan Anda, jalankan /status di dalam Claude Code. Baris penyedia API menampilkan Microsoft Foundry, beserta nama resource atau base URL yang Anda konfigurasikan.

Konfigurasi Azure RBAC

Jika Anda melakukan autentikasi dengan Microsoft Entra ID atau bearer token yang diterbitkannya, tetapkan peran Foundry User atau Cognitive Services User kepada identitas Anda pada resource Foundry Anda. Anda mungkin masih melihat Foundry User dengan nama sebelumnya, Azure AI User. Jika peran-peran ini tidak memenuhi kebutuhan Anda, lihat dokumentasi RBAC Microsoft Foundry untuk peran khusus.

1M token context window

Di Microsoft Foundry, model Fable, Sonnet 5 dan yang lebih baru, serta Opus 4.7 dan yang lebih baru berjalan dengan 1M token context window secara default. Ini tidak memerlukan akhiran [1m], selama Claude Code dapat mengetahui model mana yang dilayani oleh deployment Anda.
Claude Code membaca model dari nama deployment dalam variabel model Anda. Beri nama setiap deployment dengan ID modelnya, seperti claude-opus-4-8, atau petakan model ke nama deployment Anda dengan modelOverrides.
Entri settings.json ini memberi tahu Claude Code bahwa deployment bernama team-opus-prod melayani Opus 4.8:
Untuk tetap menggunakan window 200K, atur CLAUDE_CODE_DISABLE_1M_CONTEXT=1. Jika Claude Code tidak dapat mencocokkan nama deployment dengan model, Claude Code mengasumsikan window 1M secara default, jadi atur window yang sebenarnya jika model yang Anda deploy menerima lebih sedikit. Opus 4.6 dan Sonnet 4.6 mencapai window 1M ketika Anda menambahkan [1m] ke nama deployment di ANTHROPIC_DEFAULT_OPUS_MODEL atau ANTHROPIC_DEFAULT_SONNET_MODEL, sebagaimana dijelaskan dalam Menyematkan model untuk deployment pihak ketiga. Sebelum v2.1.287, model Fable serta Opus 4.7 dan yang lebih baru juga memerlukan akhiran tersebut di Microsoft Foundry dan berjalan dengan window 200K secara default tanpanya.

Pemecahan Masalah

Jika Anda menerima kesalahan “Failed to get token from azureADTokenProvider: ChainedTokenCredential authentication failed”:
  • Konfigurasi Entra ID di lingkungan, atau atur ANTHROPIC_FOUNDRY_API_KEY.
Jika permintaan gagal dengan kesalahan koneksi berulang pada prompt pertama:
  • Periksa bahwa ANTHROPIC_FOUNDRY_RESOURCE diatur ke nama sumber daya aktual Anda daripada placeholder. Claude Code membangun URL endpoint dari nilai ini, jadi nama yang salah menunjuk ke host yang tidak ada.

Sumber daya tambahan