Matrix 设置

Hermes Agent 集成了 Matrix，这是一个开放、联邦式的消息协议。Matrix 允许你运行自己的家庭服务器，或者使用像 matrix.org 这样的公共服务器——无论哪种方式，你都能控制自己的通信。该机器人通过 mautrix Python SDK 连接，通过 Hermes Agent 的处理管道（包括工具使用、记忆和推理）处理消息，并实时响应。它支持文本、文件附件、图片、音频、视频以及可选的端到端加密（E2EE）。

Hermes 可与任何 Matrix 家庭服务器配合使用——Synapse、Conduit、Dendrite 或 matrix.org。

在开始设置之前，这里是你可能最想知道的部分：Hermes 连接后的行为方式。

Hermes 的行为方式

场景	行为
私聊	Hermes 会响应每一条消息，无需 `@提及`。每个私聊都有独立的会话。设置 `MATRIX_DM_MENTION_THREADS=true` 可在私聊中 `@提及` 机器人时启动一个线程。
群聊	默认情况下，Hermes 需要 `@提及` 才会响应。设置 `MATRIX_REQUIRE_MENTION=false` 或将房间 ID 添加到 `MATRIX_FREE_RESPONSE_ROOMS` 以创建自由响应房间。房间邀请会自动接受。
线程	Hermes 支持 Matrix 线程（MSC3440）。如果你在某个线程中回复，Hermes 会将该线程的上下文与主房间时间线隔离。机器人已参与过的线程不需要提及。
自动创建线程	默认情况下，Hermes 会为它在房间中响应的每条消息自动创建一个线程。这可以保持对话的隔离性。设置 `MATRIX_AUTO_THREAD=false` 来禁用此功能。
多用户共享房间	默认情况下，Hermes 会在房间内为每个用户隔离会话历史。两个人在同一个房间内交谈不会共享一个对话记录，除非你明确禁用此功能。

提示

机器人被邀请时会自动加入房间。只需将机器人的 Matrix 用户邀请到任何房间，它就会加入并开始响应。

Matrix 中的会话模型

默认情况下：

每个私聊拥有独立的会话
每个线程拥有独立的会话命名空间
共享房间中的每个用户在该房间内拥有自己的会话

这由 config.yaml 控制：

group_sessions_per_user: true

仅当你明确希望整个房间共享一个对话时，才将其设置为 false：

group_sessions_per_user: false

共享会话对于协作房间可能有用，但也意味着：

用户共享上下文增长和令牌成本
一个人冗长且大量使用工具的任务可能会膨胀其他人的上下文
一个人正在运行的任务可能会中断另一个人在同一房间内的后续操作

提及与线程配置

你可以通过环境变量或 config.yaml 配置提及和自动创建线程的行为：

matrix:
  require_mention: true           # 在房间中需要 @提及（默认：true）
  free_response_rooms:            # 免除提及要求的房间
    - "!abc123:matrix.org"
  auto_thread: true               # 为响应自动创建线程（默认：true）
  dm_mention_threads: false       # 在私聊中被 @提及 时创建线程（默认：false）

或者通过环境变量：

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          # 默认：true — 处理过程中的表情符号反应

禁用反应

MATRIX_REACTIONS=false 会关闭机器人在接收消息时发布的处理生命周期表情符号反应（👀/✅/❌）。对于反应事件嘈杂或并非所有参与客户端都支持的房间很有用。

备注

如果你是从没有 MATRIX_REQUIRE_MENTION 的版本升级而来，机器人之前会响应房间中的所有消息。要保留该行为，请设置 MATRIX_REQUIRE_MENTION=false。

本指南将引导你完成完整的设置过程——从创建机器人账户到发送第一条消息。

步骤 1：创建机器人账户

你需要一个 Matrix 用户账户来运行这个机器人。有几种方法可以实现：

选项 A：在你的 Homeserver 上注册（推荐）

如果你运行自己的 homeserver（如 Synapse、Conduit、Dendrite）：

使用管理员 API 或注册工具创建一个新用户：

# Synapse 示例
register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008

选择一个用户名，例如 hermes —— 完整的用户 ID 将是 @hermes:your-server.org。

选项 B：使用 matrix.org 或其他公共 Homeserver

访问 Element Web 并创建一个新账户。
为你的机器人选择一个用户名（例如 hermes-bot）。

选项 C：使用你自己的账户

你也可以让 Hermes 使用你自己的用户账户运行。这意味着机器人将以你的身份发布消息——这对于个人助手很有用。

步骤 2：获取访问令牌

Hermes 需要一个访问令牌来与 homeserver 进行身份验证。你有两个选择：

选项 A：访问令牌（推荐）

获取令牌最可靠的方式：

通过 Element：

使用机器人账户登录 Element。
进入设置 → 帮助与关于。
向下滚动并展开高级 —— 访问令牌会显示在那里。
立即复制它。

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

响应中包含一个 access_token 字段 —— 复制它。

妥善保管你的访问令牌

访问令牌授予对机器人 Matrix 账户的完全访问权限。切勿公开分享或将其提交到 Git。如果令牌泄露，请通过注销该用户的所有会话来撤销它。

除了提供访问令牌，你也可以给 Hermes 机器人的用户 ID 和密码。Hermes 会在启动时自动登录。这更简单，但意味着密码会存储在你的 .env 文件中。

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

步骤 3：找到你的 Matrix 用户 ID

Hermes Agent 使用你的 Matrix 用户 ID 来控制谁可以与机器人交互。Matrix 用户 ID 遵循 @用户名:服务器 的格式。

要找到你的用户 ID：

打开 Element（或你首选的 Matrix 客户端）。
点击你的头像 → 设置。
你的用户 ID 会显示在个人资料顶部（例如 @alice:matrix.org）。

提示

Matrix 用户 ID 总是以 @ 开头，并包含一个 : 后跟服务器名称。例如：@alice:matrix.org，@bob:your-server.com。

步骤 4：配置 Hermes Agent

选项 A：交互式设置（推荐）

运行引导式设置命令：

hermes gateway setup

当提示时选择 Matrix，然后按要求提供你的 homeserver URL、访问令牌（或用户 ID + 密码）以及允许的用户 ID。

选项 B：手动配置

将以下内容添加到你的 ~/.hermes/.env 文件中：

使用访问令牌：

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

# 可选：用户 ID（如果省略，将从令牌自动检测）
# MATRIX_USER_ID=@hermes:matrix.example.org

# 安全：限制谁可以与机器人交互
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

# 多个允许的用户（用逗号分隔）
# MATRIX_ALLOWED_USERS=@alice:matrix.example.org,@bob:matrix.example.org

使用密码登录：

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

# 安全
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

在 ~/.hermes/config.yaml 中的可选行为设置：

group_sessions_per_user: true

group_sessions_per_user: true 在共享房间内保持每个参与者的上下文隔离

启动网关

配置完成后，启动 Matrix 网关：

hermes gateway

机器人应该会连接到你的 homeserver 并在几秒钟内开始同步。发送一条消息给它——可以是私聊或它已加入的房间——来进行测试。

提示

你可以把 hermes gateway 后台运行或设为 systemd 服务来持久化运行。具体部署方法请参考部署文档。

端到端加密 (E2EE)

Hermes 支持 Matrix 端到端加密，因此你可以与你的 bot 在加密房间里聊天。

前提条件

启用 E2EE 需要安装带有加密额外支持的 mautrix 库以及 C 库 libolm：

# 安装支持 E2EE 的 mautrix
pip install 'mautrix[encryption]'

# 或者通过 hermes extras 安装
pip install 'hermes-agent[matrix]'

你的系统还需要安装 libolm：

# Debian/Ubuntu
sudo apt install libolm-dev

# macOS
brew install libolm

# Fedora
sudo dnf install libolm-devel

启用 E2EE

在你的 ~/.hermes/.env 文件中添加：

MATRIX_ENCRYPTION=true

启用 E2EE 后，Hermes 会：

将加密密钥存储在 ~/.hermes/platforms/matrix/store/（旧版本安装路径：~/.hermes/matrix/store/)
首次连接时上传设备密钥
自动解密收到的消息并加密发出的消息
受邀时自动加入加密房间

交叉签名验证（推荐）

如果你的 Matrix 账户启用了交叉签名（Element 客户端默认启用），请设置恢复密钥，以便 bot 在启动时能够对其设备进行自签名。不设置此密钥的话，在其他 Matrix 客户端进行设备密钥轮换后，它们可能拒绝与 bot 共享加密会话。

MATRIX_RECOVERY_KEY=EsT... 你的恢复密钥放在这里

如何找到它： 在 Element 中，进入 Settings → Security & Privacy → Encryption → 你的恢复密钥（也称为“安全密钥”）。这是你首次设置交叉签名时被要求保存的密钥。

每次启动时，如果设置了 MATRIX_RECOVERY_KEY，Hermes 会从 homeserver 的安全秘密存储导入交叉签名密钥并签名当前设备。这个过程幂等，可以永久开启而安全。

删除加密存储

如果你删除 ~/.hermes/platforms/matrix/store/crypto.db，bot 将失去其加密身份。仅用相同的设备 ID 重启无法完全恢复——homeserver 仍持有用旧身份密钥签名的一次性密钥，对端无法建立新的 Olm 会话。

Hermes 会在启动时检测到这种情况并拒绝启用 E2EE，日志会显示：device XXXX has stale one-time keys on the server signed with a previous identity key。

最简单的恢复方法：生成一个新的访问令牌（这会获得一个全新的设备 ID，没有旧密钥历史）。请参阅下面的“从旧版本升级并启用 E2EE”章节。这是最可靠的方法，无需触及 homeserver 数据库。

手动恢复（高级操作——保持同一设备 ID）：

停止 Synapse 并从其数据库中删除旧设备：

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

或者通过 Synapse 管理 API（注意 URL 编码的用户 ID）：

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

注意：通过管理 API 删除设备可能也会使关联的访问令牌失效。你可能需要之后生成一个新的令牌。

删除本地加密存储并重启 Hermes：

rm -f ~/.hermes/platforms/matrix/store/crypto.db*
# 重启 hermes

其他 Matrix 客户端（Element、matrix-commander）可能会缓存旧设备密钥。恢复完成后，在 Element 中输入 /discardsession 来强制与 bot 建立新的加密会话。

信息

如果未安装 mautrix[encryption] 或缺少 libolm，机器人会自动回退到普通（未加密）客户端。你会在日志中看到警告。

主房间

你可以指定一个“主房间”，机器人会向其中发送主动消息（例如定时任务输出、提醒和通知）。有两种设置方式：

使用斜杠命令

在机器人所在的任何 Matrix 房间中，输入 /sethome。该房间将成为主房间。

手动配置

将此添加到你的 ~/.hermes/.env 文件中：

MATRIX_HOME_ROOM=!abc123def456:matrix.example.org

提示

要查找房间 ID：在 Element 中，进入房间 → 设置 → 高级 → 内部房间 ID 显示在那里（以 ! 开头）。

故障排除

机器人不响应消息

原因：机器人尚未加入房间，或者 MATRIX_ALLOWED_USERS 未包含你的用户 ID。

修复：邀请机器人加入房间 — 它会在收到邀请时自动加入。确认你的用户 ID 在 MATRIX_ALLOWED_USERS 中（使用完整的 @user:server 格式）。重启网关。

启动时出现“Failed to authenticate” / “whoami failed”

原因：访问令牌或家庭服务器 URL 不正确。

修复：验证 MATRIX_HOMESERVER 指向你的家庭服务器（包含 https://，末尾没有斜杠）。检查 MATRIX_ACCESS_TOKEN 是否有效 — 使用 curl 测试：

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

如果返回你的用户信息，则令牌有效。如果返回错误，请生成一个新令牌。

“mautrix not installed” 错误

原因：未安装 mautrix Python 包。

修复：安装它：

pip install 'mautrix[encryption]'

或者使用 Hermes 的额外依赖：

pip install 'hermes-agent[matrix]'

加密错误 / “could not decrypt event”

原因：缺少加密密钥、未安装 libolm，或机器人的设备未被信任。

修复：

验证系统上已安装 libolm（参见上面的 E2EE 部分）。
确保在 .env 文件中设置了 MATRIX_ENCRYPTION=true。
在你的 Matrix 客户端（Element）中，进入机器人的个人资料 -> 会话 -> 验证/信任机器人的设备。
如果机器人刚加入一个加密房间，它只能解密在它加入之后发送的消息。旧消息无法访问。

从支持 E2EE 的旧版本升级

提示

如果你还手动删除了 crypto.db，请参阅上面 E2EE 部分中的“删除加密存储”警告 — 需要额外的步骤来从家庭服务器清除过时的一次性密钥。

如果你之前使用 Hermes 时设置了 MATRIX_ENCRYPTION=true，并且正在升级到使用新的基于 SQLite 的加密存储的版本，那么机器人的加密身份已经改变。你的 Matrix 客户端（Element）可能会缓存旧的设备密钥，并拒绝与机器人共享加密会话。

症状：机器人连接成功并在日志中显示“E2EE enabled”，但所有消息都显示“could not decrypt event”，且机器人从不响应。

发生了什么：旧的加密状态（来自之前的 matrix-nio 或基于序列化的 mautrix 后端）与新的 SQLite 加密存储不兼容。机器人创建了一个全新的加密身份，但你的 Matrix 客户端仍然缓存着旧密钥，并且不会与一个密钥已更改的设备共享房间的加密会话。这是 Matrix 的一项安全功能 — 客户端会将同一设备更改的身份密钥视为可疑。

修复（一次性迁移）：

生成一个新的访问令牌以获取新的设备 ID。最简单的方法：

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

复制新的 access_token 并更新 ~/.hermes/.env 中的 MATRIX_ACCESS_TOKEN。

删除旧的加密状态：

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

设置你的恢复密钥（如果你使用交叉签名——大多数 Element 用户都使用）。添加到 ~/.hermes/.env：
```
MATRIX_RECOVERY_KEY=EsT... 你的恢复密钥放在这里
```
这会让机器人在启动时使用交叉签名密钥进行自签名，因此 Element 会立即信任新设备。如果没有这个，Element 可能会将新设备视为未验证，并拒绝共享加密会话。在 Element 的设置 → 安全与隐私 → 加密下找到你的恢复密钥。
强制你的 Matrix 客户端轮换加密会话。在 Element 中，打开与机器人的私聊房间并输入 /discardsession。这会强制 Element 创建一个新的加密会话并与机器人的新设备共享。
重启网关：
```
hermes gateway run
```
如果设置了 MATRIX_RECOVERY_KEY，你应该会在日志中看到 Matrix: cross-signing verified via recovery key。
发送一条新消息。机器人应该能正常解密和回复。

备注

迁移后，升级前发送的消息将无法解密——旧的加密密钥已经丢失。这只影响过渡阶段；新消息可以正常工作。

提示

新安装不受影响。 仅当你之前使用 Hermes 的旧版本已建立了可用的 E2EE 设置并正在升级时，才需要此迁移。

为什么需要新的访问令牌？ 每个 Matrix 访问令牌都绑定到一个特定的设备 ID。使用新的加密密钥重用相同的设备 ID 会导致其他 Matrix 客户端不信任该设备（它们会将身份密钥的更改视为潜在的安全漏洞）。一个新的访问令牌会获得一个没有陈旧密钥历史的新设备 ID，因此其他客户端会立即信任它。

代理模式 (macOS 上的 E2EE)

Matrix E2EE 需要 libolm，而它在 macOS ARM64 (Apple Silicon) 上无法编译。hermes-agent[matrix] 额外依赖项仅限 Linux。如果你在 macOS 上，代理模式允许你在 Linux 虚拟机上的 Docker 容器中运行 E2EE，而实际的 Agent 则原生运行在 macOS 上，可以完全访问你的本地文件、内存和技能。

工作原理

macOS (宿主机):
  └─ hermes gateway
       ├─ api_server adapter ← 监听 0.0.0.0:8642
       ├─ AIAgent ← 单一事实来源
       ├─ Sessions, memory, skills
       └─ Local file access (Obsidian, projects, etc.)

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

Docker 容器仅处理 Matrix 协议 + E2EE。当消息到达时，它解密消息并通过标准 HTTP 请求将文本转发给宿主机。宿主机运行 Agent，调用工具，生成响应，并将其流式传输回来。容器加密响应并将其发送到 Matrix。所有会话都是统一的——CLI、Matrix、Telegram 以及任何其他平台共享相同的内存和对话历史。

步骤 1：配置宿主机 (macOS)

启用 API 服务器，以便宿主机接受来自 Docker 容器的传入请求。

添加到 ~/.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 绑定到所有接口，以便 Docker 容器可以访问它。
API_SERVER_KEY 对于非环回绑定是必需的。选择一个强随机字符串。
API 服务器默认在端口 8642 上运行（如果需要，可以使用 API_SERVER_PORT 更改）。

启动网关：

hermes gateway

你应该会看到 API 服务器与你配置的任何其他平台一起启动。验证它可以从虚拟机访问：

# 从 Linux 虚拟机
curl http://<mac-ip>:8642/health

步骤 2：配置 Docker 容器 (Linux 虚拟机)

容器需要 Matrix 凭据和代理 URL。它不需要 LLM API 密钥。 docker-compose.yml:

services:
  hermes-matrix:
    build: .
    environment:
      # 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"

      # 代理模式 — 转发到主机的 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:

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"]

这就是整个容器。不需要 OpenRouter、Anthropic 或其他推理服务的 API 密钥。

第 3 步：启动两者

先启动主机网关：
```
hermes gateway
```
启动 Docker 容器：
```
docker compose up -d
```
在一个加密的 Matrix 房间发送消息。容器会解密消息，转发给主机，并流式返回响应。

配置参考

代理模式在 容器端（轻量网关）配置：

设置	描述
`GATEWAY_PROXY_URL`	远程 Hermes API 服务器的 URL（例如 `http://192.168.1.100:8642`)
`GATEWAY_PROXY_KEY`	Bearer 令牌，用于认证（必须与主机上的 `API_SERVER_KEY` 匹配）
`gateway.proxy_url`	同 `GATEWAY_PROXY_URL`，但在 `config.yaml` 中配置

主机端需要：

设置	描述
`API_SERVER_ENABLED`	设置为 `true`
`API_SERVER_KEY`	Bearer 令牌（与容器共享）
`API_SERVER_HOST`	设置为 `0.0.0.0` 以便网络访问
`API_SERVER_PORT`	端口号（默认：`8642`)

适用于任何平台

代理模式不仅限于 Matrix。任何平台适配器都可以使用它——在任何网关实例上设置 GATEWAY_PROXY_URL，它就会转发到远程 Agent，而不是在本地运行一个。这在平台适配器需要在与 Agent 不同的环境中运行（网络隔离、E2EE 要求、资源限制）的任何部署中都很有用。

提示

会话连续性通过 X-Hermes-Session-Id 头部来维持。主机的 API 服务器通过此 ID 跟踪会话，因此对话可以在多条消息间持续存在，就像使用本地 Agent 一样。

备注

限制 (v1)： 来自远程 Agent 的工具进度消息不会被回传——用户只能看到流式传输的最终响应，看不到单个工具调用。危险的命令批准提示在主机端处理，不会转发给 Matrix 用户。这些问题可以在未来更新中解决。

同步问题 / 机器人滞后

原因: 长时间运行的工具执行可能延迟同步循环，或者 homeserver 速度慢。

解决: 同步循环在出错时会自动每 5 秒重试一次。检查 Hermes 日志中与同步相关的警告。如果机器人持续滞后，请确保你的 homeserver 资源充足。

机器人离线

原因: Hermes 网关没有运行，或者连接失败。

解决: 检查 hermes gateway 是否在运行。查看终端输出中的错误消息。常见问题：错误的 homeserver URL、访问令牌过期、homeserver 无法访问。

"用户未允许" / 机器人忽略你

原因: 你的用户 ID 不在 MATRIX_ALLOWED_USERS 中。

解决: 把你的用户 ID 添加到 ~/.hermes/.env 中的 MATRIX_ALLOWED_USERS 并重启网关。使用完整的 @user:server 格式。

安全

注意

务必设置 MATRIX_ALLOWED_USERS 以限制谁可以与机器人交互。如果不设置，网关默认拒绝所有用户作为安全措施。只添加你信任的用户 ID——授权用户可以完全访问 Agent 的能力，包括工具使用和系统访问。

有关保护 Hermes Agent 部署的更多信息，请参阅安全指南。

注意事项

支持任何 homeserver：可与 Synapse、Conduit、Dendrite、matrix.org 或任何符合规范的 Matrix homeserver 配合使用。无需特定的 homeserver 软件。
联邦（Federation）：如果你在联邦化的 homeserver 上，该 bot 可以与其他服务器的用户通信——只需将他们的完整 @user:server ID 添加到 MATRIX_ALLOWED_USERS 中即可。
自动加入：该 bot 会自动接受房间邀请并加入。加入后立即开始响应。
媒体支持：Hermes 可以发送和接收图片、音频、视频和文件附件。媒体文件会使用 Matrix 内容仓库 API 上传到你的 homeserver。
原生语音消息（MSC3245）：Matrix 适配器会自动为外发的语音消息打上 org.matrix.msc3245.voice 标签。这意味着 TTS 回复和语音音频在 Element 及其他支持 MSC3245 的客户端中会显示为原生语音气泡，而不是普通的音频文件附件。带有 MSC3245 标签的传入语音消息也能被正确识别并路由到语音转文字转录功能。无需额外配置——此功能自动生效。

Hermes 的行为方式​

Matrix 中的会话模型​

提及与线程配置​

步骤 1：创建机器人账户​

选项 A：在你的 Homeserver 上注册（推荐）​

选项 B：使用 matrix.org 或其他公共 Homeserver​

选项 C：使用你自己的账户​

步骤 2：获取访问令牌​

选项 A：访问令牌（推荐）​

选项 B：密码登录​

步骤 3：找到你的 Matrix 用户 ID​

步骤 4：配置 Hermes Agent​

选项 A：交互式设置（推荐）​

选项 B：手动配置​

启动网关​

端到端加密 (E2EE)​

前提条件​

启用 E2EE​

交叉签名验证（推荐）​

主房间​

使用斜杠命令​

手动配置​

故障排除​

机器人不响应消息​

启动时出现“Failed to authenticate” / “whoami failed”​

“mautrix not installed” 错误​

加密错误 / “could not decrypt event”​

从支持 E2EE 的旧版本升级​

代理模式 (macOS 上的 E2EE)​

工作原理​

步骤 1：配置宿主机 (macOS)​

步骤 2：配置 Docker 容器 (Linux 虚拟机)​

第 3 步：启动两者​

配置参考​

适用于任何平台​

同步问题 / 机器人滞后​

机器人离线​

"用户未允许" / 机器人忽略你​

安全​

注意事项​