Matrix 设置

Hermes Agent 可以集成到 Matrix。Matrix 是一个开放、联邦式的即时通信协议，你既可以自建 homeserver，也可以直接使用 matrix.org 这类公共服务。机器人通过 mautrix Python SDK 连接 Matrix，把消息交给 Hermes Agent 管道处理，再实时返回结果。它支持文本、文件附件、图片、音频、视频，以及可选的端到端加密（E2EE）。

Hermes 兼容任意 Matrix homeserver，包括 Synapse、Conduit、Dendrite 和 matrix.org。

在真正开始配置前，先回答一个大家最关心的问题：接入之后，Hermes 会怎么响应消息？

Hermes 的行为方式

场景	行为
私聊（DM）	Hermes 会回复每条消息，不需要 `@mention`。每个私聊都有独立会话。若设置 `MATRIX_DM_MENTION_THREADS=true`，则在私聊里被 `@mentioned` 时会新建线程。
房间（Room）	默认要求 `@mention` 才回复。若设置 `MATRIX_REQUIRE_MENTION=false`，或把房间 ID 加到 `MATRIX_FREE_RESPONSE_ROOMS`，则可切换为自由回复模式。机器人会自动接受房间邀请。
线程（Thread）	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。

本指南会带你走完整个配置流程，从创建机器人账号到发出第一条消息。

第一步：创建机器人账号

你需要一个 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 直接以你自己的 Matrix 用户身份运行。这样机器人发出的消息看起来就是“你本人”发的，比较适合个人助理场景。

第二步：获取访问令牌

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 字段，把它复制出来即可。

请妥善保管访问令牌

访问令牌等同于机器人账号的完全访问权限。不要公开分享，也不要提交到 Git。一旦泄露，请立刻让该账号退出所有会话并重新生成令牌。

方案 B：密码登录

你也可以不给访问令牌，而是直接提供机器人账号的用户 ID 和密码。Hermes 会在启动时自动登录。这样配置更简单，但意味着密码会存放在 .env 文件中。

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

第三步：找到你的 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。

第四步：配置 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

启用后，Hermes 会：

将加密密钥保存在 ~/.hermes/platforms/matrix/store/（旧安装可能在 ~/.hermes/matrix/store/）
首次连接时上传设备密钥
自动解密收到的消息，并自动加密发出的消息
被邀请进入加密房间后自动加入

跨签名验证（推荐）

如果你的 Matrix 账号启用了跨签名（Element 默认如此），建议配置恢复密钥，这样机器人在启动时就能自动为自己的设备做签名。否则在设备密钥轮换后，其他 Matrix 客户端可能拒绝和它共享加密会话。

MATRIX_RECOVERY_KEY=EsT... your recovery key here

查看方法： 在 Element 中打开 Settings → Security & Privacy → Encryption，找到你的 recovery key（有时也叫 Security Key）。这通常就是你首次启用跨签名时让你保存的那串密钥。

如果设置了 MATRIX_RECOVERY_KEY，Hermes 每次启动时都会从 homeserver 的安全密钥存储中导入跨签名密钥，并对当前设备进行签名。这个过程是幂等的，可以长期保持开启。

warning

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

info

如果没有安装 mautrix[encryption] 或缺少 libolm，机器人会自动回退到普通未加密客户端，日志里也会出现提醒。

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 里没有你的用户 ID。

处理方法： 邀请机器人进入房间，它会自动加入。确认你的完整用户 ID（格式为 @user:server）已经写入 MATRIX_ALLOWED_USERS，然后重启网关。

启动时报 “Failed to authenticate” 或 “whoami failed”

原因： 访问令牌不正确，或 homeserver URL 配错了。

处理方法： 检查 MATRIX_HOMESERVER 是否指向正确地址，要求带 https:// 且不要有结尾斜杠。再测试 MATRIX_ACCESS_TOKEN 是否有效：

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。
确认 .env 中已设置 MATRIX_ENCRYPTION=true。
在 Matrix 客户端（如 Element）中打开机器人资料 → Sessions，验证并信任该设备。
如果机器人刚加入加密房间，它只能解密加入之后的新消息，之前的历史消息无法解密。

从旧版本升级后，E2EE 不工作

如果你之前已经在 Hermes 中启用过 MATRIX_ENCRYPTION=true，而现在升级到了使用 SQLite 加密存储的新版本，那么机器人的加密身份可能已经变化。你的 Matrix 客户端（例如 Element）可能还缓存着旧设备密钥，因此拒绝把新的加密会话分享给机器人。

典型症状： 机器人能连接，日志里也显示 “E2EE enabled”，但所有消息都报 “could not decrypt event”，机器人始终不回复。

发生原因： 旧的加密状态（来自更早的 matrix-nio 或旧版 mautrix 存储）与新的 SQLite 加密存储不兼容。机器人会创建一份新的加密身份，但客户端仍然记着旧密钥，因此会把“同一设备 ID 却变了身份密钥”视作可疑行为。

一次性修复方法：

生成一个新的访问令牌，拿到新的 device 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 用户都建议设置）：
```
MATRIX_RECOVERY_KEY=EsT... your recovery key here
```
这样机器人启动时就能通过跨签名为新设备自签名，Element 会更容易立即信任它。恢复密钥可以在 Element 的 Settings → Security & Privacy → Encryption 中找到。
强制 Matrix 客户端轮换加密会话。在 Element 中打开与机器人的私聊，输入 /discardsession。这会让 Element 创建新的加密会话并分享给机器人的新设备。
重启网关：
```
hermes gateway run
```
如果设置了 MATRIX_RECOVERY_KEY，日志中应出现 Matrix: cross-signing verified via recovery key。
发送一条新消息测试。此时机器人应能正常解密并回复。

note

升级前发出的旧消息在迁移后无法再被解密，因为旧密钥已经废弃。这只影响迁移过程中的旧消息，不影响后续新消息。

tip

新安装不受影响。 只有在你以前已经运行过带 E2EE 的 Hermes，并且现在升级到新版本时，才需要这一步迁移。

为什么要重新生成访问令牌？ 因为每个 Matrix 访问令牌都绑定一个设备 ID。如果继续沿用旧设备 ID，但密钥身份变了，其他客户端会把它视为潜在安全风险。新的访问令牌意味着新的设备 ID，没有旧密钥历史包袱，更容易立即被信任。

同步异常 / 机器人明显落后

原因： 长时间工具执行可能拖慢同步循环，或者 homeserver 本身比较慢。

处理方法： 同步循环在出错后会自动每 5 秒重试一次。查看 Hermes 日志中的同步警告。如果机器人长期跟不上，通常要检查 homeserver 的资源情况。

机器人离线

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

处理方法： 确认 hermes gateway 正在运行，查看终端输出中的报错。常见原因包括 homeserver 地址错误、访问令牌过期、homeserver 不可达。

报 “User not allowed” / 机器人无视你

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

处理方法： 把你的完整用户 ID 写入 ~/.hermes/.env 的 MATRIX_ALLOWED_USERS，然后重启网关。

安全建议

warning

务必设置 MATRIX_ALLOWED_USERS 来限制可与机器人交互的用户。出于安全考虑，如果不设置，网关默认会拒绝所有用户。只有你信任的人才应被加入允许名单，因为授权用户将获得对 agent 能力的完整访问，包括工具调用与系统操作能力。

关于如何更安全地部署 Hermes，请继续阅读安全指南。

说明

兼容任意 homeserver：可用于 Synapse、Conduit、Dendrite、matrix.org，以及任何符合规范的 Matrix homeserver。
支持联邦：如果你的 homeserver 开启联邦，机器人也可以与其他服务器上的用户通信，只需把他们完整的 @user:server 写入 MATRIX_ALLOWED_USERS。
自动入房：机器人会自动接受房间邀请并加入，加入后即可开始回复。
媒体支持：Hermes 可以收发图片、音频、视频和文件附件，媒体通过 Matrix 内容仓库 API 上传到你的 homeserver。
原生语音消息（MSC3245）：Matrix 适配器会自动给发出的语音消息打上 org.matrix.msc3245.voice 标记，因此 TTS 回复和语音音频会在 Element 等支持 MSC3245 的客户端中显示为原生语音气泡，而不是普通音频附件。带有 MSC3245 标记的传入语音消息，也会被正确识别并路由到语音转文本流程。这个能力默认自动生效，无需额外配置。

Hermes 的行为方式​

Matrix 中的会话模型​

提及与线程配置​

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

方案 A：在你自己的 homeserver 上注册（推荐）​

方案 B：使用 matrix.org 或其他公共 homeserver​

方案 C：直接使用你自己的账号​

第二步：获取访问令牌​

方案 A：访问令牌（推荐）​

方案 B：密码登录​

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

第四步：配置 Hermes Agent​

方案 A：交互式配置（推荐）​

方案 B：手动配置​

启动网关​

端到端加密（E2EE）​

前置要求​

启用 E2EE​

跨签名验证（推荐）​

Home Room​

使用斜杠命令​

手动配置​

故障排查​

机器人不回复消息​

启动时报 “Failed to authenticate” 或 “whoami failed”​

报 “mautrix not installed”​

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

从旧版本升级后，E2EE 不工作​

同步异常 / 机器人明显落后​

机器人离线​

报 “User not allowed” / 机器人无视你​

安全建议​

说明​