Chuyển tới nội dung chính

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ảnhHà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:

`YAML
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:

`bash
pip install "Hermes-agent[DingTalk]"

`
``Hoặc riêng lẻ:

`bash
pip install DingTalk-stream httpx alibabacloud-DingTalk

`

- 
`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
- 
`alibabacloud-DingTalk
` — DingTalk OpenAPI SDK dành cho Thẻ AI, phản ứng biểu tượng cảm xúc và tải xuống phương tiện

## Bước 1: Tạo ứng dụng DingTalk
1. Đi tới [DingTalk Developer Console](https://open-dev.DingTalk.com/).
2. Đăng nhập bằng tài khoản quản trị DingTalk của bạn.
3. 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).
4. Điền vào:
   - **Tên ứng dụng**: ví dụ: 
`Hermes Agent

   - **Mô tả**: tùy chọn
5. 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.

:::warning[Credentials shown only once]
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
1. Trong trang cài đặt ứng dụng của bạn, hãy đi tới **Thêm khả năng** → **Robot**.
2. Kích hoạt khả năng của robot.
3. 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).

:::tip
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ạn

Đại lý Hermes 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:
1. 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**.
2. Ngoài ra, bot sẽ ghi lại 
`sender_id
` cho 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 đại lý Hermes

### 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:

``` bash
Hermes gateway setup

`
``Chọn **DingTalk** khi được nhắc. Trình hướng dẫn thiết lập có thể ủy quyền thông qua một trong hai đường dẫn:
- **Luồng thiết bị mã QR (được khuyến nghị).** Quét mã QR in trong terminal của bạn bằng ứng dụng di động DingTalk — ID khách hàng và Bí mật khách hàng của bạn sẽ tự động được trả về và ghi vào 

~/.Hermes/.env

. Không cần chuyến đi giữa bảng điều khiển dành cho nhà phát triển.

- **Dán thủ công.** Nếu bạn đã có thông tin xác thực (hoặc quét QR không thuận tiện), hãy 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 nhắc.:::note OpenClaw branding disclosure
Vì 
`verification_uri_complete
` của DingTalk được mã hóa cứng thành danh tính OpenClaw ở lớp API nên QR hiện ủy quyền theo chuỗi nguồn 
`OpenClaw
` cho đến khi Alibaba / DingTalk-Real-AI đăng ký phía máy chủ mẫu dành riêng cho Hermes. Đây hoàn toàn là cách DingTalk trình bày màn hình chấp thuận — bot bạn tạo hoàn toàn là của bạn và riêng tư đối với người thuê của bạn.
:::

### 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:

``` bash

# 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

# Optional: group-chat gating (mirrors Slack/Telegram/Discord/WhatsApp)
# DingTalk_REQUIRE_MENTION=true
# DingTalk_FREE_RESPONSE_CHATS=cidABC==,cidDEF==
# DingTalk_MENTION_PATTERNS=^小马
# DingTalk_HOME_CHANNEL=cidXXXX==
# DingTalk_ALLOW_ALL_USERS=true

`
``Cài đặt hành vi tùy chọn trong 

~/.Hermes/config.yaml

:

``` yaml
group_sessions_per_user: true`gateway:
  platforms:
    DingTalk:
      extra:

        # Require @mention in groups before the bot replies (parity with Slack/Telegram/Discord).
        # DMs ignore this — the bot always replies in 1:1 chats.
        require_mention: true

# Per-platform allowlist. When set, only these DingTalk user IDs can interact with the bot
        # (same semantics as DingTalk_ALLOWED_USERS, but scoped here instead of in .env).
        allowed_users:
          - user-id-1
          - user-id-2

`

- 
`group_sessions_per_user: true
` giúp tá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ẻ
- 
`require_mention: true
` ngăn bot phản hồi mọi tin nhắn nhóm - nó chỉ trả lời khi ai đó @-đề cập đến nó
- 
`allowed_users
` thuộc 
`DingTalk.extra
` là sự thay thế cho 
`DingTalk_ALLOWED_USERS

; nếu cả hai được đặt, chúng sẽ được hợp nhất

### Khởi động cổng

Sau khi định cấu hình, hãy khởi động cổng DingTalk:

``` bash
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.

:::tip
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.

:::

## Tính năng

### Thẻ AI

Hermes có thể trả lời bằng Thẻ AI DingTalk thay vì tin nhắn đánh dấu đơn giản. Thẻ cung cấp màn hình phong phú hơn, có cấu trúc hơn và hỗ trợ cập nhật phát trực tuyến khi tác nhân tạo phản hồi.

Để bật Thẻ AI, hãy định cấu hình ID mẫu thẻ trong 
`config.yaml

:

``` yaml
platforms:
  DingTalk:
    enabled: true
    extra:
      card_template_id: "your-card-template-id"

`
``Bạn có thể tìm thấy ID mẫu thẻ của mình trong Bảng điều khiển dành cho nhà phát triển DingTalk trong cài đặt Thẻ AI của ứng dụng. Khi Thẻ AI được bật, tất cả các câu trả lời sẽ được gửi dưới dạng thẻ có nội dung cập nhật văn bản trực tuyến.

### Phản ứng biểu tượng cảm xúc

Hermes tự động thêm biểu tượng cảm xúc vào tin nhắn của bạn để hiển thị trạng thái xử lý:
- 🤔Suy nghĩ — được thêm vào khi bot bắt đầu xử lý tin nhắn của bạn

- 🥳Xong — được thêm khi phản hồi hoàn tất (thay thế phản ứng Suy nghĩ)

Những phản ứng này hoạt động trong cả tin nhắn trực tiếp và trò chuyện nhóm.

### Cài đặt hiển thị

Bạn có thể tùy chỉnh hành vi hiển thị của DingTalk độc lập với các nền tảng khác:

``` yaml
display:
  platforms:
    DingTalk:
      show_reasoning: false   # Show model reasoning/thinking in replies
      streaming: true         # Enable streaming responses (works with AI Cards)
      tool_progress: all      # Show tool execution progress (all/new/off)
      interim_assistant_messages: true  # Show intermediate commentary messages

`
``Để tắt tiến trình công cụ và thông báo trung gian để có trải nghiệm rõ ràng hơn:

`YAML
display:
  platforms:
    DingTalk:
      tool_progress: off
      interim_assistant_messages: false

`

## 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ó nằm trong 
`DingTalk_ALLOWED_USERS
` hay không. Khởi động lại cổng.

### lỗi "DingTalk-stream chưa được cài đặt"`**Nguyên nhân**: Gói Python 
`DingTalk-stream
` chưa được cài đặt.

**Khắc phục**: Cài đặt nó:

`bash
pip install DingTalk-stream httpx

`

### "Bắt buộc phải có DingTalk_CLIENT_ID và DingTalk_CLIENT_SECRET"`**Lý do**: Thông tin xác thực 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 đăng nhập 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 vệ:::warning
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 Đại lý Hermes của bạn, hãy xem [Security Guide](../security.md).

## 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.
- **Thẻ AI**: Tùy chọn trả lời bằng Thẻ AI phong phú thay vì đánh dấu đơn giản. Định cấu hình qua 
`card_template_id

.
- **Phản ứng biểu tượng cảm xúc**: Tự động 🤔Đang suy nghĩ/🥳Phản ứng đã hoàn thành để biết trạng thái xử lý.
- **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.
- **Hỗ trợ phương tiện**: Hình ảnh và tập tin trong tin nhắn đến sẽ được tự động phân giải và có thể được xử lý bằng các công cụ thị giá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.