Tóm tắt nhanh: Hook của Claude Code là các tập lệnh tự động hóa thực thi tại các điểm vòng đời cụ thể trong các phiên lập trình AI, cho phép các nhà phát triển chạy các lệnh tùy chỉnh, xác thực hành động, định dạng mã, gửi thông báo và thực thi các quy tắc dự án. Các hook này tích hợp với quy trình làm việc của Claude thông qua các sự kiện như SessionStart, PreToolUse và PostToolUse, hỗ trợ các mẫu thực thi dựa trên lệnh, dựa trên HTTP và dựa trên lời nhắc với thời gian chờ có thể cấu hình và hành vi mã thoát.
Hệ thống hook của Claude Code biến trợ lý lập trình AI từ một công cụ hữu ích thành một môi trường phát triển được tự động hóa hoàn toàn. Hầu hết các nhà phát triển không nhận ra mức độ kiểm soát có sẵn thông qua các hook.
Đây là vấn đề - các hook không chỉ là chạy tập lệnh sau khi chỉnh sửa tệp. Chúng cung cấp các điểm chặn trong toàn bộ quy trình ra quyết định của Claude. Trước khi thực thi một lệnh. Sau khi cuộc gọi công cụ thất bại. Khi nó cần sự cho phép. Thậm chí trước khi xử lý các lời nhắc của người dùng.
Hướng dẫn này bao gồm mọi thứ mà tài liệu chính thức cung cấp, cộng với các mẫu thực tế mà các cuộc thảo luận cộng đồng tiết lộ là hoạt động trong môi trường sản xuất.
Hook Claude Code Thực sự làm gì
Theo tài liệu chính thức của Claude Code, các hook là các lệnh shell do người dùng xác định, các điểm cuối HTTP hoặc các lời nhắc được chèn thực thi tại các điểm cụ thể trong vòng đời của Claude Code. Chúng nhận đầu vào JSON có cấu trúc qua stdin và kiểm soát quy trình làm việc thông qua mã thoát hoặc phản hồi HTTP.
Tự động hóa đi sâu hơn hầu hết các hướng dẫn gợi ý. Các hook có thể chặn hoàn toàn việc thực thi công cụ, chèn ngữ cảnh bổ sung vào quá trình suy luận của Claude, kích hoạt các dịch vụ bên ngoài và thực thi các quy tắc xác thực mà Claude phải tuân thủ.
Có ba loại hook cốt lõi:
- Hook lệnh: Các tập lệnh shell giao tiếp qua stdout, stderr và mã thoát
- Hook HTTP: Các điểm cuối từ xa nhận yêu cầu POST và trả về phản hồi JSON
- Hook lời nhắc: Các hướng dẫn động được chèn vào ngữ cảnh của Claude tại các sự kiện cụ thể
Mỗi loại phục vụ các mẫu tự động hóa khác nhau. Hook lệnh xử lý xác thực và định dạng cục bộ. Hook HTTP tích hợp với các dịch vụ và cơ sở dữ liệu bên ngoài. Hook lời nhắc sửa đổi hành vi của Claude mà không cần các quy trình bên ngoài.
Vòng đời Hook và Hệ thống Sự kiện
Tài liệu chính thức xác định nhiều sự kiện hook (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification, và các sự kiện khác) được kích hoạt trong luồng thực thi của Claude Code. Hiểu được thời điểm mỗi sự kiện được kích hoạt sẽ xác định khả năng tự động hóa.
| Sự kiện | Thời điểm kích hoạt | Có thể chặn |
|---|---|---|
| SessionStart | Khi một phiên bắt đầu hoặc tiếp tục | Không |
| UserPromptSubmit | Khi bạn gửi lời nhắc, trước khi Claude xử lý nó | Có |
| PreToolUse | Trước khi lệnh gọi công cụ thực thi | Có |
| PermissionRequest | Khi hộp thoại xin phép xuất hiện | Có |
| PostToolUse | Sau khi lệnh gọi công cụ thành công | Không |
| PostToolUseFailure | Sau khi lệnh gọi công cụ thất bại | Không |
| Notification | Khi Claude Code gửi thông báo | Không |
| SubmitMessage | Khi Claude gửi tin nhắn cho người dùng | Không |
| ContextCompaction | Khi cửa sổ ngữ cảnh gần đạt giới hạn | Không |
Khả năng chặn là quan trọng nhất. Hook PreToolUse có thể ngăn chặn các thao tác nguy hiểm trước khi chúng được thực thi. Mã thoát 1 sẽ chặn hành động. Mã thoát 0 cho phép nó. Mã thoát 2 yêu cầu Claude xem xét lại.
Nhưng chờ đã. Hook PostToolUse không thể hoàn tác các hành động vì công cụ đã được thực thi. Hạn chế này định hình cách cấu trúc logic xác thực. Các kiểm tra quan trọng thuộc về PreToolUse. Việc dọn dẹp và định dạng thuộc về PostToolUse.
Duyệt Ưu đãi Công cụ AI khi Thiết lập Claude Code
Nếu bạn đang làm việc với các hook của Claude Code, bạn có thể cũng đang chọn các công cụ AI khác xung quanh quy trình làm việc của mình. Get AI Perks thu thập các khoản tín dụng khởi động và giảm giá phần mềm cho các công cụ AI và đám mây ở một nơi. Nền tảng này bao gồm hơn 200 ưu đãi, với các điều kiện ưu đãi và hướng dẫn yêu cầu cho từng ưu đãi.
Tìm kiếm Ưu đãi Claude hoặc Công cụ AI khác?
Kiểm tra Get AI Perks để:
- duyệt ưu đãi Claude và các công cụ AI khác
- so sánh các điều kiện ưu đãi trước khi đăng ký
- tìm ưu đãi khởi nghiệp trên toàn bộ ngăn xếp công cụ của bạn
👉 Truy cập Get AI Perks để khám phá các ưu đãi phần mềm AI hiện tại.
Cấu hình và Cấu trúc Tệp
Các hook được xác định trong tệp .claude/settings.json trong một dự án. Lược đồ cấu hình hỗ trợ các hook toàn cục và các trình so khớp dành riêng cho công cụ để lọc khi các hook thực thi.
Cấu trúc hook lệnh cơ bản:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
Biến ${file} sẽ mở rộng thành đường dẫn tệp thực tế từ đầu vào công cụ. Theo tài liệu chính thức, các hook hỗ trợ các phép mở rộng biến này trong các trường lệnh và đối số.
Thứ bậc Vị trí Hook
Claude Code kiểm tra nhiều vị trí cho các định nghĩa hook, với thứ tự ưu tiên rõ ràng:
- Cấp dự án: .claude/settings.json trong không gian làm việc hiện tại
- Cấp người dùng: ~/.claude/settings.json cho tất cả các phiên
- Do plugin cung cấp: Các hook được đóng gói với các plugin đã cài đặt
Các hook dự án ghi đè các hook người dùng cho cùng một sự kiện. Điều này cho phép các quy tắc định dạng dành riêng cho dự án đồng thời duy trì các trình xử lý thông báo toàn cục.
Mẫu Đối sánh để Thực thi Chọn lọc
Hệ thống đối sánh lọc các hook cho các công cụ hoặc điều kiện cụ thể. Nếu không có trình đối sánh, các hook sẽ được kích hoạt cho mỗi lần xảy ra sự kiện của chúng.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
Trường pathPattern chấp nhận cú pháp glob. Trường toolName khớp với các công cụ tích hợp sẵn của Claude như edit_file, execute_command, read_file và create_directory.
Các cuộc thảo luận cộng đồng tiết lộ rằng sự kết hợp của các trình đối sánh hoạt động với logic AND. Tất cả các trình đối sánh được chỉ định phải khớp để hook được thực thi.
Hook Lệnh: Tích hợp Tập lệnh Shell
Hook lệnh thực thi các lệnh hoặc tập lệnh shell với đầu vào JSON có cấu trúc. Chúng đại diện cho loại hook phổ biến nhất cho tự động hóa cục bộ.
Tài liệu chính thức quy định rằng hook lệnh nhận JSON qua stdin với cấu trúc này:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Scripts parse this input to make decisions. A Python validation hook might look like:#!/usr/bin/env python3 import sys import json input_data = json.load(sys.stdin) tool_input = input_data.get(‘toolInput’, {}) file_path = tool_input.get(‘path’, ”) if file_path.startswith(‘protected/’): print(“Cannot edit protected files”, file=sys.stderr) sys.exit(1) sys.exit(0) |
Mã thoát 0 cho phép thao tác. Mã thoát 1 chặn nó và hiển thị thông báo stderr cho Claude. Mã thoát 2 kích hoạt hành vi đặc biệt tùy thuộc vào sự kiện.
Hành vi Mã thoát 2
Theo tài liệu tham khảo hook chính thức, mã thoát 2 có ý nghĩa cụ thể theo sự kiện (PreToolUse: chặn và yêu cầu xem xét lại; UserPromptSubmit: cung cấp ngữ cảnh mà không chặn; PermissionRequest: chặn yêu cầu phép):
- PreToolUse: Chặn công cụ và yêu cầu Claude xem xét lại với thông báo stderr làm ngữ cảnh
- UserPromptSubmit: Cung cấp đầu ra stderr làm ngữ cảnh bổ sung mà không chặn
- PermissionRequest: Chặn việc cấp phép
Điều này tạo ra một vùng trung gian giữa việc chặn cứng và cho phép. Claude nhận phản hồi về lý do tại sao hành động có thể có vấn đề và có thể điều chỉnh cách tiếp cận của nó.
Hook Lệnh Bất đồng bộ
Cờ async: true chạy các hook ở chế độ nền mà không chặn quy trình làm việc của Claude. Điều này quan trọng đối với các hoạt động chậm như thông báo triển khai hoặc thu thập số liệu.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Khi một hook không đồng bộ được kích hoạt, Claude Code sẽ bắt đầu quy trình và tiếp tục ngay lập tức. Trường timeout đặt thời gian thực thi tối đa bằng giây. Nếu không được chỉ định, các hook không đồng bộ sẽ sử dụng thời gian chờ mặc định 10 phút.
Thực tế: các hook không đồng bộ không thể chặn các thao tác vì chúng chạy sau khi Claude tiếp tục. Chúng hoạt động để ghi nhật ký, thông báo và dọn dẹp - không phải để xác thực.
Hook HTTP: Tích hợp Dịch vụ Bên ngoài
Hook HTTP gửi tải trọng JSON đến các điểm cuối từ xa và phân tích cú pháp phản hồi để kiểm soát quyết định. Chúng cho phép tích hợp với các dịch vụ xác thực, cơ sở dữ liệu và công cụ của bên thứ ba.
Cấu hình hook HTTP cơ bản:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
Cấu trúc tải trọng khớp với đầu vào hook lệnh nhưng đến dưới dạng thân của yêu cầu POST HTTP. Phản hồi sẽ xác định hành động tiếp theo của Claude.
Xử lý Phản hồi HTTP
Theo tài liệu chính thức, hook HTTP diễn giải các phản hồi dựa trên mã trạng thái và nội dung thân:
| Mã trạng thái | Hiệu ứng | Nguồn thông báo |
|---|---|---|
| 200 | Cho phép thao tác | Thân phản hồi (tùy chọn) |
| 400 | Chặn thao tác | Thân phản hồi hiển thị cho Claude |
| 500 | Lỗi hook, cho phép thao tác | Đã ghi nhật ký nhưng không hiển thị cho Claude |
| Khác | Cho phép thao tác | Lỗi hook không chặn quy trình làm việc |
Thân phản hồi có thể bao gồm trường thông báo mà Claude nhìn thấy làm ngữ cảnh. Điều này cho phép các dịch vụ xác thực giải thích lý do tại sao một thao tác bị chặn.
Nội suy Biến Môi trường
Hook HTTP hỗ trợ cú pháp ${VAR} trong url, headers và các trường chuỗi khác. Các biến được nội suy từ môi trường mà Claude Code chạy.
Theo tài liệu chính thức về MCP, phép nội suy biến môi trường bao gồm cú pháp dự phòng mặc định: ${VAR:-default} sẽ nội suy VAR nếu được đặt, nếu không sẽ sử dụng giá trị mặc định.
Hạn chế bảo mật: Theo yêu cầu tính năng trên GitHub #28044, hook HTTP chỉ có thể truy cập các biến môi trường được liệt kê rõ ràng trong trường cấu hình allowedEnvVars. Điều này ngăn chặn việc lộ thông tin xác thực không mong muốn.
Hook Lời nhắc: Chèn Ngữ cảnh
Hook lời nhắc chèn các hướng dẫn động vào ngữ cảnh của Claude tại các sự kiện cụ thể. Chúng sửa đổi hành vi mà không cần các quy trình hoặc lệnh gọi API bên ngoài.
| { “event”: “SessionStart”, “prompt”: “Bạn đang làm việc trên một dự án TypeScript. Luôn sử dụng kiểm tra null nghiêm ngặt và ưu tiên async/await hơn promises.” } |
Văn bản được chèn trở thành một phần của hướng dẫn hệ thống của Claude cho phiên đó. Hook lời nhắc cũng có thể sử dụng các biến mẫu nội suy dựa trên dữ liệu sự kiện.
Tạo Lời nhắc Động
Theo tài liệu chính thức, hook lời nhắc hỗ trợ các trường lệnh tạo lời nhắc động:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Lệnh nhận đầu vào JSON tiêu chuẩn qua stdin và xuất văn bản lời nhắc ra stdout. Điều này cho phép tạo hướng dẫn nhận biết ngữ cảnh dựa trên trạng thái dự án.
Hook Dựa trên Tác nhân
Hook tác nhân chỉ định một tác nhân con xử lý sự kiện thay vì chèn lời nhắc trực tiếp. Tác nhân con nhận ngữ cảnh về sự kiện và có thể thực hiện suy luận nhiều bước.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Một lệnh gọi công cụ đã thất bại. Phân tích lỗi và đề xuất các bản sửa lỗi.” } |
Tác nhân con được đặt tên phải được xác định trong cấu hình dự án. Hook tác nhân cho phép logic quyết định phức tạp mà việc chèn lời nhắc đơn giản không thể cung cấp.
Các Mẫu Hook Thực tế
Các cuộc thảo luận cộng đồng và các ví dụ chính thức tiết lộ các mẫu tự động hóa cụ thể hoạt động đáng tin cậy trong sản xuất.
Tự động định dạng Mã sau khi Chỉnh sửa
Mẫu phổ biến nhất tự động định dạng mã sau khi Claude chỉnh sửa tệp:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
Biến ${toolInput.path} sẽ mở rộng thành đường dẫn tệp đã được chỉnh sửa. PostToolUse đảm bảo định dạng xảy ra sau các chỉnh sửa thành công nhưng không chặn quy trình làm việc của Claude.
Chặn Sửa đổi Tệp Bảo vệ
Hook PreToolUse thực thi các quy tắc bảo vệ tệp:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Tập lệnh xác thực đường dẫn đích so với các mẫu được bảo vệ và thoát với mã 1 để chặn các lần chỉnh sửa bị cấm.
Nhận Thông báo Khi Claude Cần Đầu vào
Theo hướng dẫn quy trình làm việc chính thức, Hook Thông báo có thể kích hoạt cảnh báo trên màn hình hoặc gửi tin nhắn đến các dịch vụ bên ngoài:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Điều này được kích hoạt bất cứ khi nào Claude Code gửi thông báo, bao gồm cả khi chờ đầu vào của người dùng hoặc sau khi hoàn thành tác vụ.
Chèn lại Ngữ cảnh sau Khi Nén
Hook ContextCompaction khôi phục ngữ cảnh quan trọng khi cửa sổ hội thoại đầy:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
Đầu ra của lệnh được chèn trở lại vào ngữ cảnh của Claude sau khi nén xóa các tin nhắn cũ hơn. Điều này ngăn chặn việc mất các hướng dẫn quan trọng dành riêng cho dự án.
Kiểm toán Thay đổi Cấu hình
Theo dõi khi Claude sửa đổi các tệp cấu hình:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Thực thi bất đồng bộ ngăn Claude bị chặn trong khi các thao tác git hoàn tất. Điều này tạo ra một dấu vết kiểm toán các thay đổi cấu hình mà không cần chuẩn bị thủ công.
Đầu ra JSON và Kiểm soát Quyết định
Hook lệnh có thể xuất JSON có cấu trúc để cung cấp phản hồi chi tiết hơn ngoài mã thoát đơn giản. Theo tài liệu tham khảo chính thức, đầu ra JSON cho phép các phản hồi đa trường mà Claude diễn giải để ra quyết định.
| { “allowed”: false, “message”: “Tệp này được bảo vệ bởi chính sách nhóm”, “suggestion”: “Tạo một tệp mới trong src/features/ thay thế” } |
Trường allowed kiểm soát việc thao tác có được phép tiếp tục hay không. Thông báo hiển thị cho Claude làm ngữ cảnh. Trường gợi ý cung cấp các phương pháp thay thế.
Để hook xuất JSON, chúng phải:
- Ghi JSON hợp lệ ra stdout
- Thoát với mã 0 (cho phép) hoặc 1 (cho phép chặn)
- Bao gồm ít nhất trường boolean cho phép
Claude Code phân tích cú pháp JSON và sử dụng nó để nâng cao vòng lặp phản hồi. Mã thoát vẫn xác định quyết định chính, nhưng JSON cung cấp ngữ cảnh phong phú hơn.
Tham chiếu Trường Đầu vào Hook
Tất cả các hook đều nhận một đối tượng JSON qua stdin với các trường chung cộng với dữ liệu cụ thể của sự kiện. Hiểu lược đồ đầy đủ cho phép logic hook phức tạp hơn.
Trường đầu vào Chung
Mọi hook đều nhận được các trường cơ sở này:
- event: Tên sự kiện hook (ví dụ: "PreToolUse")
- sessionId: Mã định danh duy nhất cho phiên Claude hiện tại
- turnId: Mã định danh cho lượt đàm thoại hiện tại
- timestamp: Dấu thời gian ISO 8601 khi sự kiện được kích hoạt
Trường Sự kiện Công cụ
Các sự kiện PreToolUse, PostToolUse và PostToolUseFailure bao gồm:
- toolName: Tên của công cụ đang được gọi (edit_file, execute_command, v.v.)
- toolInput: Đối tượng chứa các tham số đầu vào của công cụ
- toolResponse: Dữ liệu đầu ra của công cụ (chỉ PostToolUse)
- error: Chi tiết lỗi bao gồm thông báo và mã (chỉ PostToolUseFailure)
Cấu trúc toolInput thay đổi tùy theo công cụ. Đối với edit_file, nó chứa đường dẫn và nội dung. Đối với execute_command, nó chứa lệnh và các đối số.
Trường Sự kiện Quyền
Các sự kiện PermissionRequest bao gồm:
- permissionType: Loại quyền được yêu cầu (file_write, command_execute, v.v.)
- requestedAction: Hành động cụ thể yêu cầu quyền
- resourcePath: Đường dẫn tệp hoặc mã định danh tài nguyên bị ảnh hưởng
Hook Công cụ MCP
Theo tài liệu tham khảo hook chính thức, các hook có thể khớp với các công cụ Giao thức Ngữ cảnh Mô hình (MCP) bằng trường trình đối sánh mcpTool. Điều này cho phép thực thi hook khi Claude sử dụng các công cụ bên ngoài do máy chủ MCP cung cấp.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
Giá trị mcpTool khớp với tên công cụ theo định dạng tên máy chủ/tên công cụ. Điều này cho phép logic xác thực cho các truy vấn cơ sở dữ liệu, lệnh gọi API hoặc các hoạt động bên ngoài khác.
Các yêu cầu tính năng trên GitHub cho thấy sự quan tâm ngày càng tăng đến việc tích hợp MCP sâu hơn, bao gồm cả các hook có thể kiểm tra thông báo của máy chủ MCP và phản hồi các sự kiện bên ngoài.
Cân nhắc Bảo mật
Các hook thực thi với cùng quyền như Claude Code. Điều này tạo ra các vấn đề bảo mật cho môi trường đa người dùng và cấu hình chia sẻ.
Sandbox Thực thi Lệnh
Theo yêu cầu tính năng trên GitHub #28044, hook HTTP được định tuyến qua một proxy sandbox hạn chế truy cập mạng và lọc các biến môi trường. Hook lệnh không có các hạn chế như vậy - chúng chạy với quyền truy cập shell đầy đủ.
Tài liệu khuyến nghị các phương pháp sau:
- Không bao giờ lưu thông tin xác thực trong các lệnh hook
- Sử dụng biến môi trường cho dữ liệu nhạy cảm
- Xác thực tất cả đầu vào từ phép nội suy ${…}
- Triển khai giới hạn thời gian chờ cho các dịch vụ bên ngoài
- Sử dụng hook không đồng bộ cho các hoạt động không quan trọng để ngăn chặn việc chặn khi xảy ra lỗi
Cô lập Thực thi Hook
Các hook cấp người dùng trong ~/.claude/settings.json áp dụng cho tất cả các dự án. Điều này tạo ra rủi ro khi làm việc với các ranh giới tin cậy khác nhau. Các hook cấp dự án ghi đè các hook người dùng nhưng không thể vô hiệu hóa hoàn toàn chúng.
Menu /hooks trong Claude Code hiển thị tất cả các hook đang hoạt động cho phiên hiện tại. Xem xét danh sách này trước khi làm việc trên các dự án nhạy cảm giúp xác định các mối quan tâm bảo mật tiềm ẩn.
Gỡ lỗi và Xử lý sự cố
Lỗi hook không phải lúc nào cũng hiển thị rõ ràng trong cuộc trò chuyện của Claude. Tài liệu chính thức cung cấp một số phương pháp gỡ lỗi.
Nhật ký Thực thi Hook
Claude Code ghi nhật ký thực thi hook vào đầu ra gỡ lỗi của phiên. Theo hướng dẫn xử lý sự cố, việc bật ghi nhật ký gỡ lỗi sẽ hiển thị:
- Những hook nào đã khớp cho mỗi sự kiện
- Đầu vào JSON được gửi đến mỗi hook
- Đầu ra stdout và stderr từ các quy trình hook
- Mã thoát và thời gian thực thi
- Mã trạng thái và thân phản hồi HTTP cho hook HTTP
Bật ghi nhật ký gỡ lỗi bằng cách đặt CLAUDE_DEBUG=1 trong môi trường trước khi khởi động Claude Code.
Kiểm tra Hook Độc lập
Hook lệnh có thể được kiểm tra bên ngoài Claude Code bằng cách xây dựng thủ công đầu vào JSON:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Điều này xác thực logic hook mà không kích hoạt các thao tác Claude thực tế. Mã thoát và đầu ra stdout/stderr phải khớp với hành vi mong đợi.
Lỗi Hook Phổ biến
Các cuộc thảo luận cộng đồng xác định các vấn đề thường gặp sau:
- Lỗi hết thời gian chờ: Thời gian chờ mặc định 10 phút quá ngắn cho các hoạt động chậm - tăng bằng trường timeout
- Lỗi mở rộng đường dẫn: Các biến như ${file} không được xác định cho các sự kiện không bao gồm ngữ cảnh tệp
- Lỗi quyền: Tập lệnh hook thiếu quyền thực thi - chạy chmod +x script.sh
- Lỗi phân tích cú pháp JSON: Đầu ra JSON bị lỗi từ hook - xác thực bằng jq trước khi trả về
- Biến môi trường không khả dụng: Biến không được truyền đến quy trình hook - kiểm tra môi trường của Claude Code
Ảnh hưởng Hiệu suất Hook
Hook đồng bộ chặn quy trình làm việc của Claude cho đến khi hoàn thành. Thời gian chờ mặc định 10 phút ngăn chặn treo vô thời hạn, nhưng ngay cả sự chậm trễ ngắn cũng tích lũy qua nhiều hoạt động.
Các chuyên gia báo cáo rằng các hook xác thực đơn giản có tác động hiệu suất không đáng kể. Hook định dạng tệp gây ra tác động hiệu suất có thể nhận thấy nhưng có thể chấp nhận được. Các lệnh gọi API bên ngoài có thể tạo ra xung đột quy trình làm việc. Các hoạt động tính toán nặng hưởng lợi từ việc thực thi không đồng bộ.
Gom nhóm Hook
Nhiều hook có thể khớp với cùng một sự kiện. Theo tài liệu tham khảo, các hook thực thi tuần tự theo thứ tự định nghĩa. Nếu bất kỳ hook nào chặn thao tác, các hook còn lại sẽ không thực thi.
Điều này quan trọng đối với hiệu suất. Năm hook đồng bộ, mỗi hook 200ms, sẽ thêm một giây cho mỗi sự kiện. Kết hợp các xác thực liên quan vào một hook duy nhất sẽ giảm chi phí.
Các Mẫu Nâng cao
Ngoài tự động hóa cơ bản, các hook cho phép tùy chỉnh quy trình làm việc phức tạp.
Chuỗi Hook có Trạng thái
Hook có thể duy trì trạng thái giữa các lần thực thi bằng cách sử dụng tệp hoặc cơ sở dữ liệu. Hook PostToolUse có thể ghi lại các hoạt động thành công mà hook PreToolUse sau đó xác thực so với:
| #!/bin/bash # Record successful edits echo “${toolInput.path}” >> .claude/edit-history.txt |
Một hook PreToolUse đi kèm có thể kiểm tra lịch sử này để ngăn chặn các thao tác trùng lặp hoặc thực thi các ràng buộc về thứ tự.
Kích hoạt Hook Có điều kiện
Các biến môi trường kiểm soát hành vi của hook tại thời gian chạy. Đặt CLAUDE_SKIP_HOOKS=1 sẽ vô hiệu hóa các hook cho các tình huống khẩn cấp.
Bản thân các hook có thể kiểm tra các cờ môi trường:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Apply strict validation exit 1 fi exit 0 |
Điều này cho phép hành vi chế độ phát triển so với chế độ sản xuất mà không cần thay đổi cấu hình.
Xác thực Đa giai đoạn
Hook PreToolUse có thể triển khai xác thực nhiều cấp, trong đó mã thoát 2 cho phép Claude tiếp tục với cảnh báo:
- Lỗi nghiêm trọng (mã thoát 1): Chặn các thao tác nguy hiểm
- Cảnh báo mềm (mã thoát 2): Cảnh báo Claude xem xét lại
- Thành công với ngữ cảnh (mã thoát 0 + JSON): Cung cấp thông tin bổ sung
Điều này tạo ra một phổ xác thực phức tạp hơn so với việc cho phép/từ chối nhị phân.
Tích hợp với CI/CD
Theo tài liệu tích hợp nền tảng chính thức, Claude Code chạy trong môi trường CI/CD để tự động xem xét mã và phân loại sự cố. Các hook mở rộng tự động hóa này.
Các quy trình GitHub Actions có thể xác định các hook thực thi các chính sách nhóm trong các phiên tự động:
| – name: Run Claude Code with strict hooks env: STRICT_MODE: 1 run: | claude “Review this PR and suggest improvements” |
Cờ STRICT_MODE kích hoạt logic xác thực có điều kiện trong các tập lệnh hook. Điều này đảm bảo các phiên tự động tuân theo các quy tắc nghiêm ngặt hơn so với phát triển tương tác.
Tạo Dấu vết Kiểm toán
Hook PostToolUse trong môi trường CI tạo nhật ký kiểm toán chi tiết về tất cả các hoạt động của Claude:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Việc ghi nhật ký nền không ảnh hưởng đến hiệu suất nhưng cung cấp lịch sử hoạt động đầy đủ để tuân thủ và gỡ lỗi.
Menu /hooks
Claude Code cung cấp lệnh /hooks hiển thị tất cả các hook đang hoạt động cho phiên hiện tại. Theo tài liệu chính thức, menu này hiển thị:
- Loại sự kiện hook
- Các mẫu đối sánh
- Điểm cuối lệnh hoặc URL
- Liệu hook có chạy không đồng bộ
- Nguồn cấu hình (dự án, người dùng hoặc plugin)
Việc chọn một hook sẽ hiển thị cấu hình đầy đủ của nó và cho phép vô hiệu hóa tạm thời cho phiên hiện tại.
Vô hiệu hóa hoặc Xóa Hook
Hook có thể bị vô hiệu hóa mà không cần xóa cấu hình bằng cách thêm "enabled": false vào định nghĩa hook. Điều này bảo toàn cấu hình trong khi ngăn chặn việc thực thi.
Để xóa vĩnh viễn một hook, hãy xóa mục của nó khỏi tệp settings.json tương ứng. Thay đổi có hiệu lực khi khởi động lại phiên tiếp theo hoặc khi chạy /reload.
Hook trong Kỹ năng và Tác nhân
Theo tài liệu chính thức, các hook được xác định trong cấu hình kỹ năng hoặc tác nhân con chỉ áp dụng khi kỹ năng hoặc tác nhân đó thực thi. Điều này cho phép tự động hóa chuyên biệt cho các quy trình làm việc cụ thể.
Một tác nhân con gỡ lỗi có thể bao gồm các hook ghi lại tất cả các lệnh gọi công cụ:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Các hook này chỉ được kích hoạt trong các phiên của tác nhân gỡ lỗi, không phải trong hoạt động Claude Code bình thường.
Tham chiếu Tập lệnh theo Đường dẫn
Các lệnh hook hỗ trợ cả đường dẫn tương đối và tuyệt đối. Đường dẫn tương đối được phân giải từ gốc dự án nơi Claude Code chạy.
Các phương pháp tốt nhất từ các cuộc thảo luận cộng đồng:
- Lưu các tập lệnh hook trong thư mục .claude/hooks/
- Sử dụng tên mô tả: validate-typescript.sh thay vì hook1.sh
- Làm cho tập lệnh có thể thực thi: chmod +x .claude/hooks/*.sh
- Bao gồm dòng shebang: #!/usr/bin/env bash hoặc #!/usr/bin/env python3
- Thêm xử lý lỗi với set -e trong các tập lệnh bash
Khả năng Hook trong Tương lai
Các yêu cầu tính năng trên GitHub tiết lộ các cải tiến hook đã được lên kế hoạch và yêu cầu:
- Hook tập lệnh nội tuyến: Xác định logic hook trực tiếp trong settings.json mà không cần tệp bên ngoài
- Tích hợp công cụ MCP: Gọi các công cụ máy chủ MCP từ hook thay vì lệnh shell
- Hợp tác đa tác nhân: Các hook phối hợp giữa các phiên bản Claude trên các máy khác nhau
- Kiểu nhập liệu nâng cao: Định nghĩa kiểu TypeScript cho lược đồ đầu vào/đầu ra của hook
Theo yêu cầu tính năng trên GitHub #4274, yêu cầu về các loại hook tích hợp (công cụ MCP, tập lệnh nội tuyến, lệnh gọi API) nhằm mục đích đơn giản hóa cấu hình và cải thiện trải nghiệm nhà phát triển.
Câu hỏi Thường gặp
Hook có thể ngăn Claude thực thi các lệnh nguy hiểm không?
Có. Hook PreToolUse có thể chặn bất kỳ lệnh gọi công cụ nào bằng cách thoát với mã 1. Điều này bao gồm việc chỉnh sửa tệp, thực thi lệnh và gọi công cụ MCP. Hook nhận đầu vào công cụ đầy đủ và có thể xác thực dựa trên bất kỳ tiêu chí nào trước khi cho phép thao tác.
Làm cách nào để gỡ lỗi một hook không hoạt động?
Bật ghi nhật ký gỡ lỗi bằng CLAUDE_DEBUG=1 trước khi khởi động Claude Code. Kiểm tra nhật ký phiên để biết chi tiết thực thi hook bao gồm hook nào đã khớp, đầu vào JSON được gửi, đầu ra stdout/stderr và mã thoát. Kiểm tra các hook độc lập bằng cách truyền JSON mẫu cho tập lệnh hook.
Hook có hoạt động với tất cả các nền tảng Claude Code không?
Hook hoạt động trong ứng dụng CLI, ứng dụng desktop và tiện ích mở rộng VS Code. Theo tài liệu chính thức, hook thực thi bất cứ nơi nào Claude Code chạy có quyền truy cập vào hệ thống tệp. Claude dựa trên trình duyệt và ứng dụng di động không hỗ trợ hook do hạn chế về sandbox.
Hook có thể sửa đổi phản hồi hoặc hành vi của Claude không?
Hook lời nhắc chèn các hướng dẫn ảnh hưởng đến hành vi của Claude. Hook tác nhân ủy quyền xử lý sự kiện cho các tác nhân con chuyên biệt. Tuy nhiên, hook không thể sửa đổi trực tiếp văn bản được tạo hoặc quy trình suy luận của Claude - chúng hoạt động bằng cách cung cấp ngữ cảnh và chặn các thao tác.
Sự khác biệt giữa hook không đồng bộ và đồng bộ là gì?
Hook đồng bộ chặn quy trình làm việc của Claude cho đến khi hoàn thành hoặc hết thời gian chờ. Hook không đồng bộ chạy ở chế độ nền mà không chặn. Hook đồng bộ có thể ngăn chặn các thao tác thông qua mã thoát. Hook không đồng bộ không thể chặn vì Claude tiếp tục trước khi hook hoàn thành. Sử dụng không đồng bộ để ghi nhật ký và thông báo, đồng bộ để xác thực.
Làm cách nào để chia sẻ hook trên một nhóm?
Lưu trữ tệp .claude/settings.json vào hệ thống kiểm soát phiên bản. Các hook cấp dự án áp dụng cho tất cả các thành viên nhóm sao chép kho lưu trữ. Đối với các chính sách trên toàn tổ chức, các nhóm có thể duy trì một tệp cài đặt cấp người dùng chung mà các thành viên sao chép vào ~/.claude/settings.json.
Hook HTTP có thể gọi các API nội bộ phía sau tường lửa không?
Có, nếu Claude Code chạy trong môi trường có quyền truy cập mạng đến các API đó. Hook HTTP thực hiện các yêu cầu POST tiêu chuẩn từ máy chạy Claude Code. Tường lửa và VPN của công ty áp dụng bình thường. Proxy sandbox được đề cập trong tài liệu kiểm soát việc hiển thị biến môi trường, không phải định tuyến mạng.
Hook có làm tăng việc sử dụng token của Claude Code không?
Hook lời nhắc chèn văn bản vào ngữ cảnh của Claude, điều này tiêu thụ token. Hook lệnh và HTTP không ảnh hưởng trực tiếp đến việc sử dụng token, nhưng đầu ra của chúng (thông báo lỗi, đề xuất) trở thành một phần của ngữ cảnh hội thoại. Mã thoát 2 với thông báo giải thích thêm ngữ cảnh hơn mã thoát 1 với việc chặn đơn giản.
Kết luận
Hook Claude Code biến trợ lý AI từ một công cụ mạnh mẽ thành một nền tảng phát triển được tự động hóa hoàn toàn. Hệ thống sự kiện cung cấp các điểm chặn trong quy trình làm việc của Claude - từ khởi tạo phiên cho đến nén ngữ cảnh.
Hook lệnh xử lý xác thực và định dạng cục bộ. Hook HTTP tích hợp các dịch vụ và cơ sở dữ liệu bên ngoài. Hook lời nhắc sửa đổi hành vi thông qua việc chèn ngữ cảnh. Cùng nhau, những điều này cho phép các mẫu tự động hóa thực thi các chính sách nhóm, duy trì chất lượng mã và tích hợp với cơ sở hạ tầng phát triển hiện có.
Hệ thống đối sánh lọc các hook cho các công cụ và mẫu tệp cụ thể. Mã thoát và đầu ra JSON kiểm soát luồng quyết định. Thực thi không đồng bộ ngăn chặn việc chặn các hoạt động chậm. Lược đồ cấu hình đầy đủ hỗ trợ mọi thứ từ định dạng tự động đơn giản đến xác thực đa giai đoạn phức tạp.
Bắt đầu với các hook PostToolUse cơ bản để định dạng mã. Thêm xác thực PreToolUse khi các chính sách xuất hiện. Thử nghiệm với các hook lời nhắc để sửa đổi hành vi. Xây dựng các tích hợp HTTP để thực thi trên toàn nhóm.
Kiểm tra tài liệu chính thức của Claude Code để biết tài liệu tham khảo hook đầy đủ và lược đồ cấu hình cập nhật khi các khả năng mới được phát hành.
