Thông báo của Claude Code không hoạt động? Checklist khắc phục

011. Kiểm tra xem Claude Code đã load hook chưa

Gõ /hooks tại prompt của Claude Code. Đây là trình xem chỉ-đọc liệt kê mọi hook mà Claude Code đã load, kèm nhãn cho biết nguồn gốc của từng hook: user settings, project settings, local settings, plugin hoặc session hiện tại. Chọn một hook để xem chính xác lệnh và file định nghĩa nó.

Nếu hook của bạn không có trong danh sách:

• JSON không hợp lệ. File settings là JSON nghiêm ngặt. Một dấu phẩy thừa ở cuối hoặc một comment // cũng làm hỏng file, và Claude Code sẽ báo Settings Error ở lần khởi động tiếp theo. Chạy claude doctor để xem những mục bị Claude Code từ chối.
• File đặt sai chỗ. Hook cá nhân nằm trong ~/.claude/settings.json (trên Windows là %USERPROFILE%\.claude\settings.json). Hook của project nằm trong .claude/settings.json bên trong project. Chạy /status và xem dòng Setting sources để biết những file nào đã được load.
• Tên event sai. Tên event phân biệt chữ hoa chữ thường: Notification, Stop, PermissionRequest. Tên event không xác định sẽ hiện Settings Warning và bị bỏ qua.
• Hook đang bị tắt. "disableAllHooks": true trong bất kỳ file settings nào cũng sẽ tắt toàn bộ hook. Nếu /hooks hiển thị Only hooks from managed settings run here, tổ chức của bạn đã bật allowManagedHooksOnly và hook của riêng bạn sẽ không chạy.
• Thay đổi chưa được nhận. Bình thường Claude Code tự reload settings. Nếu sau vài giây hook vẫn chưa xuất hiện, hãy khởi động lại session.

022. Chấp nhận workspace trust

Trong session tương tác, Claude Code sẽ tạm giữ hook từ mọi file settings, kể cả ~/.claude/settings.json của bạn, cho đến khi bạn chấp nhận hộp thoại workspace trust cho thư mục đó. Nếu bạn đã bỏ qua hộp thoại, hoặc đang ở thư mục chưa từng mở Claude Code, hook sẽ không chạy ở đó. Hãy chạy claude trong thư mục đó và chấp nhận hộp thoại.

033. Đảm bảo event kích hoạt đúng lúc bạn nghĩ

Nhiều thông báo "bị hỏng" thực ra chỉ là vấn đề thời điểm. Theo tài liệu tham khảo về hook của Anthropic:

Vì vậy nếu bạn test hook Notification trong lúc vẫn đang gõ trong terminal, có thể nó sẽ không bao giờ kích hoạt. Hãy chuyển sang cửa sổ khác và chờ. Nếu muốn nhận thông báo ngay khi một lượt kết thúc, hãy dùng Stop; xem hướng dẫn về Stop hook.

Hãy kiểm tra cả permission mode. Các phiên bản gần đây của Claude Code khởi động session tương tác ở auto mode, trong đó một classifier tự duyệt hầu hết các thao tác mà không hỏi. Không có prompt thì cũng không có thông báo permission_prompt và không có hook PermissionRequest. Để test thông báo xin quyền, nhấn Shift+Tab cho đến khi thanh trạng thái hiện manual mode, rồi yêu cầu Claude làm việc gì đó cần phê duyệt. Chi tiết có trong Giải thích về permission mode.

Matcher cũng phân biệt chữ hoa chữ thường. Matcher PermissionRequest có giá trị bash sẽ không khớp với tool Bash.

044. Tự chạy lệnh của hook

Copy lệnh từ /hooks và chạy trong terminal với input mẫu:

echo '{"hook_event_name":"Stop","cwd":"/tmp","last_assistant_message":"done"}' | ./my-hook.sh
echo $?

Các lỗi thường gặp:

• command not found: dùng đường dẫn tuyệt đối tới script, hoặc ${CLAUDE_PROJECT_DIR} cho script nằm trong project.
• Script hoàn toàn không làm gì: cấp quyền thực thi bằng chmod +x ./my-hook.sh.
• jq: command not found: cài jq, hoặc parse JSON bằng Python hay Node.js.

055. Đọc debug log

Khởi động Claude Code bằng claude --debug. Terminal sẽ không in thêm gì; log được ghi vào ~/.claude/debug/<session-id>.txt. Để tự chọn đường dẫn, dùng claude --debug-file /tmp/claude.log và chạy tail -f /tmp/claude.log ở một terminal khác. Nếu session đang chạy, /debug sẽ bật logging và cho bạn biết log nằm ở đâu.

Tìm các dòng bắt đầu bằng Hooks:. Mỗi dòng ghi tên event, lệnh, cách nó kết thúc (finished with status 0, timed out, failed to start) và thời gian chạy. Để xem chi tiết hơn về việc so khớp, đặt CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose.

Có hai vấn đề chỉ lộ ra ở đây:

• Shell profile của bạn in ra gì đó. Nếu ~/.bashrc hoặc ~/.zshrc chạy lệnh echo và shell source file đó, đoạn text này sẽ chen vào trước JSON output của hook, và Claude Code sẽ coi output là text thường. Tìm trong log dòng Hook output does not start with {. Bọc phần output của profile trong if [[ $- == *i* ]]; then ... fi để nó chỉ chạy trong shell tương tác.
• Không có terminal để ghi ra. Trên Mac và Linux, command hook chạy mà không có controlling terminal. Hook nào cố rung chuông hoặc ghi escape code vào /dev/tty sẽ thất bại mà không báo lỗi. Hãy dùng lệnh thông báo desktop, hoặc setting preferredNotifChannel có sẵn của Claude Code, được trình bày trong hướng dẫn về terminal bell.

066. Kiểm tra hệ điều hành

Nếu debug log cho thấy hook đã chạy xong với status 0 mà bạn vẫn không thấy gì, thì hệ điều hành đã ẩn thông báo. Hãy kiểm tra xem ứng dụng hiển thị thông báo có được phép hiện notification không, và đảm bảo Focus (Mac), Do not disturb (Windows) hoặc nút chặn làm phiền trên desktop Linux của bạn đang tắt. Trên Linux, cần có một notification daemon đang chạy.

Các lệnh riêng cho từng nền tảng có trong hướng dẫn cho macOS, Windows và Linux.

07Nếu bạn dùng Claude Code Notifier

Claude Code Notifier là một công cụ độc lập (không phải do Anthropic phát triển), cài một chương trình nhỏ tên ccn làm hook cho Claude Code. Mọi điều ở trên vẫn áp dụng, vì ccn cũng chỉ là một hook như bao hook khác. Hãy bắt đầu với các lệnh kiểm tra của nó:

1. ccn doctor kiểm tra hook, thông tin xác thực, kết nối tới server và khả năng phát hiện bạn có đang ở máy hay không. Hãy sửa những lỗi nó báo trước tiên.
2. ccn test gửi một thông báo thử. Nếu nhận được, vấn đề nằm ở sự kiện hoặc cài đặt, không phải ở đường truyền.
3. ccn devices liệt kê các điện thoại đã ghép nối với máy tính này. Nếu không có cái nào, hãy ghép nối lại bằng ccn pair; hướng dẫn ghép nối sẽ chỉ từng bước.
4. ccn config show in ra các cài đặt đang có hiệu lực. Kiểm tra xem notify_on_done, notify_on_permission và notify_on_question đã bật chưa, và quiet_hours có đang bao trùm thời điểm hiện tại không. Cài đặt thay đổi trên điện thoại sẽ được đồng bộ về máy tính bằng ccn sync.

Một vài hành vi trông giống lỗi nhưng thực ra là có chủ đích:

• Bạn đang ngồi trước bàn phím. Nếu bạn gõ phím trong 30 giây gần nhất, sẽ không có gì chờ phản hồi từ điện thoại và terminal hỏi như bình thường. Khi bật quiet_when_present (mặc định), điện thoại sẽ không nhận gì khi bạn đang ở terminal mà Claude đang chạy, và chỉ nhận một thẻ thông tin nếu bạn đang dùng ứng dụng khác.
• Thông báo bị trùng hoặc bị thiếu trên Mac. Đừng chạy cùng lúc ứng dụng menu bar cũ trên Mac và ccn trên cùng một máy Mac.
• Lâu ngày không dùng. Nếu một điện thoại hoặc máy tính không được dùng trong 60 ngày, server sẽ xoá ghép nối của nó, nên bạn cần ghép nối lại.

Trên điện thoại, hãy kiểm tra xem ứng dụng có được phép gửi thông báo không, và Focus (iPhone) hoặc Do Not Disturb (Android) có đang tắt tiếng nó không. Trên Android, tính năng tối ưu pin có thể làm trễ thông báo của một số ứng dụng; nếu thông báo đến muộn, hãy cho phép ứng dụng chạy không giới hạn trong phần cài đặt pin. Nếu bạn đã sửa settings.json bằng tay, ccn doctor sẽ cho biết các hook của nó còn nguyên không. ccn upgrade cập nhật lên bản mới nhất.

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