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

Thiết lập ma trận

Hermes Agent tích hợp với Matrix, giao thức nhắn tin mở, liên kết. Matrix cho phép bạn chạy máy chủ gia đình của riêng mình hoặc sử dụng máy chủ công cộng như Matrix.org — dù bằng cách nào, bạn vẫn giữ quyền kiểm soát thông tin liên lạc của mình. Bot kết nối thông qua matrix-nio SDK Python, 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 theo thời gian thực. Nó hỗ trợ văn bản, tệp đính kèm, hình ảnh, âm thanh, video và mã hóa đầu cuối tùy chọn (E2EE).

Hermes hoạt động với bất kỳ máy chủ gia đình Matrix nào - Synapse, Conduit, Dendrite hoặc Matrix.org.

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 sẽ hoạt động như thế nào sau khi được kết nối.

Cách Hermes cư xử

Bối cảnhHành vi
DMHermes trả lời mọi tin nhắn. Không cần @mention. Mỗi DM có phiên riêng.
PhòngTheo mặc định, Hermes yêu cầu @mention để phản hồi. Đặt MATRIX_REQUIRE_MENTION=false hoặc thêm ID phòng vào MATRIX_FREE_RESPONSE_ROOMS đối với các phòng phản hồi miễn phí. Lời mời vào phòng được tự động chấp nhận.
Chủ đềHermes hỗ trợ các luồng Ma trận (MSC3440). Nếu bạn trả lời trong một chuỗi, Hermes sẽ tách biệt bối cảnh của chuỗi đó với dòng thời gian của phòng chính. Các chủ đề mà bot đã tham gia không cần phải đề cập đến.
Tự động phân luồngTheo mặc định, Hermes tự động tạo một chuỗi cho mỗi tin nhắn mà nó phản hồi trong phòng. Điều này giữ cho cuộc trò chuyện bị cô lập. Đặt MATRIX_AUTO_THREAD=false để tắt.
Phòng chung với nhiều người dùngTheo mặc định, Hermes tách biệt lịch sử phiên của mỗi người dùng trong phòng. Hai người đang nói chuyện trong cùng một phòng 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

Bot tự động tham gia phòng khi được mời. Chỉ cần mời người dùng Ma trận của bot vào bất kỳ phòng nào, nó sẽ tham gia và bắt đầu phản hồi.

Mô hình phiên trong Ma trận​

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 phòng chung có phiên riêng của họ trong phòng đó

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

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

Cấu hình đề cập và phân luồng​

Bạn có thể định cấu hình hành vi đề cập và tự động phân luồng thông qua các biến môi trường hoặc config.yaml :

matrix:
  require_mention: true           

# Require @mention in rooms (default: true)
  free_response_rooms:            

# Rooms exempt from mention requirement
    - "!abc123:matrix.org"
  auto_thread: true               

# Auto-create threads for responses (default: true)

Hoặc thông qua các biến môi trường:

MATRIX_REQUIRE_MENTION=true
MATRIX_FREE_RESPONSE_ROOMS=!abc123:matrix.org,!def456:matrix.org
MATRIX_AUTO_THREAD=true

ghi chú

Nếu bạn đang nâng cấp từ phiên bản không có MATRIX_REQUIRE_MENTION thì bot trước đó đã trả lời tất cả tin nhắn trong phòng. Để duy trì hành vi đó, hãy đặt MATRIX_REQUIRE_MENTION=false .

Hướng dẫn này sẽ hướng dẫn bạn toàn bộ quá trình thiết lập — từ việc tạo tài khoản bot đến gửi tin nhắn đầu tiên của bạn.

Bước 1: Tạo tài khoản BotBạn cần có tài khoản người dùng Matrix cho bot. Có một số cách để làm điều này:

Tùy chọn A: Đăng ký trên Homeserver của bạn (Được khuyến nghị)​

Nếu bạn chạy máy chủ gia đình của riêng mình (Synapse, Conduit, Dendrite):

  1. Sử dụng API quản trị hoặc công cụ đăng ký để tạo người dùng mới:
# Synapse example
register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008

  1. Chọn tên người dùng như hermes — ID người dùng đầy đủ sẽ là @hermes:your-server.org .

Tùy chọn B: Sử dụng Matrix.org hoặc Máy chủ công cộng khác​

  1. Đi tới Element Web và tạo một tài khoản mới.
  2. Chọn tên người dùng cho bot của bạn (ví dụ: hermes-bot ).

Tùy chọn C: Sử dụng tài khoản của chính bạn​

Bạn cũng có thể chạy Hermes với tư cách là người dùng của riêng bạn. Điều này có nghĩa là bot đăng bài với tư cách là bạn - hữu ích cho trợ lý cá nhân.

Bước 2: Nhận Access Token

Hermes cần mã thông báo truy cập để xác thực với máy chủ gia đình. Bạn có hai lựa chọn:

Tùy chọn A: Mã thông báo truy cập (Được khuyến nghị)​

Cách đáng tin cậy nhất để nhận mã thông báo:

Qua phần tử:

  1. Đăng nhập vào Element bằng tài khoản bot.
  2. Đi tới Cài đặt → Trợ giúp & Giới thiệu.
  3. Cuộn xuống và mở rộng Nâng cao — mã thông báo truy cập được hiển thị ở đó.
  4. Sao chép ngay.

Thông qua API:

curl -X POST https://your-server/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "@hermes:your-server.org",
    "password": "your-password"
  }'

Phản hồi bao gồm trường access_token — sao chép trường đó.

Giữ mã thông báo truy cập của bạn an toàn

Mã thông báo truy cập cung cấp quyền truy cập đầy đủ vào tài khoản Matrix của bot. Không bao giờ chia sẻ nó một cách công khai hoặc cam kết nó với Git. Nếu bị xâm phạm, hãy thu hồi nó bằng cách đăng xuất tất cả các phiên của người dùng đó.

Tùy chọn B: Đăng nhập bằng mật khẩu​

Thay vì cung cấp mã thông báo truy cập, bạn có thể cung cấp cho Hermes ID người dùng và mật khẩu của bot. Hermes sẽ đăng nhập tự động khi khởi động. Việc này đơn giản hơn nhưng có nghĩa là mật khẩu được lưu trữ trong tệp .env của bạn.

MATRIX_USER_ID=@hermes:your-server.org
MATRIX_PASSWORD=your-password

Bước 3: Tìm ID người dùng ma trận của bạn

Hermes Agent sử dụng ID người dùng Matrix của bạn để kiểm soát ai có thể tương tác với bot. ID người dùng ma trận có định dạng @username:server .

Để tìm của bạn:

  1. Mở Element (hoặc ứng dụng khách Ma trận ưa thích của bạn).
  2. Nhấp vào hình đại diện của bạn → Cài đặt.
  3. ID người dùng của bạn được hiển thị ở đầu hồ sơ (ví dụ: @alice:matrix.org ).
mẹo

ID người dùng ma trận luôn bắt đầu bằng @ và chứa : theo sau là tên máy chủ. Ví dụ: @alice:matrix.org , @bob:your-server.com .

Bước 4: 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 Ma trận khi được nhắc, sau đó cung cấp URL máy chủ gia đình, mã thông báo truy cập (hoặc ID người dùng + mật khẩu) và ID người dùng được phép khi được yêu cầu.

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:

Sử dụng mã thông báo truy cập:

# Required
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_ACCESS_TOKEN=***

# Optional: user ID (auto-detected from token if omitted)
# MATRIX_USER_ID=@hermes:matrix.example.org

# Security: restrict who can interact with the bot
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

# Multiple allowed users (comma-separated)
# MATRIX_ALLOWED_USERS=@alice:matrix.example.org,@bob:matrix.example.org

Sử dụng mật khẩu đăng nhập:

# Required
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_USER_ID=@hermes:matrix.example.org
MATRIX_PASSWORD=***

# Security
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

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 mỗi người tham gia trong các phòng chung

Khởi động cổng​

Sau khi được định cấu hình, hãy khởi động Cổng ma trận:

hermes gateway

```Bot sẽ kết nối với máy chủ gia đình của bạn và bắt đầu đồng bộ hóa trong vòng vài giây. Gửi tin nhắn cho nó — DM hoặc trong phòng mà nó đã tham gia — để 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.

:::

#

# Mã hóa đầu cuối (E2EE)

Hermes hỗ trợ mã hóa đầu cuối Matrix, vì vậy bạn có thể trò chuyện với bot của mình trong các phòng được mã hóa.

#

## Yêu cầu

E2EE yêu cầu thư viện `matrix-nio` có tính năng bổ sung mã hóa và thư viện `libolm` C:

```bash
# Install matrix-nio with E2EE support
pip install 'matrix-nio[e2e]'

# Or install with hermes extras
pip install 'hermes-agent[matrix]'

Bạn cũng cần cài đặt libolm trên hệ thống của mình:

# Debian/Ubuntu
sudo apt install libolm-dev

# macOS
brew install libolm

# Fedora
sudo dnf install libolm-devel

Kích hoạt E2EE​

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

MATRIX_ENCRYPTION=true

Khi E2EE được bật, Hermes:

  • Lưu trữ khóa mã hóa trong ~/.hermes/platforms/matrix/store/ (cài đặt cũ: ~/.hermes/matrix/store/ )
  • Tải lên khóa thiết bị trong lần kết nối đầu tiên
  • Giải mã tin nhắn đến và tự động mã hóa tin nhắn gửi đi
  • Tự động tham gia phòng được mã hóa khi được mời
cảnh báo

Nếu bạn xóa thư mục ~/.hermes/platforms/matrix/store/, bot sẽ mất khóa mã hóa. Bạn sẽ cần xác minh lại thiết bị trong ứng dụng khách Matrix của mình. Sao lưu thư mục này nếu bạn muốn bảo toàn các phiên được mã hóa.

thông tin

Nếu matrix-nio[e2e] chưa được cài đặt hoặc thiếu libolm, bot sẽ tự động quay trở lại máy khách đơn giản (không được mã hóa). Bạn sẽ thấy cảnh báo trong nhật ký.

Phòng ở nhà

Bạn có thể chỉ định một "phòng 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ỳ phòng Ma trận nào có bot. Căn phòng đó trở thành phòng chủ.

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

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

MATRIX_HOME_ROOM=!abc123def456:matrix.example.org

mẹo

Để tìm ID phòng: trong Element, hãy đi tới phòng → Cài đặt → Nâng cao → ID phòng nội bộ được hiển thị ở đó (bắt đầu bằng ! ).

Khắc phục sự cố

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

Lý do: Bot chưa tham gia phòng hoặc MATRIX_ALLOWED_USERS không bao gồm ID người dùng của bạn.

Khắc phục: Mời bot vào phòng — nó tự động tham gia khi được mời. Xác minh ID người dùng của bạn ở định dạng MATRIX_ALLOWED_USERS (sử dụng định dạng @user:server đầy đủ). Khởi động lại cổng.

"Không xác thực được" / "whoami không thành công" khi khởi động​

Nguyên nhân: Mã thông báo truy cập hoặc URL máy chủ chủ không chính xác.

Khắc phục: Xác minh MATRIX_HOMESERVER trỏ đến máy chủ chủ của bạn (bao gồm https:// , không có dấu gạch chéo ở cuối). Kiểm tra xem MATRIX_ACCESS_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/_matrix/client/v3/account/whoami

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

lỗi "ma trận-nio chưa được cài đặt"​

Nguyên nhân: Gói Python matrix-nio chưa được cài đặt.

Khắc phục: Cài đặt nó:

pip install 'matrix-nio[e2e]'

Hoặc với các tính năng bổ sung của Hermes:

pip install 'hermes-agent[matrix]'

Lỗi mã hóa / "sự kiện không thể giải mã"​

Lý do: Thiếu khóa mã hóa, libolm chưa được cài đặt hoặc thiết bị của bot không đáng tin cậy.Khắc phục:

  1. Xác minh libolm đã được cài đặt trên hệ thống của bạn (xem phần E2EE ở trên).
  2. Đảm bảo MATRIX_ENCRYPTION=true được đặt trong .env của bạn.
  3. Trong ứng dụng khách Ma trận (Phần tử) của bạn, hãy đi tới hồ sơ của bot → Phiên → xác minh/tin cậy thiết bị của bot.
  4. Nếu bot vừa tham gia một phòng được mã hóa, nó chỉ có thể giải mã các tin nhắn được gửi sau khi nó tham gia. Tin nhắn cũ hơn không thể truy cập được.

Sự cố đồng bộ hóa / bot bị tụt lại phía sau​

Lý do: Việc thực thi công cụ trong thời gian dài có thể làm chậm vòng lặp đồng bộ hóa hoặc máy chủ gia đình chạy chậm.

Khắc phục: Vòng lặp đồng bộ hóa tự động thử lại sau mỗi 5 giây nếu có lỗi. Kiểm tra nhật ký Hermes để biết các cảnh báo liên quan đến đồng bộ hóa. Nếu bot liên tục bị tụt lại phía sau, hãy đảm bảo máy chủ gia đình của bạn có đủ tài nguyên.

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 vấn đề thường gặp: URL máy chủ gia đình sai, mã thông báo truy cập đã hết hạn, máy chủ gia đình 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 MATRIX_ALLOWED_USERS .

Khắc phục: Thêm ID người dùng của bạn vào MATRIX_ALLOWED_USERS trong ~/.hermes/.env và khởi động lại cổng. Sử dụng định dạng @user:server đầy đủ.

Bảo mật

cảnh báo

Luôn đặt MATRIX_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ú

  • Bất kỳ máy chủ gia đình nào: Hoạt động với Synapse, Conduit, Dendrite, Matrix.org hoặc bất kỳ máy chủ gia đình Matrix nào tuân thủ thông số kỹ thuật. Không yêu cầu phần mềm máy chủ gia đình cụ thể.
  • Liên kết: Nếu bạn đang sử dụng máy chủ gia đình được liên kết, bot có thể giao tiếp với người dùng từ các máy chủ khác — chỉ cần thêm ID @user:server đầy đủ của họ vào MATRIX_ALLOWED_USERS .
  • Tự động tham gia: Bot tự động chấp nhận lời mời vào phòng và tham gia. Nó bắt đầu phản hồi ngay sau khi tham gia.
  • Hỗ trợ phương tiện: Hermes có thể gửi và nhận hình ảnh, âm thanh, video và tệp đính kèm. Phương tiện được tải lên máy chủ gia đình của bạn bằng API kho lưu trữ nội dung Matrix.
  • Tin nhắn thoại gốc (MSC3245): Bộ điều hợp Matrix tự động gắn thẻ tin nhắn thoại gửi đi bằng cờ org.matrix.msc3245.voice. Điều này có nghĩa là phản hồi TTS và âm thanh giọng nói được hiển thị dưới dạng bong bóng thoại gốc trong Element và các ứng dụng khách khác hỗ trợ MSC3245, thay vì dưới dạng tệp đính kèm tệp âm thanh chung. Tin nhắn thoại đến có cờ MSC3245 cũng được xác định chính xác và chuyển sang chuyển giọng nói thành văn bản. Không cần cấu hình - thao tác này hoạt động tự động.