Blog

Pemulihan Claude Code: Safe Mode, /cd dan Sandaran

Markdown

Mendiagnosis Claude Code menggunakan safe mode, arahan /cd, model sandaran dan pemulihan tetapan. Turutan pemeriksaan dan batasan asal.

Baca artikel penuh

Bahan praktikal tentang bekerja dengan ejen: dokumentasi Ailoot.

Apakah yang Berubah dalam Claude Code pada Jun 2026?

Inti penting

Pada 8 Jun 2026, dalam Claude Code v2.1.169, Anthropic menambah bendera --safe-mode dan arahan /cd. Dua hari sebelumnya, v2.1.166 memperkenalkan model sandaran, sehingga 3 model dalam satu rantaian. Tiga ciri ini menangani masalah paling lazim bagi vibe coder: “semuanya sudah rosak, saya tak tahu siapa yang patut dipersalahkan, dan saya tak mahu kehilangan sejam untuk memasang semula.”

Sebelum ini, apabila Claude Code mula berkelakuan pelik—pemutar pemuatan yang tidak berhenti, ranap semasa dimulakan, ejen mengabaikan peraturan dalam CLAUDE.md, hook yang gagal berjalan tanpa sebarang petunjuk—hanya ada satu jalan keluar: ulas keluar bahagian .claude/settings.json secara manual, nyahaktifkan pelayan MCP satu demi satu, atau, dalam keadaan paling teruk, padam ~/.claude dan pasang semula. Dalam satu kes yang diterangkan, ~/.claude dipadam lalu persediaan pelayan MCP yang mengambil masa sejam setengah untuk disiapkan turut hilang. Kemudian barulah jelas bahawa puncanya satu baris dalam CLAUDE.md, yang boleh ditemukan dalam 10 saat—tetapi perkara itu hanya jelas selepas pemulihan penuh.

Pada Jun 2026, Anthropic melancarkan tiga mekanisme yang mengubah keadaan ini. Secara ringkas, perkara yang diperkenalkan dan waktunya:

VersiTarikhPerkara yang diperkenalkan
2.1.1666 Jun 2026Tetapan fallbackModel + bendera --fallback-model untuk sesi interaktif
2.1.1698 Jun 2026Bendera --safe-mode dan pemboleh ubah persekitaran CLAUDE_CODE_SAFE_MODE, arahan /cd
2.1.17612 Jun 2026Pembetulan: /cd dan pertukaran worktree tidak lagi memaparkan cabang git lama

Di bawah, setiap mekanisme diterangkan langkah demi langkah, bersama-sama turutan penggunaannya apabila sesi Claude Code tersasar.

Apakah yang Paling Kerap Merosakkan Claude Code?

Inti penting

Berdasarkan pengalaman yang diterangkan, Claude Code biasanya rosak untuk vibe coder disebabkan empat perkara: CLAUDE.md yang terlalu panjang dengan peraturan bercanggah, hook dengan kod keluar yang salah, pelayan MCP yang gagal secara senyap, dan tetapan bertindih merentasi tiga peringkat settings.json. Hanya ada satu punca, diagnosis mengambil masa beberapa minit, tetapi panik mendorong orang terus menggunakan rm -rf.

Dalam contoh yang diterangkan, CLAUDE.md pada mulanya disediakan dengan 80 baris—dan berfungsi selama sebulan. Pada bulan kedua, mula kelihatan bahawa sekali seminggu Claude akan melanggar setiap peraturan yang ditetapkan: menyentuh .env, menjalankan git push --force, menyelongkar node_modules. Bukan kerana niat jahat—Claude cuma terlupa. Pernah sekali .gitignore dipadam dan sebabnya tidak jelas serta-merta. Senario ini dibincangkan dengan lebih terperinci dalam panduan tentang CLAUDE.md.

Apabila CLAUDE.md berkembang hingga 400+ baris, ia mula menimbulkan masalah secara senyap: fail itu menggunakan sebahagian besar tetingkap konteks ketika sesi bermula dan mencairkan arahan penting dengan arahan sampingan. Claude masih membaca fail itu secara formal, jadi dari luar nampaknya “peraturannya ada, tetapi tidak berfungsi”—tanda lazim kontrak yang terlalu panjang.

Hook ialah punca lazim kedua. Claude Code hooks mempunyai satu kelainan yang tidak ditekankan oleh Anthropic.

Maksudnya, sys.exit(1) dalam hook Python (atau sebarang cara Unix lazim untuk “gagal dengan ralat”) tidak akan menghentikan Claude. Hanya kod 2 yang menyekat. Dalam kes yang diterangkan, hook itu dianggap sebagai “larangan keras”, tetapi sebenarnya ia hanya merekodkan aduan dan membenarkan tindakan diteruskan.

Pelayan MCP ialah lapisan ketiga dan juga boleh rosak dengan cara tersendiri.

Gejalanya selalunya sama: arahan MCP tersedia tetapi memulangkan failed tanpa traceback. Untuk maklumat lanjut tentang mengkonfigurasi MCP dan menambah pelayan dengan claude mcp add, lihat panduan berasingan.

Punca keempat ialah hierarki tiga peringkat settings.json. Anda mempunyai ~/.claude/settings.json (peringkat pengguna), .claude/settings.json di akar projek (projek), .claude/settings.local.json (setempat), dan, secara pilihan, tetapan terurus daripada pentadbir syarikat. Tetapan ini digabungkan mengikut peraturan keutamaan. Apabila seseorang menambah pelayan MCP pada peringkat projek sedangkan anda mempunyai entri serupa dengan konfigurasi pelancaran berbeza pada peringkat pengguna, konflik senyap berlaku dan kelihatan seperti “Claude Code rosak”.

Bagaimanakah --safe-mode Berfungsi, dan Apakah yang Dilumpuhkannya?

Inti penting

claude --safe-mode melancarkan Claude Code dengan semua penyesuaian dilumpuhkan sepenuhnya: CLAUDE.md, pemalam, kemahiran, hook, pelayan MCP, arahan pengguna, ejen, gaya output, aliran kerja dan kekunci pintasan. Pengesahan, pemilihan model, alat terbina dalam dan kebenaran kekal aktif. Ini alat diagnostik: jika masalah hilang dalam safe mode, salah satu lapisan yang anda tambah ialah puncanya.

Kata-kata asal Anthropic dalam changelog v2.1.169 berbunyi:

Menambah bendera --safe-mode (dan CLAUDE_CODE_SAFE_MODE) untuk melancarkan Claude Code dengan penyesuaian dilumpuhkan (CLAUDE.md, pemalam, kemahiran, hook, pelayan MCP) bagi tujuan diagnostik.

— Anthropic Claude Code Changelog, https://code.claude.com/docs/en/changelog

Anthropic menjelaskan dalam dokumentasi konfigurasi model:

Untuk memeriksa sama ada penyesuaian yang menjadi punca, mulakan sesi dengan claude --safe-mode, yang melumpuhkan CLAUDE.md, kemahiran, pelayan MCP dan hook. Status Git dan nama direktori tidak dianggap sebagai penyesuaian dan kekal tersedia.

— Anthropic Docs - Model configuration, https://code.claude.com/docs/en/model-config

Ini alat diagnostik, bukan “persekitaran bersih”. Safe mode membantu menjawab satu soalan: adakah masalah berpunca daripada tingkah laku asal Claude Code, atau daripada penyesuaian yang ditambah? Ini sebahagian daripada kejuruteraan konteks—mengurus perkara yang dilihat dan tidak dilihat oleh Claude pada sesuatu masa. Jika semuanya berfungsi dalam safe mode, lapisan-lapisan itu perlu diperiksa menggunakan carian binari. Jika masih tidak berfungsi, masalahnya terletak pada pemasangan, pengesahan, rangkaian atau infrastruktur; dalam keadaan itu, semak claude doctor dan log.

Perkara yang dilumpuhkan oleh safe mode (senarai rasmi Anthropic—5 lapisan utama):

  • CLAUDE.md pada semua peringkat (pengguna / projek)
  • Pemalam
  • Kemahiran
  • Hook
  • Pelayan MCP

Perkara yang kekal berfungsi:

  • Pengesahan (sesi OAuth atau kunci API anda)
  • Pemilihan model (--model sonnet, --model opus)
  • Alat terbina dalam (Read, Write, Bash, Grep dan sebagainya)
  • Kebenaran
  • Status Git
  • Nama direktori

Satu perincian penting: safe mode tidak melumpuhkan tetapan terurus atau dasar daripada pentadbir syarikat. Jika anda bekerja dalam pasukan yang menggunakan Bedrock GovCloud atau konfigurasi MDM untuk menetapkan availableModels, sekatan itu kekal—safe mode hanya melumpuhkan penyesuaian anda, bukan dasar syarikat.

Bagaimanakah Cara Mengasingkan Satu Lapisan dan Mencari Puncanya dalam 60 Saat?

Inti penting

Langkah 1: jalankan claude --safe-mode dalam folder yang sama tempat masalah berlaku. Jika ia berfungsi, isu itu berpunca daripada penyesuaian anda. Kemudian aktifkannya satu demi satu: CLAUDE.md -> hook -> MCP -> kemahiran. Jika safe mode pun tidak berfungsi, masalahnya berkaitan pengesahan, versi, rangkaian atau OS. Dalam keadaan itu, jalankan claude doctor untuk diagnostik automatik tanpa menyentuh rm -rf.

Senario diagnostik untuk keadaan apabila Claude Code “berhenti mendengar”. Versi minimum untuk semua arahan di bawah ialah Claude Code v2.1.169. Jika versi anda lebih lama, kemas kini dahulu (npm update -g @anthropic-ai/claude-code atau gunakan pemasang natif Anthropic).

  1. Buka folder yang sama tempat masalah berlaku.
  2. Jalankan claude --safe-mode.
  3. Jika ia bermula dengan bersih, semak permintaan asal anda. Adakah ia berfungsi? Jika ya, salah satu lapisan itu puncanya. Pergi ke langkah 4.
  4. Jika ia masih rosak dalam safe mode, jangan usik konfigurasi. Jalankan claude doctor dahulu; semak pengesahan, versi dan pemasangan yang bercanggah.

Sebaik sahaja safe mode bermula dengan bersih, aktifkan lapisan satu demi satu, bermula dengan punca yang paling berkemungkinan. Turutan ini berdasarkan pengalaman yang diterangkan:

  1. CLAUDE.md. Jalankan claude tanpa safe mode tetapi namakan semula fail itu buat sementara waktu: mv CLAUDE.md CLAUDE.md.bak. Jika ia berfungsi, fail itu puncanya. Kemudian anda boleh membuat carian binari: kekalkan separuh baris dan semak.
  2. Hook. Buka .claude/settings.json dan tetapkan [] buat sementara waktu dalam bahagian hooks. Mulakan semula claude. Adakah ia berfungsi? Jika ya, salah satu hook itu puncanya. Aktifkan hook satu demi satu.
  3. Pelayan MCP. Begitu juga, dalam ~/.claude.json atau .claude/settings.json, tetapkan bahagian mcpServers kepada objek kosong buat sementara waktu, mulakan semula dan semak.
  4. Kemahiran. Pindahkan .claude/skills/ ke folder sementara. Lancarkan dan semak.

Maksud “menamakan semula buat sementara waktu”: fail tidak dipadam semasa diagnosis. mv atau git stash membolehkan anda memulihkan semuanya dengan satu arahan jika lapisan itu bukan puncanya.

Bagaimanakah Cara Menukar Folder Kerja dengan /cd Tanpa Kehilangan Konteks?

Inti penting

Arahan /cd <path> dalam Claude Code 2.1.169+ menukar folder kerja dalam sesi aktif tanpa kehilangan cache prompt. Ia berguna apabila konfigurasi projek semasa rosak: anda boleh beralih ke folder bersih, menyemak bahawa Claude berfungsi dan kembali semula. Sebelum ini, anda perlu menutup sesi dan memulakannya semula.

Daripada changelog v2.1.169 pada 8 Jun:

Menambah arahan /cd untuk menukar sesi ke folder kerja baharu tanpa menetapkan semula cache prompt di tengah sesi.

— Anthropic Claude Code Changelog, https://code.claude.com/docs/en/changelog

Mengapa ciri ini berguna untuk menyelesaikan masalah. Katakan anda berada dalam folder projek ~/work/myapp dan Claude Code berkelakuan pelik. Dahulu, satu-satunya cara untuk menyemak “adakah ia berfungsi langsung?” ialah menutup sesi, beralih ke folder lain dan memulakannya semula. Anda kehilangan konteks, sejarah dan cache prompt yang telah dipanaskan. Kini:

# In the same session:
/cd ~/sandbox/test

Claude beralih ke folder baharu dan membaca CLAUDE.md di situ (jika ada) sebagai mesej, bukan sebagai pengganti prompt sistem—jadi cache kekal tersedia. Jika semuanya berfungsi dalam ~/sandbox/test, jelaslah bahawa masalahnya terdapat dalam konfigurasi ~/work/myapp.

Pada 12 Jun, v2.1.176 membetulkan satu regresi yang menyusahkan—/cd memaparkan cabang git lama sehingga sesi dimulakan semula sepenuhnya. Jika versi anda lebih lama, kemas kini atau abaikan git status sahaja untuk beberapa mesej pertama selepas pertukaran; status itu akan dikemas kini.

Bagaimanakah Cara Mengkonfigurasi Model Sandaran untuk Ralat 529?

Inti penting

Dalam v2.1.166, Anthropic menambah fallbackModel—rantaian sehingga 3 model yang dicuba mengikut turutan apabila model utama terlebih muatan atau tidak tersedia. Rantaian ini hanya diaktifkan oleh keadaan terlebih muatan dan ralat pelayan yang tidak boleh dicuba semula. Ralat pengesahan, pengebilan, had kadar dan pengangkutan tidak mengaktifkan rantaian sandaran—ralat tersebut mengikut logik percubaan semula biasa.

Dalam senario yang diterangkan, tugasan panjang dijalankan menggunakan Opus dalam sebuah projek seminggu sekali; selepas 10 minit, API memulangkan 529 Overloaded dan sesi ranap. Sebelum ini, anda perlu menunggu atau menukar sendiri kepada Sonnet dengan --model sonnet, lalu kehilangan semua konteks yang telah dipanaskan. Dalam business/ besar dengan persediaan second-brain, proses ini mengambil kira-kira dua puluh minit kerja. Kini tersedia mekanisme yang sewajarnya.

Petikan tepat daripada dokumentasi rasmi:

Apabila model utama terlebih muatan, tidak tersedia atau memulangkan ralat pelayan lain yang tidak boleh dicuba semula, Claude Code boleh bertukar kepada model sandaran dan bukannya menggagalkan permintaan. Ralat pengesahan, pengebilan, had kadar, saiz permintaan dan pengangkutan tidak akan mengaktifkan pertukaran—ralat tersebut mengikut laluan percubaan semula dan pengendalian ralat biasa.

— Anthropic Docs - Model configuration, https://code.claude.com/docs/en/model-config

Dan secara berasingan, cara rantaian itu berfungsi:

Konfigurasikan satu atau lebih model sandaran, lalu Claude Code mencubanya mengikut turutan dan memaparkan pemberitahuan apabila model bertukar. Pertukaran hanya digunakan untuk giliran semasa—mesej seterusnya akan mencuba model utama semula. Rantaian dihadkan kepada tiga model selepas pendua dibuang; entri tambahan diabaikan.

— Anthropic Docs - Model configuration, https://code.claude.com/docs/en/model-config

Terdapat dua cara untuk mengkonfigurasikannya. Melalui CLI:

claude --fallback-model sonnet,haiku

Melalui ~/.claude/settings.json:

{
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}

Satu perkara berasingan tentang had kadar. Anthropic sengaja tidak menghantar ralat 429 melalui rantaian ini supaya anda tidak boleh memintas had permintaan dengan bertukar kepada model seterusnya. Model sandaran hanya berfungsi apabila model utama terlebih muatan, tidak tersedia atau memulangkan ralat pelayan yang tidak boleh dicuba semula (contohnya, 529 Overloaded). Had kadar menggunakan logik percubaan semula dan jeda biasa.

Satu lagi perkara—pada 12 Jun, v2.1.174 membetulkan regresi: pemampatan tidak mematuhi --fallback-model. Jika anda mempunyai sesi panjang yang dimampatkan semasa sistem terlebih muatan, model sandaran tidak akan dipanggil dalam versi sebelum pembetulan ini. Jika anda bekerja dengan sesi panjang (/compact, /loop semalaman), kemas kini sekurang-kurangnya kepada v2.1.174.

Apakah yang Perlu Dibaiki Jika CLAUDE.md, Hook, MCP atau Skill Menjadi Punca?

Inti penting

Apabila safe mode mengenal pasti lapisan yang menjadi punca, cara pembaikan bergantung pada lapisan tersebut. Untuk CLAUDE.md, gunakan carian binari atau kembali kepada templat siap guna yang kurang daripada 200 baris. Untuk hook, semak kod keluar (2 menyekat, 1 tidak) dan logiknya. Untuk MCP, keluarkan satu pelayan dan semak. Untuk skill, periksa sama ada SKILL.md bercanggah dengan CLAUDE.md.

Strategi khusus bagi setiap lapisan.

Jika CLAUDE.md Menjadi Punca

Buka fail itu dan semak saiznya. Berdasarkan pengalaman yang diterangkan, hadkan CLAUDE.md aktif kepada tidak lebih daripada 200 baris; pindahkan selebihnya ke penghala dan dokumen sokongan di sebelah projek (struktur second-brain lengkap tersedia dalam panduan second-brain). Jika fail itu mempunyai 400+ baris, hampir pasti fail itulah puncanya. Langkah:

  1. Buat sandaran: cp CLAUDE.md CLAUDE.md.full.
  2. Kembali kepada templat ringkas yang berfungsi. Templat siap guna tersedia dalam panduan “Cara Mengkonfigurasi CLAUDE.md”.
  3. Mulakan semula Claude Code. Semak.
  4. Jika ia berfungsi, pulihkan peraturan dalam blok kecil sebanyak 10–20 baris dan semak selepas setiap blok.
  5. Cari blok yang merosakkan tingkah laku. Tulis semula sebagai hook dengan kod keluar yang betul (kod keluar untuk hook diterangkan dalam subseksyen seterusnya bagi H2 ini).

Jika Hook Menjadi Punca

Soalan utama ialah sama ada kod keluarnya betul. Hook Claude Code menggunakan:

  • Exit 0 — semuanya baik; tindakan diteruskan.
  • Exit 1 — ralat, tetapi tidak menyekat. Claude terus berjalan seolah-olah tiada apa-apa berlaku.
  • Exit 2 — ralat menyekat. Hanya kod ini yang benar-benar menghentikan tindakan.

Jika anda menulis sys.exit(1) atau exit 1 dalam hook shell kerana menyangka tindakan itu akan disekat, kod tersebut berfungsi sebagai log amaran dalam Claude Code dan tidak menghentikan tindakan. Tukarkannya kepada 2. Untuk butiran tentang hook dan cara mengkonfigurasikannya tanpa masalah ini, lihat panduan berasingan.

Kes lazim kedua ialah hook memulangkan JSON tidak sah pada stdout. Claude Code menghuraikan respons hook sebagai JSON; jika terdapat kandungan tambahan (log, penanda kemajuan, emoji), hook dianggap gagal dan tindakan diteruskan. Peraturannya: stdout hanya untuk JSON; segala-galanya yang lain dihantar ke stderr.

Kes ketiga ialah hook membaca sesuatu daripada ~/.claude/ yang disembunyikan oleh safe mode. Ini senario biasa; penyelesaiannya bukan menampal hook, tetapi menyemak os.environ.get('CLAUDE_CODE_SAFE_MODE') pada permulaan dan keluar dengan kod 0.

Jika Pelayan MCP Menjadi Punca

Gejala: arahan MCP tersedia tetapi memulangkan failed tanpa traceback yang jelas. Langkah:

  1. Jalankan claude mcp list—pelayan manakah yang ditakrifkan?
  2. Nyahaktifkan pelayan satu demi satu dalam ~/.claude.json: namakan semula kekunci claude-server-A kepada _claude-server-A (ini menyahaktifkannya tanpa memadamkannya).
  3. Mulakan semula claude. Semak panggilan yang berfungsi.
  4. Selepas menemui pelayan yang menjadi punca, semak lognya: claude mcp logs <name>.
  5. Jika pelayan pihak ketiga (@modelcontextprotocol/server-postgres dan yang seumpamanya), semak sama ada terdapat keluaran terbaharu. Ekosistem MCP masih tidak stabil; pelayan kerap rosak apabila Claude Code dikemas kini.

Jika anda mengalami “ranap semasa permulaan, dan hanya dengan dua MCP”, bandingkan tingkah laku dalam safe mode tanpa MCP.

Jika Skill Menjadi Punca

Skill terdiri daripada SKILL.md dan kod dalam .claude/skills/<name>/. Gejalanya: Claude mengabaikan skill, menggunakannya pada masa yang salah, atau menggunakannya tetapi menghasilkan output yang tidak berguna. Langkah:

  1. Buka SKILL.md. Semak keterangannya—keterangan itu sepatutnya 1–2 ayat dan menerangkan secara khusus bila skill patut digunakan. Jika keterangannya menyatakan “pembantu serba guna untuk segala-galanya”, Claude tidak memahami bila perlu menggunakannya.
  2. Semak percanggahan dengan CLAUDE.md. Jika CLAUDE.md menyatakan “sentiasa tulis ujian”, tetapi keterangan skill menyatakan “gunakan untuk prototaip pantas tanpa ujian”, kedua-duanya bercanggah.
  3. Jika skill menggunakan arahan luaran (npm, python, git), semak sama ada arahan itu tersedia dalam PATH seluruh sistem. Skill mempunyai persekitaran minimumnya sendiri.

Apa yang Perlu Dilakukan Jika Safe Mode Tidak Membantu: Diagnosis dan Simpan Keadaan Sebelum Pembaikan

Inti penting

Jika safe mode juga gagal, kemungkinan berbaki termasuk pemasangan, pengesahan, rangkaian atau infrastruktur. Jalankan claude doctor dan periksa buktinya. Laporan tidak muktamad tidak membenarkan pemadaman tetapan atau sesi: simpan serta sahkan seluruh keadaan dahulu, kemudian baiki hanya pemasangan didiagnosis.

Pembuangan keadaan pengguna bukan jalan pintas diagnostik. Gunakan pemeriksaan di bawah untuk mengenal pasti kesalahan; jika tidak muktamad, simpan bukti dan teruskan siasatan. Sebarang pembaikan pemasangan bermula dengan sandaran disahkan dan mengekalkan akaun serta identiti stor kelayakan sedia ada. Turutan:

  1. claude doctor — diagnostik automatik. Anthropic menyatakan dalam dokumentasinya:

Jika `claude --version` berfungsi tetapi perkara lain tidak kena, jalankan `claude doctor` untuk menjana laporan diagnostik automatik.

— Anthropic Docs - Troubleshoot installation, https://code.claude.com/docs/en/troubleshoot-install
  1. Semak sama ada terdapat pemasangan bercanggah. Ramai orang memasang versi global npm dan pemasang natif pada masa yang sama:

Beberapa pemasangan Claude Code boleh menyebabkan ketidakpadanan versi atau tingkah laku yang tidak dijangka.

— Anthropic Docs - Troubleshoot installation, https://code.claude.com/docs/en/troubleshoot-install
  1. Semak sama ada ANTHROPIC_API_KEY memintas sesi OAuth anda. Ini punca lazim bagi keadaan “tiada apa yang berfungsi, kunci sudah tamat tempoh”:

Apabila `ANTHROPIC_API_KEY` ditetapkan dan anda mengesahkannya, Claude Code menggunakan kunci itu dan bukannya kelayakan OAuth langganan anda.

— Anthropic Docs - Troubleshoot installation, https://code.claude.com/docs/en/troubleshoot-install

Penyelesaian: jalankan unset ANTHROPIC_API_KEY dalam sesi shell semasa atau keluarkannya daripada ~/.zshrc / ~/.bashrc.

  1. Baiki hanya pemasangan yang dikenal pasti diagnostik; simpan semua keadaan pengguna dahulu. Kegagalan safe mode atau laporan doctor tidak muktamad tidak membuktikan data pengguna perlu dibuang. Hentikan semua sesi Claude dan penulis lain sebelum membuat sandaran konsisten. Kekalkan akaun Unix, HOME, stor kelayakan OS dan akaun Anthropic yang sama; jangan putar kunci atau cipta identiti pengganti.

Contoh sandaran berikut untuk Linux dengan GNU tar. Pada macOS atau Windows gunakan alat sandaran yang mengekalkan ACL, atribut lanjutan, pautan dan metadata platform serta sahkan pemulihan sebelum meneruskan; jangan anggap bendera khusus GNU berfungsi di situ. Arkib mengandungi kelayakan dan transkrip sesi: rahsiakan dan simpan di luar repositori.

# Run as the same user who owns the Claude state, after stopping writers.
set -eu
umask 077
backup_dir=$(mktemp -d "$HOME/.claude-recovery-XXXXXXXX")
set --
if [ -e "$HOME/.claude" ] || [ -L "$HOME/.claude" ]; then
  set -- "$@" .claude
fi
if [ -e "$HOME/.claude.json" ] || [ -L "$HOME/.claude.json" ]; then
  set -- "$@" .claude.json
fi
[ "$#" -gt 0 ] || exit 1
tar --acls --xattrs --numeric-owner -cpf "$backup_dir/claude-state.tar" -C "$HOME" "$@"
tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$HOME"
sha256sum "$backup_dir/claude-state.tar" > "$backup_dir/claude-state.sha256"
(cd "$backup_dir" && sha256sum -c claude-state.sha256)
mkdir "$backup_dir/restore-check"
tar --acls --xattrs -xpf "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check"
tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check"
printf 'Verified recovery directory: %s\n' "$backup_dir"

Semua arahan mesti berjaya. Arkib merangkumi seluruh pepohon .claude sedia ada, termasuk sesi diabaikan/tidak dijejaki dan keadaan plugin, serta .claude.json, bukan tetapan dijejaki Git sahaja. Jika salah satu laluan symlink atau data berada di lokasi dikonfigurasikan berasingan, berhenti dan sertakan sasaran diselesaikan dalam sandaran disahkan yang sama; mengarkib pautan sahaja tidak menyandarkan sasarannya. Arkib tidak mengandungi macOS Keychain atau stor kelayakan luaran lain, jadi kekalkan identiti itu.

Jika diagnostik secara khusus mengenal pasti pemasangan setempat legasi sebagai salinan bercanggah, alihkan pemasangan itu sahaja ke direktori pemulihan peribadi daripada memadam konfigurasi dan sesi:

# Use the verified backup_dir from the previous block.
if [ -d "$HOME/.claude/local" ]; then
  mv "$HOME/.claude/local" "$backup_dir/legacy-local"
fi

Buang pemasangan npm hanya jika diagnostik mengenal pastinya sebagai pemasangan bercanggah dan anda mahu mengekalkan pemasangan natif. Kemudian gunakan pemasang natif didokumenkan, tanpa memadam .claude atau .claude.json:

curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor

Pada Windows, arahan pemasangan natif kekal:

irm https://claude.ai/install.ps1 | iex

Pulihkan secara berasingan. Hentikan penulis sekali lagi. Semak checksum arkib dan ekstrak ke direktori pemulihan kosong seperti di atas; bandingkan dengan berjaya sebelum menggunakan fail. Jika pemasangan legasi dialih perlu dipulihkan, pastikan dahulu $HOME/.claude/local tidak wujud, kemudian alih $backup_dir/legacy-local kembali ke laluan tepat itu. Pulihkan fail tetapan didiagnosis daripada ekstrak disahkan hanya selepas menyimpan sebarang pengganti semasa; jangan tindih seluruh pepohon membuta tuli. Sesi, tetapan MCP dan identiti asal kekal disimpan. Snapshot Git sahaja tidak meliputi transkrip diabaikan/tidak dijejaki, kelayakan atau metadata sistem fail.

Apakah yang TIDAK Patut Dilakukan Apabila Claude Code Rosak?

Inti penting

Enam antipola yang ditemukan dalam kes sokongan yang diterangkan: menukar kunci sebelum diagnosis, melakukan tetapan semula penuh sebagai langkah pertama, panik kerana ralat UI dalam hook, menaikkan kod keluar hook sebelum membetulkan logik, mengedit CLAUDE.md tanpa perlindungan safe mode, dan percaya bahawa “Claude membaiki MCP miliknya sendiri”. Setiap satunya membazirkan masa berjam-jam dan tiada satu pun diperlukan.

Jangan Tukar Kunci Sebelum Diagnosis

“Pengesahan tidak berfungsi” dalam 90% kes berpunca daripada ANTHROPIC_API_KEY memintas langganan, pepijat UI hook atau MCP yang gagal. Menggilirkan kunci tidak akan menyelesaikan mana-mana masalah ini, tetapi akan menyebabkan satu lagi jam masa henti: anda perlu membatalkan kunci lama, mengeluarkan kunci baharu, menandatangani semula CI dengannya dan mengemas kini pemboleh ubah dalam produksi. Jalankan claude --safe-mode dahulu. Berfungsi? Maka masalahnya berpunca daripada penyesuaian; kunci tidak perlu disentuh.

Jangan Lakukan Tetapan Semula Penuh Sebelum Safe Mode

Safe mode menyediakan persekitaran terasing dalam 1 saat. Memadam .claude boleh memusnahkan sesi, konfigurasi MCP dan keadaan tidak dijejaki lain. Diagnosis dahulu, sahkan sandaran peribadi dan gunakan pengalihan boleh balik hanya bagi lapisan pemasangan atau konfigurasi yang benar-benar terlibat.

Jangan Panik Kerana Ralat UI dalam Hook

Sebelum membetulkan apa-apa, semak sama ada hook benar-benar berjalan (melalui log ke stderr atau output yang dinyatakan secara jelas), bukan bergantung pada petunjuk visual.

Jangan Naikkan Kod Keluar Hook Sebelum Membetulkan Logiknya

Apabila hook penyekat anda tidak menyekat, anda mungkin tergoda untuk menetapkan exit 2 dan menganggap masalah itu selesai. Ini pembaikan yang berfungsi, tetapi menyembunyikan satu lagi masalah: jika sekatan itu tidak berfungsi selama sebulan, semua perkara yang sepatutnya dilarang oleh hook telah terlepas. Semak log git dahulu untuk mengetahui dengan tepat perkara yang telah terlepas. Kemudian tambah sekatan itu. Sekatan yang ditutup sekarang tidak membatalkan perkara yang telah berlaku sebelumnya.

Jangan Edit CLAUDE.md Produksi Tanpa Perlindungan Safe Mode

Dalam kes yang diterangkan: anda mengedit CLAUDE.md, Claude mula berkelakuan pelik, anda menjalankan git diff dan mendapati seseorang turut menambah pelayan MCP dan hook pada repo pada petang itu. Anda menyalahkan suntingan anda, membatalkannya dan Claude masih berkelakuan pelik. Peraturannya: sebelum menjalankan git revert, jalankan claude --safe-mode. Jika masalah berterusan dalam safe mode, suntingan anda tiada kaitan dengannya; anda tidak perlu membatalkannya.

Jangan Percaya “Claude Membaiki MCP Miliknya Sendiri”

Senario biasa: anda meminta Claude “menambah alat tertentu pada pelayan MCP”, Claude menulis semula konfigurasi yang berfungsi, semuanya rosak, kemudian Claude menggunakan beberapa giliran untuk menyahpepijat kerosakan yang dibuatnya—dan menghabiskan kuota sesi dalam proses itu. Apabila MCP rosak, dapatkan konfigurasi itu secara manual; jangan serahkan tugas tersebut kepada ejen. Sebahagian daripada kelengkapan alatnya juga beroperasi melalui MCP, dan MCP yang rosak bermaksud alat diagnosis juga rosak.

Ke Mana Hendak Pergi Selepas Membaikinya?

Inti penting

Selepas memulihkan Claude Code, tambah langkah pencegahan supaya ia tidak rosak lagi. Sekurang-kurangnya: disableBypassPermissionsMode: "disable" dalam tetapan pengguna, hook yang menyekat .env dan git push --force, serta sandbox untuk pelaksanaan autonomi yang panjang. Panduan pencegahan ialah panduan pasangannya.

Selepas menganalisis insiden, jangan terus kembali bekerja. Tambah langkah pencegahan dahulu supaya insiden itu tidak berulang. Anda boleh menghabiskan berjam-jam membina second-brain (folder business/ dengan struktur projek) dan CLAUDE.md, dan memulihkannya secara manual bukan mudah—itu alasan yang kukuh. Set minimum:

  1. ~/.claude/settings.json dengan permissions.disableBypassPermissionsMode: "disable"—larangan dari segi seni bina terhadap mod pintasan, supaya --dangerously-skip-permissions tidak akan berfungsi jika dilancarkan secara tidak sengaja.
  2. Hook untuk Read(./env*), Bash(git push --force), Write(./node_modules/**)—perkara yang mesti ditangkap pada tahap undang-undang, bukan sekadar harapan.
  3. Konfigurasi sandbox untuk pelaksanaan autonomi yang panjang (/loop, /schedule).
  4. /compact dengan peraturan anda sendiri tentang perkara yang perlu dibuang daripada konteks supaya Claude tidak kehabisan tenaga.

Skim perlindungan empat lapisan yang lengkap ada dalam panduan “Cara Mengkonfigurasi Claude Code Supaya Tidak Merosakkan Projek Anda Semalaman”. Satu panduan membincangkan pencegahan sebelum melancarkan /loop; satu lagi membincangkan pemulihan selepas /loop merosakkan sesuatu. Kedua-duanya memang sepadan.

Sumber

Bahan praktikal: dokumentasi Ailoot.

Lebih banyak bahan dan alat: Ailoot.

Butiran lanjut

Soalan lazim: Pemulihan Claude Code: Safe Mode, /cd dan Sandaran | Ailoot

Adakah kegagalan safe mode bermakna saya patut memadam ~/.claude?

Tidak. Pemasangan, pengesahan, rangkaian dan infrastruktur masih perlu disiasat. Laporan doctor tidak muktamad bukan bukti tetapan atau sesi perlu dibuang; baiki lapisan yang didiagnosis sahaja.

Apakah yang mesti disimpan sebelum pembaikan pemasangan?

Hentikan penulis dan sandarkan seluruh keadaan Claude, termasuk sesi, konfigurasi plugin/MCP, fail diabaikan dan metadata sistem fail. Sahkan checksum serta ekstraksi sebelum meneruskan, kekalkan akaun dan stor kelayakan sedia ada, serta pulihkan lapisan didiagnosis sahaja tanpa menindih keadaan semasa membuta tuli.

Semua artikel