Thiết lập Matrix

Hermes Agent tích hợp với Matrix, giao thức nhắn tin mở và liên kết. Matrix cho phép bạn chạy homeserver riêng hoặc sử dụng homeserver công khai như matrix.org — dù bằng cách nào, bạn vẫn kiểm soát được giao tiếp của mình. Bot kết nối qua SDK Python mautrix, xử lý tin nhắn thông qua pipeline Hermes Agent (bao gồm sử dụng công cụ, bộ nhớ và suy luận), và 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ỳ homeserver 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: cách Hermes hoạt động sau khi kết nối.

Cách Hermes hoạt động

Ngữ cảnh	Hành vi
DM	Hermes phản hồi mọi tin nhắn. Không cần @đề cập. Mỗi DM có phiên riêng. Đặt MATRIX_DM_MENTION_THREADS=true để bắt đầu thread khi bot được @đề cập trong DM.
Phòng	Mặc định, Hermes yêu cầu @đề cập để phản hồi. Đặt MATRIX_REQUIRE_MENTION=false hoặc thêm room ID vào MATRIX_FREE_RESPONSE_ROOMS cho phòng phản hồi tự do. Lời mời phòng được tự động chấp nhận.
Thread	Hermes hỗ trợ Matrix threads (MSC3440). Nếu bạn trả lời trong thread, Hermes giữ ngữ cảnh thread cô lập khỏi timeline phòng chính. Thread mà bot đã tham gia không yêu cầu đề cập.
Tự động tạo thread	Mặc định, Hermes tự động tạo thread cho mỗi tin nhắn nó phản hồi trong phòng. Điều này giữ các cuộc hội thoại cô lập. Đặt MATRIX_AUTO_THREAD=false để tắt.
Phòng chung nhiều người dùng	Mặc định, Hermes cô lập lịch sử phiên theo người dùng trong phòng. Hai người nói chuyện trong cùng phòng không chia sẻ bản ghi trừ khi bạn tắt tính năng này.

mẹo

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

Mô hình phiên trong Matrix

Mặc định:

• mỗi DM có phiên riêng
• mỗi thread 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 trong phòng đó

Được kiểm soát bởi config.yaml:

group_sessions_per_user: true

Chỉ đặt false nếu bạn muốn một cuộc hội thoại chung cho toàn bộ phòng:

group_sessions_per_user: false

Phiên chung có thể hữu ích cho phòng cộng tác, nhưng cũng có nghĩa:

• người dùng chia sẻ tăng trưởng ngữ cảnh và chi phí token
• tác vụ dài sử dụng nhiều công cụ của một người có thể làm phình ngữ cảnh của mọi người khác
• tác vụ đang chạy của một người có thể gián đoạn theo dõi của người khác trong cùng phòng

Cấu hình đề cập và threading

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

matrix:
  require_mention: true           # Yêu cầu @đề cập trong phòng (mặc định: true)
  free_response_rooms:            # Các phòng miễn yêu cầu đề cập
    - "!abc123:matrix.org"
  auto_thread: true               # Tự động tạo thread cho phản hồi (mặc định: true)
  dm_mention_threads: false       # Tạo thread khi @đề cập trong DM (mặc định: false)

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

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

ghi chú

Nếu bạn đang nâng cấp từ phiên bản chưa có MATRIX_REQUIRE_MENTION, bot trước đó phản hồi tất cả tin nhắn trong phòng. Để giữ hành vi đó, đặt MATRIX_REQUIRE_MENTION=false.

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

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

Bạn cần một tài khoản người dùng Matrix cho bot. Có một số cách:

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

Nếu bạn chạy homeserver riêng (Synapse, Conduit, Dendrite):

1. Sử dụng admin API hoặc công cụ đăng ký để tạo người dùng mới:

# Ví dụ Synapse
register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008

2. 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 Homeserver công khai khác

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

Tùy chọn C: Sử dụng tài khoản cá nhân

Bạn cũng có thể chạy Hermes bằng tài khoản cá nhân. Điều này có nghĩa bot đăng bài dưới danh nghĩa bạn — hữu ích cho trợ lý cá nhân.

Bước 2: Lấy Access Token

Hermes cần access token để xác thực với homeserver. Bạn có hai tùy chọn:

Tùy chọn A: Access Token (Khuyến nghị)

Cách đáng tin cậy nhất để lấy token:

Qua Element:

1. Đăng nhập Element bằng tài khoản bot.
2. Vào Settings → Help & About.
3. Cuộn xuống và mở rộng Advanced — access token được hiển thị ở đó.
4. Sao chép ngay lập tức.

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"
  }'

Kết quả trả về có trường access_token — sao chép nó.

Giữ an toàn access token

Access token cho phép truy cập đầy đủ vào tài khoản Matrix của bot. Không bao giờ chia sẻ công khai hoặc commit vào Git. Nếu bị lộ, thu hồi bằng cách đăng xuất tất 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 access token, bạn có thể cho Hermes ID người dùng và mật khẩu của bot. Hermes sẽ tự đăng nhập khi khởi động. Đơn giản hơn nhưng mật khẩu được lưu trong tệp .env.

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

Bước 3: Tìm Matrix User ID của bạn

Hermes Agent sử dụng Matrix User ID để kiểm soát ai có thể tương tác với bot. Matrix User ID có định dạng @username:server.

Để tìm:

1. Mở Element (hoặc ứng dụng Matrix ưa thích).
2. Nhấp avatar → Settings.
3. User ID được hiển thị ở đầu hồ sơ (ví dụ: @alice:matrix.org).

mẹo

Matrix User ID luôn bắt đầu bằng @ và chứa : theo sau bởi tên server. 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 (Khuyến nghị)

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

hermes gateway setup

Chọn Matrix khi được hỏi, sau đó cung cấp URL homeserver, access token (hoặc user ID + mật khẩu) và User ID được phép khi được yêu cầu.

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

Thêm vào tệp ~/.hermes/.env:

Sử dụng access token:

# Bắt buộc
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_ACCESS_TOKEN=***

# Tùy chọn: user ID (tự phát hiện từ token nếu bỏ qua)
# MATRIX_USER_ID=@hermes:matrix.example.org

# Bảo mật: giới hạn ai có thể tương tác với bot
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

# Nhiều người dùng được phép (phân cách bằng dấu phẩy)
# MATRIX_ALLOWED_USERS=@alice:matrix.example.org,@bob:matrix.example.org

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

# Bắt buộc
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_USER_ID=@hermes:matrix.example.org
MATRIX_PASSWORD=***

# Bảo mật
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 giữ ngữ cảnh của mỗi người tham gia cô lập trong phòng chung

Khởi động Gateway

Sau khi cấu hình xong, khởi động Matrix gateway:

hermes gateway

Bot sẽ kết nối đến homeserver và bắt đầu đồng bộ trong vài giây. Gửi tin nhắn — DM hoặc trong phòng nó đã tham gia — để kiểm tra.

mẹo

Bạn có thể chạy hermes gateway ở nền hoặc như dịch vụ systemd cho 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, cho phép bạn trò chuyện với bot trong phòng được mã hóa.

Yêu cầu

E2EE yêu cầu thư viện mautrix với extras mã hóa và thư viện C libolm:

# Cài đặt mautrix với hỗ trợ E2EE
pip install 'mautrix[encryption]'

# Hoặc cài đặt với hermes extras
pip install 'hermes-agent[matrix]'

Bạn cũng cần libolm được cài trên hệ thống:

# Debian/Ubuntu
sudo apt install libolm-dev

# macOS
brew install libolm

# Fedora
sudo dnf install libolm-devel

Bật E2EE

Thêm vào ~/.hermes/.env:

MATRIX_ENCRYPTION=true

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

• Lưu 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ị khi kết nối lần đầu
• Tự động giải mã tin nhắn đến và mã hóa tin nhắn đi
• Tự động tham gia phòng mã hóa khi được mời

Xác minh ký chéo (Khuyến nghị)

Nếu tài khoản Matrix của bạn đã bật ký chéo (mặc định trong Element), đặt khóa khôi phục để bot tự ký thiết bị khi khởi động. Nếu không, các ứng dụng Matrix khác có thể từ chối chia sẻ phiên mã hóa với bot sau khi xoay khóa thiết bị.

MATRIX_RECOVERY_KEY=EsT... khóa khôi phục của bạn ở đây

Nơi tìm: Trong Element, vào Settings → Security & Privacy → Encryption → khóa khôi phục của bạn (còn gọi là "Security Key"). Đây là khóa bạn được yêu cầu lưu khi thiết lập ký chéo lần đầu.

Mỗi lần khởi động, nếu MATRIX_RECOVERY_KEY được đặt, Hermes nhập khóa ký chéo từ kho lưu trữ bí mật an toàn của homeserver và ký thiết bị hiện tại. Thao tác này idempotent và an toàn để giữ bật vĩnh viễn.

cảnh báo

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

thông tin

Nếu mautrix[encryption] chưa được cài hoặc thiếu libolm, bot tự động quay lại client thuần (không mã hóa). Bạn sẽ thấy cảnh báo trong nhật ký.

Phòng chính

Bạn có thể chỉ định "phòng chính" nơi bot gửi tin nhắn chủ động (như đầu ra cron job, nhắc nhở và thông báo). Có hai cách để đặt:

Sử dụng lệnh Slash

Gõ /sethome trong bất kỳ phòng Matrix nào có bot. Phòng đó trở thành phòng chính.

Cấu hình thủ công

Thêm vào ~/.hermes/.env:

MATRIX_HOME_ROOM=!abc123def456:matrix.example.org

mẹo

Để tìm Room ID: trong Element, vào phòng → Settings → Advanced → Internal room ID được hiển thị ở đó (bắt đầu bằng !).

Khắc phục sự cố

Bot không phản hồi tin nhắn

Nguyên nhân: Bot chưa tham gia phòng, hoặc MATRIX_ALLOWED_USERS không bao gồm User ID của bạn.

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

"Failed to authenticate" / "whoami failed" khi khởi động

Nguyên nhân: Access token hoặc URL homeserver không đúng.

Khắc phục: Xác minh MATRIX_HOMESERVER trỏ đến homeserver của bạn (bao gồm https://, không có dấu gạch chéo cuối). Kiểm tra MATRIX_ACCESS_TOKEN hợp lệ — thử với curl:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-server/_matrix/client/v3/account/whoami

Nếu trả về thông tin người dùng, token hợp lệ. Nếu trả lỗi, tạo token mới.

Lỗi "mautrix not installed"

Nguyên nhân: Gói Python mautrix chưa được cài.

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

pip install 'mautrix[encryption]'

Hoặc với Hermes extras:

pip install 'hermes-agent[matrix]'

Lỗi mã hóa / "could not decrypt event"

Nguyên nhân: Thiếu khóa mã hóa, libolm chưa cài, hoặc thiết bị bot chưa được tin cậy.

Khắc phục:

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

Nâng cấp từ phiên bản trước có E2EE

Nếu bạn đã sử dụng Hermes với MATRIX_ENCRYPTION=true và đang nâng cấp lên phiên bản sử dụng crypto store dựa trên SQLite mới, danh tính mã hóa của bot đã thay đổi. Ứng dụng Matrix (Element) có thể cache khóa thiết bị cũ và từ chối chia sẻ phiên mã hóa với bot.

Triệu chứng: Bot kết nối và hiển thị "E2EE enabled" trong nhật ký, nhưng tất cả tin nhắn hiển thị "could not decrypt event" và bot không bao giờ phản hồi.

Đang xảy ra gì: Trạng thái mã hóa cũ (từ backend matrix-nio hoặc mautrix dựa trên serialization trước đó) không tương thích với crypto store SQLite mới. Bot tạo danh tính mã hóa mới, nhưng ứng dụng Matrix vẫn có khóa cũ được cache và sẽ không chia sẻ phiên mã hóa của phòng với thiết bị có khóa đã thay đổi. Đây là tính năng bảo mật Matrix — các ứng dụng coi khóa danh tính thay đổi cho cùng thiết bị là đáng ngờ.

Khắc phục (di chuyển một lần):

1. Tạo access token mới để nhận device ID mới. Cách đơn giản nhất:

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

   Sao chép access_token mới và cập nhật MATRIX_ACCESS_TOKEN trong ~/.hermes/.env.

2. Xóa trạng thái mã hóa cũ:

   rm -f ~/.hermes/platforms/matrix/store/crypto.db
   rm -f ~/.hermes/platforms/matrix/store/crypto_store.*

3. Đặt khóa khôi phục (nếu bạn dùng ký chéo — hầu hết người dùng Element dùng). Thêm vào ~/.hermes/.env:

   MATRIX_RECOVERY_KEY=EsT... khóa khôi phục của bạn ở đây

   Điều này cho phép bot tự ký với khóa ký chéo khi khởi động, để Element tin cậy thiết bị mới ngay lập tức. Nếu không, Element có thể coi thiết bị mới là chưa xác minh và từ chối chia sẻ phiên mã hóa. Tìm khóa khôi phục trong Element tại Settings → Security & Privacy → Encryption.

4. Buộc ứng dụng Matrix xoay phiên mã hóa. Trong Element, mở phòng DM với bot và gõ /discardsession. Điều này buộc Element tạo phiên mã hóa mới và chia sẻ với thiết bị mới của bot.

5. Khởi động lại gateway:

   hermes gateway run

   Nếu MATRIX_RECOVERY_KEY được đặt, bạn sẽ thấy Matrix: cross-signing verified via recovery key trong nhật ký.

6. Gửi tin nhắn mới. Bot sẽ giải mã và phản hồi bình thường.

ghi chú

Sau di chuyển, tin nhắn gửi trước nâng cấp không thể giải mã — khóa mã hóa cũ đã mất. Điều này chỉ ảnh hưởng giai đoạn chuyển tiếp; tin nhắn mới hoạt động bình thường.

mẹo

Cài đặt mới không bị ảnh hưởng. Di chuyển này chỉ cần thiết nếu bạn đã có E2EE hoạt động với phiên bản Hermes trước đó và đang nâng cấp.

Tại sao cần access token mới? Mỗi access token Matrix gắn với device ID cụ thể. Sử dụng lại cùng device ID với khóa mã hóa mới khiến ứng dụng Matrix khác không tin cậy thiết bị (chúng coi khóa danh tính thay đổi là vi phạm bảo mật tiềm ẩn). Token mới nhận device ID mới không có lịch sử khóa cũ, nên các ứng dụng khác tin cậy ngay lập tức.

Chế độ Proxy (E2EE trên macOS)

Matrix E2EE yêu cầu libolm, không thể biên dịch trên macOS ARM64 (Apple Silicon). Extra hermes-agent[matrix] chỉ dành cho Linux. Nếu bạn dùng macOS, chế độ proxy cho phép chạy E2EE trong container Docker trên máy ảo Linux trong khi tác nhân thực chạy gốc trên macOS với đầy đủ quyền truy cập tệp, bộ nhớ và kỹ năng cục bộ.

Cách hoạt động

macOS (Host):
  └─ hermes gateway
       ├─ api_server adapter ← lắng nghe trên 0.0.0.0:8642
       ├─ AIAgent ← nguồn sự thật duy nhất
       ├─ Sessions, bộ nhớ, kỹ năng
       └─ Truy cập tệp cục bộ (Obsidian, dự án, v.v.)

Linux VM (Docker):
  └─ hermes gateway (chế độ proxy)
       ├─ Matrix adapter ← giải mã/mã hóa E2EE
       └─ HTTP forward → macOS:8642/v1/chat/completions
           (không có khóa API LLM, không có tác nhân, không có suy luận)

Container Docker chỉ xử lý giao thức Matrix + E2EE. Khi tin nhắn đến, nó giải mã và chuyển tiếp văn bản đến host qua yêu cầu HTTP chuẩn. Host chạy tác nhân, gọi công cụ, tạo phản hồi và truyền ngược lại. Container mã hóa và gửi phản hồi đến Matrix. Tất cả phiên được hợp nhất — CLI, Matrix, Telegram và bất kỳ nền tảng nào khác chia sẻ cùng bộ nhớ và lịch sử hội thoại.

Bước 1: Cấu hình Host (macOS)

Bật API server để host chấp nhận yêu cầu đến từ container Docker.

Thêm vào ~/.hermes/.env:

API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key-here
API_SERVER_HOST=0.0.0.0

• API_SERVER_HOST=0.0.0.0 bind tất cả interface để container Docker có thể kết nối.
• API_SERVER_KEY bắt buộc cho bind không phải loopback. Chọn chuỗi ngẫu nhiên mạnh.
• API server chạy trên cổng 8642 mặc định (thay đổi bằng API_SERVER_PORT nếu cần).

Khởi động gateway:

hermes gateway

Bạn sẽ thấy API server khởi động cùng với các nền tảng khác đã cấu hình. Xác minh có thể truy cập từ VM:

# Từ Linux VM
curl http://<mac-ip>:8642/health

Bước 2: Cấu hình Container Docker (Linux VM)

Container cần thông tin xác thực Matrix và URL proxy. KHÔNG cần khóa API LLM.

docker-compose.yml:

services:
  hermes-matrix:
    build: .
    environment:
      # Thông tin xác thực Matrix
      MATRIX_HOMESERVER: "https://matrix.example.org"
      MATRIX_ACCESS_TOKEN: "syt_..."
      MATRIX_ALLOWED_USERS: "@you:matrix.example.org"
      MATRIX_ENCRYPTION: "true"
      MATRIX_DEVICE_ID: "HERMES_BOT"

      # Chế độ proxy — chuyển tiếp đến tác nhân host
      GATEWAY_PROXY_URL: "http://192.168.1.100:8642"
      GATEWAY_PROXY_KEY: "your-secret-key-here"
    volumes:
      - ./matrix-store:/root/.hermes/platforms/matrix/store

Dockerfile:

FROM python:3.11-slim

RUN apt-get update && apt-get install -y libolm-dev && rm -rf /var/lib/apt/lists/*
RUN pip install 'hermes-agent[matrix]'

CMD ["hermes", "gateway"]

Đó là toàn bộ container. Không cần khóa API cho OpenRouter, Anthropic hay bất kỳ nhà cung cấp suy luận nào.

Bước 3: Khởi động cả hai

1. Khởi động gateway host trước:

   hermes gateway

2. Khởi động container Docker:

   docker compose up -d

3. Gửi tin nhắn trong phòng Matrix mã hóa. Container giải mã, chuyển tiếp đến host và truyền phản hồi ngược lại.

Tham chiếu cấu hình

Chế độ proxy được cấu hình ở phía container (gateway mỏng):

Cài đặt	Mô tả
GATEWAY_PROXY_URL	URL của Hermes API server từ xa (ví dụ: http://192.168.1.100:8642)
GATEWAY_PROXY_KEY	Bearer token để xác thực (phải khớp API_SERVER_KEY trên host)
gateway.proxy_url	Giống GATEWAY_PROXY_URL nhưng trong config.yaml

Phía host cần:

Cài đặt	Mô tả
API_SERVER_ENABLED	Đặt true
API_SERVER_KEY	Bearer token (chia sẻ với container)
API_SERVER_HOST	Đặt 0.0.0.0 cho truy cập mạng
API_SERVER_PORT	Số cổng (mặc định: 8642)

Hoạt động với mọi nền tảng

Chế độ proxy không giới hạn Matrix. Bất kỳ bộ điều hợp nền tảng nào cũng có thể sử dụng — đặt GATEWAY_PROXY_URL trên bất kỳ gateway instance nào và nó sẽ chuyển tiếp đến tác nhân từ xa thay vì chạy cục bộ. Hữu ích cho bất kỳ deployment nào mà bộ điều hợp nền tảng cần chạy trong môi trường khác với tác nhân (cô lập mạng, yêu cầu E2EE, hạn chế tài nguyên).

mẹo

Tính liên tục phiên được duy trì qua header X-Hermes-Session-Id. API server của host theo dõi phiên theo ID này, nên cuộc hội thoại được giữ liên tục giữa các tin nhắn như khi dùng tác nhân cục bộ.

ghi chú

Giới hạn (v1): Tin nhắn tiến trình công cụ từ tác nhân từ xa không được chuyển tiếp — người dùng chỉ thấy phản hồi cuối cùng được truyền, không phải từng lệnh gọi công cụ. Lời nhắc phê duyệt lệnh nguy hiểm được xử lý ở phía host, không chuyển tiếp đến người dùng Matrix. Những điều này có thể được cải thiện trong các bản cập nhật tương lai.

Vấn đề đồng bộ / bot bị tụt lại

Nguyên nhân: Thực thi công cụ dài có thể trì hoãn vòng lặp đồng bộ, hoặc homeserver chậm.

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

Bot offline

Nguyên nhân: Hermes gateway không chạy, hoặc kết nối thất bại.

Khắc phục: Kiểm tra hermes gateway đang chạy. Xem đầu ra terminal để tìm thông báo lỗi. Vấn đề thường gặp: URL homeserver sai, access token hết hạn, homeserver không truy cập được.

"User not allowed" / Bot phớt lờ bạn

Nguyên nhân: User ID của bạn không có trong MATRIX_ALLOWED_USERS.

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

Bảo mật

cảnh báo

Luôn đặt MATRIX_ALLOWED_USERS để giới hạn ai có thể tương tác với bot. Nếu không, gateway từ chối tất cả người dùng mặc định như biện pháp an toàn. Chỉ thêm User ID của người bạn tin cậy — người dùng được ủy quyền có đầy đủ quyền truy cập khả năng của tác nhân, bao gồm sử dụng công cụ và truy cập hệ thống.

Để biết thêm thông tin về bảo mật triển khai Hermes Agent, xem Hướng dẫn bảo mật.

Ghi chú

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