Langsung ke konten utama

​
Masalah instalasi umum

​
Masalah instalasi Windows: kesalahan di WSL

Anda mungkin mengalami masalah berikut di WSL: Masalah deteksi OS/platform: Jika Anda menerima kesalahan selama instalasi, WSL mungkin menggunakan npm Windows. Coba:
  • Jalankan npm config set os linux sebelum instalasi
  • Instal dengan npm install -g @anthropic-ai/claude-code --force --no-os-check (JANGAN gunakan sudo)
Kesalahan Node tidak ditemukan: Jika Anda melihat exec: node: not found saat menjalankan claude, lingkungan WSL Anda mungkin menggunakan instalasi Node.js Windows. Anda dapat mengkonfirmasi ini dengan which npm dan which node, yang harus menunjuk ke jalur Linux yang dimulai dengan /usr/ bukan /mnt/c/. Untuk memperbaikinya, coba instal Node melalui manajer paket distribusi Linux Anda atau melalui nvm. Konflik versi nvm: Jika Anda memiliki nvm terinstal di WSL dan Windows, Anda mungkin mengalami konflik versi saat beralih versi Node di WSL. Ini terjadi karena WSL mengimpor PATH Windows secara default, menyebabkan nvm/npm Windows mengambil prioritas atas instalasi WSL. Anda dapat mengidentifikasi masalah ini dengan:
  • Menjalankan which npm dan which node - jika mereka menunjuk ke jalur Windows (dimulai dengan /mnt/c/), versi Windows sedang digunakan
  • Mengalami fungsionalitas yang rusak setelah beralih versi Node dengan nvm di WSL
Untuk mengatasi masalah ini, perbaiki PATH Linux Anda untuk memastikan versi node/npm Linux mengambil prioritas: Solusi utama: Pastikan nvm dimuat dengan benar di shell Anda Penyebab paling umum adalah nvm tidak dimuat di shell non-interaktif. Tambahkan berikut ini ke file konfigurasi shell Anda (~/.bashrc, ~/.zshrc, dll.): 
# Load nvm if it exists
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
Atau jalankan langsung di sesi Anda saat ini: 
source ~/.nvm/nvm.sh
Alternatif: Sesuaikan urutan PATH Jika nvm dimuat dengan benar tetapi jalur Windows masih mengambil prioritas, Anda dapat secara eksplisit menambahkan jalur Linux Anda ke PATH di konfigurasi shell Anda: 
export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"
Hindari menonaktifkan impor PATH Windows (appendWindowsPath = false) karena ini menghilangkan kemampuan untuk dengan mudah memanggil executable Windows dari WSL. Demikian pula, hindari mencopot instalasi Node.js dari Windows jika Anda menggunakannya untuk pengembangan Windows.

​
Masalah instalasi Linux dan Mac: kesalahan izin atau perintah tidak ditemukan

Saat menginstal Claude Code dengan npm, masalah PATH dapat mencegah akses ke claude. Anda juga mungkin mengalami kesalahan izin jika awalan global npm Anda tidak dapat ditulis oleh pengguna (misalnya /usr, atau /usr/local).

​
Solusi yang direkomendasikan: Instalasi Claude Code asli

Claude Code memiliki instalasi asli yang tidak bergantung pada npm atau Node.js.
Penginstal Claude Code asli saat ini dalam beta.
Gunakan perintah berikut untuk menjalankan penginstal asli. macOS, Linux, WSL: 
# Install stable version (default)
curl -fsSL https://claude.ai/install.sh | bash

# Install latest version
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Install specific version number
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
Windows PowerShell: 
# Install stable version (default)
irm https://claude.ai/install.ps1 | iex

# Install latest version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# Install specific version number
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58
Perintah ini menginstal build Claude Code yang sesuai untuk sistem operasi dan arsitektur Anda dan menambahkan symlink ke instalasi di ~/.local/bin/claude.
Pastikan Anda memiliki direktori instalasi di PATH sistem Anda.

​
Solusi alternatif: Migrasi ke instalasi lokal

Alternatifnya, jika Claude Code akan berjalan, Anda dapat bermigrasi ke instalasi lokal: 
claude migrate-installer
Ini memindahkan Claude Code ke ~/.claude/local/ dan menyiapkan alias di konfigurasi shell Anda. Tidak ada sudo yang diperlukan untuk pembaruan di masa depan. Setelah migrasi, mulai ulang shell Anda, kemudian verifikasi instalasi Anda: Di macOS/Linux/WSL: 
which claude  # Should show an alias to ~/.claude/local/claude
Di Windows: 
where claude  # Should show path to claude executable
Verifikasi instalasi: 
claude doctor # Check installation health

​
Izin dan autentikasi

​
Permintaan izin berulang

Jika Anda menemukan diri Anda berulang kali menyetujui perintah yang sama, Anda dapat mengizinkan alat tertentu untuk berjalan tanpa persetujuan menggunakan perintah /permissions. Lihat dokumentasi Izin.

​
Masalah autentikasi

Jika Anda mengalami masalah autentikasi:
  1. Jalankan /logout untuk keluar sepenuhnya
  2. Tutup Claude Code
  3. Mulai ulang dengan claude dan selesaikan proses autentikasi lagi
Jika masalah berlanjut, coba: 
rm -rf ~/.config/claude-code/auth.json
claude
Ini menghapus informasi autentikasi yang disimpan dan memaksa login yang bersih.

​
Kinerja dan stabilitas

​
Penggunaan CPU atau memori tinggi

Claude Code dirancang untuk bekerja dengan sebagian besar lingkungan pengembangan, tetapi dapat mengonsumsi sumber daya yang signifikan saat memproses basis kode besar. Jika Anda mengalami masalah kinerja:
  1. Gunakan /compact secara teratur untuk mengurangi ukuran konteks
  2. Tutup dan mulai ulang Claude Code di antara tugas-tugas besar
  3. Pertimbangkan untuk menambahkan direktori build besar ke file .gitignore Anda

​
Perintah hang atau freeze

Jika Claude Code tampak tidak responsif:
  1. Tekan Ctrl+C untuk mencoba membatalkan operasi saat ini
  2. Jika tidak responsif, Anda mungkin perlu menutup terminal dan memulai ulang

​
Masalah pencarian dan penemuan

Jika alat Pencarian, penyebutan @file, agen khusus, dan perintah slash khusus tidak berfungsi, instal ripgrep sistem: 
# macOS (Homebrew)  
brew install ripgrep

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine Linux
apk add ripgrep

# Arch Linux
pacman -S ripgrep
Kemudian atur USE_BUILTIN_RIPGREP=0 di lingkungan Anda.

​
Hasil pencarian lambat atau tidak lengkap di WSL

Penalti kinerja pembacaan disk saat bekerja di seluruh sistem file di WSL dapat menghasilkan kecocokan yang lebih sedikit dari yang diharapkan (tetapi bukan kekurangan fungsionalitas pencarian yang lengkap) saat menggunakan Claude Code di WSL.
/doctor akan menampilkan Pencarian sebagai OK dalam hal ini.
Solusi:
  1. Kirimkan pencarian yang lebih spesifik: Kurangi jumlah file yang dicari dengan menentukan direktori atau jenis file: “Cari logika validasi JWT dalam paket auth-service” atau “Temukan penggunaan hash md5 dalam file JS”.
  2. Pindahkan proyek ke sistem file Linux: Jika memungkinkan, pastikan proyek Anda berada di sistem file Linux (/home/) bukan sistem file Windows (/mnt/c/).
  3. Gunakan Windows asli sebagai gantinya: Pertimbangkan untuk menjalankan Claude Code secara asli di Windows bukan melalui WSL, untuk kinerja sistem file yang lebih baik.

​
Masalah integrasi IDE

​
IDE JetBrains tidak terdeteksi di WSL2

Jika Anda menggunakan Claude Code di WSL2 dengan IDE JetBrains dan mendapatkan kesalahan “No available IDEs detected”, ini kemungkinan besar karena konfigurasi jaringan WSL2 atau Windows Firewall memblokir koneksi.

​
Mode jaringan WSL2

WSL2 menggunakan jaringan NAT secara default, yang dapat mencegah deteksi IDE. Anda memiliki dua opsi: Opsi 1: Konfigurasikan Windows Firewall (direkomendasikan)
  1. Temukan alamat IP WSL2 Anda: 
    wsl hostname -I
# Example output: 172.21.123.456
  2. Buka PowerShell sebagai Administrator dan buat aturan firewall: 
    New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16
    (Sesuaikan rentang IP berdasarkan subnet WSL2 Anda dari langkah 1)
  3. Mulai ulang IDE dan Claude Code Anda
Opsi 2: Beralih ke jaringan mirrored Tambahkan ke .wslconfig di direktori pengguna Windows Anda: 
[wsl2]
networkingMode=mirrored
Kemudian mulai ulang WSL dengan wsl --shutdown dari PowerShell.
Masalah jaringan ini hanya mempengaruhi WSL2. WSL1 menggunakan jaringan host secara langsung dan tidak memerlukan konfigurasi ini.
Untuk tips konfigurasi JetBrains tambahan, lihat panduan integrasi IDE kami.

​
Melaporkan masalah integrasi IDE Windows (asli dan WSL)

Jika Anda mengalami masalah integrasi IDE di Windows, silakan buat masalah dengan informasi berikut: apakah Anda asli (git bash), atau WSL1/WSL2, mode jaringan WSL (NAT atau mirrored), nama/versi IDE, versi ekstensi/plugin Claude Code, dan jenis shell (bash/zsh/dll)

​
Tombol ESC tidak berfungsi di terminal JetBrains (IntelliJ, PyCharm, dll.)

Jika Anda menggunakan Claude Code di terminal JetBrains dan tombol ESC tidak mengganggu agen seperti yang diharapkan, ini kemungkinan besar karena benturan keybinding dengan pintasan default JetBrains. Untuk memperbaiki masalah ini:
  1. Buka Settings → Tools → Terminal
  2. Salah satu:
    • Hapus centang “Move focus to the editor with Escape”, atau
    • Klik “Configure terminal keybindings” dan hapus pintasan “Switch focus to Editor”
  3. Terapkan perubahan
Ini memungkinkan tombol ESC untuk dengan benar mengganggu operasi Claude Code.

​
Masalah pemformatan Markdown

Claude Code kadang-kadang menghasilkan file markdown dengan tag bahasa yang hilang pada pagar kode, yang dapat mempengaruhi penyorotan sintaks dan keterbacaan di GitHub, editor, dan alat dokumentasi.

​
Tag bahasa yang hilang dalam blok kode

Jika Anda melihat blok kode seperti ini dalam markdown yang dihasilkan: 
```
function example() {
  return "hello";
}
```
Bukan blok yang diberi tag dengan benar seperti: 
```javascript
function example() {
  return "hello";
}
```
Solusi:
  1. Minta Claude untuk menambahkan tag bahasa: Cukup minta “Please add appropriate language tags to all code blocks in this markdown file.”
  2. Gunakan hook pemrosesan pasca: Siapkan hook pemformatan otomatis untuk mendeteksi dan menambahkan tag bahasa yang hilang. Lihat contoh hook pemformatan markdown untuk detail implementasi.
  3. Verifikasi manual: Setelah menghasilkan file markdown, tinjau untuk pemformatan blok kode yang tepat dan minta koreksi jika diperlukan.

​
Spasi dan pemformatan yang tidak konsisten

Jika markdown yang dihasilkan memiliki baris kosong yang berlebihan atau spasi yang tidak konsisten: Solusi:
  1. Minta koreksi pemformatan: Minta Claude untuk “Fix spacing and formatting issues in this markdown file.”
  2. Gunakan alat pemformatan: Siapkan hook untuk menjalankan pemformat markdown seperti prettier atau skrip pemformatan khusus pada file markdown yang dihasilkan.
  3. Tentukan preferensi pemformatan: Sertakan persyaratan pemformatan dalam prompt Anda atau file memori proyek.

​
Praktik terbaik untuk pembuatan markdown

Untuk meminimalkan masalah pemformatan:
  • Jadilah eksplisit dalam permintaan: Minta “properly formatted markdown with language-tagged code blocks”
  • Gunakan konvensi proyek: Dokumentasikan gaya markdown pilihan Anda di CLAUDE.md
  • Siapkan hook validasi: Gunakan hook pemrosesan pasca untuk secara otomatis memverifikasi dan memperbaiki masalah pemformatan umum

​
Mendapatkan bantuan lebih lanjut

Jika Anda mengalami masalah yang tidak tercakup di sini:
  1. Gunakan perintah /bug dalam Claude Code untuk melaporkan masalah langsung ke Anthropic
  2. Periksa repositori GitHub untuk masalah yang diketahui
  3. Jalankan /doctor untuk memeriksa kesehatan instalasi Claude Code Anda
  4. Tanyakan Claude secara langsung tentang kemampuan dan fiturnya - Claude memiliki akses bawaan ke dokumentasinya