Matrix 配置

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

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

在开始配置前，这里是你最关心的部分：Hermes 连接后的行为表现。

Hermes 的行为表现

上下文	行为
私聊（DMs）	Hermes 对每条消息都会响应，无需 `@mention`。每个私聊拥有独立的会话。设置 `MATRIX_DM_MENTION_THREADS=true` 可在机器人被 `@mentioned` 时启动线程。
房间（Rooms）	默认情况下，Hermes 需要 `@mention` 才会响应。设置 `MATRIX_REQUIRE_MENTION=false` 或将房间 ID 添加到 `MATRIX_FREE_RESPONSE_ROOMS` 可启用自由响应房间。房间邀请会自动接受。
线程（Threads）	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

共享会话在协作型房间中可能有用，但也意味着：

用户共享上下文增长和 Token 成本
某个人的长时间工具任务可能导致其他人的上下文膨胀
某个人正在进行的任务可能中断另一个人在同个房间中的后续回复

提及与线程配置

你可以通过环境变量或 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)
  dm_mention_threads: false       # Create thread when @mentioned in DM (default: 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_REQUIRE_MENTION 的旧版本升级，机器人之前会在房间中对所有消息做出响应。为保留此行为，请设置 MATRIX_REQUIRE_MENTION=false。

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

第一步：创建机器人账户

你需要一个 Matrix 用户账户用于机器人。有几种方式可以实现：

选项 A：在你的主服务器上注册（推荐）

如果你运行自己的主服务器（Synapse、Conduit、Dendrite）：

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

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

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

选项 B：使用 matrix.org 或其他公开主服务器

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

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

你也可以以自己的用户身份运行 Hermes。这意味着机器人将以你的身份发帖 —— 适用于个人助手场景。

第二步：获取访问令牌

Hermes 需要一个访问令牌来认证与主服务器的连接。你有两个选择：

选项 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。若被泄露，请通过注销该用户的全部会话来撤销。

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

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

第三步：查找你的 Matrix 用户 ID

Hermes Agent 使用你的 Matrix 用户 ID 来控制谁可以与机器人互动。Matrix 用户 ID 的格式为 @username:server。

要查找你的用户 ID：

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

提示

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

第 4 步：配置 Hermes Agent

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

运行引导式设置命令：

hermes gateway setup

当提示时选择 Matrix，然后提供您的主服务器 URL、访问令牌（或用户 ID + 密码），以及允许的用户 ID。

选项 B：手动配置

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

使用访问令牌：

# 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

使用密码登录：

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

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

可选的行为设置项，位于 ~/.hermes/config.yaml 中：

group_sessions_per_user: true

group_sessions_per_user: true 会在共享房间中为每位参与者保持上下文隔离

启动网关

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

hermes gateway

机器人应在几秒内连接到您的主服务器并开始同步。向它发送一条消息——无论是私信还是它已加入的房间中的消息——以进行测试。

提示

您可以将 hermes gateway 在后台运行，或作为 systemd 服务运行以实现持久化操作。详情请参阅部署文档。

端到端加密（E2EE）

Hermes 支持 Matrix 端到端加密，因此您可以在加密房间中与机器人聊天。

要求

E2EE 需要安装带有加密扩展的 matrix-nio 库以及 libolm C 库：

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

# Or install with 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/）
在首次连接时上传设备密钥
自动解密传入消息并加密传出消息
在收到邀请时自动加入加密房间

注意

如果您删除了 ~/.hermes/platforms/matrix/store/ 目录，机器人将丢失其加密密钥。您需要在 Matrix 客户端中重新验证该设备。若要保留加密会话，请备份此目录。

信息

如果未安装 matrix-nio[e2e] 或缺少 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）。重启网关。

启动时出现“认证失败” / “whoami 失败”

原因：访问令牌或主服务器 URL 错误。

解决方法：验证 MATRIX_HOMESERVER 是否指向您的主服务器（请包含 https://，不要加尾部斜杠）。检查 MATRIX_ACCESS_TOKEN 是否有效——尝试使用 curl 测试：

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

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

出现“matrix-nio 未安装”错误

原因：matrix-nio Python 包未安装。

解决方法：安装它：

pip install 'matrix-nio[e2e]'

或使用 Hermes 的附加组件安装：

pip install 'hermes-agent[matrix]'

加密错误 / “无法解密事件”

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

解决方法：

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

同步问题 / 机器人落后

原因：长时间运行的工具执行会延迟同步循环，或主服务器响应缓慢。

解决方法：同步循环在出错时会自动每 5 秒重试一次。检查 Hermes 日志中是否有与同步相关的警告。如果机器人持续落后，请确保您的主服务器具备足够的资源。

机器人离线

原因：Hermes 网关未运行，或连接失败。

解决方法：检查 hermes gateway 是否正在运行。查看终端输出中的错误信息。常见问题包括：主服务器 URL 错误、访问令牌过期、主服务器无法访问。

“用户不允许” / 机器人忽略你

原因：你的用户 ID 未包含在 MATRIX_ALLOWED_USERS 中。

解决方法：将你的用户 ID 添加到 ~/.hermes/.env 文件中的 MATRIX_ALLOWED_USERS，然后重启网关。请使用完整的 @user:server 格式。

安全性

注意

始终设置 MATRIX_ALLOWED_USERS 以限制可以与机器人交互的用户。如果没有设置，网关会默认拒绝所有用户，这是一种安全措施。仅添加你信任的用户的用户 ID —— 授权用户将拥有对代理所有功能的完全访问权限，包括工具使用和系统访问。

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

注意事项

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

Hermes 的行为表现​

Matrix 中的会话模型​

提及与线程配置​

第一步：创建机器人账户​

选项 A：在你的主服务器上注册（推荐）​

选项 B：使用 matrix.org 或其他公开主服务器​

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

第二步：获取访问令牌​

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

选项 B：密码登录​

第三步：查找你的 Matrix 用户 ID​

第 4 步：配置 Hermes Agent​

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

选项 B：手动配置​

启动网关​

端到端加密（E2EE）​

要求​

启用 E2EE​

主房间​

使用斜杠命令​

手动配置​

故障排除​

机器人未响应消息​

启动时出现“认证失败” / “whoami 失败”​

出现“matrix-nio 未安装”错误​

加密错误 / “无法解密事件”​

同步问题 / 机器人落后​

机器人离线​

“用户不允许” / 机器人忽略你​

安全性​

注意事项​

Hermes 的行为表现

Matrix 中的会话模型

提及与线程配置

第一步：创建机器人账户

选项 A：在你的主服务器上注册（推荐）

选项 B：使用 matrix.org 或其他公开主服务器

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

第二步：获取访问令牌

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

选项 B：密码登录

第三步：查找你的 Matrix 用户 ID

第 4 步：配置 Hermes Agent

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

选项 B：手动配置

启动网关

端到端加密（E2EE）

要求

启用 E2EE

主房间

使用斜杠命令

手动配置

故障排除

机器人未响应消息

启动时出现“认证失败” / “whoami 失败”

出现“matrix-nio 未安装”错误

加密错误 / “无法解密事件”

同步问题 / 机器人落后

机器人离线

“用户不允许” / 机器人忽略你

安全性

注意事项