跳到主要内容

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

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

  • 用户共享上下文增长和 Token 消耗
  • 一个人执行工具密集型任务可能会撑大所有人的上下文
  • 一个人正在进行的任务可能会打断同一房间中另一个人的后续操作

提及与话题配置​

可通过环境变量或 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 — 处理期间的 Emoji 反应
禁用反应

MATRIX_REACTIONS=false 关闭机器人在入站消息上发布的处理生命周期 Emoji 反应（👀/✅/❌）。适用于反应事件较多或部分客户端不支持的房间。

备注

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

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

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

你需要一个 Matrix 用户账户供机器人使用。有以下几种方式：

方式 A：在家庭服务器上注册（推荐）​

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

  1. 使用管理 API 或注册工具创建新用户：
# Synapse 示例
register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008
  1. 选择一个用户名，例如 hermes——完整用户 ID 将为 @hermes:your-server.org。

方式 B：使用 matrix.org 或其他公共家庭服务器​

  1. 前往 Element Web 创建新账户。
  2. 为机器人选择一个用户名（例如 hermes-bot）。

方式 C：使用你自己的账户​

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

步骤 2：获取访问 Token​

Hermes 需要访问 Token 来向家庭服务器进行身份验证。有两种方式：

方式 A：访问 Token（推荐）​

获取 Token 最可靠的方式：

通过 Element：

  1. 用机器人账户登录 Element。
  2. 前往 设置 → 帮助与关于。
  3. 向下滚动展开高级——访问 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 字段——复制它。

保护你的访问 Token

访问 Token 可完全访问机器人的 Matrix 账户。切勿公开分享或将其提交到 Git。如果泄露，请通过注销该用户的所有会话来吊销它。

方式 B：密码登录​

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

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

步骤 3：获取你的 Matrix 用户 ID​

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

查找方式：

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

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

步骤 4：配置 Hermes Agent​

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

运行引导式设置命令：

hermes gateway setup

在提示中选择 Matrix，然后按要求提供家庭服务器 URL、访问 Token（或用户 ID + 密码）和允许的用户 ID。

方式 B：手动配置​

在 ~/.hermes/.env 文件中添加以下内容：

使用访问 Token：

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

# 可选：用户 ID（省略时从 Token 自动检测）
# 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

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

提示

你可以在后台运行 hermes gateway 或将其作为 systemd 服务长期运行。详见部署文档。

端对端加密（E2EE）​

Hermes 支持 Matrix 端对端加密，让你可以在加密房间中与机器人对话。

前提条件​

E2EE 需要安装带加密扩展的 mautrix 库和 libolm C 库：

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

# 或使用 hermes 扩展安装
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 默认开启），请设置恢复密钥，以便机器人在启动时自签名其设备。没有此配置，设备密钥轮换后，其他 Matrix 客户端可能会拒绝与机器人共享加密会话。

MATRIX_RECOVERY_KEY=EsT... your recovery key here

查找方式： 在 Element 中，前往 设置 → 安全与隐私 → 加密 → 你的恢复密钥（也称为"安全密钥"）。这是你首次设置交叉签名时被要求保存的密钥。

每次启动时，如果设置了 MATRIX_RECOVERY_KEY，Hermes 会从家庭服务器的安全密钥存储中导入交叉签名密钥并签名当前设备。此操作是幂等的，可以永久保持启用状态。

删除加密存储

如果你删除 ~/.hermes/platforms/matrix/store/crypto.db，机器人会丢失其加密身份。仅仅使用相同的设备 ID 重启不能完全恢复——家庭服务器仍保存着用旧身份密钥签名的一次性密钥，其他节点无法建立新的 Olm 会话。

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

最简单的恢复方式：生成新的访问 Token（获得一个没有陈旧密钥历史的全新设备 ID）。请参阅下面的"从带 E2EE 的旧版本升级"部分。这是最可靠的方式，无需修改家庭服务器数据库。

手动恢复（高级——保留相同设备 ID）：

  1. 停止 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 删除设备可能同时使关联的访问 Token 失效。之后可能需要生成新 Token。

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

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

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

信息

如果未安装 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 中（使用完整的 @用户名:服务器 格式）。重启网关。

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

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

解决方法：验证 MATRIX_HOMESERVER 指向你的家庭服务器（包含 https://，无尾部斜杠）。检查 MATRIX_ACCESS_TOKEN 是否有效——用 curl 测试：

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

如果返回你的用户信息，Token 有效。如果返回错误，请生成新 Token。

"mautrix not installed" 错误​

原因：未安装 mautrix Python 包。

解决方法：安装它：

pip install 'mautrix[encryption]'

或使用 Hermes 扩展：

pip install 'hermes-agent[matrix]'

加密错误 / "could not decrypt event"​

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

解决方法：

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

从带 E2EE 的旧版本升级​

提示

如果你还手动删除了 crypto.db，请参阅上方 E2EE 部分的"删除加密存储"警告——需要额外步骤清理家庭服务器上的陈旧一次性密钥。

如果你之前使用 Hermes 启用了 MATRIX_ENCRYPTION=true，并升级到使用新 SQLite 加密存储的版本，机器人的加密身份已发生变化。你的 Matrix 客户端（Element）可能缓存了旧的设备密钥，并拒绝与机器人共享加密会话。

症状：机器人连接后日志显示"E2EE enabled"，但所有消息显示"could not decrypt event"，机器人从不响应。

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

解决方法（一次性迁移）：

  1. 生成新的访问 Token 以获得全新的设备 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。

  2. 删除旧加密状态：

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

  3. 设置恢复密钥（如果你使用交叉签名——大多数 Element 用户都使用）。在 ~/.hermes/.env 中添加：

    MATRIX_RECOVERY_KEY=EsT... your recovery key here

    这让机器人在启动时使用交叉签名密钥自签名，使 Element 立即信任新设备。没有此设置，Element 可能将新设备视为未验证并拒绝共享加密会话。在 Element 的 设置 → 安全与隐私 → 加密 中找到你的恢复密钥。

  4. 强制 Matrix 客户端轮换加密会话。在 Element 中，打开与机器人的私信房间并输入 /discardsession。这会强制 Element 创建新的加密会话并与机器人的新设备共享。

  5. 重启网关：

    hermes gateway run

    如果设置了 MATRIX_RECOVERY_KEY，日志中应出现 Matrix: cross-signing verified via recovery key。

  6. 发送新消息。机器人应能正常解密并响应。

备注

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

提示

新安装不受影响。 此迁移仅适用于使用旧版 Hermes 已有可用 E2EE 设置并正在升级的情况。

为什么需要新访问 Token？ 每个 Matrix 访问 Token 绑定到特定的设备 ID。用新的加密密钥重用相同的设备 ID 会导致其他 Matrix 客户端不信任该设备（它们将身份密钥的更改视为潜在安全漏洞）。新访问 Token 获得一个没有陈旧密钥历史的新设备 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 适配器 ← 监听 0.0.0.0:8642
       ├─ AIAgent ← 唯一数据来源
       ├─ 会话、记忆、技能
       └─ 本地文件访问（Obsidian、项目等）

Linux 虚拟机（Docker）：
  └─ hermes gateway（代理模式）
       ├─ Matrix 适配器 ← E2EE 解密/加密
       └─ HTTP 转发 → macOS:8642/v1/chat/completions
           （无 LLM API 密钥、无 Agent、无推理）

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：启动两者​

  1. 先启动宿主机网关：

    hermes gateway

  2. 启动 Docker 容器：

    docker compose up -d

  3. 在加密 Matrix 房间中发送消息。容器解密消息，转发到宿主机，并流式返回响应。

配置参考​

代理模式在容器侧（精简网关）配置：

设置描述
GATEWAY_PROXY_URL远程 Hermes API 服务器 URL（例如 http://192.168.1.100:8642）
GATEWAY_PROXY_KEY身份验证 Bearer Token（必须与宿主机的 API_SERVER_KEY 匹配）
gateway.proxy_url与 GATEWAY_PROXY_URL 相同，但在 config.yaml 中配置

宿主机侧需要：

设置描述
API_SERVER_ENABLED设置为 true
API_SERVER_KEYBearer Token（与容器共享）
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 用户。这些问题可在未来版本中解决。

同步问题 / 机器人落后​

原因：长时间运行的工具执行可能延迟同步循环，或家庭服务器响应较慢。

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

机器人离线​

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

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

"User not allowed" / 机器人忽略你​

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

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

安全​

注意

始终设置 MATRIX_ALLOWED_USERS 来限制谁可以与机器人交互。没有此设置，网关默认会拒绝所有用户作为安全措施。只添加你信任的人的用户 ID——授权用户可以完全访问 Agent 的功能，包括工具调用和系统访问权限。

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

说明​

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