Thiết lập discord
Hermes Agent tích hợp với Discord dưới dạng bot, 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 kênh máy chủ. Bot nhận tin nhắn của bạn, xử lý chúng thông qua quy trình của Đại lý Hermes (bao gồm việc sử dụng công cụ, bộ nhớ và lý luận) rồi phản hồi theo thời gian thực. Nó hỗ trợ văn bản, tin nhắn thoại, tệp đính kèm và lệnh gạch chéo.
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 nó ở trong máy chủ của bạn.
Cách Hermes cư xử
| Bối cảnh | Hành vi |
|---|---|
| DM | Hermes trả lời mọi tin nhắn. Không cần |
@mention
. Mỗi DM có phiên riêng. | | Kênh máy chủ | Theo mặc định, Hermes chỉ phản hồi khi bạn
@mention
. Nếu bạn đăng bài trên một kênh mà không đề cập đến kênh đó, Hermes sẽ bỏ qua tin nhắn đó. |
| Kênh phản hồi miễn phí | Bạn có thể đặt các kênh cụ thể không được đề cập bằng
Discord_FREE_RESPONSE_CHANNELS hoặc tắt tính năng đề cập trên toàn cầu bằng
`Discord_REQUIRE_MENTION=false
. Tin nhắn trong các kênh này được trả lời nội tuyến — tính năng tự động phân luồng bị bỏ qua để kênh duy trì cuộc trò chuyện nhẹ nhàng. |
| Chủ đề | Hermes trả lời trong cùng một chủ đề. Quy tắc đề cập vẫn được áp dụng trừ khi chuỗi đó hoặc kênh chính của nó được định cấu hình là phản hồi miễn phí. Các chủ đề được tách biệt khỏi kênh chính đối với lịch sử phiên. |
| Kênh đượ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 kênh để đảm bảo an toàn và rõ ràng. Hai người đang nói chuyện trong cùng một kênh sẽ không chia sẻ một bản ghi trừ khi bạn tắt tính năng đó một cách rõ ràng. |
| Tin nhắn đề cập đến người dùng khác | Khi
Discord_IGNORE_NO_MENTION là
true (mặc định), Hermes sẽ giữ im lặng nếu một tin nhắn @đề cập đến người dùng khác nhưng không đề cập đến bot. Điều này ngăn bot nhảy vào cuộc trò chuyện hướng vào người khác. Đặt thành
false nếu bạn muốn bot phản hồi tất cả tin nhắn bất kể ai được đề cập. Điều này chỉ áp dụng trong các kênh máy chủ, không phải DM. |
mẹo
Nếu bạn muốn có một kênh trợ giúp bot bình thường, nơi mọi người có thể nói chuyện với Hermes mà không cần gắn thẻ kênh đó mọi lúc, hãy thêm kênh đó vào `Discord_FREE_RESPONSE_CHANNELS
.
Mô hình cổng Discord
Hermes trên Discord không phải là một webhook trả lời không trạng thái. Nó chạy qua cổng nhắn tin đầy đủ, có nghĩa là mỗi tin nhắn đến đều phải trải qua:
- ủy quyền ( `Discord_ALLOWED_USERS
) 2. đề cập / kiểm tra phản hồi miễn phí 3. tra cứu phiên 4. tải bảng điểm phiên 5. Thực thi tác nhân Hermes thông thường, bao gồm các công cụ, bộ nhớ và lệnh gạch chéo 6. Gửi phản hồi trở lại Discord
Điều đó quan trọng vì hoạt động trong một máy chủ bận phụ thuộc vào cả chính sách định tuyến Discord và phiên Hermes.
Mô hình phiên trong Discord
Theo mặc định:
- mỗi DM có phiên riêng
- mỗi luồng máy chủ có không gian tên phiên riêng
- mỗi người dùng trong kênh được chia sẻ sẽ có phiên riêng của họ trong kênh đó
Vì vậy, nếu Alice và Bob đều nói chuyện với Hermes trong
#research
, thì theo mặc định, Hermes coi đó là những cuộc trò chuyện riêng biệt ngay cả khi họ đang sử dụng cùng một kênh Discord hiển thị.
Đ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ộ phòng:
`YAML
group_sessions_per_user: false
`
``Phiên chia sẻ có thể hữu ích cho phòng cộng tác nhưng chúng cũng có nghĩa là:
- người dùng chia sẻ mức tăng trưởng bối cảnh và chi phí mã thông báo
- nhiệm vụ nặng nề và tốn nhiều công cụ của một người có thể làm bối rối bối cảnh của những người khác
- việc chạy trên chuyến bay của một người có thể làm gián đoạn việc theo dõi của người khác trong cùng phòng
### Ngắt và đồng thời
Hermes theo dõi các đại lý đang chạy bằng khóa phiên.
Với
`group_sessions_per_user: true
` mặc định:
- Alice làm gián đoạn yêu cầu của mình trên chuyến bay chỉ ảnh hưởng đến phiên của Alice trên kênh đó
- Bob có thể tiếp tục nói chuyện trên cùng một kênh mà không kế thừa lịch sử của Alice hoặc làm gián đoạn quá trình chạy của Alice
Với
`group_sessions_per_user: false
:
- toàn bộ phòng chia sẻ một khe cắm tác nhân đang chạy cho kênh/luồng đó
- tin nhắn tiếp theo từ những người khác nhau có thể làm gián đoạn hoặc xếp hàng sau nhau
Hướng dẫn này sẽ hướng dẫn bạn toàn bộ quy trình thiết lập — từ việc tạo bot trên Cổng thông tin dành cho nhà phát triển của Discord đến gửi tin nhắn đầu tiên của bạn.
## Bước 1: Tạo ứng dụng Discord1. Truy cập [Discord Developer Portal](https://Discord.com/developers/applications) và đăng nhập bằng tài khoản Discord của bạn.
2. Nhấp vào **Ứng dụng mới** ở góc trên bên phải.
3. Nhập tên cho ứng dụng của bạn (ví dụ: "Đại lý Hermes") và chấp nhận Điều khoản dịch vụ dành cho nhà phát triển.
4. Nhấp vào **Tạo**.
Bạn sẽ đến trang **Thông tin chung**. Lưu ý **ID ứng dụng** — sau này bạn sẽ cần nó để tạo URL lời mời.
## Bước 2: Tạo Bot
1. Ở thanh bên trái, nhấp vào **Bot**.
2. Discord tự động tạo người dùng bot cho ứng dụng của bạn. Bạn sẽ thấy tên người dùng của bot mà bạn có thể tùy chỉnh.
3. Trong **Quy trình ủy quyền**:
- Đặt **Public Bot** thành **BẬT** — bắt buộc phải sử dụng liên kết mời do Discord cung cấp (được khuyến nghị). Điều này cho phép tab Cài đặt tạo URL ủy quyền mặc định.
- Đặt **Yêu cầu cấp mã OAuth2** thành **TẮT**.
:::tip
Bạn có thể đặt hình đại diện và biểu ngữ tùy chỉnh cho bot của mình trên trang này. Đây là những gì người dùng sẽ thấy trong Discord.
:::
:::info[Private Bot Alternative]
Nếu bạn muốn giữ bot của mình ở chế độ riêng tư (Bot công cộng = TẮT), bạn **phải** sử dụng phương thức **URL thủ công** ở Bước 5 thay vì tab Cài đặt. Liên kết do Discord cung cấp yêu cầu bật Bot công cộng.
:::
## Bước 3: Kích hoạt Ý định cổng đặc quyền
Đây là bước quan trọng nhất trong toàn bộ quá trình thiết lập. Nếu không bật ý định chính xác, bot của bạn sẽ kết nối với Discord nhưng **sẽ không thể đọc nội dung tin nhắn**.
Trên trang **Bot**, cuộn xuống **Ý định cổng đặc quyền**. Bạn sẽ thấy ba nút chuyển đổi:
| Ý định | Mục đích | Yêu cầu? |
|--------|----------|----------|
| **Ý định hiện diện** | Xem trạng thái trực tuyến/ngoại tuyến của người dùng | Tùy chọn |
| **Ý định của thành viên máy chủ** | Truy cập danh sách thành viên, giải quyết tên người dùng | **Bắt buộc** |
| **Ý định nội dung tin nhắn** | Đọc nội dung tin nhắn | **Bắt buộc** |
**Bật cả Ý định của Thành viên Máy chủ và Ý định Nội dung Thông báo** bằng cách bật chúng **BẬT**.
- Nếu không có **Ý định nội dung tin nhắn**, bot của bạn sẽ nhận được các sự kiện tin nhắn nhưng nội dung tin nhắn trống — bot thực sự không thể nhìn thấy những gì bạn đã nhập.
- Nếu không có **Ý định của thành viên máy chủ**, bot không thể phân giải tên người dùng cho danh sách người dùng được phép và có thể không xác định được ai đang nhắn tin cho nó.
:::warning[This is the #1 reason Discord bots don't work]
Nếu bot của bạn trực tuyến nhưng không bao giờ trả lời tin nhắn thì **Ý định nội dung tin nhắn** gần như chắc chắn bị vô hiệu hóa. Quay lại [Developer Portal](https://Discord.com/developers/applications), chọn ứng dụng của bạn → Bot → Ý định cổng đặc quyền và đảm bảo **Ý định nội dung thông báo** được BẬT. Nhấp vào **Lưu thay đổi**.
:::
**Về số lượng máy chủ:**
- Nếu bot của bạn ở **dưới 100 máy chủ**, bạn chỉ cần bật và tắt ý định một cách thoải mái.
- Nếu bot của bạn ở **100 máy chủ trở lên**, Discord yêu cầu bạn gửi đơn đăng ký xác minh để sử dụng các ý định đặc quyền. Đối với sử dụng cá nhân, đây không phải là một mối quan tâm.
Nhấp vào **Lưu thay đổi** ở cuối trang.
## Bước 4: Lấy Bot Token
Mã thông báo bot là thông tin xác thực mà Đại lý Hermes sử dụng để đăng nhập với tư cách là bot của bạn. Vẫn ở trang **Bot**:
1. Trong phần **Mã thông báo**, hãy nhấp vào **Đặt lại mã thông báo**.
2. Nếu bạn đã bật xác thực hai yếu tố trên tài khoản Discord của mình, hãy nhập mã 2FA của bạn.
3. Discord sẽ hiển thị mã thông báo mới của bạn. **Sao chép nó ngay lập tức.**
:::warning[Token shown only once]
Mã thông báo chỉ được hiển thị một lần. Nếu mất nó, bạn cần phải đặt lại và tạo một cái mới. Không bao giờ chia sẻ công khai mã thông báo của bạn hoặc cam kết mã thông báo đó với Git - bất kỳ ai có mã thông báo này đều có toàn quyền kiểm soát bot của bạn.
:::
Lưu trữ mã thông báo ở nơi an toàn (ví dụ: trình quản lý mật khẩu). Bạn sẽ cần nó ở Bước 8.
## Bước 5: Tạo URL mời
Bạn cần có URL OAuth2 để mời bot vào máy chủ của mình. Có hai cách để làm điều này:
### Tùy chọn A: Sử dụng tab Cài đặt (Được khuyến nghị)
:::note[Requires Public Bot]
Phương pháp này yêu cầu **Public Bot** được đặt thành **BẬT** ở Bước 2. Nếu bạn đặt Bot công khai thành TẮT, thay vào đó hãy sử dụng phương pháp URL thủ công bên dưới.
:::
1. Ở thanh bên trái, nhấp vào **Cài đặt**.
2. Trong **Bối cảnh cài đặt**, bật **Cài đặt bang hội**.
3. Đối với **Liên kết cài đặt**, chọn **Liên kết được cung cấp từ Discord**.
4. Trong **Cài đặt cài đặt mặc định** cho Cài đặt Bang hội:
- **Phạm vi**: chọn
`bot
` và
`applications.commands
- **Quyền**: chọn các quyền được liệt kê bên dưới.
### Tùy chọn B: URL thủ công
Bạn có thể tạo URL lời mời trực tiếp bằng định dạng sau:
`
https://Discord.com/OAuth2/authorize?CLIent_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274878286912
`
`Thay thế
`YOUR_APP_ID
` bằng ID ứng dụng từ Bước 1.
### Quyền cần thiết
Đây là những quyền tối thiểu mà bot của bạn cần:
- **Xem kênh** — xem các kênh mà nó có quyền truy cập
- **Gửi tin nhắn** — trả lời tin nhắn của bạn
- **Liên kết nhúng** — phản hồi có định dạng phong phú
- **Đính kèm tệp** — gửi hình ảnh, âm thanh và đầu ra tệp
- **Đọc lịch sử tin nhắn** — duy trì bối cảnh cuộc trò chuyện
### Quyền bổ sung được đề xuất
- **Gửi tin nhắn trong chuỗi** — trả lời trong các cuộc hội thoại theo chuỗi
- **Thêm phản ứng** — phản ứng với tin nhắn để xác nhận
### Số nguyên quyền
| Cấp độ | Số nguyên quyền | Bao gồm những gì |
|-------|-------------------|-----------------|
| Tối thiểu |
117760
` | Xem kênh, gửi tin nhắn, đọc lịch sử tin nhắn, đính kèm tệp |
| Được đề xuất |
274878286912
` | Tất cả những điều trên cộng với Liên kết nhúng, Gửi tin nhắn trong chủ đề, Thêm phản ứng |
## Bước 6: Mời vào máy chủ của bạn
1. Mở URL mời trong trình duyệt của bạn (từ tab Cài đặt hoặc URL thủ công bạn đã tạo).
2. Trong trình đơn thả xuống **Thêm vào máy chủ**, hãy chọn máy chủ của bạn.
3. Nhấp vào **Tiếp tục**, sau đó nhấp vào **Ủy quyền**.
4. Hoàn thành CAPTCHA nếu được nhắc.
:::info
Bạn cần có quyền **Quản lý máy chủ** trên máy chủ Discord để mời bot. Nếu bạn không thấy máy chủ của mình trong danh sách thả xuống, hãy yêu cầu quản trị viên máy chủ sử dụng liên kết mời.
:::
Sau khi ủy quyền, bot sẽ xuất hiện trong danh sách thành viên máy chủ của bạn (nó sẽ hiển thị ở trạng thái ngoại tuyến cho đến khi bạn khởi động cổng Hermes).
## Bước 7: Tìm ID người dùng Discord của bạn
Đại lý Hermes sử dụng ID người dùng Discord của bạn để kiểm soát ai có thể tương tác với bot. Để tìm thấy nó:
1. Mở Discord (máy tính để bàn hoặc ứng dụng web).
2. Đi tới **Cài đặt** → **Nâng cao** → chuyển **Chế độ nhà phát triển** sang **BẬT**.
3. Đóng cài đặt.
4. Nhấp chuột phải vào tên người dùng của chính bạn (trong tin nhắn, danh sách thành viên hoặc hồ sơ của bạn) → **Sao chép ID người dùng**.
ID người dùng của bạn là một số dài như
`284102345871466496
.
:::tip
Chế độ nhà phát triển cũng cho phép bạn sao chép **ID kênh** và **ID máy chủ** theo cách tương tự — nhấp chuột phải vào tên kênh hoặc tên máy chủ và chọn Sao chép ID. Bạn sẽ cần ID kênh nếu muốn đặt kênh chính theo cách thủ công.
:::
## Bước 8: 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 **Discord** khi được nhắc, sau đó dán mã thông báo bot và ID người dùng của bạn 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:
`bash
# Required
Discord_BOT_TOKEN=your-bot-token
Discord_ALLOWED_USERS=284102345871466496
# Multiple allowed users (comma-separated)
# Discord_ALLOWED_USERS=284102345871466496,198765432109876543
`
``Sau đó khởi động cổng:
``` bash
Hermes gateway
`
``Bot sẽ trực tuyến trong Discord trong vòng vài giây. Gửi cho nó một tin nhắn - DM hoặc trong một kênh mà nó có thể nhìn thấy - để 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.
:::
## Tham khảo cấu hình
Hành vi Discord được kiểm soát thông qua hai tệp: **
~/.Hermes/.env
** dành cho thông tin xác thực và chuyển đổi cấp độ env và **
~/.Hermes/config.yaml
** dành cho cài đặt có cấu trúc. Các biến môi trường luôn được ưu tiên hơn các giá trị config.yaml khi cả hai đều được đặt.
### Biến môi trường (
.env
)| Biến | Bắt buộc | Mặc định | Mô tả |
|----------|----------|---------|-------------|
|
`Discord_BOT_TOKEN
` | **Có** | — | Mã thông báo bot từ [Discord Developer Portal](https://Discord.com/developers/applications). |
|
`Discord_ALLOWED_USERS
` | **Có** | — | ID người dùng Discord được phân tách bằng dấu phẩy được phép tương tác với bot. Nếu không có **hoặc**
`Discord_ALLOWED_ROLES
` này, cổng sẽ từ chối tất cả người dùng. |
|
`Discord_ALLOWED_ROLES
` | Không | — | ID vai trò Discord được phân tách bằng dấu phẩy. Bất kỳ thành viên nào có một trong các vai trò này đều được ủy quyền — HOẶC ngữ nghĩa với
`Discord_ALLOWED_USERS
. Tự động kích hoạt **Ý định của thành viên máy chủ** khi kết nối. Hữu ích khi nhóm kiểm duyệt ngừng hoạt động: các mod mới có quyền truy cập ngay khi vai trò được cấp, không cần đẩy cấu hình. |
|
`Discord_HOME_CHANNEL
` | Không | — | ID kênh nơi bot gửi tin nhắn chủ động (đầu ra cron, lời nhắc, thông báo). |
|
`Discord_HOME_CHANNEL_NAME
` | Không |
"Home"
` | Hiển thị tên của kênh chính trong nhật ký và đầu ra trạng thái. |
|
`Discord_COMMAND_SYNC_POLICY
` | Không |
"safe"
` | Kiểm soát đồng bộ hóa khởi động lệnh gạch chéo gốc.
"safe"
` khác biệt với các lệnh chung hiện có và chỉ cập nhật những gì đã thay đổi, tạo lại các lệnh khi không thể áp dụng các thay đổi siêu dữ liệu Discord thông qua bản vá.
"bulk"
` duy trì hoạt động
`tree.sync()
` cũ.
"off"
` bỏ qua hoàn toàn quá trình đồng bộ hóa khởi động. |
|
`Discord_REQUIRE_MENTION
` | Không |
true
` | Khi
`true
, bot chỉ phản hồi trong các kênh máy chủ khi
@mentioned
. Đặt thành
`false
` để trả lời tất cả tin nhắn ở mọi kênh. |
|
`Discord_THREAD_REQUIRE_MENTION
` | Không |
false
` | Khi
`true
, phím tắt đề cập trong luồng bị tắt - các luồng được kiểm soát giống như các kênh, yêu cầu
@mention
` ngay cả sau khi bot đã tham gia. Sử dụng tính năng này khi nhiều bot chia sẻ một chuỗi và bạn muốn mỗi bot chỉ kích hoạt trên
@mention
` rõ ràng. |
|
`Discord_FREE_RESPONSE_CHANNELS
` | Không | — | ID kênh được phân tách bằng dấu phẩy trong đó bot phản hồi mà không yêu cầu
@mention
, ngay cả khi
`Discord_REQUIRE_MENTION
` là
`true
. |
|
`Discord_IGNORE_NO_MENTION
` | Không |
true
` | Khi
`true
, bot sẽ im lặng nếu có tin nhắn
@mentions
` của người dùng khác nhưng **không** đề cập đến bot. Ngăn chặn bot nhảy vào cuộc trò chuyện hướng vào người khác. Chỉ áp dụng ở kênh server, không áp dụng ở DM. |
|
`Discord_AUTO_THREAD
` | Không |
true
` | Khi
`true
, tự động tạo một chuỗi mới cho mọi
@mention
` trong kênh văn bản, do đó mỗi cuộc hội thoại đều được tách biệt (tương tự như hành vi của Slack). Các tin nhắn đã có trong chủ đề hoặc tin nhắn trực tiếp sẽ không bị ảnh hưởng. |
|
`Discord_ALLOW_BOTS
` | Không |
"none"
` | Kiểm soát cách bot xử lý tin nhắn từ các bot Discord khác.
"none"
- bỏ qua tất cả các bot khác.
"mentions"
- chỉ chấp nhận tin nhắn bot
@mention
` Hermes.
"all"
- chấp nhận tất cả tin nhắn của bot. |
|
`Discord_REACTIONS
` | Không |
true
` | Khi
`true
, bot sẽ thêm phản ứng biểu tượng cảm xúc vào tin nhắn trong quá trình xử lý (👀 khi bắt đầu, ✅ thành công, ❌ lỗi). Đặt thành
`false
` để tắt hoàn toàn các phản ứng. |
|
`Discord_IGNORED_CHANNELS
` | Không | — | ID kênh được phân tách bằng dấu phẩy trong đó bot **không bao giờ** phản hồi, ngay cả khi
@mentioned
. Được ưu tiên hơn tất cả các cài đặt kênh khác. |
|
`Discord_ALLOWED_CHANNELS
` | Không | — | ID kênh được phân tách bằng dấu phẩy. Khi được đặt, bot **chỉ** phản hồi trong các kênh này (cộng với tin nhắn trực tiếp nếu được phép). Ghi đè
`config.yaml
`
`Discord.allowed_channels
. Kết hợp với
`Discord_IGNORED_CHANNELS
` để thể hiện quy tắc cho phép/từ chối. |
|
`Discord_NO_THREAD_CHANNELS
` | Không | — | ID kênh được phân tách bằng dấu phẩy trong đó bot phản hồi trực tiếp trong kênh thay vì tạo chuỗi. Chỉ phù hợp khi
`Discord_AUTO_THREAD
` là
`true
. |
|
`Discord_HISTORY_BACKFILL
` | Không |
true
` | Khi
`true
, thêm cuộn lùi kênh gần đây (kể từ phản hồi cuối cùng của bot) vào thông báo của người dùng khi bot được đề cập. Khôi phục bối cảnh mà bot có thể bỏ lỡ với
`require_mention
. Đã bỏ qua tin nhắn trực tiếp và các kênh phản hồi miễn phí. Đặt thành
`false
` để tắt. |
|
`Discord_HISTORY_BACKFILL_LIMIT
` | Không |
50
` | Số lượng thông báo tối đa để quét ngược khi lắp ráp khối chèn lấp. Trong thực tế, quá trình quét thường dừng sớm hơn — tại tin nhắn cuối cùng của bot trong kênh. ||
Discord_REPLY_TO_MODE
` | Không |
"first"
` | Kiểm soát hành vi tham chiếu trả lời:
"off"
` — không bao giờ trả lời thư gốc,
"first"
` — chỉ tham chiếu trả lời trên đoạn thư đầu tiên (mặc định),
"all"
` — tham chiếu trả lời trên mỗi đoạn. |
|
`Discord_ALLOW_MENTION_EVERYONE
` | Không |
false
` | Khi
`false
` (mặc định), bot không thể ping
@everyone
` hoặc
@here
` ngay cả khi phản hồi của nó có chứa các mã thông báo đó. Đặt thành
`true
` để chọn tham gia lại. Xem [Mention Control](#mention-control) bên dưới. |
|
`Discord_ALLOW_MENTION_ROLES
` | Không |
false
` | Khi
`false
` (mặc định), bot không thể ping đề cập đến
@role
. Đặt thành
`true
` để cho phép. |
|
`Discord_ALLOW_MENTION_USERS
` | Không |
true
` | Khi
`true
` (mặc định), bot có thể ping từng người dùng theo ID. |
|
`Discord_ALLOW_MENTION_REPLIED_USER
` | Không |
true
` | Khi
`true
` (mặc định), việc trả lời tin nhắn sẽ ping tác giả ban đầu. |
|
`Discord_PROXY
` | Không | — | URL proxy cho các kết nối Discord (HTTP, WebSocket, REST). Ghi đè
`HTTPS_PROXY
/
`ALL_PROXY
. Hỗ trợ các chương trình
`http://
,
`https://
` và
`socks5://
. |
|
`Discord_ALLOW_ANY_ATTACHMENT
` | Không |
false
` | Khi
`true
, bot chấp nhận tệp đính kèm thuộc bất kỳ loại tệp nào (không chỉ danh sách cho phép PDF/văn bản/zip/office tích hợp sẵn). Các loại không xác định được lưu vào bộ nhớ đệm vào đĩa và hiển thị cho tác nhân dưới dạng đường dẫn cục bộ với
`application/octet-stream
` MIME để tác nhân có thể kiểm tra chúng bằng
`terminal
` /
`read_file
` /
`ffprobe
` / v.v. |
|
`Discord_MAX_ATTACHMENT_BYTES
` | Không |
33554432
` | Số byte tối đa cho mỗi tệp đính kèm mà cổng sẽ tải xuống và lưu vào bộ đệm. Mặc định 32 MiB. Đặt thành
`0
` không có giới hạn (các tệp đính kèm được giữ trong bộ nhớ khi được ghi, do đó không giới hạn sẽ mang theo chi phí bộ nhớ thực). |
|
`Hermes_Discord_TEXT_BATCH_DELAY_SECONDS
` | Không |
0.6
` | Cửa sổ Grace, bộ chuyển đổi chờ trước khi xóa một đoạn văn bản được xếp hàng đợi. Hữu ích cho việc làm mịn đầu ra truyền phát. |
|
`Hermes_Discord_TEXT_BATCH_SPLIT_DELAY_SECONDS
` | Không |
2.0
` | Độ trễ giữa các phần được chia khi một tin nhắn vượt quá giới hạn độ dài của Discord. |### Tệp cấu hình (
`config.yaml
)
Phần
`Discord
` trong
~/.Hermes/config.yaml
` phản ánh các biến env ở trên. Cài đặt config.yaml được áp dụng làm mặc định - nếu var env tương đương đã được đặt thì var env sẽ thắng.
``` yaml
# Discord-specific settings
Discord:
require_mention: true # Require @mention in server channels
thread_require_mention: false # If true, require @mention in threads too (multi-bot threads)
free_response_channels: "" # Comma-separated channel IDs (or YAML list)
auto_thread: true # Auto-create threads on @mention
reactions: true # Add emoji reactions during processing
ignored_channels: [] # Channel IDs where bot never responds
no_thread_channels: [] # Channel IDs where bot responds without threading
history_backfill: true # Prepend recent channel scrollback on mention (default: true)
history_backfill_limit: 50 # Max messages to scan backwards (default: 50)
channel_prompts: \{} # Per-channel ephemeral system prompts
allow_mentions: # What the bot is allowed to ping (safe defaults)
everyone: false # @everyone / @here pings (default: false)
roles: false # @role pings (default: false)
users: true # @user pings (default: true)
replied_user: true # reply-reference pings the author (default: true)
# Session isolation (applies to all gateway platforms, not just Discord)
group_sessions_per_user: true # Isolate sessions per user in shared channels
`
####
`Discord.require_mention
``**Loại:** boolean — **Mặc định:**
`true
``Khi được bật, bot chỉ phản hồi trong các kênh máy chủ khi trực tiếp
@mentioned
. DM luôn nhận được phản hồi bất kể cài đặt này.
####
`Discord.thread_require_mention
``**Loại:** boolean — **Mặc định:**
`false
``Theo mặc định, sau khi bot đã tham gia vào một chuỗi (được tạo tự động trên
@mention
` hoặc trả lời một lần), bot sẽ tiếp tục phản hồi mọi tin nhắn tiếp theo trong chuỗi đó mà không cần phải là
@mentioned
` nữa. Đó là chế độ mặc định phù hợp cho cuộc trò chuyện trực tiếp.
Trong **chuỗi nhiều bot** nơi người dùng xử lý một bot mỗi lượt, chế độ mặc định này sẽ trở thành súng ngắn — mọi bot khác trong chuỗi cũng kích hoạt mọi tin nhắn, đốt cháy tín dụng và gửi thư rác cho kênh. Đặt
`thread_require_mention: true
` để tắt lối tắt trong chuỗi và chuỗi cổng giống như cách kiểm soát các kênh. Rõ ràng
@mentions
` vẫn hoạt động như trước.
``` yaml
Discord:
require_mention: true
thread_require_mention: true # multi-bot setup
`
####
`Discord.free_response_channels
``**Loại:** chuỗi hoặc danh sách — **Mặc định:**
""
``ID kênh nơi bot phản hồi tất cả tin nhắn mà không cần
@mention
. Chấp nhận chuỗi được phân tách bằng dấu phẩy hoặc danh sách YAML:
`YAML
# String format
Discord:
free_response_channels: "1234567890,9876543210"
# List format
Discord:
free_response_channels:
- 1234567890
- 9876543210
`
``Nếu kênh chính của chủ đề nằm trong danh sách này thì chủ đề đó cũng sẽ không được đề cập.
Các kênh phản hồi miễn phí cũng **bỏ qua chuỗi tự động** — bot trả lời nội tuyến thay vì tạo ra một chuỗi mới cho mỗi tin nhắn. Điều này giúp kênh có thể sử dụng được như một bề mặt trò chuyện nhẹ. Nếu bạn muốn hoạt động phân luồng, đừng liệt kê kênh là phản hồi miễn phí (thay vào đó hãy sử dụng luồng
@mention
` bình thường).
####
`Discord.auto_thread
``**Loại:** boolean — **Mặc định:**
`true
``Khi được bật, mọi
@mention
` trong kênh văn bản thông thường sẽ tự động tạo một chuỗi mới cho cuộc trò chuyện. Điều này giữ cho kênh chính luôn sạch sẽ và cung cấp cho mỗi cuộc trò chuyện lịch sử phiên riêng biệt. Khi một chuỗi được tạo, các tin nhắn tiếp theo trong chuỗi đó không yêu cầu
@mention
` — bot biết rằng nó đã tham gia. Đặt [XPROTECTX175XPROTECTX](#Discordthread_require_mention) thành
`true
` để tắt lối tắt trong chuỗi này cho các thiết lập nhiều bot.
Tin nhắn được gửi trong chuỗi hoặc DM hiện có không bị ảnh hưởng bởi cài đặt này. Các kênh được liệt kê trong
`Discord.free_response_channels
` hoặc
`Discord.no_thread_channels
` cũng bỏ qua tự động phân luồng và thay vào đó nhận phản hồi nội tuyến.
####
`Discord.reactions
``**Loại:** boolean — **Mặc định:**
`true
``Kiểm soát xem bot có thêm biểu tượng cảm xúc vào tin nhắn dưới dạng phản hồi trực quan hay không:
- 👀 được thêm khi bot bắt đầu xử lý tin nhắn của bạn
- ✅ được thêm khi phản hồi được gửi thành công
- ❌ thêm nếu xảy ra lỗi trong quá trình xử lý
Tắt tính năng này nếu bạn thấy các phản ứng gây mất tập trung hoặc nếu vai trò của bot không có quyền **Thêm phản ứng**.
####
`Discord.ignored_channels
``**Loại:** chuỗi hoặc danh sách — **Mặc định:**
[]
``ID kênh mà bot **không bao giờ** phản hồi, ngay cả khi trực tiếp
@mentioned
. Điều này có mức độ ưu tiên cao nhất — nếu một kênh nằm trong danh sách này thì bot sẽ âm thầm bỏ qua tất cả các tin nhắn ở đó, bất kể
`require_mention
,
`free_response_channels
` hay bất kỳ cài đặt nào khác.
``` yaml
# String format
Discord:
ignored_channels: "1234567890,9876543210"
# List format
Discord:
ignored_channels:
- 1234567890
- 9876543210
`
``Nếu kênh chính của chuỗi có trong danh sách này thì các tin nhắn trong chuỗi đó cũng bị bỏ qua.
####
`Discord.no_thread_channels
``**Loại:** chuỗi hoặc danh sách — **Mặc định:**
[]
``ID kênh nơi bot phản hồi trực tiếp trong kênh thay vì tự động tạo chuỗi. Điều này chỉ có hiệu lực khi
`auto_thread
` là
`true
` (mặc định). Trong các kênh này, bot phản hồi nội tuyến giống như một tin nhắn bình thường thay vì tạo ra một chuỗi mới.
``` yaml
Discord:
no_thread_channels:
- 1234567890 # Bot responds inline here
`
``Hữu ích cho các kênh dành riêng cho tương tác với bot, nơi các luồng sẽ tạo ra tiếng ồn không cần thiết.
####
`Discord.channel_prompts
``**Loại:** ánh xạ — **Mặc định:**
\{}
``Lời nhắc của hệ thống tạm thời trên mỗi kênh được đưa vào mỗi lượt trong kênh hoặc chuỗi Discord phù hợp mà không được lưu vào lịch sử bản ghi.
``` yaml
Discord:
channel_prompts:
"1234567890": |
This channel is for research tasks. Prefer deep comparisons,
citations, and concise synthesis.
"9876543210": |
This forum is for therapy-style support. Be warm, grounded,
and non-judgmental.
`
`Hành vi:
- ID kênh/chủ đề chính xác phù hợp sẽ giành chiến thắng.
- Nếu một tin nhắn đến bên trong một chủ đề hoặc bài đăng trên diễn đàn và chủ đề đó không có mục nhập rõ ràng, Hermes sẽ quay trở lại ID diễn đàn/kênh chính.
- Lời nhắc được áp dụng nhất thời trong thời gian chạy, vì vậy việc thay đổi chúng sẽ ảnh hưởng ngay lập tức đến các lượt trong tương lai mà không cần ghi lại lịch sử phiên trước đây.
####
`Discord.history_backfill
``**Loại:** boolean — **Mặc định:**
`true
``Khi được bật, bot sẽ khôi phục các tin nhắn kênh bị bỏ lỡ trên mỗi
@mention
. Với
`require_mention: true
, bot chỉ xử lý các tin nhắn gắn thẻ trực tiếp — mọi thứ khác trong kênh đều không hiển thị với bản ghi phiên. Chèn lấp lịch sử quét ngược qua lịch sử kênh gần đây khi được kích hoạt, thu thập thông báo giữa phản hồi cuối cùng của bot và đề cập hiện tại, đồng thời đưa chúng vào làm ngữ cảnh.
Hành vi theo bề mặt:
- **Kênh máy chủ** (với
`require_mention: true
): chèn lấp quét kênh kể từ phản hồi cuối cùng của bot. Hữu ích khi những người tham gia khác đăng bài trong khi bot chưa được xử lý.
- **Chủ đề**: chèn lấp chỉ quét chuỗi —
`channel.history()
` của Discord trên một chuỗi chỉ trả về tin nhắn của chuỗi đó chứ không trả về kênh chính. Đây là phạm vi phù hợp vì các chủ đề thường là các cuộc hội thoại độc lập.
- **DMs**: bỏ qua. Mọi tin nhắn DM đều kích hoạt bot, vì vậy bản ghi phiên đã hoàn tất — không có khoảng trống đề cập nào cần điền.
- **Các kênh phản hồi miễn phí** và **các chủ đề được tạo tự động bởi chính bot**: bị bỏ qua vì lý do tương tự — không đề cập đến cổng có nghĩa là không có khoảng cách.
Phiên của mỗi người dùng (
`group_sessions_per_user: true
, mặc định) cũng có lợi: phiên của người dùng thiếu ngữ cảnh do những người tham gia kênh khác đăng và tin nhắn của chính người dùng đó trước khi họ gắn thẻ bot. Chèn lấp lấp đầy cả hai khoảng trống.
``` yaml
Discord:
history_backfill: true # default
`
``Để tắt nó:
`YAML
Discord:
history_backfill: false
`
``> **Lưu ý:** Các tin nhắn đến *trong khi* bot đang xử lý (giữa trình kích hoạt và phản hồi của nó) sẽ không được ghi lại. Đây là một sự đơn giản hóa được chấp nhận — người dùng có thể gửi lại hoặc gắn thẻ lại.
####
`Discord.history_backfill_limit
``**Loại:** số nguyên — **Mặc định:**
`50
``Số lượng tin nhắn tối đa cần quét ngược khi khôi phục ngữ cảnh kênh. Trong thực tế, quá trình quét thường dừng sớm hơn nhiều — tại tin nhắn cuối cùng của bot trong kênh, đây là ranh giới tự nhiên giữa các lượt. Giới hạn này là giới hạn an toàn cho việc khởi động nguội và khoảng thời gian dài mà không có thông báo bot nào tồn tại trong lịch sử gần đây.
`YAML
Discord:
history_backfill: true
history_backfill_limit: 50
`
####
`group_sessions_per_user
``**Loại:** boolean — **Mặc định:**
`true
``Đây là cài đặt cổng chung (không dành riêng cho Discord) để kiểm soát xem người dùng trong cùng một kênh có lịch sử phiên riêng biệt hay không.
Khi
`true
: Alice và Bob nói chuyện trong
#research
, mỗi người đều có cuộc trò chuyện riêng với Hermes. Khi
`false
: toàn bộ kênh chia sẻ một bản ghi cuộc hội thoại và một vị trí tác nhân đang chạy.
`YAML
group_sessions_per_user: true
`
``Xem phần [Session Model](#session-model-in-Discord) ở trên để biết đầy đủ ý nghĩa của từng chế độ.
####
`display.tool_progress
``**Loại:** chuỗi — **Mặc định:**
"all"
` — **Giá trị:**
`off
,
`new
,
`all
,
`verbose
``Kiểm soát xem bot có gửi thông báo tiến trình trong cuộc trò chuyện trong khi xử lý hay không (ví dụ: "Đọc tệp...", "Đang chạy lệnh terminal..."). Đây là cài đặt cổng chung áp dụng cho tất cả các nền tảng.
`YAML
display:
tool_progress: "all" # off | new | all | verbose
`
-
`off
- không có thông báo tiến trình
-
`new
- chỉ hiển thị lệnh gọi công cụ đầu tiên mỗi lượt
-
`all
- hiển thị tất cả các cuộc gọi công cụ (cắt ngắn còn 40 ký tự trong thông báo cổng)
-
`verbose
- hiển thị đầy đủ chi tiết cuộc gọi công cụ (có thể tạo tin nhắn dài)
####
`display.tool_progress_command
``**Loại:** boolean — **Mặc định:**
`false
``Khi được bật, lệnh gạch chéo
/verbose
` có sẵn trong cổng, cho phép bạn chuyển qua các chế độ tiến trình công cụ (
`off → new → all → verbose → off
) mà không cần chỉnh sửa config.yaml.
``` yaml
display:
tool_progress_command: true
`
## Kiểm soát truy cập lệnh gạch chéo
Theo mặc định, mọi người dùng được phép đều có thể chạy mọi lệnh gạch chéo. Để chia danh sách cho phép của bạn thành **quản trị viên** (quyền truy cập lệnh gạch chéo đầy đủ) và **người dùng thông thường** (chỉ những lệnh bạn bật rõ ràng), hãy thêm
`allow_admin_from
` và
`user_allowed_commands
` vào khối
`extra
` của nền tảng Discord:
`YAML
gateway:
platforms:
Discord:
extra:
# Existing user allowlist (unchanged)
allow_from:
- "123456789012345678" # admin user ID
- "999888777666555444" # regular user ID
# NEW — admins get all slash commands (built-in + plugin)
allow_admin_from:
- "123456789012345678"
# NEW — non-admin allowed users can only run these slash commands.
# /help and /whoami are always allowed so users can see their access.
user_allowed_commands:
- status
- model
- history
# Optional: separate admin / command lists for server channels
group_allow_admin_from:
- "123456789012345678"
group_user_allowed_commands:
- status
`
``**Hành vi:**- Người dùng trong
`allow_admin_from
` cho một phạm vi (kênh DM hoặc máy chủ) có thể chạy **mọi** lệnh gạch chéo đã đăng ký — tích hợp VÀ đã đăng ký plugin — thông qua sổ đăng ký lệnh trực tiếp.
- Người dùng không có trong
`allow_admin_from
` chỉ có thể chạy các lệnh được liệt kê trong
`user_allowed_commands
, cộng với tầng luôn được phép:
/help
` và
/whoami
.
- Trò chuyện đơn giản (tin nhắn không gạch chéo) không bị ảnh hưởng. Người dùng không phải quản trị viên vẫn có thể nói chuyện với đại lý một cách bình thường; họ chỉ không thể kích hoạt các lệnh tùy ý.
- **Tương thích ngược:** nếu
`allow_admin_from
` không được đặt cho một phạm vi, việc đặt lệnh gạch chéo sẽ bị vô hiệu hóa cho phạm vi đó. Các cài đặt hiện tại tiếp tục hoạt động mà không có thay đổi nào.
- Trạng thái quản trị viên DM không bao hàm trạng thái quản trị viên kênh máy chủ. Mỗi phạm vi có danh sách quản trị viên riêng.
Sử dụng
/whoami
` để xem phạm vi hoạt động, cấp độ của bạn (quản trị viên / người dùng / không bị hạn chế) và lệnh gạch chéo nào bạn có thể chạy.
## Bộ chọn mô hình tương tác
Gửi
/model
` không có đối số trong kênh Discord để mở bộ chọn mô hình dựa trên thả xuống:
1. **Lựa chọn nhà cung cấp** — menu thả xuống Chọn hiển thị các nhà cung cấp có sẵn (tối đa 25).
2. **Lựa chọn mô hình** — menu thả xuống thứ hai chứa các mô hình cho nhà cung cấp đã chọn (tối đa 25).
Bộ chọn hết thời gian sau 120 giây. Chỉ những người dùng được ủy quyền (những người trong
`Discord_ALLOWED_USERS
) mới có thể tương tác với nó. Nếu bạn biết tên model, hãy nhập trực tiếp
/model <name>
.
## Lệnh gạch chéo gốc cho kỹ năng
Hermes tự động đăng ký các kỹ năng đã cài đặt dưới dạng **Lệnh ứng dụng Discord gốc**. Điều này có nghĩa là các kỹ năng xuất hiện trong menu
/
` tự động hoàn thành của Discord cùng với các lệnh tích hợp.
- Mỗi kỹ năng sẽ trở thành lệnh gạch chéo Discord (ví dụ:
/code-review
,
/ascii-art
)
- Kỹ năng chấp nhận tham số chuỗi
`args
` tùy chọn
- Discord có giới hạn 100 lệnh ứng dụng cho mỗi bot — nếu bạn có nhiều kỹ năng hơn số chỗ có sẵn, các kỹ năng bổ sung sẽ bị bỏ qua kèm theo cảnh báo trong nhật ký
- Các kỹ năng được đăng ký trong quá trình khởi động bot cùng với các lệnh tích hợp như
/model
,
/reset
` và
/background
``Không cần cấu hình bổ sung — mọi kỹ năng được cài đặt qua
`Hermes skills install
` sẽ tự động được đăng ký dưới dạng lệnh gạch chéo Discord trong lần khởi động lại cổng tiếp theo.
### Vô hiệu hóa đăng ký lệnh gạch chéo
Nếu bạn chạy nhiều cổng Hermes trên cùng một ứng dụng Discord (ví dụ: dàn dựng + sản xuất), chỉ một trong số chúng phải sở hữu đăng ký lệnh gạch chéo toàn cầu - nếu không, lần khởi động cuối cùng sẽ thắng và lượt đăng ký sẽ sụp đổ. Tắt đăng ký dấu gạch chéo trên cổng "người theo dõi":
``` yaml
gateway:
platforms:
Discord:
extra:
slash_commands: false # default: true
`
``Để lại điều này tại
`true
` trên cổng "chính" sẽ duy trì hoạt động bình thường - các lệnh trong menu
/
` toàn cầu dành cho các kỹ năng đã cài đặt và tích hợp sẵn.
## Gửi phương tiện (thẻ
`send_message
+
`MEDIA:
)
Bộ điều hợp Discord hỗ trợ tải lên tệp gốc cho mọi loại phương tiện phổ biến thông qua công cụ
`send_message
` và thẻ
`MEDIA:/path/to/file
` nội tuyến do tác nhân phát ra:
| Loại | Nó được phân phối như thế nào |
|---|---|
| Hình ảnh (PNG/JPG/WebP) | Tệp đính kèm hình ảnh Discord gốc với bản xem trước nội tuyến |
| GIF hoạt hình |
send_animation
` tải lên dưới dạng
`animation.gif
` để Discord phát nội tuyến (không phải dưới dạng hình thu nhỏ tĩnh) |
| Video (MP4/MOV) |
send_video
` — trình phát video gốc |
| Âm thanh / Giọng nói |
send_voice
` — tin nhắn thoại gốc khi có thể, nếu không thì đính kèm tệp |
| Tài liệu (PDF/ZIP/docx/v.v.) |
send_document
` — tệp đính kèm gốc có nút tải xuống |
Giới hạn kích thước mỗi lần tải lên của Discord tùy thuộc vào cấp tăng cường của máy chủ (25 MB miễn phí, tối đa 500 MB). Nếu Hermes nhận được HTTP 413, bộ điều hợp sẽ quay trở lại liên kết trỏ đến đường dẫn bộ đệm cục bộ thay vì bị lỗi âm thầm.
## Nhận các loại tệp tùy ý
Theo mặc định, bot lưu vào bộ nhớ đệm các nội dung tải lên khớp với danh sách cho phép tích hợp sẵn — hình ảnh, âm thanh, video, PDF, văn bản/markdown/csv/log, JSON/XML/YAML/TOML, zip, docx/xlsx/pptx. Mọi thứ khác (
.wav
,
.bin
, kết xuất tiện ích mở rộng tùy chỉnh) đều được ghi lại dưới dạng
`Unsupported document type
` và bị loại bỏ trước khi tác nhân nhìn thấy nó.
Để chấp nhận các loại tệp tùy ý, hãy bật
`Discord.allow_any_attachment
:
`YAML
Discord:
allow_any_attachment: true
# Optional — raise/disable the per-file size cap. Default is 32 MiB.
# The whole file is held in memory while being cached, so unlimited
# uploads carry a real memory cost.
max_attachment_bytes: 33554432 # bytes; 0 = unlimited
`
`Khi cờ này bật, mọi tệp đã tải lên sẽ được tải xuống, lưu vào bộ nhớ đệm trong
~/.Hermes/cache/documents/
` và hiển thị cho tổng đài viên dưới dạng sự kiện tin nhắn được nhập
`DOCUMENT
` với
`application/octet-stream
` MIME. Tác nhân nhận được ghi chú ngữ cảnh trỏ đến đường dẫn cục bộ (được dịch tự động cho các terminal được đóng hộp cát Docker/Modal thông qua
`to_agent_visible_cache_path
) và có thể kiểm tra tệp bằng
`terminal
` (
`ffprobe
,
`unzip
,
`file
,
`strings
, v.v.) hoặc
`read_file
. Nội dung tệp **không** được đưa vào dấu nhắc - chỉ có đường dẫn - vì vậy tải lên nhị phân không làm nổ tung cửa sổ ngữ cảnh.
Các định dạng văn bản đã biết đã có trong danh sách cho phép (
.txt
,
.md
,
.log
) tiếp tục được tự động chèn nội dung lên tới 100 KiB; hành vi đó không thay đổi khi cờ được bật.
Các loại env tương đương:
`Discord_ALLOW_ANY_ATTACHMENT=true
` và
`Discord_MAX_ATTACHMENT_BYTES=33554432
` (hoặc
`0
` không có giới hạn).
:::warning[Memory cost of unlimited]
Việc tắt giới hạn kích thước (
`max_attachment_bytes: 0
) có nghĩa là người dùng có thể thả một tệp nhiều GB vào bot và cổng sẽ đệm nó một cách nghiêm túc qua bộ nhớ trong khi lưu vào đĩa. Chỉ đặt cài đặt này trong các bản cài đặt một người dùng đáng tin cậy. Đối với các bot được chia sẻ, hãy giữ nguyên 32 MiB mặc định hoặc tăng nó lên một cách thận trọng.
:::
## Lời nhắc tương tác (làm rõ)
Khi nhân viên gọi đến công cụ
`clarify
` — để hỏi bạn thích phương pháp nào hơn, nhận phản hồi sau nhiệm vụ hoặc kiểm tra trước khi đưa ra một quyết định quan trọng — Discord sẽ hiển thị câu hỏi bằng **một nút cho mỗi lựa chọn**:`> Tôi nên sử dụng khung nào cho trang tổng quan?
>
> [1. Next.js] [2. Phối lại] [3. Astro] [Khác (nhập câu trả lời)]
Nhấp vào nút được đánh số để trả lời hoặc nhấp vào **Khác** để nhập phản hồi dạng tự do (tin nhắn tiếp theo bạn gửi trong kênh đó sẽ trở thành câu trả lời). Cuộc gọi
`clarify
` kết thúc mở (không có lựa chọn đặt trước) bỏ qua các nút và chỉ ghi tin nhắn tiếp theo của bạn.
Các nút sẽ tự vô hiệu hóa sau khi thực hiện lựa chọn để các lần nhấp trùng lặp không giải quyết được lời nhắc hai lần. Định cấu hình thời gian chờ phản hồi qua
`agent.clarify_timeout
` trong
~/.Hermes/config.yaml
` (giây
`600
` mặc định). Nếu bạn không phản hồi trong thời gian chờ, nhân viên sẽ bỏ chặn bằng một tin nhắn trọng điểm và điều chỉnh thay vì treo máy.
## Kênh chủ
Bạn có thể chỉ định một "kênh chính" để bot gửi tin nhắn chủ động (chẳng hạn như đầu ra công việc định kỳ, lời nhắc và thông báo). Có hai cách để thiết lập nó:
### Sử dụng lệnh gạch chéo
Nhập
/sethome
` vào bất kỳ kênh Discord nào có bot. Kênh đó trở thành kênh chủ.
### Cấu hình thủ công
Thêm những thứ này vào
~/.Hermes/.env
` của bạn:
``` bash
Discord_HOME_CHANNEL=123456789012345678
Discord_HOME_CHANNEL_NAME="#bot-updates"
`
``Thay thế ID bằng ID kênh thực tế (nhấp chuột phải → Sao chép ID kênh khi bật Chế độ nhà phát triển).
## Tin nhắn thoại
Đại lý Hermes hỗ trợ tin nhắn thoại Discord:
- **Tin nhắn thoại đến** được chép lời tự động bằng cách sử dụng nhà cung cấp STT đã định cấu hình:
`faster-whisper
` cục bộ (không có khóa), Groq Whisper (
`GROQ_API_KEY
) hoặc OpenAI Whisper (
`VOICE_TOOLS_OpenAI_KEY
).
- **Chuyển văn bản thành giọng nói**: Sử dụng
/voice tts
` để yêu cầu bot gửi phản hồi bằng giọng nói cùng với trả lời bằng văn bản.
- **Kênh thoại Discord**: Hermes cũng có thể tham gia kênh thoại, nghe người dùng nói và nói lại trong kênh.
Để biết hướng dẫn thiết lập và vận hành đầy đủ, hãy xem:
- [Voice Mode](/docs/user-guide/features/voice-mode)
- [Use Voice Mode with Hermes](/docs/guides/use-voice-mode-with-Hermes)
## Kênh diễn đàn
Các kênh diễn đàn Discord (loại 15) không chấp nhận tin nhắn trực tiếp — mọi bài đăng trong diễn đàn phải là một chủ đề. Hermes tự động phát hiện các kênh diễn đàn và tạo một bài đăng chủ đề mới bất cứ khi nào nó cần gửi đến đó, vì vậy
`send_message
, TTS, hình ảnh, tin nhắn thoại và tệp đính kèm đều hoạt động mà không cần xử lý đặc biệt từ đại lý.
- **Tên chủ đề** được lấy từ dòng đầu tiên của tin nhắn (tiền tố tiêu đề đánh dấu bị loại bỏ, giới hạn ở 100 ký tự). Khi thư chỉ ở dạng tệp đính kèm, tên tệp sẽ được sử dụng làm tên chuỗi dự phòng.
- **Các tệp đính kèm** đi kèm với thông báo bắt đầu của chuỗi mới — không có bước tải lên riêng biệt, không gửi một phần.
- **Một cuộc gọi, một chủ đề**: mỗi lần gửi diễn đàn sẽ tạo một chủ đề mới. Do đó, việc gửi liên tiếp tới cùng một diễn đàn sẽ tạo ra các chủ đề riêng biệt.
- **Khả năng phát hiện có ba lớp**: bộ đệm thư mục kênh trước tiên, bộ đệm thăm dò cục bộ quy trình thứ hai và đầu dò
`GET /channels/\{id}
` trực tiếp là phương án cuối cùng (kết quả của nó sau đó sẽ được ghi nhớ trong suốt vòng đời của quy trình).Làm mới thư mục (
/channels refresh
` trên các nền tảng hiển thị thư mục đó hoặc khởi động lại cổng) sẽ điền vào bộ đệm bất kỳ kênh diễn đàn nào được tạo sau khi bot khởi động.
## Khắc phục sự cố
### Bot đang online nhưng không trả lời tin nhắn`**Lý do**: Ý định nội dung tin nhắn bị vô hiệu hóa.
**Khắc phục**: Truy cập [Developer Portal](https://Discord.com/developers/applications) → ứng dụng của bạn → Bot → Ý định cổng đặc quyền → bật **Ý định nội dung tin nhắn** → Lưu thay đổi. Khởi động lại cổng.
### Lỗi "Ý định không được phép" khi khởi động`**Lý do**: Mã của bạn yêu cầu các ý định chưa được bật trong Cổng thông tin dành cho nhà phát triển.
**Khắc phục**: Kích hoạt cả ba Ý định cổng đặc quyền (Hiện diện, Thành viên máy chủ, Nội dung tin nhắn) trong cài đặt Bot, sau đó khởi động lại.
### Bot không thể xem tin nhắn trong một kênh cụ thể`**Lý do**: Vai trò của bot không có quyền xem kênh đó.
**Khắc phục**: Trong Discord, hãy đi tới cài đặt của kênh → Quyền → thêm vai trò của bot với **Xem kênh** và **Đọc lịch sử tin nhắn** được bật.
### 403 Lỗi bị cấm`**Lý do**: Bot thiếu các quyền cần thiết.
**Khắc phục**: Mời lại bot có quyền chính xác bằng cách sử dụng URL từ Bước 5 hoặc điều chỉnh thủ công quyền vai trò của bot trong Cài đặt máy chủ → Vai trò.`###Bot đang ngoại tuyến`**Nguyên nhân**: Cổng Hermes không chạy hoặc mã thông báo không chính xác.
**Khắc phục**: Kiểm tra xem
`Hermes gateway
` có đang chạy không. Xác minh
`Discord_BOT_TOKEN
` trong tệp
.env
` của bạn. Nếu gần đây bạn đặt lại mã thông báo, hãy cập nhật mã thông báo đó.
### "Người dùng không được phép" / Bot phớt lờ bạn`**Lý do**: ID người dùng của bạn không có trong
`Discord_ALLOWED_USERS
.
**Khắc phục**: Thêm ID người dùng của bạn vào
`Discord_ALLOWED_USERS
` trong
~/.Hermes/.env
` và khởi động lại cổng.`###Mọi người trong cùng một kênh đang chia sẻ bối cảnh một cách bất ngờ`**Lý do**:
`group_sessions_per_user
` bị vô hiệu hóa hoặc nền tảng không thể cung cấp ID người dùng cho các tin nhắn trong ngữ cảnh đó.
**Khắc phục**: Đặt cái này trong
~/.Hermes/config.yaml
` và khởi động lại cổng:
``` yaml
group_sessions_per_user: true
`
``Nếu bạn cố tình muốn có một cuộc trò chuyện trong phòng chung, hãy tắt nó đi — chỉ cần chờ lịch sử bản chép lại được chia sẻ và hành vi gián đoạn được chia sẻ.
## Bảo mật
:::warning
Luôn đặt
`Discord_ALLOWED_USERS
` (hoặc
`Discord_ALLOWED_ROLES
) để hạn chế người có thể tương tác với bot. Nếu không có, cổng sẽ từ chối tất cả người dùng theo mặc định như một biện pháp an toàn. Chỉ ủy quyền cho những người bạn tin cậy — những 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.
:::
### Kiểm soát truy cập dựa trên vai trò
Đối với các máy chủ nơi quyền truy cập được quản lý theo vai trò thay vì danh sách người dùng riêng lẻ (nhóm người kiểm duyệt, nhân viên hỗ trợ, công cụ nội bộ), hãy sử dụng
`Discord_ALLOWED_ROLES
` — danh sách ID vai trò được phân tách bằng dấu phẩy. Bất kỳ thành viên nào có một trong những vai trò đó đều được ủy quyền.
``` bash
# ~/.Hermes/.env — works alongside or instead of Discord_ALLOWED_USERS
Discord_ALLOWED_ROLES=987654321098765432,876543210987654321
`
``Ngữ nghĩa:
- **HOẶC với danh sách cho phép của người dùng.** Người dùng được ủy quyền nếu ID của họ nằm trong
`Discord_ALLOWED_USERS
` **hoặc** họ có bất kỳ vai trò nào trong
`Discord_ALLOWED_ROLES
.
- **Tự động kích hoạt Ý định của Thành viên Máy chủ.** Khi
`Discord_ALLOWED_ROLES
` được đặt, bot sẽ cho phép Ý định của Thành viên kết nối - cần thiết để Discord gửi thông tin vai trò cùng với hồ sơ thành viên.
- **ID vai trò, không phải tên.** Lấy chúng từ Discord: **Cài đặt người dùng → Nâng cao → BẬT Chế độ nhà phát triển**, sau đó nhấp chuột phải vào bất kỳ vai trò nào → **Sao chép ID vai trò**.
- **Dự phòng DM.** Trong DM, việc kiểm tra vai trò sẽ quét các bang hội lẫn nhau; người dùng có vai trò được phép trong bất kỳ máy chủ dùng chung nào cũng được ủy quyền trong DM.
Đây là mẫu ưa thích khi nhóm kiểm duyệt ngừng hoạt động — người kiểm duyệt mới có quyền truy cập vào thời điểm vai trò được cấp mà không cần chỉnh sửa
.env
` hoặc khởi động lại cổng.
### Đề cập tới Kiểm soát
Theo mặc định, Hermes chặn bot ping
@everyone
,
@here
` và đề cập đến vai trò, ngay cả khi phản hồi của bot có chứa các mã thông báo đó. Điều này ngăn cản nội dung người dùng nhắc nhở hoặc lặp lại bằng từ ngữ kém gửi thư rác đến toàn bộ máy chủ. Các ping
@user
` riêng lẻ và ping tham chiếu trả lời (chip "trả lời..." nhỏ) vẫn được bật để cuộc trò chuyện bình thường vẫn hoạt động.
Bạn có thể thư giãn các giá trị mặc định này thông qua env vars hoặc
`config.yaml
:
``` yaml
# ~/.Hermes/config.yaml
Discord:
allow_mentions:
everyone: false # allow the bot to ping @everyone / @here
roles: false # allow the bot to ping @role mentions
users: true # allow the bot to ping individual @users
replied_user: true # ping the author when replying to their message
`
`
``` bash
# ~/.Hermes/.env — env vars win over config.yaml
Discord_ALLOW_MENTION_EVERYONE=false
Discord_ALLOW_MENTION_ROLES=false
Discord_ALLOW_MENTION_USERS=true
Discord_ALLOW_MENTION_REPLIED_USER=true
`
:::tip
Để
`everyone
` và
`roles
` tại
`false
` trừ khi bạn biết chính xác lý do bạn cần chúng. Rất dễ dàng để LLM tạo ra chuỗi
@everyone
` bên trong phản hồi trông bình thường; không có sự bảo vệ này, điều đó sẽ thông báo cho mọi thành viên trong máy chủ của bạn.
:::Để 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).