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 Windows npm. 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 mengonfirmasi ini dengan which npm dan which node, yang seharusnya 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 yang diinstal 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 Windows nvm/npm 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 menghancurkan kemampuan untuk 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 mungkin mencegah akses ke claude. Anda juga mungkin mengalami kesalahan izin jika awalan global npm Anda tidak dapat ditulis 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. 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 (atau %USERPROFILE%\.local\bin\claude.exe di Windows).
Pastikan Anda memiliki direktori instalasi di PATH sistem Anda.

​
Windows: “Claude Code on Windows requires git-bash”

Claude Code di Windows asli memerlukan Git for Windows yang mencakup Git Bash. Jika Git diinstal tetapi tidak terdeteksi:
  1. Atur jalur secara eksplisit di PowerShell sebelum menjalankan Claude: 
    $env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"
  2. Atau tambahkan ke variabel lingkungan sistem Anda secara permanen melalui System Properties → Environment Variables.
Jika Git diinstal di lokasi non-standar, sesuaikan jalur sesuai kebutuhan.

​
Windows: “installMethod is native, but claude command not found”

Jika Anda melihat kesalahan ini setelah instalasi, perintah claude tidak ada di PATH Anda. Tambahkan secara manual:
1

Buka Environment Variables

Tekan Win + R, ketik sysdm.cpl, dan tekan Enter. Klik Advanced → Environment Variables.
2

Edit User PATH

Di bawah “User variables”, pilih Path dan klik Edit. Klik New dan tambahkan:
%USERPROFILE%\.local\bin
3

Restart terminal Anda

Tutup dan buka kembali PowerShell atau CMD agar perubahan berlaku.
Verifikasi instalasi: 
claude doctor # Check installation health

​
Izin dan autentikasi

​
Prompt 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 terus berlanjut, coba: 
rm -rf ~/.config/claude-code/auth.json
claude
Ini menghapus informasi autentikasi yang disimpan dan memaksa login bersih.

​
Lokasi file konfigurasi

Claude Code menyimpan konfigurasi di beberapa lokasi:
FileTujuan
~/.claude/settings.jsonPengaturan pengguna (izin, hook, penggantian model)
.claude/settings.jsonPengaturan proyek (diperiksa ke kontrol sumber)
.claude/settings.local.jsonPengaturan proyek lokal (tidak dikomit)
~/.claude.jsonStatus global (tema, OAuth, server MCP, alat yang diizinkan)
.mcp.jsonServer MCP proyek (diperiksa ke kontrol sumber)
managed-settings.jsonPengaturan terkelola
managed-mcp.jsonServer MCP terkelola
Di Windows, ~ mengacu pada direktori home pengguna Anda, seperti C:\Users\YourName. Lokasi file terkelola:
  • macOS: /Library/Application Support/ClaudeCode/
  • Linux/WSL: /etc/claude-code/
  • Windows: C:\Program Files\ClaudeCode\
Untuk detail tentang mengonfigurasi file ini, lihat Pengaturan dan MCP.

​
Mengatur ulang konfigurasi

Untuk mengatur ulang Claude Code ke pengaturan default, Anda dapat menghapus file konfigurasi: 
# Reset all user settings and state
rm ~/.claude.json
rm -rf ~/.claude/

# Reset project-specific settings
rm -rf .claude/
rm .mcp.json
Ini akan menghapus semua pengaturan, alat yang diizinkan, konfigurasi server MCP, dan riwayat sesi Anda.

​
Kinerja dan stabilitas

​
Penggunaan CPU atau memori tinggi

Claude Code dirancang untuk bekerja dengan sebagian besar lingkungan pengembangan, tetapi mungkin menggunakan 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 Search, penyebutan @file, agen kustom, dan perintah slash kustom tidak berfungsi, instal sistem ripgrep: 
# 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 mungkin menghasilkan kecocokan yang lebih sedikit dari yang diharapkan (tetapi bukan kekurangan fungsionalitas pencarian lengkap) saat menggunakan Claude Code di WSL.
/doctor akan menampilkan Search sebagai OK dalam kasus ini.
Solusi:
  1. Kirimkan pencarian yang lebih spesifik: Kurangi jumlah file yang dicari dengan menentukan direktori atau jenis file: “Search for JWT validation logic in the auth-service package” atau “Find use of md5 hash in JS files”.
  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

​
JetBrains IDE 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: Konfigurasi 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 IDE JetBrains kami.

​
Melaporkan masalah integrasi IDE Windows (asli dan WSL)

Jika Anda mengalami masalah integrasi IDE di Windows, buat masalah dengan informasi berikut:
  • Jenis lingkungan: Windows asli (Git Bash) atau WSL1/WSL2
  • Mode jaringan WSL (jika berlaku): NAT atau mirrored
  • Nama dan versi IDE
  • Versi ekstensi/plugin Claude Code
  • Jenis shell: Bash, Zsh, PowerShell, dll.

​
Tombol Escape 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:
    • Batalkan 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 menambahkan tag bahasa: Minta “Add appropriate language tags to all code blocks in this markdown file.”
  2. Gunakan hook pemrosesan pasca: Atur 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 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: Atur hook untuk menjalankan pemformat markdown seperti prettier atau skrip pemformatan kustom pada file markdown yang dihasilkan.
  3. Tentukan preferensi pemformatan: Sertakan persyaratan pemformatan dalam prompt atau file memori proyek Anda.

​
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
  • Atur 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