Debug cấu hình của bạn

Khi Claude bỏ qua một chỉ dẫn hay một tính năng bạn cấu hình không xuất hiện, nguyên nhân thường là file không nạp, nạp từ vị trí khác với bạn nghĩ, hoặc bị file khác override. Bài này hướng dẫn kiểm tra thực tế Claude Code đã nạp gì để thu hẹp nguyên nhân.

Với sự cố cài đặt, xác thực, và kết nối, xem Khắc phục sự cố cài đặt và đăng nhập thay vào đó.

Xem những gì đã nạp vào context

Lệnh /context hiện mọi thứ đang chiếm context window của phiên hiện tại, chia theo nhóm: system prompt, system tool, MCP tool, custom subagent (kèm nguồn nạp), memory file, skill, và tin nhắn hội thoại. Chạy lệnh này đầu tiên để xác nhận CLAUDE.md, rule, hay mô tả skill có xuất hiện hay không.

Muốn chi tiết hơn về một nhóm cụ thể, dùng lệnh chuyên biệt:

Lệnh	Hiện gì
/memory	Vị trí memory file ở cả scope user và project, kèm tuỳ chọn mở từng file trong editor
/skills	Skill khả dụng từ project, user, và nguồn plugin
/hooks	Cấu hình hook đang active
/mcp	MCP server đang kết nối và trạng thái
/permissions	Allow/deny rule đã resolve, đang có hiệu lực
/doctor	Kiểm tra tổng thể: sức khoẻ cài đặt, settings file không hợp lệ, extension không dùng, subagent trùng tên, và nội dung CLAUDE.md Claude có thể tự suy ra từ codebase, kèm đề xuất fix
/debug [issue]	Bật debug log cho phiên và nhờ Claude chẩn đoán bằng log output và đường dẫn settings
/status	Nguồn settings đang active, gồm cả việc managed settings có hiệu lực hay không

Nếu một memory file không xuất hiện trong /context, kiểm tra vị trí file so với cách CLAUDE.md nạp. CLAUDE.md ở thư mục con nạp theo yêu cầu khi Claude đọc file trong thư mục đó bằng Read tool, không phải lúc khởi động phiên.

Nếu /context xác nhận file đã nạp nhưng Claude vẫn không theo một chỉ dẫn cụ thể, vấn đề thường nằm ở cách chỉ dẫn được viết chứ không phải việc nó có nạp hay không. Độ tuân thủ giảm khi chỉ dẫn mơ hồ, hai file mâu thuẫn nhau, hay file đã dài tới mức từng quy tắc riêng lẻ ít được chú ý.

Ghi chú

CLAUDE.md và permission giải quyết hai vấn đề khác nhau. CLAUDE.md cho Claude biết project của bạn hoạt động thế nào để ra quyết định tốt. Permission và hook thực thi giới hạn bất kể Claude quyết định gì. Dùng CLAUDE.md cho “ở đây chúng ta làm theo cách này”. Dùng permission hay hook cho ranh giới bảo mật và mọi thứ tuyệt đối không được xảy ra, nơi bạn cần một đảm bảo chứ không phải hướng dẫn.

Kiểm tra settings đã resolve

Settings được gộp qua các scope managed, user, project, và local. Managed settings luôn thắng khi có mặt. Trong số các scope còn lại, scope gần hơn override scope rộng hơn theo thứ tự local, rồi project, rồi user. Một số setting còn có thể đặt qua CLI flag hay environment variable, là một lớp override khác.

Chạy /doctor để kiểm tra cấu hình và cài đặt. Lệnh này báo cáo những gì phát hiện được, gồm settings file không hợp lệ, cài đặt trùng lặp, extension không dùng, và nội dung CLAUDE.md đã checkin mà Claude có thể tự suy ra từ codebase, rồi đề xuất fix chỉ áp dụng sau khi bạn xác nhận.

Từ terminal, claude doctor in ra chẩn đoán cài đặt và settings read-only mà không khởi động phiên.

Chạy /status để xem nguồn settings nào đang active, gồm cả managed settings.

Kiểm tra MCP server

Chạy /mcp để xem mọi server đã cấu hình, trạng thái kết nối, và đã được duyệt cho project hiện tại hay chưa. Một server có thể được định nghĩa đúng nhưng vẫn không cung cấp tool vì vài lý do phổ biến:

• Server ở project-scope trong .mcp.json cần duyệt một lần. Nếu prompt duyệt bị bỏ qua, server đứng yên ở trạng thái disabled cho tới khi bạn duyệt từ /mcp
• Server fail khi khởi động hiện trạng thái failed trong /mcp. Đường dẫn tương đối trong command hoặc args là nguyên nhân thường gặp, vì nó resolve theo thư mục bạn khởi động Claude Code chứ không phải vị trí .mcp.json
• Server hiện connected nhưng liệt kê 0 tool đã khởi động thành công nhưng không trả về danh sách tool. Chọn Reconnect từ /mcp. Nếu vẫn 0, chạy claude --debug mcp để xem stderr của server

Kiểm tra hook

Chạy /hooks để liệt kê mọi hook đăng ký cho phiên hiện tại, theo từng event. Nếu một hook bạn định nghĩa không xuất hiện, nó không được đọc: hook nằm dưới key "hooks" trong một settings file, không phải file riêng.

Nếu hook xuất hiện nhưng không chạy, matcher thường là nguyên nhân:

• Trường matcher là một chuỗi duy nhất dùng | để khớp nhiều tool, ví dụ "Edit|Write". Dấu , cũng tương đương từ v2.1.191 trở đi
• Tên tool viết sai chính tả khiến matcher không khớp gì, hook fail âm thầm
• Giá trị dạng array là lỗi schema: Claude Code hiện thông báo lỗi settings và từ chối toàn bộ file user/project/local đó

Sửa settings.json có hiệu lực trong phiên đang chạy sau một khoảng trễ ổn định file ngắn - không cần khởi động lại.

Nếu /hooks vẫn hiện hook nhưng nó không chạy, bước tiếp theo là theo dõi việc đánh giá hook trực tiếp. Khởi động phiên với claude --debug hooks và kích hoạt tool call. Debug log ghi lại từng event, matcher nào được kiểm tra, và exit code/output của hook.

Test với cấu hình sạch

Bắt đầu với claude --safe-mode, khởi động phiên với mọi tuỳ biến bị tắt, gồm CLAUDE.md, skill, plugin, hook, MCP server, và custom command/agent. Xác thực, chọn model, tool có sẵn, và permission vẫn hoạt động bình thường. Nếu vấn đề biến mất ở safe mode, một trong các môi trường trên là nguyên nhân - dùng các kiểm tra ở trên để tìm cái nào. Safe mode vẫn áp dụng managed hook và policy settings từ tổ chức.

Nếu vấn đề vẫn còn ở safe mode, hoặc bản thân settings của bạn đáng ngờ, so sánh với một phiên không nạp gì từ setup thường lệ. Trỏ CLAUDE_CONFIG_DIR vào một thư mục rỗng để bỏ qua mọi thứ dưới ~/.claude, và khởi động từ thư mục không có .claude, .mcp.json, hay CLAUDE.md:

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

Phiên sạch không có user/project settings, hook, MCP server, plugin, hay memory. Lần khởi động đầu tiên sẽ thấy màn hình setup lần đầu, bắt đầu bằng chọn theme.

• Managed settings vẫn áp dụng nếu tổ chức bạn triển khai, vì chúng nằm ở path hệ thống ngoài ~/.claude
• Trên Linux và Windows, bạn sẽ được nhắc đăng nhập lại vì credential lưu dưới config directory
• Trên macOS, credential nằm trong Keychain và vẫn dùng được ở phiên sạch

Nếu vấn đề biến mất ở đây, nguyên nhân nằm đâu đó trong ~/.claude hay .claude của project thật. Đưa lại từng file một để tìm ra cái nào gây vấn đề. Nếu vẫn còn ở phiên sạch, nguyên nhân nằm ngoài cấu hình user/project của bạn - chạy /status để kiểm tra managed settings, tìm environment variable ảnh hưởng Claude Code, rồi xem Khắc phục sự cố.

Kiểm tra các nguyên nhân thường gặp

Hầu hết các bất ngờ về cấu hình đều bắt nguồn từ một số quy tắc vị trí và cú pháp. Kiểm tra các mục này trước khi cho rằng đó là bug:

Triệu chứng	Nguyên nhân	Cách sửa
Hook không bao giờ chạy	matcher là JSON array thay vì string	Dùng một string duy nhất với |, ví dụ "Edit|Write"
Hook không bao giờ chạy	matcher dùng , trên bản trước v2.1.191	Cập nhật Claude Code, hoặc dùng |
Hook không bao giờ chạy	Giá trị matcher viết thường, ví dụ "bash"	Matching phân biệt hoa/thường: Bash, Edit, Write, Read
Hook không bao giờ chạy	Hook định nghĩa trong file riêng thay vì settings.json	Không có file hook riêng cho project/user config - chỉ plugin mới nạp hooks/hooks.json riêng
Permission/hook/env đặt global bị bỏ qua	Cấu hình đặt trong ~/.claude.json	~/.claude.json chứa app state và UI toggle. permissions, hooks, env thuộc ~/.claude/settings.json
Giá trị settings.json như bị bỏ qua	Cùng key đặt trong settings.local.json	settings.local.json override settings.json, cả hai override ~/.claude/settings.json
Skill không xuất hiện trong /skills	File skill ở .claude/skills/name.md thay vì trong folder	Dùng folder có SKILL.md bên trong: .claude/skills/name/SKILL.md
Skill xuất hiện trong /skills nhưng Claude không bao giờ gọi	disable-model-invocation: true trong frontmatter, hoặc mô tả không khớp cách bạn diễn đạt yêu cầu	Kiểm tra badge trong /skills
Chỉ dẫn CLAUDE.md ở thư mục con bị bỏ qua	File thư mục con nạp theo yêu cầu, không phải lúc khởi động	Chúng nạp khi Claude đọc file trong thư mục đó bằng Read tool
Subagent bỏ qua chỉ dẫn CLAUDE.md	Explore và Plan agent tích hợp sẵn bỏ qua CLAUDE.md	Nhắc lại chỉ dẫn quan trọng trong prompt uỷ quyền, hoặc đặt vào body của custom subagent
Logic dọn dẹp không chạy lúc kết thúc phiên	Không có SessionEnd hook	Thêm SessionEnd hook trong settings.json
MCP server trong .mcp.json không bao giờ nạp	File nằm dưới .claude/ hoặc dùng format config của Claude Desktop	Project MCP config đặt ở repository root là .mcp.json, không nằm trong .claude/
MCP server thêm dưới mcpServers trong settings.json không xuất hiện	settings.json không đọc key mcpServers	Định nghĩa server project trong .mcp.json, hoặc claude mcp add --scope user
Project MCP server đã thêm nhưng không xuất hiện	Prompt duyệt một lần bị bỏ qua	Chạy /mcp để xem trạng thái và duyệt
MCP server fail khi khởi động từ một số thư mục	command/args dùng đường dẫn tương đối	Dùng đường dẫn tuyệt đối cho script cục bộ
MCP server khởi động thiếu env var mong đợi	Biến đặt trong env của settings.json, không truyền cho MCP child process	Đặt env riêng cho từng server trong .mcp.json
Bash(rm *) deny rule không chặn /bin/rm hay find -delete	Prefix rule khớp chuỗi lệnh literal, không khớp executable bên dưới	Thêm pattern rõ ràng cho từng biến thể, hoặc dùng PreToolUse hook / sandbox

Nguồn

Dịch và biên soạn từ Debug your configuration.