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 SDK Python `mautrix
, xử lý tin nhắn thông qua đường dẫn Tác nhân Hermes (bao gồm việc sử dụng công cụ, bộ nhớ và lý 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ỳ 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ả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. Đặt Matrix_DM_MENTION_THREADS=true để bắt đầu một chuỗi khi bot là
@mentioned ` trong DM. | | Phòng | Theo 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 cho 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ồng** | Theo 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ùng | Theo 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:

`YAML
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

:

``` 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)
  dm_mention_threads: false       # Create thread when @mentioned in DM (default: false)

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

``` bash
Matrix_REQUIRE_MENTION=true
Matrix_FREE_RESPONSE_ROOMS=!abc123:Matrix.org,!def456:Matrix.org
Matrix_AUTO_THREAD=true
Matrix_DM_MENTION_THREADS=false
Matrix_REACTIONS=true          # default: true — emoji reactions during processing

`

:::tip[Disabling reactions]
`Matrix_REACTIONS=false
` tắt phản ứng biểu tượng cảm xúc trong vòng đời xử lý (👀/❌/❌) mà bot đăng trên tin nhắn gửi đến. Hữu ích cho những phòng có sự kiện phản ứng ồn ào hoặc không được tất cả khách hàng tham gia hỗ trợ.

:::

:::note
Nếu bạn đang nâng cấp từ phiên bản không có 
`Matrix_REQUIRE_MENTION
` thì bot trước đó đã phản hồ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 Bot

Bạ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:

``` bash

# Synapse example
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 Máy chủ công cộng khác
1. Truy cập [Element Web](https://app.element.io) và tạo 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](https://app.element.io) 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:**

``` bash
curl -X POST https://your-server/_Matrix/CLIent/v3/login \

  -H "Content-Type: application/JSON" \
  -d '&#123;
    "type": "m.login.password",
    "user": "@Hermes:your-server.org",
    "password": "your-password"
  &#125;'

`
``Phản hồi bao gồm trường 
`access_token

 - sao chép nó.

:::warning[Keep your access token safe]
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. Điều 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.

``` bash
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

Đại lý Hermes 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 tuân theo định dạng 

@username:server

.

Để tìm của bạn:
1. Mở [Element](https://app.element.io) (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

).

:::tip
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 đại lý Hermes

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

``` bash
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:**

`bash

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

``` bash

# 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

:

``` yaml
group_sessions_per_user: true

`

- 
`group_sessions_per_user: true
` giúp 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:

`bash
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 
`mautrix
` có tính năng bổ sung mã hóa và thư viện 
`libolm
` C:

``` bash

# Install mautrix with E2EE support
pip install 'mautrix[encryption]'

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

``` bash

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

``` bash
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

### Xác minh chữ ký chéo (Được khuyến nghị)

Nếu tài khoản Matrix của bạn đã bật tính năng ký chéo (mặc định trong Element), hãy đặt khóa khôi phục để bot có thể tự ký thiết bị của nó khi khởi động. Nếu không có điều này, các máy khách 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ị.

``` bash
Matrix_RECOVERY_KEY=EsT... your recovery key here

`
``**Tìm ở đâu:** Trong Element, đi tới **Cài đặt** → **Bảo mật & quyền riêng tư** → **Mã hóa** → khóa khôi phục của bạn (còn được gọi là "Khóa bảo mật"). Đây là khóa bạn được yêu cầu lưu khi thiết lập ký chéo lần đầu tiên.

Trong mỗi lần khởi động, nếu 
`Matrix_RECOVERY_KEY
` được đặt, Hermes sẽ nhập khóa ký chéo từ bộ lưu trữ bí mật an toàn của máy chủ gia đình và ký thiết bị hiện tại. Điều này là bình thường và an toàn khi được kích hoạt vĩnh viễn.

:::warning[Deleting the crypto store]
Nếu bạn xóa 

~/.Hermes/platforms/Matrix/store/crypto.db

, bot sẽ mất danh tính mã hóa. Chỉ cần khởi động lại với cùng một ID thiết bị sẽ **không** khôi phục hoàn toàn — máy chủ gia đình vẫn giữ các khóa dùng một lần được ký bằng khóa nhận dạng cũ và các thiết bị ngang hàng không thể thiết lập phiên Olm mới.

Hermes phát hiện tình trạng này khi khởi động và từ chối bật E2EE, ghi nhật ký: 
`device XXXX has stale one-time keys on the server signed with a previous identity key

.**Khôi phục dễ dàng nhất: tạo mã thông báo truy cập mới** (nhận ID thiết bị mới không có lịch sử khóa cũ). Xem phần "Nâng cấp từ phiên bản trước bằng E2EE" bên dưới. Đây là đường dẫn đáng tin cậy nhất và tránh chạm vào cơ sở dữ liệu homeserver.

**Khôi phục thủ công** (nâng cao — giữ nguyên ID thiết bị):
1. Dừng Synapse và xóa thiết bị cũ khỏi cơ sở dữ liệu của nó:

`bash
   sudo systemctl stop Matrix-synapse
   sudo SQLite3 /var/lib/Matrix-synapse/homeserver.db "
     DELETE FROM e2e_device_keys_JSON WHERE device_id = 'DEVICE_ID' AND user_id = '@Hermes:your-server';
     DELETE FROM e2e_one_time_keys_JSON WHERE device_id = 'DEVICE_ID' AND user_id = '@Hermes:your-server';
     DELETE FROM e2e_fallback_keys_JSON WHERE device_id = 'DEVICE_ID' AND user_id = '@Hermes:your-server';
     DELETE FROM devices WHERE device_id = 'DEVICE_ID' AND user_id = '@Hermes:your-server';
   "
   sudo systemctl start Matrix-synapse

`
   Hoặc thông qua API quản trị Synapse (lưu ý ID người dùng được mã hóa URL):

`bash
   curl -X DELETE -H "Authorization: Bearer ADMIN_TOKEN" \
     'https://your-server/_synapse/admin/v2/users/%40Hermes%3Ayour-server/devices/DEVICE_ID'

`
   Lưu ý: việc xóa thiết bị qua API quản trị cũng có thể làm mất hiệu lực mã thông báo truy cập được liên kết. Bạn có thể cần tạo mã thông báo mới sau đó.
2. Xóa cửa hàng tiền điện tử cục bộ và khởi động lại Hermes:

`bash
   rm -f ~/.Hermes/platforms/Matrix/store/crypto.db*

   # restart Hermes

``Các máy khách Ma trận khác (Phần tử, lệnh ma trận) có thể lưu vào bộ đệm các khóa thiết bị cũ. Sau khi khôi phục, nhập 

/discardsession
` trong Element để buộc bot thực hiện phiên mã hóa mới.
:::

:::info
Nếu 
`mautrix[encryption]
` chưa được cài đặt hoặc 
`libolm
` bị thiếu, 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:

``` bash
Matrix_HOME_ROOM=!abc123def456:Matrix.example.org

`

## Danh sách phòng cho phép (
`allowed_rooms

)

Giới hạn bot trong một nhóm phòng Ma trận cố định. Khi được đặt, bot **chỉ** phản hồi trong các phòng có ID xuất hiện trong danh sách — tin nhắn từ bất kỳ phòng nào khác sẽ được âm thầm bỏ qua, ngay cả khi bot được đề cập.

**DM (phòng trò chuyện trực tiếp) được miễn** khỏi bộ lọc này, vì vậy người dùng được ủy quyền luôn có thể liên hệ trực tiếp với bot.

`YAML
Matrix:
  allowed_rooms:

    - "!abc123def456:Matrix.example.org"
    - "!opsroom789:Matrix.example.org"

`
``Hoặc thông qua env var (được phân tách bằng dấu phẩy):

``` bash
Matrix_ALLOWED_ROOMS="!abc123def456:Matrix.example.org,!opsroom789:Matrix.example.org"

`
``Hành vi:
- Trống / không đặt → không hạn chế (mặc định).

- Không trống → ID phòng phải có trong danh sách. Quá trình kiểm tra diễn ra **trước** bất kỳ cổng nào khác (yêu cầu đề cập, danh sách cho phép của người gửi, v.v.).
- Sử dụng **ID nội bộ** của phòng (

!abc...:server

), không phải bí danh của phòng (

#room:server

). Bạn có thể tìm thấy ID nội bộ của phòng trong Element thông qua Phòng → Cài đặt → Nâng cao.

Xem thêm: [admin/user slash command split](../../reference/slash-commands.md#permissions-and-adminuser-split).

:::tip
Để 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 ở dạng 
`Matrix_ALLOWED_USERS
` (sử dụng định dạng 

@user:server
` đầy đủ). Khởi động lại cổng.

### Bot vào phòng nhưng âm thầm bỏ từng tin nhắn (đồng hồ lệch)

**Lý do**: Đồng hồ hệ thống của máy chủ được đặt trước thời gian thực. Bộ điều hợp Ma trận áp dụng bộ lọc ân hạn khởi động 5 giây (
`event_ts &lt; startup_ts - 5

) để bỏ qua các sự kiện được phát lại từ lần đồng bộ hóa ban đầu. Khi đồng hồ treo tường chạy nhanh, mọi sự kiện đến trông có vẻ "cũ hơn thời điểm khởi động" và bị hủy trước khi đến trình xử lý tin nhắn — bot có vẻ như đã kết nối nhưng không bao giờ trả lời. Xem [#12614](https://GitHub.com/NousResearch/Hermes-agent/issues/12614).

**Triệu chứng**: Nhật ký cổng hiển thị 
`Matrix: dropped N live events as 'too old' more than 30s after startup

.

**Khắc phục**: Đồng bộ đồng hồ máy chủ với NTP và khởi động lại bot:

``` bash

# Debian/Ubuntu
sudo timedatectl set-ntp true
timedatectl status   # confirm "System clock synchroniZed: yes"

# macOS
sudo sntp -sS time.Apple.com

`

### "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ủ gia đình 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:

``` bash
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 "mautrix chưa được cài đặt"`**Nguyên nhân**: Gói Python 
`mautrix
` chưa được cài đặt.

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

`bash
pip install 'mautrix[encryption]'

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

`bash
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 Matrix (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.

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

:::tip
Nếu bạn cũng đã xóa 
`crypto.db
` theo cách thủ công, hãy xem cảnh báo "Xóa cửa hàng tiền điện tử" trong phần E2EE ở trên — có các bước bổ sung để xóa khóa một lần cũ khỏi máy chủ chủ.
:::

Nếu trước đây bạn đã sử dụng Hermes với 
`Matrix_ENCRYPTION=true
` và đang nâng cấp lên
một phiên bản sử dụng kho lưu trữ mật mã dựa trên SQLite mới, mã hóa của bot
danh tính đã thay đổi. Máy khách Matrix (Phần tử) của bạn có thể lưu trữ các khóa thiết bị cũ
và từ chối chia sẻ các phiên mã hóa với bot.

**Triệu chứng**: Bot kết nối và hiển thị "E2EE đã bật" trong nhật ký, nhưng tất cả
thông báo hiển thị "không thể giải mã sự kiện" và bot không bao giờ phản hồi.

**Chuyện gì đang xảy ra**: Trạng thái mã hóa cũ (từ 
`Matrix-nio
` trước đó hoặc
Phần phụ trợ 
`mautrix
` dựa trên tuần tự hóa) không tương thích với mật mã SQLite mới
cửa hàng. Bot tạo danh tính mã hóa mới, nhưng ứng dụng khách Matrix của bạn vẫn
đã lưu các khóa cũ vào bộ nhớ đệm 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 Ma trận -- khách hàng xử lý
đã thay đổi khóa nhận dạng cho cùng một thiết bị là đáng ngờ.

**Khắc phục** (di chuyển một lần):
1. **Tạo mã thông báo truy cập mới** để nhận ID thiết bị mới. Cách đơn giản nhất:

``` bash
   curl -X POST https://your-server/_Matrix/CLIent/v3/login \

     -H "Content-Type: application/JSON" \
     -d '&#123;
       "type": "m.login.password",
       "identifier": \&#123;"type": "m.id.user", "user": "@Hermes:your-server.org"&#125;,
       "password": "***",
       "initial_device_display_name": "Hermes Agent"
     &#125;'

``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ũ**:

``` bash
   rm -f ~/.Hermes/platforms/Matrix/store/crypto.db
   rm -f ~/.Hermes/platforms/Matrix/store/crypto_store.*

3. **Đặt khóa khôi phục của bạn** (nếu bạn sử dụng ký chéo - hầu hết người dùng Element đều làm như vậy). Thêm vào 

~/.Hermes/.env

:

`bash
   Matrix_RECOVERY_KEY=EsT... your recovery key here

``Điều này cho phép bot tự ký bằng các khóa ký chéo khi khởi động, vì vậy Element tin cậy thiết bị mới ngay lập tức. Nếu không có điều này, Element có thể coi thiết bị mới là chưa được xác minh và từ chối chia sẻ các phiên mã hóa. Tìm khóa khôi phục của bạn trong Element trong **Cài đặt** → **Bảo mật & quyền riêng tư** → **Mã hóa**.
4. **Buộc máy khách Ma trận của bạn xoay phiên mã hóa**. Trong phần tử,
   mở phòng DM có bot và gõ 

/discardsession

. Điều này buộc Element
   để tạo phiên mã hóa mới và chia sẻ nó với thiết bị mới của bot.
5. **Khởi động lại cổng**:

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

:::note
Sau khi di chuyển, các tin nhắn được gửi *trước* bản nâng cấp không thể giải mã được -- bản cũ
khóa mã hóa đã biến mất. Điều này chỉ ảnh hưởng đến quá trình chuyển đổi; tin nhắn mới hoạt động
bình thường.

:::

:::tip
**Các cài đặt mới không bị ảnh hưởng.** Việc di chuyển này chỉ cần thiết nếu bạn đã có
thiết lập E2EE đang hoạt động với phiên bản trước của Hermes và đang nâng cấp.

**Tại sao lại có mã thông báo truy cập mới?** Mỗi mã thông báo truy cập Matrix được liên kết với một thiết bị cụ thể
ID. Việc sử dụng lại cùng một ID thiết bị với các khóa mã hóa mới sẽ gây ra Ma trận khác
khách hàng không tin tưởng vào thiết bị (họ coi các khóa nhận dạng đã thay đổi có thể là một nguy cơ
vi phạm an ninh). Mã thông báo truy cập mới nhận được ID thiết bị mới không có khóa cũ
lịch sử, vì vậy các khách hàng khác tin tưởng nó ngay lập tức.
:::

## Chế độ proxy (E2EE trên macOS)

Matrix E2EE yêu cầu 
`libolm

, không biên dịch được trên macOS ARM64 (Apple Silicon). Phần bổ sung 
`Hermes-agent[Matrix]
` chỉ dành cho Linux. Nếu bạn đang sử dụng macOS, chế độ proxy cho phép bạn chạy E2EE trong bộ chứa Docker trên máy ảo Linux trong khi tác nhân thực tế chạy tự nhiên trên macOS với toàn quyền truy cập vào các tệp, bộ nhớ và kỹ năng cục bộ của bạn.

### Cách thức hoạt động

`
macOS (Host):
  └─ Hermes gateway
       ├─ API_server adapter ← listens on 0.0.0.0:8642
       ├─ AIAgent ← single source of truth
       ├─ Sessions, memory, skills
       └─ Local file access (Obsidian, projects, etc.)

Linux VM (Docker):
  └─ Hermes gateway (proxy mode)
       ├─ Matrix adapter ← E2EE decryption/encryption
       └─ HTTP forward → macOS:8642/v1/chat/completions
           (no LLM API keys, no agent, no inference)

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

### Bước 1: Cấu hình Host (macOS)Kích hoạt máy chủ API để máy chủ chấp nhận các yêu cầu đến từ vùng chứa Docker.

Thêm vào 

~/.Hermes/.env

:

``` bash
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
` liên kết với tất cả các giao diện để Docker container có thể tiếp cận được.

- Cần có 
`API_SERVER_KEY
` để liên kết không lặp lại. Chọn một chuỗi ngẫu nhiên mạnh mẽ.
- Máy chủ API chạy trên cổng 8642 theo mặc định (thay đổi bằng 
`API_SERVER_PORT
` nếu cần).

Bắt đầu cổng:

``` bash
Hermes gateway

`
``Bạn sẽ thấy máy chủ API khởi động cùng với mọi nền tảng khác mà bạn đã định cấu hình. Xác minh rằng nó có thể truy cập được từ VM:

`bash

# From the Linux VM
curl http://&lt;mac-ip>:8642/health

`

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

Vùng chứa cần thông tin xác thực Ma trận và URL proxy. Nó KHÔNG cần khóa API LLM.

**
`Docker-compose.yml

:**

``` yaml
services:
  Hermes-Matrix:
    build: .
    environment:

      # Matrix credentials
      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"

# Proxy mode — forward to host agent
      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

:**

`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ó khóa API cho OpenRouter, Anthropic hoặc bất kỳ nhà cung cấp suy luận nào.

### Bước 3: Bắt đầu cả hai
1. Khởi động cổng máy chủ trước:

`bash
   Hermes gateway

2. Khởi động vùng chứa Docker:

`bash
   Docker compose up -d

3. Gửi tin nhắn trong phòng Ma trận được mã hóa. Vùng chứa giải mã nó, chuyển tiếp nó đến máy chủ và truyền phản hồi trở lại.

### Tham khảo cấu hình

Chế độ proxy được định cấu hình ở **phía vùng chứa** (cổng mỏng):

| Cài đặt | Mô tả |
|----------|-------------|
| 
`GATEWAY_PROXY_URL
` | URL của máy chủ API Hermes từ xa (ví dụ: 
`http://192.168.1.100:8642

) |
| 
`GATEWAY_PROXY_KEY
` | Mã thông báo mang để xác thực (phải khớp 
`API_SERVER_KEY
` trên máy chủ) |
| 
`gateway.proxy_url
` | Tương tự như 
`GATEWAY_PROXY_URL
` nhưng ở 
`config.yaml
` |

Phía chủ nhà cần:

| Cài đặt | Mô tả |
|----------|-------------|
| 
`API_SERVER_ENABLED
` | Đặt thành 
`true
` |
| 
`API_SERVER_KEY
` | Mã thông báo mang (được chia sẻ với vùng chứa) |
| 
`API_SERVER_HOST
` | Đặt thành 
`0.0.0.0
` để truy cập mạng |
| 
`API_SERVER_PORT
` | Số cổng (mặc định: 
`8642

) |

### Hoạt động cho 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 nó — đặt 
`GATEWAY_PROXY_URL
` trên bất kỳ phiên bản cổng nào và nó sẽ chuyển tiếp đến tác nhân từ xa thay vì chạy cục bộ. Điều này hữu ích cho bất kỳ hoạt động triển khai 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ách ly mạng, yêu cầu E2EE, hạn chế về tài nguyên).

:::tip
Tính liên tục của phiên được duy trì thông qua tiêu đề 
`X-Hermes-Session-Id

. Máy chủ API của máy chủ theo dõi các phiên theo ID này, do đó, các cuộc hội thoại vẫn tiếp tục diễn ra trên các tin nhắn giống như với một tổng đài viên địa phương.

:::

:::note
**Hạn chế (v1):** Thông báo tiến trình công cụ từ tác nhân từ xa không được chuyển tiếp trở lại — người dùng chỉ nhìn thấy phản hồi cuối cùng được truyền trực tiếp chứ không phải các lệnh gọi công cụ riêng lẻ. Lời nhắc phê duyệt lệnh nguy hiểm được xử lý ở phía máy chủ, không được chuyển tiếp đến người dùng Matrix. Những vấn đề này có thể được giải quyết trong các bản cập nhật trong tương lai.
:::

### 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`**Lý do**: 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

:::warning
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 đảm bảo triển khai Đại lý Hermes của bạn, hãy xem [Security Guide](../security.md).

## 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 Ma trận tự động gắn thẻ các 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.
Cách Hermes cư xử​

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

Cách Hermes cư xử

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