Blog

Khôi phục Claude Code: Safe Mode, /cd và mô hình dự phòng

Markdown

Chẩn đoán Claude Code bằng safe mode, lệnh /cd, mô hình dự phòng và khôi phục cài đặt. Thứ tự kiểm tra và các giới hạn ban đầu.

Đọc toàn bộ bài viết

Tài liệu thực hành về cách làm việc với các tác tử: tài liệu Ailoot.

Claude Code thay đổi gì vào tháng 6 năm 2026?

Điểm chính

Ngày 8 tháng 6 năm 2026, trong Claude Code v2.1.169, Anthropic bổ sung cờ --safe-mode và lệnh /cd. Hai ngày trước đó, v2.1.166 giới thiệu các mô hình dự phòng, tối đa 3 mô hình trong một chuỗi. Ba tính năng này giải quyết vấn đề thường gặp nhất của những người viết mã theo kiểu vibe coding: “mọi thứ hỏng hết rồi, tôi không biết lỗi do đâu và không muốn mất cả tiếng cài đặt lại.”

Trước đây, khi Claude Code bắt đầu hoạt động bất thường—vòng xoay tải vô tận, bị lỗi khi khởi động, tác tử phớt lờ các quy tắc trong CLAUDE.md, hay một hook âm thầm không chạy—chỉ có một cách xử lý: tự thêm chú thích vào các phần trong .claude/settings.json, lần lượt tắt từng máy chủ MCP, hoặc trong trường hợp tệ nhất, xóa ~/.claude rồi cài đặt lại. Trong một trường hợp được mô tả, ~/.claude bị xóa, khiến cấu hình máy chủ MCP mất theo, dù đã mất một tiếng rưỡi để thiết lập. Sau đó mới rõ một dòng trong CLAUDE.md là thủ phạm, và có thể tìm ra trong 10 giây—nhưng chỉ sau khi khôi phục toàn bộ.

Vào tháng 6 năm 2026, Anthropic đưa ra ba cơ chế làm thay đổi tình huống này. Tóm tắt những gì được bổ sung và thời điểm ra mắt:

Phiên bảnNgàyNội dung mới
2.1.1666 tháng 6 năm 2026Cài đặt fallbackModel + cờ --fallback-model cho các phiên tương tác
2.1.1698 tháng 6 năm 2026Cờ --safe-mode và biến môi trường CLAUDE_CODE_SAFE_MODE, lệnh /cd
2.1.17612 tháng 6 năm 2026Bản sửa lỗi: /cd và chuyển worktree không còn hiển thị nhánh git cũ

Dưới đây là hướng dẫn từng bước cho mỗi cơ chế, cùng thứ tự áp dụng khi một phiên Claude Code đi chệch hướng.

Điều gì thường làm Claude Code bị lỗi nhất?

Điểm chính

Dựa trên trải nghiệm được mô tả, Claude Code thường gặp lỗi với người viết mã theo kiểu vibe coding vì bốn nguyên nhân: CLAUDE.md quá dài với các quy tắc mâu thuẫn, hook có mã thoát sai, máy chủ MCP âm thầm gặp lỗi và các cài đặt settings.json chồng chéo ở ba cấp. Chỉ có một thủ phạm, việc chẩn đoán mất vài phút, nhưng hoảng loạn khiến mọi người lập tức dùng rm -rf.

Trong ví dụ được mô tả, ban đầu CLAUDE.md được soạn thành 80 dòng—và hoạt động tốt trong một tháng. Sang tháng thứ hai, người ta bắt đầu nhận thấy mỗi tuần Claude lại vi phạm mọi quy tắc đã đặt ra: đụng đến .env, chạy git push --force, lục lọi trong node_modules. Không phải do ác ý—nó chỉ đơn giản là quên. Có lần .gitignore bị xóa mà không rõ ngay lý do. Tình huống này được trình bày chi tiết hơn trong hướng dẫn về CLAUDE.md.

Khi CLAUDE.md dài đến 400+ dòng, nó bắt đầu âm thầm gây rắc rối: chiếm một phần đáng kể cửa sổ ngữ cảnh khi khởi tạo phiên, khiến các chỉ dẫn quan trọng bị loãng giữa những chỉ dẫn thứ yếu. Claude vẫn đọc tệp theo đúng nghĩa đen, nên nhìn từ bên ngoài có vẻ như “quy tắc vẫn ở đó nhưng không có tác dụng”—một dấu hiệu điển hình của một bộ quy tắc quá dài.

Hooks là nguồn gây lỗi phổ biến thứ hai. Claude Code hooks có một điểm cần lưu ý mà Anthropic không nhấn mạnh.

Nói cách khác, sys.exit(1) trong hook Python (hoặc cách báo “thất bại do lỗi” thông thường của Unix) sẽ không dừng Claude. Chỉ code 2 mới chặn hoạt động. Trong trường hợp được mô tả, hook được xem là “lệnh cấm tuyệt đối”, nhưng trên thực tế nó chỉ ghi lại lời phàn nàn rồi vẫn cho phép hành động.

Máy chủ MCP là lớp thứ ba, và chúng cũng có thể hỏng theo cách riêng.

Triệu chứng thường giống nhau: lệnh MCP có sẵn nhưng trả về failed mà không có traceback. Xem thêm về cách cấu hình MCP và thêm máy chủ bằng claude mcp add trong hướng dẫn riêng.

Nguồn thứ tư là hệ thống phân cấp ba tầng của settings.json. Bạn có ~/.claude/settings.json (cấp người dùng), .claude/settings.json ở thư mục gốc dự án (cấp dự án), .claude/settings.local.json (cấp cục bộ) và có thể có cả cài đặt do quản trị viên công ty quản lý. Các cài đặt này được kết hợp theo quy tắc ưu tiên. Khi ai đó thêm một máy chủ MCP ở cấp dự án trong lúc bạn có một mục tương tự nhưng cấu hình khởi chạy khác ở cấp người dùng, xung đột âm thầm sẽ xảy ra, trông như thể “Claude Code bị hỏng.”

--safe-mode hoạt động thế nào và tắt những gì?

Điểm chính

claude --safe-mode khởi chạy Claude Code với toàn bộ tùy chỉnh bị tắt: CLAUDE.md, plugin, skill, hook, máy chủ MCP, lệnh người dùng, tác tử, kiểu đầu ra, quy trình làm việc và phím tắt. Xác thực, chọn mô hình, công cụ tích hợp và quyền vẫn được giữ nguyên. Đây là công cụ chẩn đoán: nếu sự cố biến mất trong safe mode, nguyên nhân nằm ở một trong những lớp bạn đã thêm.

Nguyên văn thông báo của Anthropic trong nhật ký thay đổi v2.1.169:

Đã thêm cờ --safe-mode (và CLAUDE_CODE_SAFE_MODE) để khởi chạy Claude Code khi tắt các tùy chỉnh (CLAUDE.md, plugin, skill, hook, máy chủ MCP) nhằm phục vụ chẩn đoán.

— Nhật ký thay đổi Anthropic Claude Code, https://code.claude.com/docs/en/changelog

Anthropic giải thích thêm trong tài liệu cấu hình mô hình:

Để kiểm tra xem tùy chỉnh có phải là nguyên nhân hay không, hãy khởi chạy phiên bằng claude --safe-mode, thao tác này sẽ tắt CLAUDE.md, skill, máy chủ MCP và hook. Trạng thái Git và tên thư mục không được xem là tùy chỉnh nên vẫn khả dụng.

— Tài liệu Anthropic - Cấu hình mô hình, https://code.claude.com/docs/en/model-config

Đây là công cụ chẩn đoán, không phải “môi trường sạch.” Safe mode giúp trả lời một câu hỏi: sự cố nằm ở hành vi mặc định của Claude Code hay ở các tùy chỉnh được thêm vào? Đây là một phần của kỹ thuật quản lý ngữ cảnh—kiểm soát những gì Claude thấy và không thấy tại từng thời điểm. Nếu mọi thứ hoạt động trong safe mode, rõ ràng cần kiểm tra từng lớp bằng phương pháp tìm kiếm nhị phân. Nếu không hoạt động, vấn đề nằm ở bản cài đặt, xác thực, mạng hoặc hạ tầng; khi đó nên kiểm tra claude doctor và nhật ký.

Những gì safe mode tắt (danh sách chính thức của Anthropic—5 lớp chính):

  • CLAUDE.md ở mọi cấp (người dùng / dự án)
  • Plugin
  • Skill
  • Hook
  • Máy chủ MCP

Những gì vẫn hoạt động:

  • Xác thực (phiên OAuth hoặc khóa API của bạn)
  • Chọn mô hình (--model sonnet, --model opus)
  • Công cụ tích hợp (Read, Write, Bash, Grep, v.v.)
  • Quyền
  • Trạng thái Git
  • Tên thư mục

Một chi tiết quan trọng: safe mode không tắt các cài đặt được quản lý hoặc chính sách do quản trị viên công ty áp dụng. Nếu bạn làm việc trong một nhóm mà Bedrock GovCloud hoặc cấu hình MDM đặt availableModels, những giới hạn đó vẫn còn—safe mode chỉ tắt các tùy chỉnh của bạn, không tắt chính sách của công ty.

Làm thế nào để cô lập một lớp và tìm ra thủ phạm trong 60 giây?

Điểm chính

Bước 1: chạy claude --safe-mode trong chính thư mục đã xảy ra sự cố. Nếu hoạt động, vấn đề nằm ở các tùy chỉnh của bạn; hãy bật lại từng thứ một: CLAUDE.md -> hook -> MCP -> skill. Nếu safe mode cũng không hoạt động, vấn đề nằm ở xác thực, phiên bản, mạng hoặc hệ điều hành. Khi đó, chạy claude doctor để chẩn đoán tự động, không đụng đến rm -rf.

Quy trình chẩn đoán khi Claude Code “không còn nghe lời.” Phiên bản tối thiểu cần có cho tất cả lệnh dưới đây là Claude Code v2.1.169. Nếu bạn đang dùng phiên bản cũ hơn, hãy cập nhật trước (npm update -g @anthropic-ai/claude-code hoặc bộ cài gốc của Anthropic).

  1. Mở đúng thư mục đã xảy ra sự cố.
  2. Chạy claude --safe-mode.
  3. Nếu khởi chạy bình thường, hãy kiểm tra yêu cầu ban đầu của bạn. Nó hoạt động chứ? Nếu có, nguyên nhân nằm ở một trong các lớp. Chuyển sang bước 4.
  4. Nếu vẫn lỗi trong safe mode, đừng đụng vào cấu hình. Trước tiên chạy claude doctor; kiểm tra xác thực, phiên bản và các bản cài đặt xung đột.

Khi safe mode khởi chạy bình thường, hãy bật từng lớp một, bắt đầu từ thủ phạm có khả năng cao nhất. Thứ tự dưới đây dựa trên trải nghiệm được mô tả:

  1. CLAUDE.md. Chạy claude không dùng safe mode, nhưng tạm đổi tên tệp: mv CLAUDE.md CLAUDE.md.bak. Nếu hoạt động, tệp đó là nguyên nhân. Sau đó bạn có thể tìm kiếm nhị phân: giữ lại một nửa số dòng rồi kiểm tra.
  2. Hooks. Mở .claude/settings.json và tạm đặt [] trong phần hooks. Khởi động lại claude. Hoạt động chứ? Nếu có, một trong các hook là nguyên nhân. Bật từng hook một.
  3. Máy chủ MCP. Tương tự, tạm đặt phần mcpServers trong ~/.claude.json hoặc .claude/settings.json thành một đối tượng rỗng, khởi động lại rồi kiểm tra.
  4. Skill. Chuyển .claude/skills/ sang một thư mục tạm. Khởi chạy và kiểm tra.

“Đổi tên tạm thời” nghĩa là không xóa tệp trong lúc chẩn đoán. mv hoặc git stash cho phép khôi phục mọi thứ bằng một lệnh nếu phát hiện lớp đó không phải thủ phạm.

Làm thế nào để đổi thư mục làm việc bằng /cd mà không mất ngữ cảnh?

Điểm chính

Lệnh /cd <path> trong Claude Code 2.1.169+ đổi thư mục làm việc của phiên hiện tại mà không làm mất bộ nhớ đệm prompt. Lệnh này hữu ích khi cấu hình của dự án hiện tại bị lỗi: bạn có thể chuyển sang một thư mục sạch, kiểm tra xem Claude có hoạt động không rồi quay lại. Trước đây, bạn phải đóng phiên và khởi động lại.

Trích nhật ký thay đổi v2.1.169 ngày 8 tháng 6:

Đã thêm lệnh /cd để chuyển phiên sang thư mục làm việc mới mà không đặt lại bộ nhớ đệm prompt giữa phiên.

— Nhật ký thay đổi Anthropic Claude Code, https://code.claude.com/docs/en/changelog

Vì sao tính năng này hữu ích khi khắc phục sự cố. Giả sử bạn đang ở thư mục dự án ~/work/myapp và Claude Code hoạt động bất thường. Trước đây, cách duy nhất để kiểm tra “nó có hoạt động không?” là đóng phiên, chuyển sang thư mục khác rồi khởi động lại. Bạn mất ngữ cảnh, lịch sử và bộ nhớ đệm prompt đã được làm nóng. Giờ đây:

# Trong cùng phiên:
/cd ~/sandbox/test

Claude chuyển sang thư mục mới và đọc CLAUDE.md ở đó (nếu có) dưới dạng một thông báo, chứ không thay thế system prompt—nghĩa là bộ nhớ đệm vẫn được giữ nguyên. Nếu mọi thứ hoạt động trong ~/sandbox/test, rõ ràng vấn đề nằm ở cấu hình của ~/work/myapp.

Ngày 12 tháng 6, v2.1.176 đã sửa một hồi quy khó chịu—/cd hiển thị nhánh git cũ cho đến khi khởi động lại hoàn toàn. Nếu phiên bản của bạn cũ hơn, hãy cập nhật hoặc tạm bỏ qua git status trong vài tin nhắn đầu sau khi chuyển thư mục—nó sẽ cập nhật lại.

Làm thế nào để cấu hình mô hình dự phòng cho lỗi 529?

Điểm chính

Trong v2.1.166, Anthropic bổ sung fallbackModel—một chuỗi tối đa 3 mô hình được thử lần lượt khi mô hình chính quá tải hoặc không khả dụng. Chuỗi này chỉ được kích hoạt bởi lỗi máy chủ do quá tải và không thể thử lại. Lỗi xác thực, thanh toán, giới hạn tốc độ và truyền tải không kích hoạt chuỗi dự phòng—chúng tuân theo logic thử lại thông thường.

Trong tình huống được mô tả, một tác vụ dài chạy bằng Opus trong dự án mỗi tuần một lần; sau 10 phút, API trả về 529 Overloaded và phiên bị lỗi. Trước đây, bạn phải chờ hoặc tự chuyển sang Sonnet bằng --model sonnet, đồng thời mất toàn bộ ngữ cảnh đã được làm nóng. Trong một thư mục business/ lớn với cấu trúc second-brain, việc này tốn khoảng hai mươi phút. Giờ đã có cơ chế phù hợp.

Trích dẫn chính xác từ tài liệu chính thức:

Khi mô hình chính quá tải, không khả dụng hoặc trả về lỗi máy chủ khác không thể thử lại, Claude Code có thể chuyển sang mô hình dự phòng thay vì để yêu cầu thất bại. Lỗi xác thực, thanh toán, giới hạn tốc độ, kích thước yêu cầu và truyền tải không bao giờ kích hoạt việc chuyển mô hình—chúng tuân theo quy trình thử lại và xử lý lỗi thông thường.

— Tài liệu Anthropic - Cấu hình mô hình, https://code.claude.com/docs/en/model-config

Và riêng phần giải thích cách chuỗi hoạt động:

Cấu hình một hoặc nhiều mô hình dự phòng để Claude Code thử lần lượt và hiển thị thông báo khi chuyển đổi. Việc chuyển đổi chỉ áp dụng cho lượt hiện tại—tin nhắn tiếp theo sẽ thử lại mô hình chính. Sau khi loại bỏ trùng lặp, chuỗi giới hạn ở ba mô hình; các mục vượt quá sẽ bị bỏ qua.

— Tài liệu Anthropic - Cấu hình mô hình, https://code.claude.com/docs/en/model-config

Có hai cách cấu hình. Qua CLI:

claude --fallback-model sonnet,haiku

Qua ~/.claude/settings.json:

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

Một điểm riêng về giới hạn tốc độ. Anthropic cố ý không đưa lỗi 429 vào chuỗi, để bạn không thể lách giới hạn yêu cầu bằng cách chuyển sang mô hình tiếp theo. Cơ chế dự phòng chỉ hoạt động khi mô hình chính quá tải, không khả dụng hoặc trả về lỗi máy chủ không thể thử lại (chẳng hạn 529 Overloaded). Lỗi giới hạn tốc độ được xử lý theo logic thử lại và backoff thông thường.

Thêm một lưu ý nữa—ngày 12 tháng 6, v2.1.174 đã sửa một hồi quy: thao tác nén ngữ cảnh không tuân theo --fallback-model. Nếu bạn có phiên dài bị nén trong lúc quá tải, trước bản sửa này mô hình dự phòng sẽ không được gọi. Nếu làm việc với các phiên dài (/compact, /loop qua đêm), hãy cập nhật lên ít nhất v2.1.174.

Cần sửa gì khi CLAUDE.md, hook, MCP hoặc skill là thủ phạm?

Điểm chính

Khi safe mode xác định lớp có lỗi, cách sửa sẽ tùy theo lớp đó. Với CLAUDE.md, hãy tìm kiếm nhị phân hoặc quay lại một mẫu có sẵn dưới 200 dòng. Với hook, kiểm tra exit code (2 chặn, 1 không chặn) và logic. Với MCP, gỡ từng máy chủ rồi kiểm tra. Với skill, kiểm tra SKILL.md xem có mâu thuẫn với CLAUDE.md không.

Các cách xử lý cụ thể cho từng lớp.

Nếu CLAUDE.md là thủ phạm

Mở tệp và kiểm tra độ dài. Dựa trên trải nghiệm được mô tả, giữ CLAUDE.md đang hoạt động không quá 200 dòng; chuyển phần còn lại vào các router và tài liệu hỗ trợ bên cạnh dự án (cấu trúc second-brain đầy đủ nằm trong hướng dẫn về second brain). Nếu tệp có 400+ dòng, gần như chắc chắn đó là thủ phạm. Các bước:

  1. Tạo bản sao lưu: cp CLAUDE.md CLAUDE.md.full.
  2. Quay lại một mẫu ngắn đang hoạt động. Có mẫu sẵn trong hướng dẫn “Cách cấu hình CLAUDE.md”.
  3. Khởi động lại Claude Code. Kiểm tra.
  4. Nếu hoạt động, khôi phục quy tắc theo từng khối nhỏ 10–20 dòng, kiểm tra sau mỗi khối.
  5. Tìm khối làm hỏng hành vi. Viết lại nó thành một hook với exit code đúng (exit code cho hooks được trình bày trong tiểu mục tiếp theo của H2 này).

Nếu hook là thủ phạm

Câu hỏi chính là exit code có đúng không. Hooks của Claude Code sử dụng:

  • Exit 0 — mọi thứ ổn; hành động được tiếp tục.
  • Exit 1 — có lỗi nhưng không chặn. Claude tiếp tục như thể không có gì xảy ra.
  • Exit 2 — lỗi chặn. Chỉ mã này mới thực sự dừng hành động.

Nếu bạn viết sys.exit(1) hoặc exit 1 trong shell hook với suy nghĩ rằng nó sẽ chặn, thì trong Claude Code mã này chỉ đóng vai trò ghi cảnh báo, không dừng hành động. Hãy đổi thành 2. Để biết chi tiết về hooks và cách cấu hình mà không gặp phải lỗi này, xem hướng dẫn riêng.

Trường hợp phổ biến thứ hai là hook trả về JSON không hợp lệ trên stdout. Claude Code phân tích phản hồi của hook dưới dạng JSON; nếu có nội dung lẫn vào đó (bản ghi, ký hiệu tiến trình, emoji), hook bị xem là thất bại và hành động vẫn tiếp tục. Quy tắc: stdout chỉ chứa JSON; mọi thứ khác chuyển sang stderr.

Trường hợp thứ ba là hook đọc thứ gì đó từ ~/.claude/ mà safe mode đã ẩn. Đây là tình huống bình thường; cách sửa không phải vá hook, mà là kiểm tra os.environ.get('CLAUDE_CODE_SAFE_MODE') ở đầu hook và thoát với mã 0.

Nếu máy chủ MCP là thủ phạm

Triệu chứng: lệnh MCP có sẵn nhưng trả về failed mà không có traceback rõ ràng. Các bước:

  1. Chạy claude mcp list—có những máy chủ nào được định nghĩa?
  2. Lần lượt tắt các máy chủ trong ~/.claude.json: đổi tên khóa claude-server-A thành _claude-server-A (cách này vô hiệu hóa nó mà không xóa).
  3. Khởi động lại claude. Kiểm tra lệnh nào hoạt động.
  4. Khi tìm thấy máy chủ có lỗi, kiểm tra nhật ký: claude mcp logs <name>.
  5. Nếu đó là máy chủ của bên thứ ba (@modelcontextprotocol/server-postgres và các máy chủ tương tự), kiểm tra xem gần đây có bản phát hành mới không. Hệ sinh thái MCP vẫn còn nhiều biến động; máy chủ thường hỏng sau các bản cập nhật Claude Code.

Nếu bạn gặp tình huống “bị lỗi khi khởi động và chỉ khi có hai MCP”, hãy so sánh hành vi trong safe mode khi không có MCP.

Nếu skill là thủ phạm

Một skill gồm SKILL.md và mã trong .claude/skills/<name>/. Triệu chứng: Claude phớt lờ skill, áp dụng không đúng lúc, hoặc có áp dụng nhưng tạo ra kết quả tệ. Các bước:

  1. Mở SKILL.md. Kiểm tra phần mô tả—phần này nên dài 1–2 câu và nêu cụ thể khi nào cần dùng skill. Nếu ghi “trợ lý đa năng cho mọi việc”, Claude sẽ không hiểu khi nào cần gọi nó.
  2. Kiểm tra xem có mâu thuẫn với CLAUDE.md không. Nếu CLAUDE.md ghi “luôn viết kiểm thử”, nhưng mô tả skill lại ghi “dùng để tạo mẫu nhanh mà không cần kiểm thử”, thì có xung đột.
  3. Nếu skill sử dụng các lệnh bên ngoài (npm, python, git), kiểm tra xem chúng có sẵn trong PATH toàn hệ thống không. Skill có môi trường tối thiểu riêng.

Safe Mode không giúp: chẩn đoán và giữ trạng thái trước khi sửa

Điểm chính

Nếu safe mode cũng lỗi, khả năng còn gồm cài đặt, xác thực, mạng, hạ tầng. Chạy claude doctor, xem bằng chứng. Báo chưa kết luận không cho phép xóa settings/phiên: giữ, xác minh toàn trạng thái trước rồi chỉ sửa bản cài đã chẩn đoán.

Xóa trạng thái người dùng không là lối tắt chẩn đoán. Dùng kiểm dưới tìm lỗi; chưa kết luận thì giữ bằng chứng và điều tra tiếp. Sửa cài bắt đầu backup đã xác minh, giữ tài khoản và danh tính kho credential cũ. Thứ tự:

  1. claude doctor — chẩn đoán tự động. Anthropic ghi trong tài liệu:

Nếu `claude --version` hoạt động nhưng có vấn đề khác, hãy chạy `claude doctor` để tạo báo cáo chẩn đoán tự động.

— Tài liệu Anthropic - Khắc phục sự cố cài đặt, https://code.claude.com/docs/en/troubleshoot-install
  1. Kiểm tra các bản cài đặt xung đột. Nhiều người cài đồng thời cả phiên bản npm toàn cục và bộ cài gốc:

Nhiều bản cài đặt Claude Code có thể gây lệch phiên bản hoặc tạo ra hành vi không mong muốn.

— Tài liệu Anthropic - Khắc phục sự cố cài đặt, https://code.claude.com/docs/en/troubleshoot-install
  1. Kiểm tra xem ANTHROPIC_API_KEY có đang chặn phiên OAuth của bạn không. Đây là nguyên nhân thường gặp của tình trạng “không có gì hoạt động, khóa đã hết hạn”:

Khi `ANTHROPIC_API_KEY` được thiết lập và bạn đã xác nhận khóa đó, Claude Code sẽ dùng khóa này thay cho thông tin xác thực OAuth của gói đăng ký.

— Tài liệu Anthropic - Khắc phục sự cố cài đặt, https://code.claude.com/docs/en/troubleshoot-install

Cách giải quyết: chạy unset ANTHROPIC_API_KEY trong phiên shell hiện tại hoặc xóa biến này khỏi ~/.zshrc / ~/.bashrc.

  1. Chỉ sửa bản cài chẩn đoán chỉ ra; giữ toàn trạng thái trước. Safe mode lỗi hay doctor chưa kết luận không xác lập phải xóa dữ liệu. Dừng mọi phiên Claude và writer khác để backup nhất quán. Giữ cùng Unix account, HOME, kho credential OS và tài khoản Anthropic; không đổi khóa hay tạo danh tính thay.

Ví dụ backup sau dành Linux với GNU tar. macOS/Windows dùng công cụ giữ ACL, xattr, link, metadata của nền tảng và xác minh phục hồi trước; không mặc định cờ GNU dùng được. Archive có credential/transcript, giữ riêng ngoài kho mã.

# 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"

Mọi lệnh phải đạt. Archive phủ toàn cây .claude, gồm phiên ignored/untracked, plugin và .claude.json, không chỉ settings tracked. Nếu đường là symlink hoặc dữ liệu ở vị trí cấu hình khác, dừng và đưa đích đã resolve vào cùng backup xác minh; lưu link không lưu đích. Archive không gồm macOS Keychain hay kho credential ngoài, nên giữ danh tính đó tại chỗ.

Chỉ khi chẩn đoán chỉ legacy local installation là bản xung đột, chuyển riêng nó vào thư mục phục hồi riêng, không xóa cấu hình/phiên:

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

Chỉ gỡ npm nếu xác định đó là bản xung đột và định giữ native. Dùng trình cài native có tài liệu, không xóa .claude hay .claude.json:

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

Trên Windows, lệnh native là:

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

Khôi phục riêng. Dừng writer lại. Kiểm checksum, giải vào thư mục trống như trên, so thành công trước dùng. Nếu cần trả legacy, xác nhận $HOME/.claude/local chưa tồn tại rồi chuyển $backup_dir/legacy-local về đúng đó. Chỉ khôi phục settings được chẩn đoán từ bản giải đã kiểm sau giữ bản hiện tại; không overlay cả cây mù. Phiên, MCP và danh tính gốc còn được giữ. Git snapshot riêng không phủ transcript ignored/untracked, credential hoặc metadata tệp.

Không nên làm gì khi Claude Code bị lỗi?

Điểm chính

Sáu cách làm sai được phát hiện trong các trường hợp hỗ trợ đã mô tả: đổi khóa trước khi chẩn đoán, đặt lại toàn bộ ngay từ đầu, hoảng loạn vì lỗi UI trong hook, tăng exit code của hook trước khi sửa logic, chỉnh sửa CLAUDE.md mà không có biện pháp bảo vệ bằng safe mode, và tin rằng “Claude tự sửa MCP của nó.” Mỗi cách đều làm mất hàng giờ, và không cách nào là cần thiết.

Đừng đổi khóa trước khi chẩn đoán

“Xác thực không hoạt động” trong 90% trường hợp là do ANTHROPIC_API_KEY chặn gói đăng ký, lỗi UI của hook hoặc MCP thất bại. Xoay vòng khóa không giải quyết được vấn đề nào trong số đó, mà còn gây thêm một giờ gián đoạn: bạn phải thu hồi khóa cũ, cấp khóa mới, đăng nhập lại CI bằng khóa đó và cập nhật biến trong môi trường production. Trước tiên, chạy claude --safe-mode. Hoạt động chứ? Nếu có, vấn đề nằm ở các tùy chỉnh; không cần đụng đến khóa.

Đừng đặt lại toàn bộ trước khi thử Safe Mode

Safe mode tạo ra môi trường cô lập chỉ trong 1 giây. Xóa .claude có thể phá phiên, MCP và trạng thái untracked khác. Chẩn đoán trước, xác minh backup riêng, chỉ dùng chuyển có thể đảo cho tầng cài hoặc cấu hình thực sự liên quan.

Đừng hoảng loạn vì lỗi UI trong hook

Trước khi sửa bất cứ thứ gì, hãy kiểm tra xem hook có thực sự chạy không (qua nhật ký ghi vào stderr hoặc một lệnh in rõ ràng), thay vì chỉ dựa vào dấu hiệu hiển thị.

Đừng tăng Exit Code của Hook trước khi sửa Logic

Khi hook chặn của bạn không chặn, rất dễ đổi thành exit 2 rồi cho là xong. Đây là một bản vá có tác dụng, nhưng lại che giấu một vấn đề khác: nếu việc chặn không hoạt động suốt một tháng, thì mọi thứ hook được cho là phải cấm đều đã lọt qua. Trước tiên, xem lại nhật ký git để tìm chính xác những gì đã lọt qua. Sau đó mới thêm chặn. Nếu không, việc đóng chặn bây giờ cũng không hoàn tác được những gì đã xảy ra trước đó.

Đừng chỉnh sửa CLAUDE.md production khi không có biện pháp bảo vệ bằng Safe Mode

Trong trường hợp được mô tả: bạn chỉnh sửa CLAUDE.md, Claude bắt đầu hoạt động lạ, bạn chạy git diff và thấy rằng tối hôm đó có người cũng thêm một máy chủ MCP và một hook vào repo. Bạn đổ lỗi cho thay đổi của mình, hoàn tác nó, nhưng Claude vẫn hoạt động bất thường. Quy tắc: trước khi chạy git revert, hãy chạy claude --safe-mode. Nếu sự cố vẫn còn trong safe mode, thay đổi của bạn không liên quan; không cần hoàn tác.

Đừng tin rằng “Claude tự sửa MCP của nó”

Một tình huống điển hình: bạn yêu cầu Claude “thêm một công cụ nhất định vào máy chủ MCP”, Claude viết lại cấu hình đang hoạt động, mọi thứ hỏng, rồi Claude dành nhiều lượt để gỡ lỗi do chính mình gây ra—đồng thời tiêu hết hạn mức của phiên. Khi MCP bị hỏng, hãy lấy cấu hình theo cách thủ công; đừng giao việc đó cho tác tử. Một phần bộ công cụ của tác tử cũng chạy trên MCP, nên MCP hỏng đồng nghĩa với công cụ chẩn đoán cũng hỏng.

Sau khi sửa xong thì nên làm gì?

Điểm chính

Sau khi khôi phục Claude Code, hãy bổ sung biện pháp phòng ngừa để sự cố không tái diễn. Tối thiểu cần có disableBypassPermissionsMode: "disable" trong cài đặt người dùng, các hook chặn .env và git push --force, cùng sandbox cho các lượt chạy tự động dài. Hướng dẫn phòng ngừa là phần bổ trợ cho hướng dẫn này.

Sau khi phân tích sự cố, đừng quay lại làm việc ngay. Trước tiên, hãy bổ sung biện pháp phòng ngừa để sự cố không lặp lại. Bạn có thể mất hàng giờ xây dựng second brain (thư mục business/ với cấu trúc dự án) và CLAUDE.md, mà việc khôi phục thủ công lại khó—đó là lý do đủ thuyết phục. Bộ tối thiểu:

  1. ~/.claude/settings.json có permissions.disableBypassPermissionsMode: "disable"—một lệnh cấm ở cấp kiến trúc đối với chế độ bỏ qua quyền, để --dangerously-skip-permissions được khởi chạy nhầm sẽ không hoạt động.
  2. Hooks cho Read(./env*), Bash(git push --force), Write(./node_modules/**)—những điều cần được thực thi như luật lệ, chứ không phải mong muốn.
  3. Cấu hình sandbox cho các lượt chạy tự động dài (/loop, /schedule).
  4. /compact cùng các quy tắc riêng về những gì cần loại khỏi ngữ cảnh, để Claude không tự làm cạn kiệt khả năng của mình.

Kế hoạch bảo vệ bốn lớp đầy đủ nằm trong hướng dẫn “Cách cấu hình Claude Code để nó không làm hỏng dự án của bạn qua đêm”. Một hướng dẫn nói về phòng ngừa trước khi chạy /loop; hướng dẫn còn lại nói về khôi phục sau khi /loop đã làm hỏng thứ gì đó. Đây là một cặp hợp lý.

Nguồn

Tài liệu thực hành: tài liệu Ailoot.

Tài liệu và công cụ khác: Ailoot.

Xem thêm chi tiết

Câu hỏi thường gặp

Safe mode thất bại có nghĩa nên xóa ~/.claude không?

Không. Vẫn cần điều tra cài đặt, xác thực, mạng và hạ tầng. Báo doctor chưa kết luận không chứng minh phải xóa thiết lập hoặc phiên; chỉ sửa tầng đã chẩn đoán.

Cần giữ gì trước khi sửa cài đặt?

Dừng writer, sao lưu toàn trạng thái Claude gồm phiên, cấu hình plugin/MCP, tệp ignore và metadata hệ thống tệp. Xác minh checksum và giải nén trước, giữ tài khoản và kho credential hiện có; chỉ khôi phục tầng lỗi, không ghi đè mù trạng thái mới.

Tất cả bài viết