Matrix 设置

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

Hermes 可与任何 Matrix homeserver 配合使用，包括 Synapse、Conduit、Dendrite 或 matrix.org。

在开始设置之前，先看大多数人最关心的一点：Hermes 连接后会如何表现。

Hermes 的行为方式

上下文	行为
私信	Hermes 会响应每条消息。不需要 `@mention`。每个私信都有自己的会话。设置 `MATRIX_DM_MENTION_THREADS=true` 后，机器人在私信中被 `@mentioned` 时会开启一个线程。
房间	默认情况下，Hermes 需要被 `@mention` 才会响应。设置 `MATRIX_REQUIRE_MENTION=false`，或将房间 ID 加入 `MATRIX_FREE_RESPONSE_ROOMS`，即可让指定房间无需提及也能自由响应。房间邀请会被自动接受。
线程	Hermes 支持 Matrix 线程（MSC3440）。如果你在线程中回复，Hermes 会把该线程上下文与主房间时间线隔离。机器人已经参与过的线程不再需要提及。
自动开线程	默认情况下，Hermes 会为房间中它响应的每条消息自动创建一个线程，以保持对话隔离。设置 `MATRIX_AUTO_THREAD=false` 可禁用。
多用户共享房间	默认情况下，Hermes 会在房间内按用户隔离会话历史。同一个房间里两个人与机器人对话，不会共享同一份转录记录，除非你显式关闭这种隔离。

tip

机器人收到邀请后会自动加入房间。只要把机器人的 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

note

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

本指南会带你完成完整设置流程：从创建机器人账号，到发送第一条消息。

第 1 步：创建机器人账号

你需要为机器人准备一个 Matrix 用户账号。可以用以下几种方式创建：

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

如果你运行自己的 homeserver（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 或其他公共 Homeserver

打开 Element Web 并创建一个新账号。
为机器人选择用户名，例如 hermes-bot。

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

你也可以让 Hermes 以你自己的用户身份运行。这意味着机器人会以你的名义发消息，适合个人助理场景。

第 2 步：获取访问令牌

Hermes 需要访问令牌来向 homeserver 认证。你有两个选择：

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

获取令牌最可靠的方式：

通过 Element：

使用机器人账号登录 Element。
进入 Settings → Help & About。
向下滚动并展开 Advanced，访问令牌会显示在那里。
立即复制它。

通过 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。如果泄露，请通过登出该用户的所有会话来撤销它。

选项 B：密码登录

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

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

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

Hermes Agent 使用你的 Matrix 用户 ID 来控制谁能与机器人交互。Matrix 用户 ID 的格式是 @username:server。

查找方法：

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

tip

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

第 4 步：配置 Hermes Agent

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

运行引导式设置命令：

hermes gateway setup

按提示选择 Matrix，然后根据提示提供 homeserver 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

机器人应会连接到你的 homeserver，并在几秒内开始同步。给它发送一条消息来测试，可以是私信，也可以是在它已加入的房间中发送。

tip

你可以在后台运行 hermes gateway，也可以把它作为 systemd 服务运行，以便长期保持在线。详情请参考部署文档。

端到端加密（E2EE）

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

要求

E2EE 需要带加密扩展的 mautrix 库，以及 libolm C 库：

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

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

warning

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

info

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

Home Room

你可以指定一个 “home room”，让机器人在那里发送主动消息，例如 cron 任务输出、提醒和通知。有两种设置方式：

使用斜杠命令

在机器人所在的任意 Matrix 房间输入 /sethome。该房间会成为 home room。

手动配置

将此项添加到你的 ~/.hermes/.env：

MATRIX_HOME_ROOM=!abc123def456:matrix.example.org

tip

查找 Room ID：在 Element 中进入房间 → Settings → Advanced → 这里会显示 Internal room ID（以 ! 开头）。

故障排查

机器人没有响应消息

原因：机器人尚未加入房间，或 MATRIX_ALLOWED_USERS 没有包含你的 User ID。

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

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

原因：访问令牌或 homeserver URL 不正确。

修复：确认 MATRIX_HOMESERVER 指向你的 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 extras：

pip install 'hermes-agent[matrix]'

加密错误 / “could not decrypt event”

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

修复：

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

同步问题 / 机器人落后

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

修复：同步循环在出错时会每 5 秒自动重试。检查 Hermes 日志中与同步相关的警告。如果机器人持续落后，请确认你的 homeserver 有足够资源。

机器人离线

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

修复：检查 hermes gateway 是否正在运行。查看终端输出中的错误信息。常见问题包括 homeserver URL 错误、访问令牌过期、homeserver 无法访问。

“User not allowed” / 机器人忽略你

原因：你的 User ID 不在 MATRIX_ALLOWED_USERS 中。

修复：将你的 User ID 添加到 ~/.hermes/.env 的 MATRIX_ALLOWED_USERS，然后重启网关。使用完整 @user:server 格式。

安全性

warning

务必设置 MATRIX_ALLOWED_USERS，限制谁能与机器人交互。未设置时，出于安全考虑，网关默认拒绝所有用户。只添加你信任的人的 User ID，因为授权用户拥有完整的智能体能力访问权，包括工具使用和系统访问。

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

备注

任何 homeserver：可与 Synapse、Conduit、Dendrite、matrix.org 或任何符合规范的 Matrix homeserver 配合使用。不要求特定 homeserver 软件。
联邦：如果你使用联邦式 homeserver，机器人可以与其他服务器上的用户通信，只需将他们完整的 @user:server ID 添加到 MATRIX_ALLOWED_USERS。
自动加入：机器人会自动接受房间邀请并加入。加入后会立即开始响应。
媒体支持：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​

Home Room​

使用斜杠命令​

手动配置​

故障排查​

机器人没有响应消息​

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

“mautrix not installed” 错误​

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

同步问题 / 机器人落后​

机器人离线​

“User not allowed” / 机器人忽略你​

安全性​

备注​