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

Thiết lập Slack

Kết nối Hermes Agent 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.

Ứng dụng Slack cổ điển không được dùng nữa

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ầnGiá trị
Thư việnslack-bolt / slack_sdk cho Python (Chế độ ổ cắm)
Kết nốiWebSocket — không yêu cầu URL công khai
Cần có mã thông báo xác thựcMã thông báo Bot ( xoxb- ) + Mã thông báo cấp ứng dụng ( xapp- )
Nhận dạng người dùngID thành viên Slack (ví dụ: U01ABC2DEF3 )

Bước 1: Tạo ứng dụng Slack

  1. Truy cập 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.

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 viMục đích
chat:writeGửi tin nhắn dưới dạng bot
app_mentions:readPhá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:readLiệ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:readXem thông tin DM cơ bản
im:writeMở và quản lý DM
users:readTra cứu thông tin người dùng
files:writeTải file lên (hình ảnh, âm thanh, tài liệu)
Thiếu phạm vi = thiếu tính năng

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. Đây là những phạm vi thường bị bỏ qua nhất.

Phạm vi tùy chọn:

Phạm viMục đích
groups:readLiệ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
mẹo

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ệnYêu cầu?Mục đích
message.imCóBot nhận tin nhắn trực tiếp
message.channelsCó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ấtBot nhận được tin nhắn trong các kênh riêng tư mà nó được mời
app_mentionCóNgăn chặn lỗi Bolt SDK khi bot được @đề cập
  1. Nhấp vào Lưu thay đổi ở cuối trang
Thiếu đăng ký sự kiện là vấn đề thiết lập số 1

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 đến 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"
Nếu không có bước này, DM sẽ bị chặn hoàn toàn

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
mẹo

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:

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

hermes gateway setup    

# Select Slack when prompted

Sau đó khởi động cổng:

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ẻ.

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

mẹo

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​

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óaMặc địnhMô 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_threadtrueKhi false , tin nhắn kênh sẽ nhận được câu trả lờ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_broadcastfalseKhi 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​

# 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 được 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​

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

  

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

thông tin

Không giống như Discord và Telegram, Slack không có free_response_channels tương đương. Bộ điều hợp Slack yêu cầu @mention để bắt đầu cuộc trò chuyện trong các kênh. Tuy nhiên, khi bot có phiên hoạt động trong một chuỗi thì các phản hồi của chuỗi tiếp theo không cần phải đề cập. Trong DM, bot luôn phản hồi mà không cần đề cập.

Xử lý người dùng trái phép​

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:

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​

# 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 chép lại bằng cách sử dụng nhà cung cấp STT đã định cấu hình trước khi được tổng đài viên xử lý.

Ví dụ đầy đủ​

# 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ị ở đó

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 :

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

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:

{
  "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 qua auth.test khi khởi động. Cổng ánh xạ mỗi 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: local faster-whisper , 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

Khắc phục sự cố

Vấn đềGiải pháp
Bot không phản hồi DMXá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ênhSự 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 vào kênh bằng /invite @Hermes Agent
Bot không phản hồi với @đề cập trong kênh1) Kiểm tra sự kiện message.channels đã được đăng ký. 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à /invite bot
"Gửi tin nhắn tới ứng dụng này đã bị tắt" trong DMBậ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ênhMời bot vào kênh cùng /invite @Hermes Agent
Lỗi "miss_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ênKiể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 đổiBạ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 công khai)
  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. ✅ Phạm vi channels:history được thêm vào (dành cho các kênh công khai)
  5. ✅ Phạm vi groups:history được thêm vào (đối với 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

cảnh báo

**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.

  • Mã thông báo 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