Thiết lập quan trọng nhất

Hermes Agent tích hợp với Matter Extreme 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 nhóm. Matter Extreme là một giải pháp thay thế Slack mã nguồn mở, tự lưu trữ — bạn chạy nó trên cơ sở hạ tầng của riêng mình, giữ toàn quyền kiểm soát dữ liệu của mình. Bot kết nối thông qua API REST API (v4) và WebSocket của Mattermost cho các sự kiện trong thời gian thực, xử lý thông báo thông qua quy trình Tác nhân Hermes (bao gồm việc sử dụng công cụ, bộ nhớ và lý luận) cũng như phản hồi trong thời gian thực. Nó hỗ trợ văn bản, tệp đính kèm, hình ảnh và lệnh gạch chéo.

Không cần thư viện Matter Extreme bên ngoài — bộ chuyển đổi sử dụng aiohttp vốn đã là một phần phụ thuộc của Hermes.

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 phiên bản Matter Extreme 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 công cộng/riêng tư	Hermes phản hồi khi bạn `@mention` nó. Không đề cập đến, Hermes bỏ qua tin nhắn.
Chủ đề	Nếu `MATTERMOST_REPLY_MODE=thread` , Hermes sẽ trả lời trong một chuỗi bên dưới tin nhắn của bạn. Bối cảnh chủ đề vẫn bị cô lập khỏi kênh chính.
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. 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.

mẹo

Nếu bạn muốn Hermes trả lời dưới dạng cuộc hội thoại theo chuỗi (được lồng trong tin nhắn gốc của bạn), hãy đặt MATTERMOST_REPLY_MODE=thread . Giá trị mặc định là off , gửi tin nhắn phẳng trong kênh.

Mô hình phiên trong Matter Extreme

Theo mặc định:

mỗi DM có phiên riêng
mỗi luồng 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 đó

Đ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 được chia sẻ cho toàn bộ kênh:

group_sessions_per_user: false

Phiên chia sẻ có thể hữu ích cho kênh 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
hoạt động 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 trên cùng một kênh

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 Matter Extreme đến gửi tin nhắn đầu tiên của bạn.

Bước 1: Kích hoạt tài khoản Bot

Tài khoản bot phải được kích hoạt trên máy chủ Matter Extreme của bạn trước khi bạn có thể tạo một tài khoản.

Đăng nhập vào Matter Extreme với tư cách Quản trị viên hệ thống.
Đi tới Bảng điều khiển hệ thống → Tích hợp → Tài khoản Bot.
Đặt Bật tạo tài khoản Bot thành true.
Nhấp vào Lưu.

thông tin

Nếu bạn không có quyền truy cập Quản trị viên hệ thống, hãy yêu cầu quản trị viên Matter Extreme bật tài khoản bot và tạo một tài khoản cho bạn.

Bước 2: Tạo tài khoản Bot1. Trong Mattermost, nhấp vào menu ☰ (trên cùng bên trái) → Tích hợp → Tài khoản Bot.

Nhấp vào Thêm tài khoản Bot.
Điền thông tin chi tiết:
- Tên người dùng: ví dụ: hermes
- Tên hiển thị: ví dụ: Hermes Agent
- Mô tả: tùy chọn
- Vai trò: Member là đủ
Nhấp vào Tạo tài khoản Bot.
Mattermost sẽ hiển thị mã thông báo bot. Sao chép nó ngay lập tức.

Mã thông báo chỉ hiển thị một lần

Mã thông báo bot chỉ được hiển thị một lần khi bạn tạo tài khoản bot. Nếu làm mất nó, bạn sẽ cần phải tạo lại nó từ cài đặt tài khoản bot. 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.

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

mẹo

Bạn cũng có thể sử dụng mã thông báo truy cập cá nhân thay vì tài khoản bot. Đi tới Hồ sơ → Bảo mật → Mã thông báo truy cập cá nhân → Tạo mã thông báo. Điều này hữu ích nếu bạn muốn Hermes đăng bài với tư cách là người dùng của riêng bạn chứ không phải là người dùng bot riêng biệt.

Bước 3: Thêm Bot vào kênh

Bot cần phải là thành viên của bất kỳ kênh nào mà bạn muốn nó phản hồi:

Mở kênh mà bạn muốn bot.
Nhấp vào tên kênh → Thêm thành viên.
Tìm kiếm tên người dùng bot của bạn (ví dụ: hermes ) và thêm nó.

Đối với DM, chỉ cần mở tin nhắn trực tiếp bằng bot - bot sẽ có thể trả lời ngay lập tức.

Bước 4: Tìm ID người dùng quan trọng nhất của bạn

Hermes Agent sử dụng ID người dùng quan trọng nhất của bạn để kiểm soát ai có thể tương tác với bot. Để tìm thấy nó:

Nhấp vào avatar của bạn (góc trên bên trái) → Hồ sơ.
ID người dùng của bạn được hiển thị trong hộp thoại hồ sơ — hãy nhấp vào nó để sao chép.

ID người dùng của bạn là một chuỗi gồm 26 ký tự chữ và số như 3uo8dkh1p7g1mfk49ear5fzs5c .

cảnh báo

ID người dùng của bạn không phải tên người dùng của bạn. Tên người dùng là tên xuất hiện sau @ (ví dụ: @alice ). ID người dùng là mã nhận dạng chữ và số dài mà Mattermost sử dụng nội bộ.

Thay thế: Bạn cũng có thể lấy ID người dùng của mình thông qua API:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-mattermost-server/api/v4/users/me | jq .id

mẹo

Để nhận ID kênh: nhấp vào tên kênh → Xem thông tin. ID kênh được hiển thị trong bảng thông tin. Bạn sẽ cần điều này nếu bạn muốn đặt kênh chính theo cách thủ công.

Bước 5: Cấu hình Hermes Agent

Tùy chọn A: Thiết lập tương tác (Được khuyến nghị)

Chạy lệnh thiết lập được hướng dẫn:

hermes gateway setup

Chọn Quan trọng nhất khi được nhắc, sau đó dán URL máy chủ, mã thông báo bot và ID người dùng khi được hỏi.

Tùy chọn B: Cấu hình thủ công

Thêm phần sau vào tệp ~/.hermes/.env của bạn:

# Required
MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=***
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c

# Multiple allowed users (comma-separated)
# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e

# Optional: reply mode (thread or off, default: off)
# MATTERMOST_REPLY_MODE=thread

# Optional: respond without @mention (default: true = require mention)
# MATTERMOST_REQUIRE_MENTION=false

# Optional: channels where bot responds without @mention (comma-separated channel IDs)
# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2

Cài đặt hành vi tùy chọn trong ~/.hermes/config.yaml :

group_sessions_per_user: true

group_sessions_per_user: true tách biệt bối cảnh của từng người tham gia bên trong các kênh và chuỗi được chia sẻ

Khởi động cổng

Sau khi được định cấu hình, hãy khởi động Cổng Matter Extreme:

hermes gateway

Bot sẽ kết nối với máy chủ Matter Extreme của bạn trong vòng vài giây. Gửi tin nhắn cho nó — DM hoặc đến kênh mà nó đã được thêm — để kiểm tra.

mẹo

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.

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 Matter Extreme nào có bot. Kênh đó trở thành kênh chủ.

Cấu hình thủ công

Thêm phần này vào ~/.hermes/.env của bạn:

MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn

Thay thế ID bằng ID kênh thực tế (nhấp vào tên kênh → Xem thông tin → sao chép ID).

Chế độ trả lời

Cài đặt MATTERMOST_REPLY_MODE kiểm soát cách Hermes đăng phản hồi:

Chế độ	Hành vi
`off` (mặc định)	Hermes đăng các tin nhắn phẳng trong kênh, giống như một người dùng bình thường.
`thread`	Hermes trả lời trong một chủ đề dưới tin nhắn ban đầu của bạn. Giữ cho các kênh luôn sạch sẽ khi có nhiều kênh qua lại.

Đặt nó trong ~/.hermes/.env :

MATTERMOST_REPLY_MODE=thread

Đề cập đến hành vi

Theo mặc định, bot chỉ phản hồi trong các kênh khi @mentioned . Bạn có thể thay đổi điều này:

Biến	Mặc định	Mô tả
`MATTERMOST_REQUIRE_MENTION`	`true`	Đặt thành `false` để trả lời tất cả tin nhắn trong các kênh (DM luôn hoạt động).
`MATTERMOST_FREE_RESPONSE_CHANNELS`	(không có)	ID kênh được phân tách bằng dấu phẩy trong đó bot phản hồi mà không có `@mention`, ngay cả khi require_mention là đúng.

Để tìm ID kênh trong Matter Extreme: hãy mở kênh, nhấp vào tiêu đề tên kênh và tìm ID trong URL hoặc chi tiết kênh.

Khi bot là @mentioned , nội dung đề cập sẽ tự động bị xóa khỏi tin nhắn trước khi xử lý.

Khắc phục sự cố

Bot không trả lời tin nhắn

Lý do: Bot không phải là thành viên của kênh hoặc MATTERMOST_ALLOWED_USERS không bao gồm ID người dùng của bạn.

Khắc phục: Thêm bot vào kênh (tên kênh → Thêm thành viên → tìm kiếm bot). Xác minh ID người dùng của bạn ở MATTERMOST_ALLOWED_USERS . Khởi động lại cổng.

403 Lỗi bị cấm

Lý do: Mã bot không hợp lệ hoặc bot không có quyền đăng bài trên kênh.

Khắc phục: Kiểm tra xem MATTERMOST_TOKEN trong tệp .env của bạn có đúng không. Đảm bảo tài khoản bot chưa bị vô hiệu hóa. Xác minh bot đã được thêm vào kênh. Nếu sử dụng mã thông báo truy cập cá nhân, hãy đảm bảo tài khoản của bạn có các quyền cần thiết.

Vòng lặp ngắt kết nối/kết nối lại WebSocket

Nguyên nhân: Mạng không ổn định, máy chủ Mattermost khởi động lại hoặc sự cố tường lửa/proxy với kết nối WebSocket.

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 → 60 giây). Kiểm tra cấu hình WebSocket của máy chủ của bạn — proxy ngược (nginx, Apache) cần định cấu hình tiêu đề nâng cấp WebSocket. Xác minh rằng không có tường lửa nào chặn kết nối WebSocket trên máy chủ Matter Extreme của bạn.

Đối với nginx, đảm bảo cấu hình của bạn bao gồm:

location /api/v4/websocket {
    proxy_pass http://mattermost-backend;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 600s;
}

"Xác thực không thành công" khi khởi động

Nguyên nhân: Mã thông báo hoặc URL máy chủ không chính xác.Khắc phục: Xác minh MATTERMOST_URL trỏ tới máy chủ Matter Extreme của bạn (bao gồm https:// , không có dấu gạch chéo ở cuối). Kiểm tra xem MATTERMOST_TOKEN có hợp lệ không - hãy thử với lệnh cuộn tròn:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-server/api/v4/users/me

Nếu điều này trả về thông tin người dùng bot của bạn thì mã thông báo hợp lệ. Nếu nó trả về lỗi, hãy tạo lại mã thông báo.

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: URL sai, mã thông báo đã hết hạn, Máy chủ Mattermost không thể truy cập được.

"Người dùng không được phép" / Bot phớt lờ bạn

Vì: ID người dùng của bạn không có trong MATTERMOST_ALLOWED_USERS .

Khắc phục: Thêm ID người dùng của bạn vào MATTERMOST_ALLOWED_USERS trong ~/.hermes/.env và khởi động lại cổng. Hãy nhớ: ID người dùng là chuỗi gồm 26 ký tự chữ và số, không phải @username của bạn.

Bảo mật

cảnh báo

Luôn đặt MATTERMOST_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 bảo mật việc triển khai Hermes Agent của bạn, hãy xem Hướng dẫn bảo mật.

Ghi chú

Thân thiện với khả năng tự lưu trữ: Hoạt động với mọi phiên bản Matter Extreme tự lưu trữ. Không cần đăng ký hoặc tài khoản Matter Extreme Cloud.
Không có phần phụ thuộc bổ sung: Bộ điều hợp sử dụng aiohttp cho HTTP và WebSocket, vốn đã có trong Hermes Agent.
Tương thích với Phiên bản nhóm: Hoạt động với cả Phiên bản nhóm Mattermost (miễn phí) và Phiên bản doanh nghiệp.

Cách Hermes cư xử

Mô hình phiên trong Matter Extreme​

Bước 1: Kích hoạt tài khoản Bot

Bước 2: Tạo tài khoản Bot1. Trong Mattermost, nhấp vào menu ☰ (trên cùng bên trái) → Tích hợp → Tài khoản Bot.

Bước 3: Thêm Bot vào kênh

Bước 4: Tìm ID người dùng quan trọng nhất của bạn

Bước 5: Cấu hình Hermes Agent

Tùy chọn A: Thiết lập tương tác (Được khuyến nghị)​

Tùy chọn B: Cấu hình thủ công​

Khởi động cổng​

Kênh chủ

Sử dụng lệnh gạch chéo​

Cấu hình thủ công​