Blog

Claude Code-helyreállítás: Safe Mode, /cd és tartalék modellek

Markdown

A 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

  1. június 8-án, a Claude Code v2.1.169-ben az Anthropic hozzáadta a --safe-mode kapcsolót és a /cd parancsot. 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.1662026. június 6.fallbackModel beállítás + --fallback-model kapcsoló interaktív munkamenetekhez
2.1.1692026. június 8.--safe-mode kapcsoló és CLAUDE_CODE_SAFE_MODE környezeti változó, /cd parancs
2.1.1762026. 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-mode kapcsolót (és a CLAUDE_CODE_SAFE_MODE vá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.

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

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-mode paranccsal, amely letiltja a CLAUDE.md fá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.

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

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.md minden 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

  1. lépés: futtassa a claude --safe-mode parancsot 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 a claude doctor parancsot az automatikus diagnosztikához, és ne nyúljon az rm -rf parancshoz.

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).

  1. Nyissa meg ugyanazt a mappát, ahol a probléma jelentkezett.
  2. Futtassa a claude --safe-mode parancsot.
  3. 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.
  4. Ha safe mode-ban is hibás, ne módosítsa a konfigurációkat. Először futtassa a claude doctor parancsot; 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:

  1. CLAUDE.md. Futtassa a claude parancsot 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.
  2. Hookok. Nyissa meg a .claude/settings.json fájlt, és ideiglenesen állítsa [] értékre a hooks részt. Indítsa újra a claude parancsot. Működik? Akkor valamelyik hook a felelős. Engedélyezze őket egyenként.
  3. MCP-szerverek. Hasonlóképpen, a ~/.claude.json fájlban vagy a .claude/settings.json fájlban ideiglenesen állítsa a mcpServers részt üres objektumra, indítsa újra, majd ellenőrizze.
  4. 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 /cd parancsot, amellyel a munkamenet új munkamappára váltható anélkül, hogy a prompt gyorsítótára a munkamenet közben visszaállna.

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

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.

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

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.

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

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:

  1. Készítsen biztonsági másolatot: cp CLAUDE.md CLAUDE.md.full.
  2. Álljon vissza egy rövid, működő sablonra. Kész sablont a „A CLAUDE.md konfigurálása” útmutatóban talál.
  3. Indítsa újra a Claude Code-ot. Ellenőrizze.
  4. Ha működik, állítsa vissza a szabályokat kis, 10–20 soros blokkokban, és minden blokk után ellenőrizze.
  5. 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:

  1. Futtassa a claude mcp list parancsot—mely szerverek vannak beállítva?
  2. Tiltsa le egyenként a szervereket a ~/.claude.json fájlban: nevezze át a claude-server-A kulcsot _claude-server-A értékre (így törlés nélkül deaktiválja).
  3. Indítsa újra a claude parancsot. Ellenőrizze, mely hívások működnek.
  4. Ha megtalálta a hibás szervert, nézze meg a naplóját: claude mcp logs <name>.
  5. 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:

  1. Nyissa meg a SKILL.md fá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.
  2. Ellenőrizze, hogy vannak-e ellentmondások a CLAUDE.md fájllal. Ha a CLAUDE.md azt 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.
  3. 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:

  1. claude doctor — automatikus diagnosztika. Az Anthropic ezt írja a dokumentációjában:

Ha a claude --version működik, de valami más nincs rendben, futtassa a claude doctor parancsot az automatikus diagnosztikai jelentés elkészítéséhez.

— Anthropic Docs - Troubleshoot installation, https://code.claude.com/docs/en/troubleshoot-install
  1. 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.

— Anthropic Docs - Troubleshoot installation, https://code.claude.com/docs/en/troubleshoot-install
  1. Ellenőrizze, hogy az ANTHROPIC_API_KEY kö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.

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

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.

  1. 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:

  1. ~/.claude/settings.json, benne permissions.disableBypassPermissionsMode: "disable"—architekturális tiltás a bypass mód ellen, így egy véletlenül elindított --dangerously-skip-permissions egyszerűen nem fog működni.
  2. 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.
  3. Sandbox-konfiguráció a hosszú, autonóm futásokhoz (/loop, /schedule).
  4. /compact sajá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

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.

Összes cikk