Thông báo tích hợp sẵn của Claude Code: terminal bell và preferredNotifChannel

01Cách khắc phục nhanh

Nếu bạn không nghe thấy gì khi Claude làm xong, hãy thêm đoạn này vào ~/.claude/settings.json:

{
  "preferredNotifChannel": "terminal_bell"
}

Sau đó đảm bảo terminal của bạn có phản ứng với bell: phát âm thanh, nảy biểu tượng trên Dock, nháy tab hoặc hiện thông báo. Thiết lập này nằm trong terminal, không phải trong Claude Code. Trên Mac, Windows và Linux, hầu hết terminal đều có mục "bell" hoặc "alert" trong phần cài đặt.

02Tất cả giá trị của preferredNotifChannel

Setting này có thể đặt trong bất kỳ file settings nào: user (~/.claude/settings.json), project (.claude/settings.json) hoặc local (.claude/settings.local.json). Các phiên bản cũ lưu nó trong ~/.claude.json, và Claude Code vẫn đọc giá trị còn sót lại ở đó.

03Khi nào thông báo tích hợp sẵn được kích hoạt

Theo tài liệu của Anthropic, cảnh báo tích hợp sẵn có cùng thời điểm kích hoạt với hook Notification. Trong một phiên terminal:

• Permission prompt: sau khi prompt đã chờ khoảng sáu giây mà không có phím nào được bấm. Mỗi lần bạn bấm phím, thời gian chờ được tính lại.
• Làm xong: khoảng 60 giây sau khi Claude dừng, và chỉ khi từ lúc đó bạn chưa gõ gì và không còn background agent nào đang chạy.

Vì vậy cảnh báo "làm xong" tích hợp sẵn được cố ý thiết kế không tức thì. Nó nhằm báo cho bạn khi bạn đã rời đi, chứ không phải ping bạn khi bạn đang theo dõi. Nếu muốn được báo ngay khi một lượt kết thúc, hãy dùng hook Stop (xem hướng dẫn về Stop hook).

04Theo từng terminal

iTerm2 (macOS)

iTerm2 nhận desktop notification theo mặc định, nhưng iTerm2 chỉ hiển thị sau khi bạn cho phép:

1. Mở Settings > Profiles > Terminal.
2. Chọn Notification Center Alerts.
3. Bấm Filter Alerts và bật Send escape sequence-generated alerts.

Đồng thời kiểm tra xem iTerm2 đã được phép hiển thị thông báo trong System Settings > Notifications chưa.

Apple Terminal (macOS)

Apple Terminal không nhận desktop notification. Với "auto", Claude Code chỉ gửi bell im lặng khi thấy Audible bell đang tắt trong profile của cửa sổ phía trước. Khi đó bell hiện thành cửa sổ nháy sáng, hoặc biểu tượng nảy trên Dock khi Terminal chạy nền, nếu tùy chọn Visual bell hoặc nảy Dock của profile đang bật.

Lưu ý một chi tiết. Nếu bạn đã chấp nhận prompt thiết lập terminal ở lần chạy đầu của Claude Code, nó đã chạy /terminal-setup, lệnh này tắt audible bell trong profile Apple Terminal của bạn. Để nghe được âm thanh, hãy đặt "terminal_bell" và bật lại Audible bell trong Settings > Profiles > Advanced.

Ghostty và Kitty (macOS và Linux)

Cả hai đều nhận desktop notification mà không cần thiết lập, và đều chuyển tiếp nó tới trung tâm thông báo của hệ điều hành.

Các terminal khác

Windows Terminal, GNOME Terminal, Konsole, Alacritty, WezTerm, Warp và terminal trong IDE mặc định không nhận được gì. Hãy đặt "terminal_bell" rồi bật xử lý bell của chính terminal đó, hoặc dùng hook. Terminal trong IDE có những điểm riêng, được trình bày trong hướng dẫn cho VS Code, Cursor và JetBrains.

05Qua SSH và trong tmux

Thông báo desktop là một escape sequence do terminal trên máy của bạn diễn giải, nên nó vẫn đến được với bạn kể cả khi Claude Code chạy trên server từ xa qua SSH. Ghostty và Kitty chuyển tiếp nó mà không cần cấu hình thêm. iTerm2 cần các thiết lập alert ở trên.

Trong tmux, sequence này bị nuốt mất trừ khi bạn cho phép passthrough. Thêm đoạn sau vào ~/.tmux.conf rồi chạy tmux source-file ~/.tmux.conf:

set -g allow-passthrough on

Session bị detach là chuyện khác: nếu không có terminal nào được attach thì chẳng có gì hiển thị được alert. Xem hướng dẫn tmux và thông báo qua SSH.

06Kết hợp alert tích hợp sẵn với hook

Hook Notification chạy song song với alert tích hợp sẵn, không thay thế nó. Tài liệu của Anthropic nói rõ hook vẫn chạy ngay cả khi đặt "notifications_disabled": thiết lập này chỉ thay đổi cách Claude Code báo cho bạn, chứ không quyết định hook có chạy hay không. Nhờ vậy bạn có thể chia rõ ràng:

• Giữ "auto" hoặc "terminal_bell" để nhận alert khi ngồi tại bàn.
• Thêm hook cho mọi thứ khác, như âm thanh hệ thống, thông báo desktop trong terminal vốn không có, hoặc push về điện thoại với ntfy.
• Nếu hook đã hiển thị thông báo desktop, hãy đặt "notifications_disabled" để tránh thấy hai thông báo.

Ví dụ, đoạn sau phát một âm thanh trên macOS mỗi khi Claude cần bạn chú ý, trong bất kỳ terminal nào:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]
      }
    ]
  }
}

Phiên bản tương đương cho Linux và Windows có trong hướng dẫn Linux và hướng dẫn Windows.

07Giới hạn của các tùy chọn tích hợp sẵn

• Chỉ ở trên máy tính. Bell hay thông báo đến từ terminal trên màn hình của bạn. Đi xuống bếp là bạn bỏ lỡ.
• Phụ thuộc vào terminal. Nhiều terminal phổ biến không nhận được gì cho đến khi bạn đổi thiết lập.
• Bạn không thể trả lời nó. Nó chỉ báo Claude đang chờ; bạn vẫn phải quay lại bàn phím.

Remote Control của Anthropic, cùng với ứng dụng di động Claude, là cách chính thức để nhận push trên điện thoại. Bài so sánh đặt nó cạnh các lựa chọn khác.

08Claude Code Notifier nằm ở đâu trong bức tranh này

Nếu bạn làm việc tại bàn, alert tích hợp sẵn cộng với "terminal_bell" có thể là đủ. Claude Code Notifier dành cho lúc bạn không ngồi tại bàn. Công cụ dòng lệnh của nó, ccn, chạy như một hook của Claude Code, nên hoạt động trong mọi terminal trên Mac, Windows và Linux, dù có thiết lập bell hay không. Riêng nó đã hiển thị thông báo desktop khi Claude làm xong, cần cấp quyền hoặc đặt câu hỏi. Khi đã ghép nối điện thoại, bạn có thể cho phép hoặc từ chối quyền, trả lời câu hỏi của Claude và gửi chỉ dẫn tiếp theo ngay từ điện thoại; còn nếu bạn vừa gõ phím trong 30 giây gần nhất thì sẽ không có gì chờ trên điện thoại cả. Xem trang ccn.

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