Claude Code-helyreállítás: Safe Mode, /cd és tartalék modellek
MarkdownA Claude Code hibakeresése safe mode, a /cd parancs, tartalék modellek és a beállítások helyreállítása segítségével. Az ellenőrzések sorrendje és az eredeti korlátozások.
A teljes cikk elolvasása
Gyakorlati anyagok az ágensekkel való munkához: Ailoot-dokumentáció.
Mi változik a Claude Code-ban 2026 júniusában?
Főbb tudnivalók
- június 8-án, a Claude Code v2.1.169-ben az Anthropic hozzáadta a
--safe-modekapcsolót és a/cdparancsot. Két nappal korábban, a v2.1.166 bevezette a tartalék modelleket, akár 3 modellt egy láncban. Ez a három funkció a vibe-kódolók leggyakoribb problémájára kínál megoldást: „minden elromlott, nem tudom, kit hibáztassak, és nem akarok egy órát veszíteni az újratelepítéssel.”
Korábban, amikor a Claude Code furcsán kezdett viselkedni—végtelenül pörgött a betöltésjelző, összeomlott indításkor, az ágens figyelmen kívül hagyta a CLAUDE.md szabályait, vagy egy hook észrevétlenül nem futott le—csak egy kiút volt: a .claude/settings.json egyes részeinek kézi kikommentelése, az MCP-szerverek egyenkénti letiltása, vagy legrosszabb esetben a ~/.claude törlése és az újratelepítés. Egy leírt esetben törölték a ~/.claude könyvtárat, és elveszett az MCP-szerverek összeállítása, amely másfél órát vett igénybe. Később kiderült, hogy a CLAUDE.md egyetlen sora okozta a hibát, és 10 másodperc alatt meg lehetett volna találni—de ez csak a teljes helyreállítás után vált világossá.
2026 júniusában az Anthropic három olyan mechanizmust vezetett be, amely megváltoztatja ezt a forgatókönyvet. Röviden, mi és mikor érkezett:
| Verzió | Dátum | Újdonság |
|---|---|---|
| 2.1.166 | 2026. június 6. | fallbackModel beállítás + --fallback-model kapcsoló interaktív munkamenetekhez |
| 2.1.169 | 2026. június 8. | --safe-mode kapcsoló és CLAUDE_CODE_SAFE_MODE környezeti változó, /cd parancs |
| 2.1.176 | 2026. június 12. | Javítás: a /cd és a worktree-váltás többé nem a régi git-ágat mutatja |
Az alábbiakban minden mechanizmust lépésről lépésre ismertetünk, valamint azt is, milyen sorrendben érdemes alkalmazni őket, ha a Claude Code-munkamenet félresiklik.
Mi szokta a leggyakrabban elrontani a Claude Code-ot?
Főbb tudnivalók
A leírt tapasztalatok alapján a Claude Code a vibe-kódolóknál jellemzően négy dolog miatt romlik el: ellentmondásos szabályokat tartalmazó, túlburjánzott CLAUDE.md, hibás kilépési kódú hook, észrevétlenül hibázó MCP-szerver, valamint a settings.json három szintjén átfedő beállítások. Egyetlen hibaforrás van, a diagnózis percekig tart, a pánik pedig rögtön az rm -rf futtatása felé tereli az embereket.
A leírt példában a CLAUDE.md kezdetben 80 sorból állt—és egy hónapig jól működött. A második hónapban feltűnt, hogy Claude hetente egyszer minden lefektetett szabályt megszeg: hozzáér a .env fájlhoz, lefuttatja a git push --force parancsot, vagy turkál a node_modules könyvtárban. Nem rosszindulatból—egyszerűen elfelejtette. Egyszer a .gitignore is törlődött, és nem volt azonnal világos, miért. Erről a forgatókönyvről bővebben a CLAUDE.md-ről szóló útmutatóban olvashat.
Amikor a CLAUDE.md eléri a 400+ sort, észrevétlenül kezdi okozni a problémákat: a munkamenet indításakor jelentős részt foglal el a kontextusablakból, és a fontos utasításokat felhígítja a másodlagosak között. Claude formálisan továbbra is beolvassa a fájlt, így kívülről úgy tűnik, hogy „a szabályok megvannak, de nem működnek”—ez a túlburjánzott szerződés tipikus jele.
A hookok jelentik a második gyakori hibaforrást. A Claude Code hooks működésének van egy olyan sajátossága, amelyet az Anthropic nem hangsúlyoz eléggé.
Vagyis a Python-hookban használt sys.exit(1) (vagy bármely, Unix-konvenció szerint „hibával meghiúsult” érték) nem állítja le Claude-ot. Csak a 2 kód blokkol. A leírt esetben a hookot „szigorú tiltásnak” szánták, de a gyakorlatban csak naplózta a kifogást, és engedte folytatódni a műveletet.
Az MCP-szerverek jelentik a harmadik réteget, és ezek is a maguk módján hibásodhatnak meg.
A tünet gyakran ugyanaz: az MCP-parancsok elérhetők, de traceback nélkül failed értéket adnak vissza. Az MCP konfigurálásáról és a szerverek claude mcp add paranccsal történő hozzáadásáról a külön útmutatóban olvashat bővebben.
A negyedik hibaforrás a settings.json háromszintű hierarchiája. Létezik a ~/.claude/settings.json (felhasználói szint), a projekt gyökerében található .claude/settings.json (projekt), a .claude/settings.local.json (helyi), és opcionálisan a vállalati rendszergazdától érkező kezelt beállítások. Ezeket a prioritási szabályok szerint egyesíti a rendszer. Ha valaki projektszinten ad hozzá egy MCP-szervert, miközben felhasználói szinten már van egy hasonló bejegyzése más indítási konfigurációval, észrevétlen ütközés keletkezik, amitől úgy tűnik, mintha „a Claude Code elromlott volna.”
Hogyan működik a --safe-mode, és mit tilt le?
Főbb tudnivalók
A claude --safe-mode úgy indítja el a Claude Code-ot, hogy teljesen letiltja a testreszabásokat: CLAUDE.md, bővítmények, skillek, hookok, MCP-szerverek, felhasználói parancsok, ágensek, kimeneti stílusok, munkafolyamatok és billentyűkiosztások. A hitelesítés, a modellválasztás, a beépített eszközök és az engedélyek megmaradnak. Ez diagnosztikai eszköz: ha safe mode-ban megszűnik a probléma, akkor az egyik hozzáadott réteg a felelős.
Az Anthropic eredeti megfogalmazása a v2.1.169 changelogjában:
Hozzáadtuk a
--safe-modekapcsolót (és aCLAUDE_CODE_SAFE_MODEváltozót), amellyel a Claude Code a testreszabások (CLAUDE.md, bővítmények, skillek, hookok, MCP-szerverek) letiltásával indítható diagnosztikai célból.
Az Anthropic a modellkonfigurációs dokumentációban pontosítja:
Annak ellenőrzéséhez, hogy a testreszabások okozzák-e a problémát, indítson munkamenetet a
claude --safe-modeparanccsal, amely letiltja aCLAUDE.mdfájlt, a skilleket, az MCP-szervereket és a hookokat. A git állapota és a könyvtárnevek nem számítanak testreszabásnak, ezért továbbra is elérhetők.
Ez diagnosztikai eszköz, nem „tiszta környezet.” A safe mode egyetlen kérdés megválaszolásában segít: a Claude Code alapértelmezett működésével van probléma, vagy a hozzáadott testreszabásokkal? Ez a kontextusmérnökség része—annak kezelése, hogy Claude mit lát és mit nem lát adott pillanatban. Ha safe mode-ban minden működik, a rétegeket bináris kereséssel kell ellenőrizni. Ha így sem működik, akkor maga a telepítés, a hitelesítés, a hálózat vagy az infrastruktúra okozza a problémát; ilyenkor érdemes megnézni a claude doctor kimenetét és a naplókat.
Mit tilt le a safe mode (az Anthropic hivatalos listája—5 fő réteg):
CLAUDE.mdminden szinten (felhasználói / projekt)- Bővítmények
- Skillek
- Hookok
- MCP-szerverek
Ami továbbra is működik:
- Hitelesítés (az OAuth-munkamenet vagy az API-kulcs)
- Modellválasztás (
--model sonnet,--model opus) - Beépített eszközök (Read, Write, Bash, Grep és így tovább)
- Engedélyek
- Git-állapot
- Könyvtárnevek
Fontos részlet: a safe mode nem tiltja le a vállalati rendszergazda által kezelt vagy előírt beállításokat. Ha olyan csapatban dolgozik, ahol a Bedrock GovCloud vagy egy MDM-konfiguráció állítja be az availableModels értéket, ezek a korlátozások érvényben maradnak—a safe mode csak a saját testreszabásait tiltja le, a vállalati szabályzatokat nem.
Hogyan különíthet el egy réteget, és találhatja meg a hibaforrást 60 másodperc alatt?
Főbb tudnivalók
- lépés: futtassa a
claude --safe-modeparancsot ugyanabban a mappában, ahol a probléma jelentkezett. Ha működik, a probléma a testreszabásokban van; ezután egyenként engedélyezze őket:CLAUDE.md-> hookok -> MCP -> skillek. Ha safe mode-ban sem működik, akkor a hitelesítés, a verzió, a hálózat vagy az operációs rendszer okozza a gondot. Ebben az esetben futtassa aclaude doctorparancsot az automatikus diagnosztikához, és ne nyúljon azrm -rfparancshoz.
Diagnosztikai forgatókönyv arra az esetre, ha a Claude Code „nem figyel többé.” Az alábbi parancsokhoz legalább Claude Code v2.1.169 szükséges. Ha régebbi verziója van, először frissítsen (npm update -g @anthropic-ai/claude-code vagy az Anthropic natív telepítője).
- Nyissa meg ugyanazt a mappát, ahol a probléma jelentkezett.
- Futtassa a
claude --safe-modeparancsot. - Ha tisztán elindul, ellenőrizze az eredeti kérését. Működött? Ha igen, akkor valamelyik réteg a felelős. Lépjen a 4. pontra.
- Ha safe mode-ban is hibás, ne módosítsa a konfigurációkat. Először futtassa a
claude doctorparancsot; ellenőrizze a hitelesítést, a verziót és az ütköző telepítéseket.
Miután a safe mode problémamentesen elindult, egyenként engedélyezze a rétegeket, a legvalószínűbb hibaforrással kezdve. A leírt tapasztalatokon alapuló sorrend:
CLAUDE.md. Futtassa aclaudeparancsot safe mode nélkül, de ideiglenesen nevezze át a fájlt:mv CLAUDE.md CLAUDE.md.bak. Ha így működik, akkor ez a fájl okozza a problémát. Ezután bináris keresést végezhet: tartsa meg a sorok felét, és ellenőrizze.- Hookok. Nyissa meg a
.claude/settings.jsonfájlt, és ideiglenesen állítsa[]értékre ahooksrészt. Indítsa újra aclaudeparancsot. Működik? Akkor valamelyik hook a felelős. Engedélyezze őket egyenként. - MCP-szerverek. Hasonlóképpen, a
~/.claude.jsonfájlban vagy a.claude/settings.jsonfájlban ideiglenesen állítsa amcpServersrészt üres objektumra, indítsa újra, majd ellenőrizze. - Skillek. Helyezze át a
.claude/skills/könyvtárat egy ideiglenes mappába. Indítsa el, és ellenőrizze.
Mit jelent az „ideiglenes átnevezés”: a fájlok a diagnózis során nem törlődnek. Az mv vagy a git stash segítségével egyetlen paranccsal visszaállíthat mindent, ha kiderül, hogy az adott réteg nem a hibaforrás.
Hogyan válthat munkamappát a /cd paranccsal a kontextus elvesztése nélkül?
Főbb tudnivalók
A Claude Code 2.1.169+ verziójában a /cd <path> parancs úgy váltja át az aktív munkamenet munkamappáját, hogy közben a prompt gyorsítótára megmarad. Hasznos, ha az aktuális projekt konfigurációja hibás: átválthat egy tiszta mappára, ellenőrizheti, hogy Claude működik-e, majd visszatérhet. Korábban be kellett zárni a munkamenetet, és újra kellett indítani.
A v2.1.169 június 8-i changelogjából:
Hozzáadtuk a
/cdparancsot, amellyel a munkamenet új munkamappára váltható anélkül, hogy a prompt gyorsítótára a munkamenet közben visszaállna.
Miért hasznos ez a hibakeresésben? Tegyük fel, hogy a ~/work/myapp projektmappában van, és a Claude Code furcsán viselkedik. Korábban csak úgy ellenőrizhette, hogy „egyáltalán működik-e”, ha bezárta a munkamenetet, átváltott egy másik mappára, majd újraindította. Elveszett a kontextus, az előzmények és a bemelegített prompt-gyorsítótár. Most:
# In the same session:
/cd ~/sandbox/test
Claude átvált az új mappára, és az ottani CLAUDE.md fájlt (ha van ilyen) üzenetként olvassa be, nem pedig a rendszerprompt helyettesítőjeként—így a gyorsítótár megmarad. Ha minden működik a ~/sandbox/test mappában, akkor a ~/work/myapp konfigurációja okozta a problémát.
Június 12-én a v2.1.176 javított egy kellemetlen visszalépést—a /cd teljes újraindításig a régi git-ágat mutatta. Ha régebbi verziót használ, frissítsen, vagy egyszerűen hagyja figyelmen kívül a git status kimenetét az átváltás utáni első néhány üzenetben—utána frissülni fog.
Hogyan konfigurálhatók a tartalék modellek 529-es hiba esetére?
Főbb tudnivalók
A v2.1.166-ban az Anthropic hozzáadta a fallbackModel beállítást—akár 3 modellből álló láncot, amelyeket egymás után próbál meg, ha az elsődleges modell túlterhelt vagy nem érhető el. A láncot csak túlterheltségi és nem újrapróbálható szerverhibák aktiválják. A hitelesítési, számlázási, sebességkorlát- és átviteli hibák nem indítják el a tartalék láncot—ezekre a szokásos újrapróbálási logika érvényes.
A leírt forgatókönyvben hetente egyszer egy hosszú feladat fut Opuson egy projektben; 10 perc múlva az API 529 Overloaded választ küld, és a munkamenet összeomlik. Korábban várni kellett, vagy kézzel át kellett váltani Sonnetre a --model sonnet kapcsolóval, elveszítve a teljesen bemelegített kontextust. Egy nagy business/ mappában, second brain beállítással ez körülbelül húsz percnyi munkát jelent. Most már van erre megfelelő mechanizmus.
A hivatalos dokumentáció pontos idézete:
Ha az elsődleges modell túlterhelt, nem érhető el, vagy más nem újrapróbálható szerverhibát ad vissza, a Claude Code a kérés meghiúsulása helyett tartalék modellre válthat. A hitelesítési, számlázási, sebességkorlát-, kérésméret- és átviteli hibák soha nem váltanak ki átváltást—ezekre a szokásos újrapróbálási és hibakezelési útvonal érvényes.
Külön arról, hogyan működik a lánc:
Állítson be egy vagy több tartalék modellt; a Claude Code sorrendben próbálja ki őket, és értesítést jelenít meg az átváltáskor. Az átváltás csak az aktuális fordulóra érvényes—a következő üzenetnél a rendszer ismét az elsődleges modellt próbálja meg. A duplikátumok kiszűrése után a lánc legfeljebb három modellt tartalmazhat; a további bejegyzéseket figyelmen kívül hagyja.
Kétféleképpen állítható be. CLI-n keresztül:
claude --fallback-model sonnet,haiku
A ~/.claude/settings.json fájlon keresztül:
{
"fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}
A sebességkorlátokkal kapcsolatban van egy külön sajátosság. Az Anthropic szándékosan nem küldi tovább a 429-es hibát a láncon, így nem lehet a kérési korlátot úgy megkerülni, hogy a következő modellre vált. A tartalék modell csak akkor működik, ha az elsődleges túlterhelt, nem érhető el, vagy nem újrapróbálható szerverhibát ad vissza (például 529 Overloaded esetén). A sebességkorlátoknál a szokásos újrapróbálási logika és a várakozási idő növelése érvényes.
Még egy részlet—június 12-én a v2.1.174 javított egy visszalépést: a tömörítés nem vette figyelembe a --fallback-model kapcsolót. Ha hosszú munkamenete van, és túlterheltség közben tömörít, a javítás előtt a tartalék modell nem lépett működésbe. Ha hosszú munkamenetekkel dolgozik (/compact, éjszakai /loop), frissítsen legalább v2.1.174-re.
Mit kell kijavítani, ha a CLAUDE.md, egy hook, az MCP vagy egy skill a hibás?
Főbb tudnivalók
Ha a safe mode azonosítja a hibás réteget, a javítás annak típusától függ. A CLAUDE.md esetén használjon bináris keresést, vagy álljon vissza egy 200 sornál rövidebb, kész sablonra. Hook esetén ellenőrizze a kilépési kódot (a 2 blokkol, az 1 nem) és a logikát. MCP esetén távolítson el egy szervert, és ellenőrizze. Skill esetén nézze meg a SKILL.md fájlt, nincs-e benne a CLAUDE.md-vel ellentmondó utasítás.
Konkrét stratégiák az egyes rétegekhez.
Ha a CLAUDE.md a hibás
Nyissa meg a fájlt, és ellenőrizze a méretét. A leírt tapasztalatok alapján az aktív CLAUDE.md legfeljebb 200 soros legyen; a többit helyezze a projekt mellé kerülő routerekbe és kiegészítő dokumentumokba (a teljes second brain-struktúráról a second brain útmutatóban olvashat). Ha 400+ sora van, szinte biztosan ez a hibás. Lépések:
- Készítsen biztonsági másolatot:
cp CLAUDE.md CLAUDE.md.full. - Álljon vissza egy rövid, működő sablonra. Kész sablont a „A CLAUDE.md konfigurálása” útmutatóban talál.
- Indítsa újra a Claude Code-ot. Ellenőrizze.
- Ha működik, állítsa vissza a szabályokat kis, 10–20 soros blokkokban, és minden blokk után ellenőrizze.
- Keresse meg azt a blokkot, amelyik megváltoztatja a viselkedést. Írja át megfelelő kilépési kódú hookká (a hookok kilépési kódjairól ennek a H2-nek a következő alfejezete szól).
Ha egy hook a hibás
A fő kérdés az, hogy helyes-e a kilépési kód. A Claude Code hookjai a következőképpen működnek:
- Exit 0 — minden rendben; a művelet folytatódik.
- Exit 1 — hiba, de nem blokkoló. Claude úgy folytatja, mintha mi sem történt volna.
- Exit 2 — blokkoló hiba. Csak ez állítja le ténylegesen a műveletet.
Ha a shell-hookban sys.exit(1) vagy exit 1 szerepel, mert azt gondolta, hogy blokkolni fog, a Claude Code-ban ez figyelmeztető naplóként működik, és nem állítja le a műveletet. Módosítsa 2-re. A hookokról, valamint az ilyen buktatót elkerülő konfigurálásukról a külön útmutatóban olvashat.
A második gyakori eset, amikor a hook érvénytelen JSON-t ad vissza a stdouton. A Claude Code JSON-ként dolgozza fel a hook válaszát; ha abban valami más is van (naplóbejegyzés, folyamatjelző, emoji), a hook sikertelennek minősül, a művelet pedig folytatódik. Szabály: a stdout kizárólag JSON-t tartalmazzon; minden más a stderrre kerüljön.
A harmadik eset, amikor a hook olyasmit próbál beolvasni a ~/.claude/ alól, amit a safe mode elrejtett. Ez normális forgatókönyv; ne a hook foltozgatásával javítsa, hanem ellenőrizze az elején az os.environ.get('CLAUDE_CODE_SAFE_MODE') értékét, majd lépjen ki 0-val.
Ha egy MCP-szerver a hibás
Tünetek: az MCP-parancsok elérhetők, de egyértelmű traceback nélkül failed értéket adnak vissza. Lépések:
- Futtassa a
claude mcp listparancsot—mely szerverek vannak beállítva? - Tiltsa le egyenként a szervereket a
~/.claude.jsonfájlban: nevezze át aclaude-server-Akulcsot_claude-server-Aértékre (így törlés nélkül deaktiválja). - Indítsa újra a
claudeparancsot. Ellenőrizze, mely hívások működnek. - Ha megtalálta a hibás szervert, nézze meg a naplóját:
claude mcp logs <name>. - Ha harmadik féltől származó szerverről van szó (
@modelcontextprotocol/server-postgresés hasonlók), ellenőrizze, hogy megjelent-e új kiadása. Az MCP-ökoszisztéma még mindig zavaros; a szerverek Claude Code-frissítések után rendszeresen elromlanak.
Ha azt tapasztalja, hogy „indításkor összeomlik, és csak két MCP-vel”, hasonlítsa össze a működését safe mode-ban, MCP nélkül.
Ha egy skill a hibás
A skill egy SKILL.md fájlból és a .claude/skills/<name>/ alatti kódból áll. Tünetek: Claude figyelmen kívül hagyja a skillt, rossz időben alkalmazza, vagy alkalmazza ugyan, de használhatatlan eredményt ad. Lépések:
- Nyissa meg a
SKILL.mdfájlt. Ellenőrizze a leírást—1–2 mondatból kell állnia, és pontosan meg kell határoznia, mikor kell használni a skillt. Ha azt írja, hogy „univerzális segéd mindenhez”, Claude nem érti, mikor kell meghívnia. - Ellenőrizze, hogy vannak-e ellentmondások a
CLAUDE.mdfájllal. Ha aCLAUDE.mdazt mondja, hogy „mindig írj teszteket”, a skill leírása pedig azt, hogy „gyors prototípus-készítéshez használd tesztek nélkül”, akkor konfliktus van. - Ha a skill külső parancsokat használ (npm, python, git), ellenőrizze, hogy azok elérhetők-e a teljes rendszerre érvényes PATH-ban. A skillnek saját, minimális környezete van.
Mit tegyen, ha a Safe Mode nem segített: diagnózis és állapotmegőrzés javítás előtt
Főbb tudnivalók
Ha a safe mode is hibázik, telepítési, hitelesítési, hálózati vagy infrastruktúra-ok is maradhat. Futtassa a claude doctor parancsot, és vizsgálja a bizonyítékát. Eldöntetlen jelentés nem indokolja beállítások vagy munkamenetek törlését: előbb őrizze meg és igazolja a teljes állapotot, majd csak a diagnosztizált telepítést javítsa.
A felhasználói állapot eltávolítása nem diagnosztikai rövidítés. Az alábbi ellenőrzésekkel azonosítsa a hibát; eldöntetlenségnél őrizze meg a bizonyítékot, és vizsgálódjon tovább. Minden telepítésjavítás ellenőrzött mentéssel indul, és megtartja a meglévő fiók és hitelesítőtár azonosságát. Sorrend:
claude doctor— automatikus diagnosztika. Az Anthropic ezt írja a dokumentációjában:
Ha a
claude --versionműködik, de valami más nincs rendben, futtassa aclaude doctorparancsot az automatikus diagnosztikai jelentés elkészítéséhez.
- Ellenőrizze az ütköző telepítéseket. Sokan egyszerre telepítették az npm globális verzióját és a natív telepítőt:
A Claude Code több telepítése eltérő verziókhoz vagy váratlan működéshez vezethet.
- Ellenőrizze, hogy az
ANTHROPIC_API_KEYközbeszól-e az OAuth-munkamenetébe. Ez gyakori oka annak, hogy „semmi sem működik, lejárt a kulcs”:
Ha az `ANTHROPIC_API_KEY` be van állítva, és Ön megerősítette, a Claude Code ezt a kulcsot használja az előfizetéséhez tartozó OAuth-hitelesítő adatok helyett.
Megoldás: futtassa az unset ANTHROPIC_API_KEY parancsot az aktuális shell-munkamenetben, vagy távolítsa el a változót a ~/.zshrc / ~/.bashrc fájlból.
- Csak a diagnózis által azonosított telepítést javítsa; előbb őrizzen meg minden felhasználói állapotot. A safe mode hibája vagy eldöntetlen doctor-jelentés nem bizonyítja a felhasználói adatok törlésének szükségét. Konzisztens mentés előtt állítson le minden Claude-munkamenetet és más írót. Ugyanaz a Unix-fiók, HOME, operációsrendszer-hitelesítőtár és Anthropic-fiók maradjon; ne cseréljen kulcsot vagy hozzon létre új azonosságot.
Az alábbi mentési példa GNU tart használó Linuxhoz való. macOS-en vagy Windowson platformjogosultságokat, kiterjesztett attribútumokat, hivatkozásokat és metaadatokat megőrző mentőeszközt használjon, és továbblépés előtt igazolja a visszaállítást; a GNU-kapcsolókról ne feltételezze, hogy máshol is működnek. Az archívum hitelesítő adatokat és munkamenet-átiratokat tartalmaz: privátan, tárolókon kívül őrizze.
# 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"
Minden parancsnak sikerülnie kell. Az archívum a teljes meglévő .claude fát, a kizárt/nem követett munkameneteket és pluginállapotot, valamint a .claude.json fájlt fedi le, nem csak a Gitben követett beállításokat. Ha bármelyik útvonal symlink vagy az adat külön konfigurált helyen van, álljon meg, és a feloldott célt is vegye fel ugyanabba az igazolt mentésbe; a hivatkozás archiválása nem menti a célját. A macOS Keychain és más külső hitelesítőtár nincs az archívumban, ezért az azonosságukat tartsa a helyükön.
Ha a diagnózis kifejezetten a régi helyi telepítést azonosítja ütköző példányként, csak azt mozgassa a privát helyreállítási könyvtárba a konfiguráció és munkamenetek törlése helyett:
# Use the verified backup_dir from the previous block.
if [ -d "$HOME/.claude/local" ]; then
mv "$HOME/.claude/local" "$backup_dir/legacy-local"
fi
Npm-telepítést csak akkor távolítson el, ha a diagnózis azt azonosította ütközőként, és a natív változatot kívánja megtartani. Ezután a dokumentált natív telepítőt használja .claude vagy .claude.json törlése nélkül:
curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor
Windowson a natív telepítési parancs:
irm https://claude.ai/install.ps1 | iex
A visszaállítás külön lépés. Ismét állítsa le az írókat. Ellenőrizze az archívum ellenőrző összegét, és mint fent, üres helyreállítási könyvtárba csomagolja ki; használat előtt sikeresen hasonlítsa össze. Ha a mozgatott régi telepítést kell visszatenni, előbb igazolja, hogy a $HOME/.claude/local nem létezik, majd a $backup_dir/legacy-local könyvtárat mozgassa vissza pontosan oda. Diagnosztizált beállításfájlt az igazolt kibontásból csak a jelenlegi helyettesítő megőrzése után állítson vissza; ne írja felül vakon az egész fát. A munkamenetek, MCP-beállítások és eredeti azonosság megmaradnak. Egy Git-pillanatkép önmagában nem fedi a kizárt/nem követett átiratokat, hitelesítő adatokat vagy fájlrendszer-metaadatokat.
Mit NE tegyen, ha a Claude Code elromlott?
Főbb tudnivalók
A leírt támogatási esetekben hat elkerülendő mintát találtak: kulcscsere a diagnózis előtt, teljes visszaállítás első lépésként, pánik egy hook UI-hibája miatt, a hook kilépési kódjának megemelése a logika kijavítása előtt, a CLAUDE.md szerkesztése safe mode-os biztosíték nélkül, valamint annak elhívése, hogy „Claude megjavítja a saját MCP-jét.” Mindegyik órákba kerül, és egyik sem szükséges.
Ne cseréljen kulcsot a diagnózis előtt
„Nem működik a hitelesítés”—az esetek 90%-ában vagy az ANTHROPIC_API_KEY írja felül az előfizetést, vagy egy hook UI-hibája, vagy egy meghibásodott MCP áll a háttérben. A kulcsok cseréje egyik problémát sem oldja meg, viszont újabb egyórás leállást okoz: vissza kell vonni a régi kulcsot, újat kell kiadni, újra alá kell írni vele a CI-t, és frissíteni kell a változókat a produkcióban. Először futtassa a claude --safe-mode parancsot. Működik? Akkor a probléma a testreszabásokban van; a kulcsokhoz nem kell nyúlni.
Ne végezzen teljes visszaállítást a Safe Mode előtt
A safe mode 1 másodperc alatt elszigetelt környezetet biztosít. A .claude törlése munkameneteket, MCP-konfigurációt és más nem követett állapotot pusztíthat el. Előbb diagnosztizáljon, igazoljon privát mentést, és visszafordítható mozgatást csak a ténylegesen érintett telepítési vagy konfigurációs rétegnél használjon.
Ne essen pánikba egy hook UI-hibája miatt
Mielőtt bármit kijavítana, ellenőrizze, hogy a hook valóban lefutott-e (például stderr-naplóval vagy explicit kiíratással), és ne csak a vizuális jelzésre hagyatkozzon.
Ne emelje meg a hook kilépési kódját a logika kijavítása előtt
Ha a blokkoló hook nem blokkol, csábító lehet exit 2-re állítani, és késznek tekinteni. Ez működő folt, de elfed egy másik problémát: ha a blokkolás egy hónapig nem működött, akkor minden, amit a hooknak meg kellett volna tiltania, végrehajtható volt. Először nézze végig a git-naplót, és derítse ki pontosan, mi jutott át. Csak ezután tegye hozzá a blokkolást. Ellenkező esetben a most működő tiltás nem teszi meg nem történtté a korábbiakat.
Ne szerkessze a produkciós CLAUDE.md fájlt safe mode-os biztosíték nélkül
A leírt esetben: szerkeszti a CLAUDE.md fájlt, Claude furcsán kezd viselkedni, futtatja a git diff parancsot, és látja, hogy valaki aznap este egy MCP-szervert és egy hookot is hozzáadott a repóhoz. A saját módosítását hibáztatja, visszavonja, Claude pedig továbbra is furcsán viselkedik. A szabály: a git revert előtt futtassa a claude --safe-mode parancsot. Ha a probléma safe mode-ban is fennáll, akkor a módosításának semmi köze hozzá; nincs szükség a visszavonására.
Ne higgye el, hogy „Claude megjavítja a saját MCP-jét”
Egy tipikus forgatókönyv: arra kéri Claude-ot, hogy „adjon hozzá egy bizonyos eszközt az MCP-szerverhez”, Claude átírja a működő konfigurációt, minden elromlik, majd Claude több fordulón át próbálja hibakeresni a saját maga okozta kárt—eközben pedig elhasználja a munkamenet kvótáját. Ha az MCP elromlott, kézzel szerezze vissza a konfigurációt; ne bízza az ágensre. Az eszköztárának egy része is MCP-n fut, ezért a meghibásodott MCP a diagnosztikát végző eszközt is működésképtelenné teszi.
Mi legyen a következő lépés a javítás után?
Főbb tudnivalók
A Claude Code helyreállítása után építsen be megelőző intézkedéseket, hogy ne romoljon el újra. Legalább ennyit: disableBypassPermissionsMode: "disable" a felhasználói beállításokban, a .env fájlt és a git push --force parancsot blokkoló hookok, valamint sandbox a hosszú, autonóm futásokhoz. A megelőzési útmutató a párja ennek.
Az incidens elemzése után ne térjen vissza rögtön a munkához. Először vezessen be megelőző intézkedéseket, hogy az eset ne ismétlődjön meg. Órákat veszíthet a second brain (a projektstruktúrát tartalmazó business/ mappa) és a CLAUDE.md miatt, ezek kézi helyreállítása pedig nehéz—ez nyomós ok. A minimális összeállítás:
~/.claude/settings.json, bennepermissions.disableBypassPermissionsMode: "disable"—architekturális tiltás a bypass mód ellen, így egy véletlenül elindított--dangerously-skip-permissionsegyszerűen nem fog működni.- Hookok a
Read(./env*),Bash(git push --force),Write(./node_modules/**)műveletekhez—ezeket szabályként kell kikényszeríteni, nem kívánságként kezelni. - Sandbox-konfiguráció a hosszú, autonóm futásokhoz (
/loop,/schedule). /compactsaját szabályokkal, amelyek meghatározzák, mit dobjon el a kontextusból, hogy Claude ne merítse ki saját magát.
A teljes, négyrétegű védelmi séma a „Hogyan állítsuk be a Claude Code-ot, hogy ne tegye tönkre a projektet egyik napról a másikra” útmutatóban található. Az egyik útmutató a /loop indítása előtti megelőzést tárgyalja; a másik a helyreállítást, miután a /loop már tönkretett valamit. Két összetartozó útmutató.
Források
- Anthropic Claude Code Changelog - hivatalos changelog a v2.1.166 (
fallbackModel), v2.1.169 (safe mode, /cd), v2.1.174 (tömörítési javítás), v2.1.176 (/cd git-ág javítása) változásairól. - Anthropic Docs - Model configuration - „Fallback model chains”, „Check what triggered fallback”, „Setting your model” című részek.
- Anthropic Docs - Troubleshoot installation and login - ütköző telepítések,
claude doctor, azANTHROPIC_API_KEYközbeszólása.
Gyakorlati anyagok: Ailoot-dokumentáció.
További anyagok és eszközök: Ailoot.
További részletek
Kérdések és válaszok: Claude Code-helyreállítás: Safe Mode, /cd és tartalék modellek | Ailoot
A safe mode hibája azt jelenti, hogy töröljem a ~/.claude mappát?
Nem. Telepítési, hitelesítési, hálózati és infrastruktúra-okok is vizsgálandók maradnak. Az eldöntetlen doctor-jelentés nem bizonyítja beállítások vagy munkamenetek eltávolításának szükségét; csak az azonosított réteget javítsa.
Mit kell megőrizni telepítésjavítás előtt?
Állítsa le az írókat, és mentse a teljes Claude-állapotot: munkameneteket, plugin/MCP-konfigurációt, kizárt fájlokat és fájlrendszer-metaadatokat. Továbblépés előtt igazolja az ellenőrző összeget és kibontást, tartsa meg a fiókot és hitelesítőtárat, és csak a diagnosztizált réteget állítsa vissza vak felülírás nélkül.