Thiết lập Slack
Kết nối Đại lý Hermes với Slack dưới dạng bot bằng Chế độ ổ cắm. Chế độ ổ cắm sử dụng WebSockets thay vì điểm cuối HTTP công khai, do đó, phiên bản Hermes của bạn không cần phải có thể truy cập công khai - nó hoạt động đằng sau tường lửa, trên máy tính xách tay của bạn hoặc trên máy chủ riêng.
Classic Slack Apps Deprecated
Các ứng dụng Slack cổ điển (sử dụng API RTM) hoàn toàn không được dùng nữa kể từ tháng 3 năm 2025. Hermes sử dụng hiện đại Bolt SDK với Chế độ ổ cắm. Nếu bạn có một ứng dụng cổ điển cũ, bạn phải tạo một ứng dụng mới sau các bước dưới đây.
Tổng quan
| Thành phần | Giá trị |
|---|---|
| Thư viện |
Slack-bolt
/ Slack_SDK
cho Python (Chế độ ổ cắm) | | **Kết nối** | WebSocket — không yêu cầu URL công khai | | **Cần có mã thông báo xác thực** | Mã thông báo Bot (xoxb-
) + Mã thông báo cấp ứng dụng ( `xapp-
) | | Nhận dạng người dùng | ID thành viên Slack (ví dụ: `U01ABC2DEF3
) |
Bước 1: Tạo ứng dụng Slack
Cách nhanh nhất là dán bảng kê khai mà Hermes tạo cho bạn. Nó khai báo mọi lệnh gạch chéo tích hợp (
/btw
,
/stop
,
/model
, …), mọi phạm vi OAuth bắt buộc, mọi đăng ký sự kiện và bật Socket Chế độ - tất cả cùng một lúc.
Tùy chọn A: Từ bảng kê khai do Hermes tạo (được khuyến nghị)
- Tạo bảng kê khai:
Hermes Slack manifest --write
`
Cái này viết
~/.Hermes/Slack-manifest.JSON
` và in dán
hướng dẫn.
2. Vào [https://API.Slack.com/apps](https://API.Slack.com/apps) →
**Tạo ứng dụng mới** → **Từ bảng kê khai ứng dụng**
3. Chọn không gian làm việc của bạn, dán nội dung JSON, xem lại, nhấp vào **Tiếp theo**
→ **Tạo**
4. Chuyển sang **Bước 6: Cài đặt ứng dụng vào Workspace**. Bản kê khai
đã xử lý các phạm vi, sự kiện và lệnh gạch chéo cho bạn.
### Tùy chọn B: Từ đầu (thủ công)
1. Vào [https://API.Slack.com/apps](https://API.Slack.com/apps)
2. Nhấp vào **Tạo ứng dụng mới**
3. Chọn **Từ đầu**
4. Nhập tên ứng dụng (ví dụ: "Hermes Agent") và chọn không gian làm việc của bạn
5. Nhấp vào **Tạo ứng dụng**
Bạn sẽ truy cập trang **Thông tin cơ bản** của ứng dụng. Tiếp tục với
Bước 2–6 bên dưới.
---
## Bước 2: Cấu hình phạm vi Bot Token
Điều hướng đến **Tính năng → OAuth & Quyền** trong thanh bên. Cuộn đến **Phạm vi → Phạm vi mã thông báo Bot** và thêm thông tin sau:
| Phạm vi | Mục đích |
|-------|----------|
|
`chat:write
` | Gửi tin nhắn dưới dạng bot |
|
`app_mentions:read
` | Phát hiện khi @được đề cập trong kênh |
|
`channels:history
` | Đọc tin nhắn trên các kênh công cộng có bot |
|
`channels:read
` | Liệt kê và lấy thông tin về các kênh công cộng |
|
`groups:history
` | Đọc tin nhắn trong các kênh riêng tư mà bot được mời |
|
`im:history
` | Đọc lịch sử tin nhắn trực tiếp |
|
`im:read
` | Xem thông tin DM cơ bản |
|
`im:write
` | Mở và quản lý DM |
|
`users:read
` | Tra cứu thông tin người dùng |
|
`files:read
` | Đọc và tải xuống các tệp đính kèm, bao gồm ghi chú thoại/âm thanh |
|
`files:write
` | Tải file lên (hình ảnh, âm thanh, tài liệu) |
:::caution[Missing scopes = missing features]
Nếu không có
`channels:history
` và
`groups:history
, bot **sẽ không nhận được tin nhắn trong các kênh** —
nó sẽ chỉ hoạt động trong DM. Nếu không có
`files:read
, Hermes có thể trò chuyện nhưng **không thể đọc tệp đính kèm do người dùng tải lên** một cách đáng tin cậy.
Đây là những phạm vi thường bị bỏ qua nhất.
:::
**Phạm vi tùy chọn:**
| Phạm vi | Mục đích |
|-------|----------|
|
`groups:read
` | Liệt kê và lấy thông tin về các kênh riêng tư |
---
## Bước 3: Kích hoạt chế độ socket
Chế độ ổ cắm cho phép bot kết nối qua WebSocket thay vì yêu cầu URL công khai.
1. Trong thanh bên, đi tới **Cài đặt → Chế độ ổ cắm**
2. Chuyển **Bật chế độ ổ cắm** sang BẬT
3. Bạn sẽ được nhắc tạo **Mã thông báo cấp ứng dụng**:
- Đặt tên nó là
`Hermes-socket
` (tên không quan trọng)
- Thêm phạm vi **
`connections:write
**
- Nhấp vào **Tạo**
4. **Sao chép mã thông báo** — nó bắt đầu bằng
`xapp-
. Đây là
`Slack_APP_TOKEN
` của bạn
:::tip
Bạn luôn có thể tìm hoặc tạo lại mã thông báo cấp ứng dụng trong **Cài đặt → Thông tin cơ bản → Mã thông báo cấp ứng dụng**.
:::
---
## Bước 4: Đăng ký sự kiện
Bước này rất quan trọng — nó kiểm soát những thông báo mà bot có thể nhìn thấy.
1. Trong thanh bên, đi tới **Tính năng → Đăng ký sự kiện**
2. Chuyển **Bật sự kiện** sang BẬT
3. Mở rộng **Đăng ký các sự kiện của bot** và thêm:| Sự kiện | Yêu cầu? | Mục đích |
|-------|-------------|---------|
|
`message.im
` | **Có** | Bot nhận tin nhắn trực tiếp |
|
`message.channels
` | **Có** | Bot nhận tin nhắn trong các kênh **công khai** mà nó được thêm vào |
|
`message.groups
` | **Được đề xuất** | Bot nhận được tin nhắn trong các kênh **riêng tư** mà nó được mời |
|
`app_mention
` | **Có** | Ngăn chặn lỗi Bolt SDK khi bot được @đề cập |
4. Nhấp vào **Lưu thay đổi** ở cuối trang
:::danger[Missing event subscriptions is the #1 setup issue]
Nếu bot hoạt động trong DM nhưng **không hoạt động trong kênh** thì bạn gần như chắc chắn đã quên thêm
`message.channels
` (đối với kênh công cộng) và/hoặc
`message.groups
` (đối với kênh riêng tư).
Nếu không có những sự kiện này, Slack sẽ không bao giờ gửi tin nhắn kênh tới bot.
:::
---
## Bước 5: Kích hoạt tab Tin nhắn
Bước này cho phép gửi tin nhắn trực tiếp tới bot. Nếu không có nó, người dùng sẽ thấy **"Gửi tin nhắn tới ứng dụng này đã bị tắt"** khi cố gắng nhắn tin cho bot.
1. Trong thanh bên, đi tới **Tính năng → Trang chủ ứng dụng**
2. Cuộn đến **Hiển thị tab**
3. Chuyển **Tab tin nhắn** sang BẬT
4. Kiểm tra **"Cho phép người dùng gửi lệnh và tin nhắn Slash từ tab tin nhắn"**
:::danger[Without this step, DMs are completely blocked]
Ngay cả với tất cả các phạm vi và đăng ký sự kiện chính xác, Slack sẽ không cho phép người dùng gửi tin nhắn trực tiếp đến bot trừ khi Tab Tin nhắn được bật. Đây là yêu cầu nền tảng Slack, không phải vấn đề cấu hình Hermes.
:::
---
## Bước 6: Cài đặt ứng dụng vào Workspace
1. Trong thanh bên, đi tới **Cài đặt → Cài đặt ứng dụng**
2. Nhấp vào **Cài đặt vào Workspace**
3. Xem lại các quyền và nhấp vào **Cho phép**
4. Sau khi ủy quyền, bạn sẽ thấy **Mã thông báo OAuth của người dùng Bot** bắt đầu bằng
`xoxb-
5. **Sao chép mã thông báo này** — đây là
`Slack_BOT_TOKEN
` của bạn
:::tip
Nếu sau này bạn thay đổi phạm vi hoặc đăng ký sự kiện, bạn **phải cài đặt lại ứng dụng** để thay đổi
để có hiệu lực. Trang Cài đặt ứng dụng sẽ hiển thị biểu ngữ nhắc bạn làm như vậy.
:::
---
## Bước 7: Tìm User ID cho Allowlist
Hermes sử dụng Slack **ID thành viên** (không phải tên người dùng hoặc tên hiển thị) cho danh sách cho phép.
Để tìm ID thành viên:
1. Trong Slack, nhấp vào tên hoặc hình đại diện của người dùng
2. Nhấp vào **Xem hồ sơ đầy đủ**
3. Nhấp vào nút **⋮** (thêm)
4. Chọn **Sao chép ID thành viên**
ID thành viên trông giống như
`U01ABC2DEF3
. Bạn cần tối thiểu ID thành viên của riêng bạn.
---
## Bước 8: Cấu hình Hermes
Thêm phần sau vào tệp
~/.Hermes/.env
` của bạn:
``` bash
# Required
Slack_BOT_TOKEN=xoxb-your-bot-token-here
Slack_APP_TOKEN=xapp-your-app-token-here
Slack_ALLOWED_USERS=U01ABC2DEF3 # Comma-separated Member IDs
# Optional
Slack_HOME_CHANNEL=C01234567890 # Default channel for cron/scheduled messages
Slack_HOME_CHANNEL_NAME=general # Human-readable name for the home channel (optional)
`
``Hoặc chạy thiết lập tương tác:
``` bash
Hermes gateway setup # Select Slack when prompted
`
``Sau đó khởi động cổng:
`bash
Hermes gateway # Foreground
Hermes gateway install # Install as a user service
sudo Hermes gateway install --system # Linux only: boot-time system service
`
---
## Bước 9: Mời Bot vào kênh
Sau khi khởi động cổng, bạn cần **mời bot** vào bất kỳ kênh nào mà bạn muốn nó phản hồi:
`
/invite @Hermes Agent
`
``Bot sẽ **không** tự động tham gia các kênh. Bạn phải mời nó vào từng kênh riêng lẻ.
---
## Lệnh gạch chéo
Mỗi lệnh Hermes (
/btw
,
/stop
,
/new
,
/model
,
/help
, ...)
là một lệnh gạch chéo Slack gốc — chính xác là cách chúng hoạt động trên Telegram
và Discord. Nhập
/
` vào Slack và bộ chọn tự động hoàn thành liệt kê mọi
Lệnh Hermes với mô tả của nó.
Tóm lại: Hermes gửi kèm bản kê khai ứng dụng Slack được tạo (xem
Bước 1, Tùy chọn A) khai báo mọi lệnh trong
[XPROTECTX67XPROTECTX](https://GitHub.com/NousResearch/Hermes-agent/blob/main/Hermes_CLI/commands.py)
như một lệnh gạch chéo. Trong Chế độ ổ cắm, Slack định tuyến sự kiện lệnh
thông qua WebSocket bất kể trường
`url
` của tệp kê khai.
### Làm mới lệnh gạch chéo sau khi cập nhật
Khi Hermes thêm các lệnh mới (ví dụ: sau
`Hermes update
), hãy tạo lại
bảng kê khai và cập nhật ứng dụng Slack của bạn:
`bash
Hermes Slack manifest --write
`
``Sau đó trong Slack:
1. Mở [https://API.Slack.com/apps](https://API.Slack.com/apps) →
ứng dụng Hermes của bạn
2. **Tính năng → Bản kê khai ứng dụng → Chỉnh sửa**
3. Dán nội dung mới của
~/.Hermes/Slack-manifest.JSON
4. **Lưu**. Slack sẽ nhắc cài đặt lại ứng dụng nếu phạm vi hoặc dấu gạch chéo
các lệnh đã thay đổi.
### Legacy
/Hermes <subcommand
` vẫn hoạt động
Để tương thích ngược với các bảng kê khai cũ hơn, bạn vẫn có thể nhập
/Hermes btw run the tests
- Hermes định tuyến theo cách tương tự như
/btw
chạy thử nghiệm
. Free-form questions also work:
/Hermes là gì
thời tiết?
` được coi như một tin nhắn thông thường.
### Sử dụng các lệnh bên trong các luồng (tiền tố
!cmd
)Bản thân Slack chặn các lệnh gạch chéo gốc bên trong các câu trả lời của luồng - hãy thử
/queue
` trong một chuỗi và Slack phản hồi bằng *"/hàng đợi không được hỗ trợ
trong chủ đề. Xin lỗi!"* Không có cài đặt phía ứng dụng nào kích hoạt lại chúng;
Slack không bao giờ giao chúng cho Hermes.
Để giải quyết vấn đề này, Hermes công nhận
!
` hàng đầu là sản phẩm thay thế
tiền tố lệnh hoạt động trong các luồng (và bất kỳ nơi nào khác). loại
!queue
,
!stop
,
!model GPT-5.4
, v.v. dưới dạng trả lời chuỗi thông thường —
Hermes xử lý nó giống hệt với hình thức gạch chéo và trả lời tương tự
chủ đề.
Chỉ mã thông báo đầu tiên được kiểm tra dựa trên danh sách lệnh đã biết, vì vậy
các tin nhắn thông thường như
!nice work
` được chuyển đến đại lý không thay đổi.
### Nâng cao: chỉ phát ra mảng lệnh gạch chéo
Nếu bạn duy trì bảng kê khai Slack của mình bằng tay và chỉ muốn dấu gạch chéo
danh sách lệnh:
``` bash
Hermes Slack manifest --slashes-only > /tmp/slashes.JSON
`
``Dán mảng đó vào khóa
`features.slash_commands
` của bạn
bảng kê khai hiện có.
---
## Cách Bot phản hồi
Hiểu cách Hermes hành xử trong các bối cảnh khác nhau:
| Bối cảnh | Hành vi |
|----------|----------|
| **DM** | Bot trả lời mọi tin nhắn — không cần @mention |
| **Kênh** | Bot **chỉ phản hồi khi được đề cập @** (ví dụ:
@Hermes Agent what time is it?
). Trong các kênh, Hermes trả lời bằng một chuỗi đính kèm tin nhắn đó. |
| **Chủ đề** | Nếu bạn @đề cập đến Hermes trong một chuỗi hiện có, nó sẽ trả lời trong cùng một chuỗi đó. Sau khi bot có một phiên hoạt động trong một chuỗi, **các câu trả lời tiếp theo trong chuỗi đó không yêu cầu @mention** — bot sẽ theo dõi cuộc trò chuyện một cách tự nhiên. |
:::tip
Trong các kênh, hãy luôn @đề cập đến bot để bắt đầu cuộc trò chuyện. Sau khi bot hoạt động trong một chuỗi, bạn có thể trả lời trong chuỗi đó mà không cần đề cập đến nó. Bên ngoài chuỗi, các tin nhắn không có @mention sẽ bị bỏ qua để tránh nhiễu trong các kênh bận.
:::
---
## Tùy chọn cấu hình
Ngoài các biến môi trường bắt buộc từ Bước 8, bạn có thể tùy chỉnh hành vi của bot Slack thông qua
~/.Hermes/config.yaml
.
### Hành vi chủ đề và trả lời
``` yaml
platforms:
Slack:
# Controls how multi-part responses are threaded
# "off" — never thread replies to the original message
# "first" — first chunk threads to user's message (default)
# "all" — all chunks thread to user's message
reply_to_mode: "first"`extra:
# Whether to reply in a thread (default: true).
# When false, channel messages get direct channel replies instead
# of threads. Messages inside existing threads still reply in-thread.
reply_in_thread: true
# Also post thread replies to the main channel
# (Slack's "Also send to channel" feature).
# Only the first chunk of the first reply is broadcast.
reply_broadcast: false
`
| Chìa khóa | Mặc định | Mô tả |
|------|----------|-------------|
|
`platforms.Slack.reply_to_mode
` |
"first"
` | Chế độ phân luồng cho tin nhắn nhiều phần:
"off"
,
"first"
` hoặc
"all"
` |
|
`platforms.Slack.extra.reply_in_thread
` |
`true
` | Khi
`false
, tin nhắn kênh nhận được phản hồi trực tiếp thay vì chuỗi. Tin nhắn bên trong chuỗi hiện có vẫn trả lời trong chuỗi. |
|
`platforms.Slack.extra.reply_broadcast
` |
`false
` | Khi
`true
, các câu trả lời theo chủ đề cũng được đăng lên kênh chính. Chỉ đoạn đầu tiên được phát sóng. |
### Cách ly phiên
``` yaml
# Global setting — applies to Slack and all other platforms
group_sessions_per_user: true
`
``Khi
`true
` (mặc định), mỗi người dùng trong kênh chia sẻ sẽ có phiên trò chuyện riêng biệt của riêng họ. Hai người nói chuyện với Hermes trong
#general
` sẽ có lịch sử và bối cảnh riêng biệt.
Đặt thành
`false
` nếu bạn muốn chế độ cộng tác trong đó toàn bộ kênh chia sẻ một phiên trò chuyện. Xin lưu ý rằng điều này 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 và
/reset
` của một người dùng sẽ xóa phiên cho mọi người.
### Hành vi đề cập & kích hoạt
``` yaml
Slack:
# Require @mention in channels (this is the default behavior;
# the Slack adapter enforces @mention gating in channels regardless,
# but you can set this explicitly for consistency with other platforms)
require_mention: true
# Prevent thread auto-engagement: only reply to channel messages that
# contain an explicit @mention. With this OFF (default), Slack can
# "auto-engage" — remembering past mentions in a thread and following
# up on bot-message replies, and resuming active sessions without a
# fresh mention. With strict_mention ON, every new channel message
# must @mention the bot before Hermes will respond.
strict_mention: false
# Custom mention patterns that trigger the bot
# (in addition to the default @mention detection)
mention_patterns:
- "hey Hermes"
- "Hermes,"
# Text prepended to every outgoing message
reply_prefix: ""
`
:::tip[When to use XPROTECTX99XPROTECTX]
Đặt giá trị này thành
`true
` trong không gian làm việc bận rộn, nơi hành vi "bot ghi nhớ chuỗi này" mặc định của Slack khiến người dùng ngạc nhiên — ví dụ: một chuỗi hỗ trợ công nghệ dài mà bot đã trợ giúp ngay từ đầu và bạn muốn nó giữ im lặng trừ khi được ping lại một cách rõ ràng. DM và các phiên tương tác tích cực không bị ảnh hưởng.
:::
:::info
Slack hỗ trợ cả hai mẫu:
@mention
` theo mặc định cần có để bắt đầu cuộc trò chuyện nhưng bạn có thể chọn không tham gia các kênh cụ thể thông qua
`Slack_FREE_RESPONSE_CHANNELS
` (ID kênh được phân tách bằng dấu phẩy) hoặc
`Slack.free_response_channels
` trong
`config.yaml
. Sau khi bot có phiên hoạt động trong một chuỗi, các câu trả lời tiếp theo của chuỗi sẽ không cần được đề cập. Trong DM, bot luôn phản hồi mà không cần đề cập.
:::
### Danh sách kênh được phép (
`allowed_channels
)
Giới hạn bot ở một nhóm kênh Slack cố định — hữu ích khi bot được mời vào nhiều kênh nhưng chỉ phản hồi ở một số kênh. Khi được đặt, các tin nhắn từ các kênh KHÔNG có trong danh sách này sẽ **bị bỏ qua âm thầm**, ngay cả khi bot là
@mentioned
.
**DM được miễn** khỏi bộ lọc này, vì vậy người dùng được ủy quyền luôn có thể liên hệ với bot bằng tin nhắn trực tiếp.
``` yaml
Slack:
allowed_channels:
- "C0123456789" # #ops
- "C0987654321" # #incident-response
`
``Hoặc thông qua env var (được phân tách bằng dấu phẩy):
`
``` bash
Slack_ALLOWED_CHANNELS="C0123456789,C0987654321"
`
``Hành vi:
- Trống / không đặt → không hạn chế (tương thích ngược hoàn toàn).
- Không trống → ID kênh phải có trong danh sách hoặc thông báo sẽ bị loại bỏ trước khi chạy bất kỳ cổng nào khác (yêu cầu đề cập,
`free_response_channels
, v.v.).
- ID kênh Slack bắt đầu bằng
`C
` (công khai),
`G
` (riêng tư) hoặc
`D
` (DM). Tra cứu chúng thông qua bảng "Chi tiết kênh mở" → "Giới thiệu" của Giao diện người dùng Slack hoặc qua API.
Xem thêm: [admin/user slash command split](../../reference/slash-commands.md#permissions-and-adminuser-split).
### Xử lý người dùng trái phép
``` yaml
Slack:
# What happens when an unauthoriZed user (not in Slack_ALLOWED_USERS) DMs the bot
# "pair" — prompt them for a pairing code (default)
# "ignore" — silently drop the message
unauthoriZed_dm_behavior: "pair"
`
``Bạn cũng có thể đặt cài đặt này trên toàn cầu cho tất cả các nền tảng:
``` yaml
unauthoriZed_dm_behavior: "pair"
`
``Cài đặt dành riêng cho nền tảng trong
`Slack:
` được ưu tiên hơn cài đặt chung.
### Phiên âm giọng nói
`YAML
# Global setting — enable/disable automatic transcription of incoming voice messages
stt_enabled: true
`
``Khi
`true
` (mặc định), các tin nhắn âm thanh đến sẽ tự động được phiên âm bằng cách sử dụng nhà cung cấp STT đã định cấu hình trước khi được tác nhân xử lý.
### Ví dụ đầy đủ
``` yaml
# Global gateway settings
group_sessions_per_user: true
unauthoriZed_dm_behavior: "pair"
stt_enabled: true
# Slack-specific settings
Slack:
require_mention: true
unauthoriZed_dm_behavior: "pair"
# Platform config
platforms:
Slack:
reply_to_mode: "first"
extra:
reply_in_thread: true
reply_broadcast: false
`
---
## Kênh chủ
Đặt
`Slack_HOME_CHANNEL
` thành ID kênh nơi Hermes sẽ gửi tin nhắn theo lịch trình,
kết quả công việc định kỳ và các thông báo chủ động khác. Để tìm ID kênh:
1. Nhấp chuột phải vào tên kênh trong Slack
2. Nhấp vào **Xem chi tiết kênh**
3. Cuộn xuống phía dưới — ID Kênh được hiển thị ở đó
``` bash
Slack_HOME_CHANNEL=C01234567890
`
``Đảm bảo bot đã được **mời vào kênh** (
/invite @Hermes Agent
).
---
## Hỗ trợ nhiều không gian làm việc
Hermes có thể kết nối đồng thời với **nhiều không gian làm việc Slack** bằng một phiên bản cổng duy nhất. Mỗi không gian làm việc được xác thực độc lập bằng ID người dùng bot riêng.
### Cấu hình
Cung cấp nhiều mã thông báo bot dưới dạng **danh sách được phân tách bằng dấu phẩy** trong
`Slack_BOT_TOKEN
:
`bash
# Multiple bot tokens — one per workspace
Slack_BOT_TOKEN=xoxb-workspace1-token,xoxb-workspace2-token,xoxb-workspace3-token
# A single app-level token is still used for Socket Mode
Slack_APP_TOKEN=xapp-your-app-token
`
``Hoặc trong
~/.Hermes/config.yaml
:
``` yaml
platforms:
Slack:
token: "xoxb-workspace1-token,xoxb-workspace2-token"
`
### Tệp mã thông báo OAuth
Ngoài mã thông báo trong môi trường hoặc cấu hình, Hermes còn tải mã thông báo từ **tệp mã thông báo OAuth** tại:
`
~/.Hermes/Slack_tokens.JSON
`
``Tệp này là ID nhóm ánh xạ đối tượng JSON tới các mục nhập mã thông báo:
`JSON
{
"T01ABC2DEF3": {
"token": "xoxb-workspace-token-here",
"team_name": "My Workspace"
}
}
`
``Mã thông báo từ tệp này được hợp nhất với bất kỳ mã thông báo nào được chỉ định qua
`Slack_BOT_TOKEN
. Mã thông báo trùng lặp sẽ tự động được loại bỏ.
### Cách thức hoạt động
- **Mã thông báo đầu tiên** trong danh sách là mã thông báo chính, được sử dụng cho kết nối Chế độ ổ cắm (AsyncApp).
- Mỗi mã thông báo được xác thực thông qua
`auth.test
` khi khởi động. Cổng ánh xạ từng
`team_id
` tới
`WebCLIent
` và
`bot_user_id
` của chính nó.
- Khi có tin nhắn đến, Hermes sử dụng đúng ứng dụng khách dành riêng cho không gian làm việc để phản hồi.
-
`bot_user_id
` chính (từ mã thông báo đầu tiên) được sử dụng để tương thích ngược với các tính năng yêu cầu một danh tính bot duy nhất.
---
## Tin nhắn thoại
Hermes hỗ trợ giọng nói trên Slack:
- **Gửi đến:** Tin nhắn thoại/âm thanh đượ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ộ, Groq Whisper (
`GROQ_API_KEY
) hoặc OpenAI Whisper (
`VOICE_TOOLS_OpenAI_KEY
)
- **Gửi đi:** Phản hồi TTS được gửi dưới dạng tệp đính kèm tệp âm thanh
---
## Lời nhắc trên mỗi kênh
Chỉ định lời nhắc hệ thống tạm thời cho các kênh Slack cụ thể. Lời nhắc được đưa vào mỗi lượt trong thời gian chạy — không bao giờ tồn tại trong lịch sử bản ghi — vì vậy các thay đổi sẽ có hiệu lực ngay lập tức.
``` yaml
Slack:
channel_prompts:
"C01RESEARCH": |
You are a research assistant. Focus on academic sources,
citations, and concise synthesis.
"C02ENGINEERING": |
Code review mode. Be precise about edge cases and
performance implications.
`
``Khóa là ID kênh Slack (tìm chúng qua chi tiết kênh → "Giới thiệu" → cuộn xuống cuối). Tất cả các tin nhắn trong kênh phù hợp đều nhận được lời nhắc dưới dạng hướng dẫn hệ thống nhất thời.
## Ràng buộc kỹ năng trên mỗi kênh
Tự động tải kỹ năng bất cứ khi nào phiên mới bắt đầu trong một kênh hoặc DM cụ thể. Không giống như lời nhắc trên mỗi kênh (được đưa vào mỗi lượt), liên kết kỹ năng sẽ đưa nội dung kỹ năng dưới dạng thông báo của người dùng vào **bắt đầu phiên** — nó trở thành một phần của lịch sử hội thoại và không cần phải tải lại vào các lượt tiếp theo.
Điều này lý tưởng cho DM hoặc các kênh có mục đích riêng (thẻ flash, bot hỏi đáp dành riêng cho từng miền, kênh phân loại hỗ trợ, v.v.) trong đó bạn không muốn bộ chọn kỹ năng riêng của mô hình quyết định có tải mỗi câu trả lời ngắn hay không.
`YAML
Slack:
channel_skill_bindings:
# DM channel — always runs in "german-flashcards" mode
- id: "D0ATH9TQ0G6"
skills:
- german-flashcards
# Research channel — preload multiple skills in order
- id: "C01RESEARCH"
skills:
- arxiv
- writing-plans
# Short form: single skill as a string
- id: "C02SUPPORT"
skill: hubspot-on-demand
`
``Ghi chú:
- Các ràng buộc khớp với ID kênh. Đối với các tin nhắn theo luồng trong kênh bị ràng buộc, luồng sẽ kế thừa liên kết của kênh mẹ.
- Kỹ năng chỉ được tải khi bắt đầu phiên (phiên mới hoặc sau khi tự động đặt lại). Nếu bạn thay đổi liên kết, hãy chạy
/new
` hoặc đợi phiên tự động đặt lại để phiên có hiệu lực.
- Kết hợp với
`channel_prompts
` để có âm/ràng buộc trên mỗi kênh theo hướng dẫn của kỹ năng.## Khắc phục sự cố
| Vấn đề | Giải pháp |
|----------|----------|
| Bot không phản hồi DM | Xác minh
`message.im
` có trong đăng ký sự kiện của bạn và ứng dụng đã được cài đặt lại |
| Bot hoạt động trong DM nhưng không hoạt động trong kênh | **Sự cố thường gặp nhất.** Thêm
`message.channels
` và
`message.groups
` vào đăng ký sự kiện, cài đặt lại ứng dụng và mời bot tham gia kênh bằng
/invite @Hermes Agent
` |
| Bot không phản hồi với @đề cập trong kênh | 1) Kiểm tra sự kiện
`message.channels
` đã được đăng ký chưa. 2) Bot phải được mời vào kênh. 3) Đảm bảo phạm vi
`channels:history
` được thêm vào. 4) Cài đặt lại ứng dụng sau khi thay đổi phạm vi/sự kiện |
| Bot bỏ qua tin nhắn trong các kênh riêng tư | Thêm cả đăng ký sự kiện
`message.groups
` và phạm vi
`groups:history
, sau đó cài đặt lại ứng dụng và bot
/invite
` |
| "Gửi tin nhắn tới ứng dụng này đã bị tắt" trong DM | Bật **Tab tin nhắn** trong cài đặt Trang chủ ứng dụng (xem Bước 5) |
| Lỗi "not_authed" hoặc "invalid_auth" | Tạo lại Mã thông báo Bot và Mã thông báo ứng dụng của bạn, cập nhật
.env
` |
| Bot phản hồi nhưng không đăng được kênh | Mời bot vào kênh cùng
/invite @Hermes Agent
` |
| Bot có thể trò chuyện nhưng không đọc được hình ảnh/file đã tải lên | Thêm
`files:read
, sau đó **cài đặt lại** ứng dụng. Hermes hiện hiển thị chẩn đoán truy cập tệp đính kèm trong cuộc trò chuyện khi Slack trả về lỗi phạm vi/xác thực/quyền. |
| Lỗi
`missing_scope
` | Thêm phạm vi được yêu cầu trong OAuth và Quyền, sau đó **cài đặt lại** ứng dụng |
| Ổ cắm ngắt kết nối thường xuyên | Kiểm tra mạng của bạn; Bolt tự động kết nối lại nhưng kết nối không ổn định gây ra hiện tượng lag |
| Đã thay đổi phạm vi/sự kiện nhưng không có gì thay đổi | Bạn **phải cài đặt lại** ứng dụng vào không gian làm việc của mình sau bất kỳ thay đổi đăng ký phạm vi hoặc sự kiện nào |
### Danh sách kiểm tra nhanh
Nếu bot không hoạt động trong các kênh, hãy xác minh **tất cả** những điều sau:
1. ✅ Sự kiện
`message.channels
` đã được đăng ký (đối với các kênh public)
2. ✅ Sự kiện
`message.groups
` đã được đăng ký (đối với kênh riêng)
3. ✅ Sự kiện
`app_mention
` đã được đăng ký
4. ✅ Đã thêm phạm vi
`channels:history
` (dành cho các kênh công cộng)
5. ✅ Đã thêm phạm vi
`groups:history
` (dành cho các kênh riêng tư)
6. ✅ Ứng dụng đã được **cài đặt lại** sau khi thêm phạm vi/sự kiện
7. ✅ Bot được **mời** vào kênh (
/invite @Hermes Agent
)
8. ✅ Bạn đang **@đề cập** bot trong tin nhắn của mình
---
## Bảo mật
:::warning
**Luôn đặt
`Slack_ALLOWED_USERS
** với ID thành viên của người dùng được ủy quyền. Nếu không có cài đặt này,
cổng sẽ **từ chối tất cả tin nhắn** theo mặc định như một biện pháp an toàn. Không bao giờ chia sẻ mã thông báo bot của bạn —
coi chúng như mật khẩu.
:::
- Token phải được lưu trữ trong
~/.Hermes/.env
` (quyền truy cập tệp
`600
)
- Xoay mã thông báo định kỳ thông qua cài đặt ứng dụng Slack
- Kiểm tra xem ai có quyền truy cập vào thư mục cấu hình Hermes của bạn
- Chế độ ổ cắm có nghĩa là không có điểm cuối công cộng nào bị lộ - ít bề mặt bị tấn công hơn