Debug konfigurasi Anda
Diagnosis mengapa CLAUDE.md, settings, hooks, server MCP, atau skills tidak berlaku. Gunakan /context, /doctor, /hooks, dan /mcp untuk melihat apa yang benar-benar dimuat.
Ketika Claude mengabaikan instruksi atau fitur yang Anda konfigurasi tidak muncul, penyebabnya biasanya adalah file tidak dimuat, dimuat dari lokasi berbeda dari yang Anda harapkan, atau file lain menggantinya. Panduan ini menunjukkan cara memeriksa apa yang benar-benar dimuat oleh Claude Code sehingga Anda dapat mempersempit mana yang berlaku.
Untuk masalah instalasi, autentikasi, dan konektivitas, lihat Troubleshoot installation and login sebagai gantinya.
Lihat apa yang dimuat ke dalam context
Perintah /context menampilkan semua yang menempati jendela context untuk sesi saat ini, dipecah berdasarkan kategori: system prompt, file memory, skills, alat MCP, dan pesan percakapan. Jalankan terlebih dahulu untuk mengonfirmasi apakah CLAUDE.md, rules, atau deskripsi skill Anda ada sama sekali.
Untuk detail tentang kategori tertentu, lanjutkan dengan perintah khusus:
| Perintah | Menampilkan |
|---|---|
/memory |
File CLAUDE.md dan rules mana yang dimuat, ditambah entri auto-memory |
/skills |
Skill yang tersedia dari sumber proyek, pengguna, dan plugin |
/agents |
Subagent yang dikonfigurasi dan pengaturannya |
/hooks |
Konfigurasi hook aktif |
/mcp |
Server MCP yang terhubung dan statusnya |
/permissions |
Aturan allow dan deny yang diselesaikan saat ini berlaku |
/doctor |
Diagnostik konfigurasi: kunci tidak valid, kesalahan schema, kesehatan instalasi |
/debug [issue] |
Mengaktifkan debug logging untuk sesi dan meminta Claude untuk mendiagnosis menggunakan output log dan jalur pengaturan |
/status |
Sumber pengaturan aktif, termasuk apakah pengaturan terkelola berlaku |
Jika file memory hilang dari /memory, periksa lokasinya terhadap bagaimana file CLAUDE.md dimuat. File CLAUDE.md subdirektori dimuat sesuai permintaan ketika Claude membaca file di direktori itu dengan alat Read, bukan pada awal sesi.
Jika /memory mengonfirmasi file dimuat tetapi Claude masih tidak mengikuti instruksi tertentu, masalahnya kemungkinan adalah cara instruksi ditulis daripada apakah itu dimuat. CLAUDE.md bekerja dengan baik untuk jenis panduan yang akan Anda berikan kepada rekan kerja baru, seperti konvensi proyek, perintah build, dan di mana file berada.
Kepatuhan menurun ketika instruksi cukup samar untuk diinterpretasikan dengan berbagai cara, ketika dua file memberikan arahan yang bertentangan, atau ketika file telah tumbuh cukup panjang sehingga aturan individual mendapat perhatian lebih sedikit. Tulis instruksi yang efektif mencakup pola spesifisitas, ukuran, dan struktur yang menjaga kepatuhan tetap tinggi.
Periksa pengaturan yang diselesaikan
Pengaturan menggabungkan di seluruh cakupan terkelola, pengguna, proyek, dan lokal. Pengaturan terkelola selalu menang ketika ada. Di antara sisanya, cakupan yang lebih dekat menggantikan yang lebih luas dalam urutan lokal, kemudian proyek, kemudian pengguna. Beberapa pengaturan juga dapat diatur oleh flag baris perintah atau variabel lingkungan, yang bertindak sebagai lapisan penggantian lain. Ketika pengaturan tidak tampak berlaku, nilai yang Anda atur biasanya ditimpa oleh cakupan lain atau variabel lingkungan.
Jalankan /doctor untuk memvalidasi file konfigurasi Anda dan permukaan kunci tidak valid atau kesalahan schema. Ketika /doctor melaporkan masalah, tekan f untuk mengirim laporan diagnostik ke Claude dan biarkan itu memandu Anda melalui perbaikan.
Jalankan /status untuk melihat sumber pengaturan mana yang aktif, termasuk apakah pengaturan terkelola berlaku. Untuk memahami cakupan mana yang menang untuk kunci tertentu, lihat Bagaimana cakupan berinteraksi.
Periksa server MCP
Jalankan /mcp untuk melihat setiap server yang dikonfigurasi, status koneksinya, dan apakah Anda telah menyetujuinya untuk proyek saat ini. Server dapat didefinisikan dengan benar tetapi masih tidak menyediakan alat untuk beberapa alasan umum:
- Server berscopeproyek di
.mcp.jsonmemerlukan persetujuan satu kali. Jika prompt ditutup, server tetap dinonaktifkan sampai Anda menyetujuinya dari/mcp. - Server yang gagal dimulai ditampilkan sebagai gagal di
/mcp. Jalur file relatif dicommandatauargsadalah penyebab yang sering, karena mereka diselesaikan terhadap direktori tempat Anda meluncurkan Claude Code daripada lokasi.mcp.json. - Server yang menampilkan sebagai terhubung tetapi mencantumkan alat nol telah dimulai dengan sukses tetapi tidak mengembalikan daftar alat. Pilih Reconnect dari
/mcp. Jika hitungan tetap nol, jalankanclaude --debug mcpuntuk melihat output stderr server.
Untuk lokasi konfigurasi dan aturan cakupan, lihat MCP.
Periksa hooks
Jalankan /hooks untuk mencantumkan setiap hook yang terdaftar untuk sesi saat ini, dikelompokkan berdasarkan acara. Jika hook yang Anda tentukan tidak muncul, itu tidak dibaca: hooks berada di bawah kunci "hooks" dalam file pengaturan, bukan dalam file mandiri.
Jika hook muncul tetapi tidak aktif, matcher adalah penyebab yang biasa. Bidang matcher adalah string tunggal yang menggunakan | untuk mencocokkan beberapa nama alat, misalnya "Edit|Write". Nama alat yang salah eja gagal diam-diam karena matcher tidak pernah cocok. Nilai array adalah kesalahan schema: Claude Code menampilkan pemberitahuan kesalahan pengaturan, /doctor melaporkan kegagalan validasi, dan entri hook dijatuhkan sehingga tidak akan muncul di /hooks.
Edit ke settings.json berlaku dalam sesi yang berjalan setelah penundaan stabilitas file singkat. Anda tidak perlu memulai ulang. Jika /hooks masih menampilkan definisi lama beberapa detik setelah menyimpan, jalankan /hooks lagi untuk menyegarkan tampilan.
Jika /hooks menampilkan hook tetapi masih tidak aktif, langkah berikutnya adalah menonton evaluasi hook secara langsung. Mulai sesi dengan claude --debug hooks dan picu panggilan alat. Log debug mencatat setiap acara, matcher mana yang diperiksa, dan kode keluar dan output hook. Lihat Debug hooks untuk format log dan troubleshooting hooks untuk pola kegagalan umum.
Uji terhadap konfigurasi bersih
Jika pemeriksaan yang ditargetkan tidak mengisolasi penyebab, atau konfigurasi Anda dalam keadaan yang tidak diketahui, bandingkan dengan sesi yang tidak memuat apa pun dari pengaturan biasa Anda. Arahkan CLAUDE_CONFIG_DIR ke direktori kosong untuk melewati semua yang ada di bawah ~/.claude, dan luncurkan dari direktori yang tidak memiliki folder .claude, .mcp.json, atau CLAUDE.md sehingga konfigurasi proyek juga dilewati.
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude
Sesi bersih tidak memiliki pengaturan pengguna atau proyek, hooks, server MCP, plugin, atau memory.
- Pengaturan terkelola masih berlaku jika organisasi Anda menerapkannya, karena mereka berada di jalur sistem di luar
~/.claude - Di Linux dan Windows, Anda akan diminta untuk masuk lagi karena kredensial disimpan di bawah direktori konfigurasi
- Di macOS, kredensial berada di Keychain dan terbawa ke sesi bersih
Jika masalah hilang di sini, penyebabnya ada di suatu tempat di file ~/.claude atau proyek .claude Anda yang sebenarnya. Perkenalkan kembali satu per satu, dengan menyalin file ke direktori sementara atau dengan meluncurkan dari proyek Anda, untuk menemukan mana yang menjadi penyebabnya. Jika itu bertahan dalam sesi bersih, penyebabnya ada di luar konfigurasi pengguna dan proyek Anda. Jalankan /status untuk memeriksa apakah pengaturan terkelola berlaku, cari variabel lingkungan yang mempengaruhi Claude Code, kemudian lihat Troubleshooting.
Periksa penyebab umum
Sebagian besar kejutan konfigurasi dapat dilacak kembali ke serangkaian kecil aturan lokasi dan sintaks. Periksa ini sebelum menganggap bug:
| Gejala | Penyebab | Perbaikan |
|---|---|---|
| Hook tidak pernah aktif | matcher adalah array JSON bukan string |
Gunakan string tunggal dengan | untuk mencocokkan beberapa alat, misalnya "Edit|Write". Lihat pola matcher. |
| Hook tidak pernah aktif | Nilai matcher adalah huruf kecil, misalnya "bash" |
Pencocokan peka huruf besar-kecil. Nama alat dikapitalisasi: Bash, Edit, Write, Read. |
| Hook tidak pernah aktif | Hook berada dalam file .claude/hooks.json mandiri |
Tidak ada file hooks mandiri. Tentukan hooks di bawah kunci "hooks" di settings.json. Lihat konfigurasi hook. |
| Permissions, hooks, atau env yang diatur secara global diabaikan | Konfigurasi ditambahkan ke ~/.claude.json |
~/.claude.json menyimpan status aplikasi dan toggle UI. permissions, hooks, dan env termasuk dalam ~/.claude/settings.json. Ini adalah dua file berbeda. |
Nilai settings.json tampak diabaikan |
Kunci yang sama diatur di settings.local.json |
settings.local.json menggantikan settings.json, dan keduanya menggantikan ~/.claude/settings.json. Lihat preseden pengaturan. |
Skill tidak muncul di /skills |
File skill berada di .claude/skills/name.md bukan dalam folder |
Gunakan folder dengan SKILL.md di dalamnya: .claude/skills/name/SKILL.md. |
Skill muncul di /skills tetapi Claude tidak pernah menginvokasinya |
Skill memiliki disable-model-invocation: true di frontmatter-nya, atau deskripsinya tidak cocok dengan cara Anda merumuskan permintaan |
Periksa lencana di /skills: label "user-only" berarti Claude tidak akan memicunya sendiri. Lihat skill invocation. |
Instruksi CLAUDE.md subdirektori tampak diabaikan |
File subdirektori dimuat sesuai permintaan, bukan pada awal sesi | Mereka dimuat ketika Claude membaca file di direktori itu dengan alat Read, bukan saat peluncuran dan bukan saat menulis atau membuat file di sana. Lihat bagaimana file CLAUDE.md dimuat. |
Subagent mengabaikan instruksi CLAUDE.md |
Subagent tidak selalu mewarisi memory proyek | Letakkan aturan penting di badan file agen, yang menjadi system prompt subagent. Lihat konfigurasi subagent. |
| Logika pembersihan tidak pernah berjalan di akhir sesi | Tidak ada hook SessionEnd yang dikonfigurasi |
Tambahkan hook SessionEnd di settings.json. Lihat daftar acara hook. |
Server MCP di .mcp.json tidak pernah dimuat |
File berada di bawah .claude/ atau menggunakan format konfigurasi Claude Desktop |
Konfigurasi MCP proyek berada di akar repositori sebagai .mcp.json, bukan di dalam .claude/. Lihat konfigurasi MCP. |
Server MCP ditambahkan di bawah mcpServers di settings.json tidak pernah muncul |
settings.json tidak membaca kunci mcpServers |
Tentukan server proyek di .mcp.json di akar repositori, atau jalankan claude mcp add --scope user untuk server berscopepengguna. Lihat konfigurasi MCP. |
| Server MCP proyek ditambahkan tetapi tidak muncul | Prompt persetujuan satu kali ditutup | Server berscopeproyek memerlukan persetujuan. Jalankan /mcp untuk melihat status dan setujui. |
| Server MCP gagal dimulai dari beberapa direktori | command atau args menggunakan jalur file relatif |
Gunakan jalur absolut untuk skrip lokal. Executable di PATH Anda seperti npx atau uvx bekerja apa adanya. |
| Server MCP dimulai tanpa variabel lingkungan yang diharapkan | Variabel berada di settings.json env, yang tidak menyebar ke proses anak MCP |
Atur env per-server di dalam .mcp.json sebagai gantinya. |
Aturan deny Bash(rm *) tidak memblokir /bin/rm atau find -delete |
Aturan awalan mencocokkan string perintah literal, bukan executable yang mendasar | Tambahkan pola eksplisit untuk setiap varian, atau gunakan hook PreToolUse atau sandbox untuk jaminan keras. |
Sumber daya terkait
Untuk referensi lengkap pada setiap permukaan konfigurasi, lihat halaman khusus:
- Referensi direktori
.claude: setiap lokasi file konfigurasi dan apa yang membacanya - Settings: urutan preseden dan daftar kunci lengkap
- Referensi Hooks: nama acara, payload, dan format output
--debug hooks - MCP: konfigurasi server, persetujuan, dan output
/mcp - Troubleshoot installation and login:
command not found, PATH, dan masalah autentikasi - Troubleshooting: kinerja, hang, dan masalah pencarian