跳到主要内容

Matrix

Hermes Agent 可接入 Matrix 这一开放、联邦化的消息协议。无论你使用自己的 homeserver，还是使用 matrix.org 这样的公共服务，都能掌控自己的通信。bot 基于 mautrix Python SDK 工作，会通过 Hermes Agent 流水线（包括工具、记忆和 reasoning）处理消息并实时回复。它支持文本、文件附件、图片、音频、视频，以及可选的端到端加密（E2EE）。

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

Hermes 的行为方式​

ContextBehavior
DMsHermes 会回复每条消息，无需 @mention。每个 DM 各自拥有独立会话。设置 MATRIX_DM_MENTION_THREADS=true 后，在 DM 中 @mention bot 还会自动开线程。
Rooms默认需要 @mention 才回复。可通过 MATRIX_REQUIRE_MENTION=false 关闭，或用 MATRIX_FREE_RESPONSE_ROOMS 指定免 mention 房间。房间邀请会自动接受。
ThreadsHermes 支持 Matrix threads（MSC3440）。在线程中回复时，thread 上下文会与主房间时间线隔离。只要 bot 已在线程里发过言，后续 thread 消息就不再需要 mention。
Auto-threading默认情况下，Hermes 会为它在房间中的每次回复自动创建线程，以保持会话隔离。可通过 MATRIX_AUTO_THREAD=false 关闭。
Shared rooms with multiple users默认会在共享房间内按用户隔离会话历史。两个用户在同一房间中与 Hermes 对话时，不会默认共享同一份 transcript。
提示

bot 被邀请进房间后会自动加入。只要把 bot 的 Matrix 用户邀请进任意房间，它就会加入并开始响应。

Matrix 中的会话模型​

默认情况下：

  • 每个 DM 都有独立会话
  • 每个 thread 都有独立会话命名空间
  • 共享房间中，每个用户在该房间内也拥有独立会话

这一行为由 config.yaml 控制：

group_sessions_per_user: true

如果你明确希望整个房间共享一段会话，才把它改成 false：

group_sessions_per_user: false

共享会话适合协作式房间，但也意味着：

  • 用户会共享上下文增长和 token 成本
  • 某个人的长时间高工具负载任务可能会拖大其他人的上下文
  • 某个人正在运行的任务可能会打断同一房间里另一人的后续消息

Mention 和 Threading 配置​

你可以通过环境变量或 config.yaml 配置 mention 与自动开线程行为：

matrix:
  require_mention: true           # 房间里要求 @mention（默认：true）
  free_response_rooms:            # 免 mention 的房间
    - "!abc123:matrix.org"
  auto_thread: true               # 自动为回复创建线程（默认：true）
  dm_mention_threads: false       # DM 中被 @mention 时创建线程（默认：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          # default: true — emoji reactions during processing
Disabling reactions

MATRIX_REACTIONS=false 会关闭 bot 在入站消息上添加的处理状态 emoji reactions（👀 / ✅ / ❌）。如果你的房间中 reaction 事件过于吵闹，或并非所有客户端都支持 reaction，可考虑关闭。

备注

如果你是从没有 MATRIX_REQUIRE_MENTION 这个配置项的旧版本升级而来，那么 bot 之前默认会在房间里响应所有消息。若想保持旧行为，请设置 MATRIX_REQUIRE_MENTION=false。

本指南会带你完成整个设置流程，从创建 bot 账号到发出第一条消息。

第 1 步：创建 Bot 账号​

你需要一个 Matrix 用户账号给 bot 使用。常见方式有：

Option A: 在你的 homeserver 上注册（推荐）​

如果你使用自建 homeserver（Synapse、Conduit、Dendrite）：

  1. 使用管理员 API 或注册工具创建新用户：
# Synapse example
register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008
  1. 例如可选择 hermes 作为用户名，那么完整 user ID 会是 @hermes:your-server.org。

Option B: 使用 matrix.org 或其他公共 homeserver​

  1. 打开 Element Web 创建新账号
  2. 给 bot 选一个用户名（例如 hermes-bot）

Option C: 直接使用你自己的账号​

你也可以让 Hermes 直接使用你自己的 Matrix 用户运行。这种方式下，bot 发出来的消息看起来就像是你本人，非常适合个人助理场景。

第 2 步：获取 Access Token​

Hermes 需要 access token 才能和 homeserver 鉴权。你有两种方式：

Option A: Access Token（推荐）​

最可靠的获取方法如下。

通过 Element：

  1. 用 bot 账号登录 Element
  2. 进入 Settings → Help & About
  3. 向下滚动展开 Advanced，即可看到 access token
  4. 立即复制

通过 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 字段，请复制它。

请妥善保管 access token

access token 相当于 bot Matrix 账号的完整控制权。不要公开分享，也不要提交到 Git。如果泄露，请通过让该用户的所有会话登出来撤销它。

Option B: 使用密码登录​

你也可以不直接提供 access token，而是向 Hermes 提供 bot 的 user ID 和密码。这样 Hermes 会在启动时自动登录。配置更简单，但意味着密码会保存在 .env 文件中。

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

第 3 步：找到你的 Matrix User ID​

Hermes Agent 使用你的 Matrix User ID 控制谁可以与 bot 交互。Matrix User ID 的格式是 @username:server。

查找方式：

  1. 打开 Element（或任意 Matrix 客户端）
  2. 点击头像 → Settings
  3. 你的 User ID 会显示在资料页顶部（例如 @alice:matrix.org）
提示

Matrix User ID 一定以 @ 开头，并包含一个 : 和服务器名，例如：@alice:matrix.org、@bob:your-server.com。

第 4 步：配置 Hermes Agent​

运行交互式向导：

hermes gateway setup

在提示时选择 Matrix，然后按要求填写 homeserver URL、access token（或 user ID + password）以及允许的用户 ID。

Option B: Manual Configuration​

把以下内容加入你的 ~/.hermes/.env：

使用 access token：

# 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 会在共享房间中按参与者隔离上下文

Start the Gateway​

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

hermes gateway

几秒内 bot 就会连接到 homeserver 并开始同步。你可以给它发一条消息测试，无论是私聊还是它已经加入的房间都可以。

提示

你也可以把 hermes gateway 作为后台进程或 systemd 服务运行，以便长期驻留。具体可参见部署文档。

End-to-End Encryption（E2EE）​

Hermes 支持 Matrix 端到端加密，因此你可以在加密房间中与 bot 对话。

Requirements​

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

Enable E2EE​

在 ~/.hermes/.env 中加入：

MATRIX_ENCRYPTION=true

启用后，Hermes 会：

  • 把加密密钥存到 ~/.hermes/platforms/matrix/store/（旧安装可能位于 ~/.hermes/matrix/store/）
  • 首次连接时上传 device keys
  • 自动解密入站消息，并自动加密出站消息
  • 在被邀请进加密房间时自动加入

Cross-Signing Verification（推荐）​

如果你的 Matrix 账号已启用 cross-signing（Element 默认如此），建议配置 recovery key。这样 bot 启动时就能给自己的设备自签名，避免其他 Matrix 客户端因设备密钥轮换而拒绝共享加密会话。

MATRIX_RECOVERY_KEY=EsT... your recovery key here

获取方法： 在 Element 中进入 Settings → Security & Privacy → Encryption，找到 recovery key（也叫 Security Key）。这就是你在最初启用 cross-signing 时被要求保存的那串密钥。

每次启动时，只要设置了 MATRIX_RECOVERY_KEY，Hermes 就会从 homeserver 的安全密钥存储中导入 cross-signing keys，并为当前设备完成签名。这个操作可重复执行，长期开启也没有问题。

删除 crypto store

如果你删除了 ~/.hermes/platforms/matrix/store/crypto.db，bot 就会失去原有的加密身份。仅仅继续使用同一个 device ID 重启，并不能完全恢复，因为 homeserver 上仍保留着由旧身份密钥签名的一次性密钥，其他客户端无法再为它建立新的 Olm 会话。

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

最简单的恢复方式是重新生成一个新的 access token。这样会得到新的 device ID，不会继承旧的一次性密钥历史。这也是最可靠的恢复路径，因为无需修改 homeserver 数据库。

信息

如果没有安装 mautrix[encryption] 或系统缺少 libolm，bot 会自动退回到普通（未加密）客户端模式，日志中会给出警告。

Home Room​

你可以指定一个 “home room”，让 bot 主动往里面发送消息（例如 cron 输出、提醒和通知）。有两种方式：

Using the Slash Command​

在任意已加入 bot 的 Matrix 房间中输入 /sethome，该房间就会成为 home room。

Manual Configuration​

把以下内容加入 ~/.hermes/.env：

MATRIX_HOME_ROOM=!abc123def456:matrix.example.org
提示

查找 Room ID：在 Element 中进入目标房间 → Settings → Advanced，其中会显示 Internal room ID，通常以 ! 开头。

Proxy Mode（macOS 下的 E2EE）​

由于 Matrix E2EE 依赖 libolm，而它在 macOS ARM64（Apple Silicon）上编译并不顺畅，因此 hermes-agent[matrix] extra 目前只对 Linux 开放。如果你使用 macOS，proxy mode 可以让你把 E2EE 放到 Linux VM 的 Docker 容器中运行，而真正的 agent 仍运行在 macOS 本机上，继续访问本地文件、记忆和技能。

How It Works​

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)

Docker 容器只负责 Matrix 协议与 E2EE。消息到来时，它会解密并通过标准 HTTP 请求转发给宿主机。宿主机运行 agent、调用工具、生成回复并流式返回。容器再把回复加密并发送回 Matrix。所有会话都是统一的：CLI、Matrix、Telegram 等平台共享同一套记忆和会话历史。

Step 1: Configure the Host (macOS)​

启用 API server，让宿主机接收来自 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 是非 loopback 绑定时必需的，请设置足够强的随机字符串
  • API server 默认运行在 8642 端口（如需修改，使用 API_SERVER_PORT）

随后启动网关：

hermes gateway

Step 2: Configure the Docker Container (Linux VM)​

容器端只需要 Matrix 凭据和 proxy URL，不需要任何 LLM API key。

docker-compose.yml:

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:

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

Step 3: Start Both​

  1. 先启动宿主机网关： 
    hermes gateway
  2. 再启动 Docker 容器： 
    docker compose up -d
  3. 然后在加密 Matrix 房间里发送一条消息。容器会负责解密、转发到宿主机，并把回复再流式送回房间。

Troubleshooting​

Bot is not responding to messages​

原因：bot 没加入房间，或 MATRIX_ALLOWED_USERS 中没有你的 User ID。

修复：把 bot 邀请进房间，它会自动加入；确认你的 User ID 已完整写入 MATRIX_ALLOWED_USERS（必须使用完整 @user:server 格式）；然后重启网关。

"Failed to authenticate" / "whoami failed" on startup​

原因：access token 或 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" error​

原因：缺少 mautrix Python 包。

修复：安装：

pip install 'mautrix[encryption]'

或：

pip install 'hermes-agent[matrix]'

Encryption errors / "could not decrypt event"​

原因：缺少加密密钥、未安装 libolm，或者 bot 设备未被信任。

修复：

  1. 确认系统已安装 libolm
  2. 确认设置了 MATRIX_ENCRYPTION=true
  3. 在 Element 中进入 bot 资料 → Sessions → 验证 / 信任 bot 的设备
  4. 如果 bot 刚加入一个加密房间，它只能解密加入之后的消息，无法读取更早的历史

Upgrading from a previous version with E2EE​

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

建议的迁移步骤：

  1. 重新生成一个新的 access token，以获得新的 device ID
  2. 删除旧的加密状态： 
    rm -f ~/.hermes/platforms/matrix/store/crypto.db
    rm -f ~/.hermes/platforms/matrix/store/crypto_store.*
  3. 如果你使用了 cross-signing，请设置 recovery key
  4. 在 Element 中对与 bot 的 DM 输入 /discardsession，强制客户端创建新的加密会话
  5. 重启网关
  6. 再发送一条新消息，确认 bot 可以正常解密并回复

Sync issues / bot falls behind​

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

修复：同步循环会在错误后每 5 秒自动重试。查看 Hermes 日志中的同步相关警告；如果 bot 长期落后，请确认 homeserver 资源足够。

Bot is offline​

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

修复：确认 hermes gateway 正在运行，并查看终端输出。常见问题包括 homeserver URL 错误、access token 过期或 homeserver 不可达。

"User not allowed" / Bot ignores you​

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

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

Security​

注意

务必设置 MATRIX_ALLOWED_USERS 来限制谁可以与 bot 交互。否则，出于安全考虑，网关默认会拒绝所有用户。被授权用户拥有 agent 的全部能力，包括工具调用和系统访问。

关于如何保护你的 Hermes Agent 部署，请参见 Security Guide。

Notes​

  • 任意 homeserver：兼容 Synapse、Conduit、Dendrite、matrix.org，或任何符合规范的 Matrix homeserver
  • 联邦：如果你的 homeserver 参与联邦，bot 同样可以和其他服务器上的用户通信，只要把他们完整的 @user:server 写入 MATRIX_ALLOWED_USERS
  • 自动加入：bot 会自动接受房间邀请并加入
  • 媒体支持：Hermes 可收发图片、音频、视频和文件附件
  • 原生语音消息（MSC3245）：Matrix 适配器会自动给出站语音消息打上 org.matrix.msc3245.voice 标记，因此 TTS 回复和语音音频会在 Element 等支持 MSC3245 的客户端中显示为原生语音气泡，而不是普通音频文件附件；带 MSC3245 标记的入站语音消息也会被正确识别并交给 STT 转写，全程无需额外配置