Cài đặt DingTalk
Hermes Agent tích hợp với DingTalk (钉钉) dưới dạng chatbot, cho phép bạn trò chuyện với trợ lý AI của mình thông qua tin nhắn trực tiếp hoặc trò chuyện nhóm. Bot kết nối thông qua Chế độ phát trực tuyến của DingTalk — một kết nối WebSocket tồn tại lâu dài, không yêu cầu URL công khai hoặc máy chủ webhook — và trả lời bằng các tin nhắn được định dạng markdown thông qua API webhook phiên của DingTalk.
Trước khi thiết lập, đây là phần mà hầu hết mọi người muốn biết: Hermes hoạt động như thế nào khi có mặt trong không gian làm việc DingTalk của bạn.
Cách Hermes cư xử
| Bối cảnh | Hành vi |
|---|---|
| DM (trò chuyện 1:1) | Hermes trả lời mọi tin nhắn. Không cần @mention. Mỗi DM có phiên riêng. |
| Trò chuyện nhóm | Hermes phản hồi khi bạn @mention nó. Không đề cập đến, Hermes bỏ qua tin nhắn. |
| Nhóm được chia sẻ với nhiều người dùng | Theo mặc định, Hermes tách biệt lịch sử phiên của mỗi người dùng trong nhóm. Hai người nói chuyện trong cùng một nhóm không chia sẻ một bản ghi trừ khi bạn tắt nó một cách rõ ràng. |
Mô hình phiên trong DingTalk
Theo mặc định:
- mỗi DM có phiên riêng
- mỗi người dùng trong cuộc trò chuyện nhóm chia sẻ sẽ có phiên riêng của họ trong nhóm đó
Điều này được kiểm soát bởi config.yaml :
group_sessions_per_user: true
Chỉ đặt thành false nếu bạn rõ ràng muốn có một cuộc trò chuyện chung cho toàn bộ nhóm:
group_sessions_per_user: false
Hướng dẫn này sẽ hướng dẫn bạn toàn bộ quá trình thiết lập — từ việc tạo bot DingTalk đến gửi tin nhắn đầu tiên của bạn.
Điều kiện tiên quyết
Cài đặt các gói Python cần thiết:
pip install dingtalk-stream httpx
dingtalk-stream— SDK chính thức của DingTalk dành cho Chế độ phát trực tuyến (nhắn tin thời gian thực dựa trên WebSocket)httpx— ứng dụng khách HTTP không đồng bộ được sử dụng để gửi phản hồi qua webhooks phiên
Bước 1: Tạo ứng dụng DingTalk
- Đi tới Bảng điều khiển dành cho nhà phát triển DingTalk.
- Đăng nhập bằng tài khoản quản trị DingTalk của bạn.
- Nhấp vào Phát triển ứng dụng → Ứng dụng tùy chỉnh → Tạo ứng dụng qua ứng dụng vi mô H5 (hoặc Robot tùy thuộc vào phiên bản bảng điều khiển của bạn).
- Điền vào:
- Tên ứng dụng: ví dụ:
Hermes Agent - Mô tả: tùy chọn
- Tên ứng dụng: ví dụ:
- Sau khi tạo, hãy điều hướng đến Thông tin xác thực & Thông tin cơ bản để tìm ID khách hàng (AppKey) và Bí mật khách hàng (AppSecret) của bạn. Sao chép cả hai.
Bí mật khách hàng chỉ được hiển thị một lần khi bạn tạo ứng dụng. Nếu bạn mất nó, bạn sẽ cần phải tạo lại nó. Không bao giờ chia sẻ công khai những thông tin đăng nhập này hoặc cam kết chúng với Git.
Bước 2: Kích hoạt khả năng của Robot
- Trong trang cài đặt ứng dụng của bạn, hãy đi tới Thêm khả năng → Robot.
- Kích hoạt khả năng của robot.
- Trong Chế độ nhận tin nhắn, chọn Chế độ phát trực tuyến (được khuyến nghị — không cần URL công khai).
Chế độ phát trực tuyến là thiết lập được đề xuất. Nó sử dụng kết nối WebSocket lâu dài được khởi tạo từ máy của bạn, vì vậy bạn không cần IP công khai, tên miền hoặc điểm cuối webhook. Điều này hoạt động đằng sau NAT, tường lửa và trên các máy cục bộ.
Bước 3: Tìm ID người dùng DingTalk của bạnHermes Agent sử dụng ID người dùng DingTalk của bạn để kiểm soát ai có thể tương tác với bot. ID người dùng DingTalk là các chuỗi chữ và số do quản trị viên tổ chức của bạn đặt.
Để tìm của bạn:
- Hỏi quản trị viên tổ chức DingTalk của bạn — ID người dùng được định cấu hình trong bảng điều khiển dành cho quản trị viên DingTalk trong Danh bạ → Thành viên.
- Ngoài ra, bot sẽ ghi lại
sender_idcho mỗi tin nhắn đến. Khởi động cổng, gửi tin nhắn cho bot, sau đó kiểm tra nhật ký để tìm ID của bạn.
Bước 4: Cấu hình Hermes Agent
Tùy chọn A: Thiết lập tương tác (Được khuyến nghị)
Chạy lệnh thiết lập được hướng dẫn:
hermes gateway setup
Chọn DingTalk khi được nhắc, sau đó dán ID khách hàng, Bí mật khách hàng và ID người dùng được phép khi được hỏi.
Tùy chọn B: Cấu hình thủ công
Thêm phần sau vào tệp ~/.hermes/.env của bạn:
# Required
DINGTALK_CLIENT_ID=your-app-key
DINGTALK_CLIENT_SECRET=your-app-secret
# Security: restrict who can interact with the bot
DINGTALK_ALLOWED_USERS=user-id-1
# Multiple allowed users (comma-separated)
# DINGTALK_ALLOWED_USERS=user-id-1,user-id-2
Cài đặt hành vi tùy chọn trong ~/.hermes/config.yaml :
group_sessions_per_user: true
group_sessions_per_user: truetách biệt bối cảnh của từng người tham gia trong các cuộc trò chuyện nhóm được chia sẻ
Khởi động cổng
Sau khi định cấu hình, hãy khởi động cổng DingTalk:
hermes gateway
Bot sẽ kết nối với Chế độ phát trực tuyến của DingTalk trong vòng vài giây. Gửi tin nhắn cho nó — DM hoặc trong nhóm mà nó đã được thêm — để kiểm tra.
Bạn có thể chạy hermes gateway ở chế độ nền hoặc dưới dạng dịch vụ systemd để hoạt động liên tục. Xem tài liệu triển khai để biết chi tiết.
Khắc phục sự cố
Bot không trả lời tin nhắn
Lý do: Khả năng của robot chưa được bật hoặc DINGTALK_ALLOWED_USERS không bao gồm ID người dùng của bạn.
Khắc phục: Xác minh rằng khả năng của robot đã được bật trong cài đặt ứng dụng của bạn và Chế độ phát trực tuyến đã được chọn. Kiểm tra xem ID người dùng của bạn có ở DINGTALK_ALLOWED_USERS hay không. Khởi động lại cổng.
lỗi "dingtalk-stream chưa được cài đặt"
Lý do: Gói Python dingtalk-stream chưa được cài đặt.
Khắc phục: Cài đặt nó:
pip install dingtalk-stream httpx
"Bắt buộc phải có DINGTALK_CLIENT_ID và DINGTALK_CLIENT_SECRET"
Lý do: Thông tin đăng nhập không được đặt trong môi trường của bạn hoặc tệp .env.
Khắc phục: Xác minh DINGTALK_CLIENT_ID và DINGTALK_CLIENT_SECRET được đặt chính xác trong ~/.hermes/.env . ID khách hàng là AppKey của bạn và Bí mật khách hàng là AppSecret của bạn từ Bảng điều khiển dành cho nhà phát triển DingTalk.
Ngắt kết nối luồng / vòng lặp kết nối lại
Nguyên nhân: Mạng không ổn định, bảo trì nền tảng DingTalk hoặc vấn đề về thông tin xác thực.
Khắc phục: Bộ điều hợp tự động kết nối lại với thời gian chờ theo cấp số nhân (2 giây → 5 giây → 10 giây → 30 giây → 60 giây). Kiểm tra xem thông tin xác thực của bạn có hợp lệ không và ứng dụng của bạn chưa bị vô hiệu hóa. Xác minh rằng mạng của bạn cho phép kết nối WebSocket gửi đi.
Bot đang ngoại tuyến
Nguyên nhân: Cổng Hermes không chạy hoặc không kết nối được.
Khắc phục: Kiểm tra xem hermes gateway có đang chạy không. Nhìn vào đầu ra của terminal để biết thông báo lỗi. Các sự cố thường gặp: thông tin đăng nhập sai, ứng dụng bị vô hiệu hóa, dingtalk-stream hoặc httpx chưa được cài đặt.
"Không có session_webhook"Lý do: Bot đã cố gắng trả lời nhưng không có URL webhook của phiên. Điều này thường xảy ra nếu webhook hết hạn hoặc bot được khởi động lại giữa lúc nhận tin nhắn và gửi trả lời.
Khắc phục: Gửi tin nhắn mới tới bot — mỗi tin nhắn đến sẽ cung cấp một phiên webhook mới để trả lời. Đây là một hạn chế DingTalk bình thường; bot chỉ có thể trả lời những tin nhắn nó nhận được gần đây.
Bảo mật
Luôn đặt DINGTALK_ALLOWED_USERS để hạn chế người có thể tương tác với bot. Nếu không có nó, cổng mặc định sẽ từ chối tất cả người dùng như một biện pháp an toàn. Chỉ thêm ID người dùng của những người bạn tin cậy — người dùng được ủy quyền có toàn quyền truy cập vào các khả năng của tổng đài viên, bao gồm cả việc sử dụng công cụ và quyền truy cập hệ thống.
Để biết thêm thông tin về việc đảm bảo triển khai Hermes Agent của bạn, hãy xem Hướng dẫn bảo mật.
Ghi chú
- Chế độ phát trực tuyến: Không cần URL công khai, tên miền hoặc máy chủ webhook. Kết nối được bắt đầu từ máy của bạn thông qua WebSocket, vì vậy nó hoạt động sau NAT và tường lửa.
- Phản hồi đánh dấu: Các câu trả lời được định dạng theo định dạng đánh dấu của DingTalk để hiển thị văn bản đa dạng thức.
- Loại bỏ tin nhắn trùng lặp: Bộ chuyển đổi sẽ loại bỏ các tin nhắn trùng lặp trong khoảng thời gian 5 phút để ngăn chặn việc xử lý cùng một tin nhắn hai lần.
- Tự động kết nối lại: Nếu kết nối luồng bị rớt, bộ điều hợp sẽ tự động kết nối lại với độ trễ theo cấp số nhân.
- Giới hạn độ dài tin nhắn: Phản hồi được giới hạn ở mức 20.000 ký tự cho mỗi tin nhắn. Những câu trả lời dài hơn sẽ bị cắt bớt.