Mattermost Hermes Agent — Chat nhóm tự host

Nếu nhóm của bạn đang dùng Mattermost, bạn đã biết sức hút của nó: giao diện và trải nghiệm giống Slack, nhưng máy chủ — và dữ liệu — vẫn nằm trên hạ tầng của chính bạn. Hermes Agent kết nối vào đó như một bot, giao tiếp qua REST API (v4) của Mattermost cùng WebSocket cho các sự kiện thời gian thực, để trợ lý của bạn có thể trả lời trong tin nhắn riêng và kênh nhóm mà không có gì rời khỏi mạng của bạn.

Không cần cài thêm thư viện nào: adapter dùng aiohttp, vốn đã có sẵn trong Hermes. Nó hoạt động với cả Mattermost Team Edition (miễn phí) và Enterprise Edition.

Hermes hoạt động thế nào trong Mattermost

Nơi bạn trò chuyện với nó	Điều gì xảy ra
Tin nhắn riêng (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	Hermes trả lời khi bạn `@mention` nó. Không có mention, nó bỏ qua tin nhắn.
Thread	Với `MATTERMOST_REPLY_MODE=thread`, câu trả lời lồng dưới tin nhắn của bạn và tách biệt khỏi kênh cha.
Kênh chia sẻ	Lịch sử phiên được tách riêng theo từng người dùng mặc định, nên hai người trong cùng một kênh không chia sẻ bản ghi hội thoại.

Hành vi cuối cùng được điều khiển bởi group_sessions_per_user trong config.yaml:

group_sessions_per_user: true   # each person keeps their own context

Chỉ đặt thành false nếu bạn thực sự muốn một cuộc hội thoại chia sẻ cho toàn bộ kênh. Phiên chia sẻ nghĩa là mọi người dùng chung ngữ cảnh tăng trưởng và chi phí token, và một tác vụ dài nhiều công cụ của một người có thể làm phình hoặc ngắt lần chạy của người khác.

Bước 1: Bật tài khoản Bot (phía quản trị viên)

Tài khoản bot phải được bật cho máy chủ trước khi bạn có thể tạo một cái:

Đăng nhập vào Mattermost với tư cách System Admin.
Vào System Console → Integrations → Bot Accounts.
Đặt Enable Bot Account Creation thành true, rồi bấm Save.

Không có quyền quản trị? Hãy nhờ quản trị viên Mattermost của bạn bật tài khoản bot và tạo một cái cho bạn.

Bước 2: Tạo tài khoản Bot

Bấm menu ☰ (góc trên bên trái) → Integrations → Bot Accounts → Add Bot Account.
Điền thông tin: Username như hermes, Display Name như Hermes Agent, và Role — Member là đủ.
Bấm Create Bot Account, rồi sao chép token ngay lập tức — nó chỉ hiển thị một lần. Mất rồi bạn sẽ phải tạo lại từ cài đặt tài khoản bot.

⚠️ Đừng bao giờ chia sẻ token hoặc commit nó lên Git. Ai giữ nó đều có toàn quyền kiểm soát bot.

Muốn agent đăng bài dưới tư cách người dùng của chính bạn thay vì một bot riêng? Tạo personal access token trong Profile → Security → Personal Access Tokens → Create Token.

Bước 3: Mời Bot vào kênh

Bot chỉ trả lời trong các kênh mà nó thuộc về:

Mở kênh → bấm tên kênh → Add Members.
Tìm username của bot (ví dụ hermes) và thêm vào.

Với DM, chỉ cần mở tin nhắn trực tiếp với bot — không cần mời.

Bước 4: Tìm User ID Mattermost của bạn

Hermes dùng User ID của bạn — không phải username — để quyết định ai được phép nói chuyện với bot:

Bấm avatar của bạn (góc trên bên trái) → Profile.
Hộp thoại hiển thị User ID của bạn: một chuỗi 26 ký tự chữ và số như 3uo8dkh1p7g1mfk49ear5fzs5c. Bấm vào để sao chép.

Bạn cũng có thể đọc nó từ API:

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

User ID của bạn không phải là @username bạn thấy trong tin nhắn. Dán username là lý do phổ biến nhất khiến bot im lặng.

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

Chạy thiết lập có hướng dẫn và chọn Mattermost khi được hỏi — nó sẽ hỏi URL máy chủ, token bot, và User ID của bạn:

hermes gateway setup

Hoặc cấu hình thủ công trong ~/.hermes/.env:

# Required
MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=your-bot-token
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c

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

# Optional: reply in a thread instead of flat messages (default: off)
# MATTERMOST_REPLY_MODE=thread

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

# Optional: channels where no @mention is needed (comma-separated channel IDs)
# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2

Rồi khởi động gateway:

hermes gateway

Bot kết nối tới máy chủ Mattermost của bạn trong vài giây. Gửi cho nó một DM, hoặc @mention nó trong kênh mà nó đã được thêm vào, để kiểm tra.

Bước 6: Các công tắc hành vi tùy chọn

Cài đặt	Nó làm gì
`MATTERMOST_REPLY_MODE`	`off` (mặc định) đăng tin nhắn phẳng; `thread` lồng câu trả lời dưới tin nhắn của bạn và giữ kênh bận rộn gọn gàng.
`MATTERMOST_REQUIRE_MENTION`	Mặc định `true`. Đặt thành `false` để trả lời mọi tin nhắn trong kênh (DM luôn hoạt động).
`MATTERMOST_FREE_RESPONSE_CHANNELS`	Các channel ID bỏ qua yêu cầu mention ngay cả khi mention được yêu cầu.
`MATTERMOST_HOME_CHANNEL`	Nơi tin nhắn chủ động đi đến — đầu ra cron, nhắc nhở, thông báo. Hoặc gõ `/sethome` trong một kênh.
`mattermost.allowed_channels`	Giới hạn bot vào một danh sách channel ID; tin nhắn từ bất kỳ nơi nào khác đều bị bỏ. DM được miễn.
`mattermost.channel_prompts`	Chèn system prompt tạm thời cho mỗi kênh — áp dụng mỗi lượt, không bao giờ lưu vào lịch sử bản ghi.

Khi bot được @mention, mention được gỡ khỏi tin nhắn trước khi xử lý, nên @hermes tóm tắt thread này đến như một chỉ thị sạch.

Khắc phục sự cố

Triệu chứng	Nguyên nhân khả dĩ	Cách sửa
Bot bỏ qua bạn trong kênh	Nó không ở trong kênh, hoặc User ID của bạn không có trong `MATTERMOST_ALLOWED_USERS`	Thêm bot vào kênh, xác minh User ID 26 ký tự, khởi động lại gateway
Bot không đăng được	Token không hợp lệ, hoặc bot thiếu quyền trong kênh đó	Kiểm tra `MATTERMOST_TOKEN`, xác nhận tài khoản đang hoạt động và là thành viên kênh
Ngắt kết nối liên tục	WebSocket rớt, máy chủ khởi động lại, hoặc vấn đề proxy/tường lửa	Adapter kết nối lại với backoff lũy thừa (2s → 60s); với nginx, đảm bảo header nâng cấp WebSocket đã được cấu hình
Không có gì xảy ra cả	Gateway không chạy, hoặc URL/token sai	Kiểm tra đầu ra `hermes gateway`, và rằng `MATTERMOST_URL` có `https://` và không có dấu gạch chéo cuối

Kiểm tra token trực tiếp bằng:

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

Bảo mật Bot

Luôn đặt MATTERMOST_ALLOWED_USERS. Không có nó, gateway từ chối tất cả người dùng theo mặc định như một biện pháp an toàn — và 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 agent, bao gồm sử dụng công cụ và truy cập hệ thống, nên hãy giữ danh sách thật chặt. Để có cái nhìn rộng hơn về việc tăng cường bảo mật cho một triển khai, xem hướng dẫn bảo mật chính thức.

Tiếp theo là gì?

Khi gateway đã chạy, Mattermost hoạt động như bất kỳ kênh Hermes nào khác: lệnh slash, tải tệp lên, ghi chú thoại, đầu ra cron gửi đến kênh nhà của bạn — tất cả trên hạ tầng bạn kiểm soát. Nếu bạn muốn dùng tùy chọn được lưu trữ, tích hợp Slack bao gồm lộ trình Socket Mode; nếu bạn chạy gateway trên nhiều máy, Hermes Relay kết nối chúng lại.