Tutorial instalasi Claude Code — perintah macOS dan Windows, lalu koneksi dengan langganan atau kunci API

Instalasi Claude Code hanya memerlukan satu perintah: di macOS, Linux, dan WSL jalankan curl -fsSL https://claude.ai/install.sh | bash; di Windows, jalankan irm https://claude.ai/install.ps1 | iex di PowerShell (di Command Prompt CMD gunakan baris install.cmd di bawah). Setelah instalasi, buka terminal baru, gunakan claude --version untuk memverifikasi, lalu jalankan claude untuk memulai. Untuk koneksi pertama, ada dua pilihan: login dengan akun Pro, Max, Team, Enterprise, atau Console (paket gratis Claude.ai tidak mencakup Claude Code), atau tetapkan dua variabel lingkungan ANTHROPIC_BASE_URL dan ANTHROPIC_AUTH_TOKEN untuk menggunakan kunci API berbasis penggunaan tanpa memerlukan langganan.

Perintah diverifikasi pada 11 September 2026, berdasarkan dokumentasi instalasi resmi Anthropic. Halaman ini hanya membahas instalasi dan koneksi pertama; untuk penggunaan sehari-hari setelah instalasi, lihat tutorial Claude Code.

Pemeriksaan sebelum instalasi

Instalasi macOS

Buka “Terminal”, lalu tempel baris ini:

# macOS、Linux、WSL
curl -fsSL https://claude.ai/install.sh | bash

Ini adalah metode instalasi native yang direkomendasikan secara resmi: yang dipasang adalah executable mandiri dan akan diperbarui otomatis di latar belakang. Titik masuk executable berada di ~/.local/bin/claude; terminal yang sudah terbuka tidak akan membaca PATH baru, jadi buka jendela baru setelah instalasi. Linux dan WSL menggunakan perintah yang sama.

Instalasi Windows

Windows memiliki dua perintah berbeda; perbedaannya hanya terminal yang Anda buka. Jika prompt-nya PS C:\Users\你的名字>, itu PowerShell; jika tidak ada PS dan hanya ada C:\Users\你的名字>, itu Command Prompt (CMD). Tidak perlu menjalankannya sebagai administrator.

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

:: Windows 命令提示字元（CMD）
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Menempelkan perintah di tempat yang salah adalah kegagalan paling umum di Windows. Jika menjalankan baris CMD di PowerShell, Anda akan melihat The token '&&' is not a valid statement separator; jika menjalankan baris PowerShell di CMD, Anda akan melihat 'irm' is not recognized as an internal or external command. Jika menempelkan curl … | bash dari macOS ke PowerShell, akan muncul A parameter cannot be found that matches parameter name 'fsSL'. Dalam ketiga kasus, cukup kembali menggunakan baris yang sesuai.

Sebaiknya instal Git for Windows secara terpisah: Claude Code akan menggunakan Git Bash yang disertakan untuk menjalankan perintah; jika tidak terinstal, Claude Code akan menggunakan PowerShell. Jika sudah terinstal tetapi Git Bash tidak ditemukan, tambahkan CLAUDE_CODE_GIT_BASH_PATH ke bagian env pada file konfigurasi dan arahkan ke jalur bash.exe.

Jika memilih WSL, jalankan baris macOS/Linux di atas di terminal WSL, dan mulai claude di WSL juga, bukan dari PowerShell atau CMD.

Instalasi dengan pengelola paket

Anda juga dapat membiarkan pengelola paket yang sudah ada mengelolanya, dengan konsekuensi default-nya tidak akan diperbarui otomatis; Anda harus melakukan peningkatan secara berkala sendiri (misalnya brew upgrade claude-code, winget upgrade Anthropic.ClaudeCode). Debian/Ubuntu, Fedora/RHEL, dan Alpine juga memiliki repositori paket apt, dnf, dan apk resmi yang ditandatangani.

# Homebrew（macOS、Linux）— stable 通道
brew install --cask claude-code

# WinGet（Windows）
winget install Anthropic.ClaudeCode

# npm — 需要 Node.js 22 以上；絕對不要加 sudo
npm install -g @anthropic-ai/claude-code

Instalasi melalui npm memerlukan Node.js 22 atau lebih baru sejak v2.1.198; jika versi Node.js lebih lama, npm hanya mencetak peringatan EBADENGINE dan instalasi tetap selesai. Yang dipasang adalah berkas executable yang sama dengan yang dipasang oleh installer native dan tidak bergantung pada Node.js saat dijalankan. Jangan pernah gunakan sudo npm install -g; hal itu akan menimbulkan masalah izin dan juga risiko keamanan.

Memastikan instalasi berhasil

claude --version   # 正常會印出版本號，例如 2.1.211 (Claude Code)
claude doctor      # 唯讀的安裝與設定診斷，不會開啟工作階段

claude doctor adalah hal yang paling penting untuk diingat: perintah ini tidak membuka sesi kerja, hanya mencantumkan status instalasi, kesalahan file konfigurasi, dan solusi yang disarankan. Ini adalah cara tercepat untuk membedakan “instalasi rusak” dari “konfigurasi rusak”.

Jika muncul command not found: claude, atau 'claude' is not recognized di Windows, berarti direktori instalasi tidak berada di PATH. Di macOS/Linux, buka terminal baru terlebih dahulu; jika masih tidak berhasil, tambahkan ~/.local/bin ke PATH ~/.zshrc atau ~/.bashrc. Lokasi instalasi Windows adalah %USERPROFILE%\.local\bin; periksa dan tambahkan menggunakan PowerShell:

# 1. 檢查安裝目錄是否已在 PATH 裡
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. 沒有任何輸出的話，把它加進「使用者」PATH，然後關掉終端機重開
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. 重開後再確認一次；若有兩份安裝，這行會列出兩個路徑
where.exe claude

Koneksi pertama: login langganan atau kunci berbasis penggunaan

Jalur A: login dengan akun langganan

Di folder proyek, jalankan claude dan ikuti petunjuk browser untuk login dengan akun Pro, Max, Team, Enterprise, atau Console. Perhatikan satu detail: jika ANTHROPIC_API_KEY sudah ada di lingkungan, Claude Code akan menanyakan sekali apakah Anda ingin menggunakan kunci tersebut; jika saat itu Anda menolak, kunci tersebut kemudian akan diabaikan tanpa pertanyaan lagi, sehingga terlihat seolah-olah variabel tidak terbaca. Untuk mengaktifkannya kembali, buka /config lalu pilih Use custom API key.

Jalur B: tanpa langganan, gunakan kunci berbasis penggunaan

Claude Code secara native mendukung ANTHROPIC_BASE_URL, sehingga menunjuk ke endpoint mana pun yang menyediakan Anthropic Messages API merupakan konfigurasi yang didukung secara resmi; tidak diperlukan plugin, proxy, atau executable yang dimodifikasi. Langkahnya: daftarkan akun, isi saldo (minimum $10), buat kunci yang diawali sk-kn- di halaman pengelolaan kunci (hanya ditampilkan sekali), lalu tetapkan variabel di bawah ini. macOS/Linux:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # 只寫到網域，不要加 /v1
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

Di Windows, untuk mencoba terlebih dahulu dalam satu jendela PowerShell:

# 只對這個 PowerShell 視窗有效，關掉就沒了
$env:ANTHROPIC_BASE_URL = "https://api.kunavo.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-kn-..."
$env:ANTHROPIC_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "claude-opus-5-5"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-4-5"
claude

Untuk penggunaan jangka panjang, sebaiknya tulis ke bagian env pada profil pengguna ~/.claude/settings.json (di Windows adalah %USERPROFILE%\.claude\settings.json). Dengan menulisnya di sini, setiap terminal, ekstensi editor, dan proses latar belakang dapat membacanya; jika file tersebut sudah memiliki pengaturan lain, gabungkan env ke dalamnya:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Pada masing-masing dari enam baris ini ada satu hal yang jika salah dikonfigurasi dapat membuat Anda terhenti cukup lama:

• ANTHROPIC_BASE_URL hanya ditulis sampai domain.Claude Code akan menambahkan /v1/messages sendiri; menambahkan /v1 akan menghasilkan /v1/v1/messages dan mengembalikan 404.
• Gunakan ANTHROPIC_AUTH_TOKEN, jangan gunakan ANTHROPIC_API_KEY.Keduanya berada di header HTTP yang berbeda: yang pertama mengirim Authorization: Bearer dan langsung berlaku; yang kedua mengirim x-api-key dan masih memerlukan konfirmasi satu kali yang dijelaskan di atas.
• ANTHROPIC_MODEL harus berisi nama model yang lengkap dan benar.Kunavo hanya menerima nama yang benar-benar cocok dan tidak otomatis memetakan nama lama dengan sufiks tanggal.
• ANTHROPIC_DEFAULT_OPUS_MODEL bertanggung jawab atas alias opus. Model default Claude Code dan alias opus sama-sama mengarah ke Opus terbaru. Jika Kunavo belum menyediakan model tersebut, hasilnya 404, sehingga baris ini dan ANTHROPIC_MODEL harus dikunci. Di sini alias opus dikunci ke Opus 5.5 (claude-opus-5-5), yang memerlukan Claude Code v2.1.280 atau lebih baru; pada versi lama, jalankan claude update terlebih dahulu.
• ANTHROPIC_DEFAULT_SONNET_MODEL bertanggung jawab atas alias sonnet. Di Anthropic API, alias sonnet mengarah ke Sonnet 5.5, sedangkan Kunavo tidak menyediakan model ini. Jika tidak dikunci, runtime /model sonnet dan opusplan, serta subagen yang disetel ke model: sonnet, akan menghasilkan 404. Karena itu, alias tersebut juga dikunci ke Claude Sonnet 5 (claude-sonnet-5).
• ANTHROPIC_DEFAULT_HAIKU_MODEL menangani alias haiku. Sejak Claude Code v2.1.293, alias haiku mengarah ke Haiku 5.5; versi sebelumnya menggunakan nama Haiku 4.5 dengan akhiran tanggal. Kunavo tidak mengenali kedua nama tersebut. Jika model tidak dipatok, /model haiku dan subagen yang ditetapkan ke model: haiku (termasuk claude-code-guide yang dijalankan Claude Code sendiri) akan menghasilkan 404. Karena itu, patok ke claude-haiku-4-5 di sini.
• ANTHROPIC_DEFAULT_HAIKU_MODEL bertanggung jawab atas panggilan latar belakang.Ringkasan dan judul yang dibuat Claude Code sendiri menggunakan model ini: Claude Haiku 4.5 per 1M token adalah $0,70 / $3,50, sedangkan model utama Claude Sonnet 5 adalah $1,40 / $7,00 (dengan harga yang sama seperti Anthropic resmi).

Jangan menulis kunci ke .claude/settings.json di dalam proyek—file tersebut akan di-commit dan dibagikan kepada setiap orang yang melakukan clone proyek. Jika menggunakan ekstensi VS Code, variabel harus ditempatkan di claudeCode.environmentVariables pada pengaturan pengguna VS Code, karena ekstensi memeriksa kredensial sebelum dimulai.

Memastikan jalur koneksi yang digunakan

Setelah masuk ke Claude Code, jalankan /status. Jika terlihat baris Auth token, berarti kunci sedang berlaku; jika terlihat Login method dan akun claude.ai, berarti variabel tidak terbaca. Keduanya tidak ditumpuk: selama variabel kunci ada, langganan yang sudah login ditangguhkan; hapus variabel untuk kembali ke langganan tanpa menginstal ulang.

Saat menggunakan gateway, tiga hal akan berbeda: Remote Control dan input suara memerlukan identitas claude.ai dan tidak dapat digunakan; pemeriksaan ketersediaan /fast akan langsung menanyakan Anthropic dan mungkin menampilkan bahwa fitur tidak tersedia, tetapi permintaan biasa tidak terpengaruh; angka /context menjadi estimasi lokal. Pemrograman, alat, subagen, MCP, hooks, dan cache prompt tetap berfungsi seperti biasa. Penjelasan lengkap ada di dokumentasi integrasi Claude Code dan panduan kunci API Claude Code (keduanya dalam bahasa Inggris).

Referensi kesalahan umum

Setelah instalasi

Saat pertama kali masuk ke proyek, jalankan /init agar seluruh proyek dibaca dan CLAUDE.md dibuat. Cara beralih antara Opus, Sonnet, dan Haiku sesuai tugas, biaya aktual per sesi, serta cara menggunakan /clear dan /compact untuk menekan biaya, semuanya dibahas dalam tutorial Claude Code.

Pilihan jalur juga layak disampaikan dengan jujur: bagi orang yang berinteraksi lama setiap hari dengan penggunaan tinggi, biaya bulanan tetap langganan biasanya lebih menguntungkan; penagihan berbasis penggunaan cocok untuk volume yang sangat berfluktuasi atau bagi mereka yang tidak ingin dibatasi jendela penggunaan 5 jam, dan bulan tanpa pekerjaan biayanya $0. Melalui Kunavo, Anda menggunakan kapasitas bersama, tanpa kuota khusus dan tanpa SLA kontraktual; tim yang memerlukan jaminan tersebut sebaiknya membeli langsung dari Anthropic. Biaya bulanan dan titik impas kedua jalur ada di biaya Claude Code.

Pertanyaan umum