Mattermost

本指南将指导您如何将 Hermes Agent 配置为 Mattermost 机器人的完整流程。

前提条件

已安装并运行的 Mattermost 服务器（版本 6.0 或更高）
具备管理员权限的账户
一个可访问的公网域名或 IP 地址（用于 Webhook）
安装了 Node.js（v18 或更高）和 npm 的开发环境

步骤 1：创建 Mattermost 应用集成

登录到您的 Mattermost 管理员面板。
导航至 System Console > Integrations > Custom Integrations。
点击 Create a new integration。
选择 Incoming Webhooks 类型。
填写以下信息：
- Name: Hermes Agent
- Description: Hermes Agent bot for Mattermost
- Channel: 选择希望机器人发送消息的频道（例如 #general）
点击 Create，系统将生成一个 Webhook URL。请复制并保存该 URL，稍后使用。

⚠️ 注意：此 Webhook URL 将用于接收来自 Hermes Agent 的响应。

步骤 2：部署 Hermes Agent

方法一：使用 Docker（推荐）

创建 docker-compose.yml 文件：

version: '3.8'
services:
  hermes-agent:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-agent
    environment:
      - MATTERMOST_WEBHOOK_URL=https://your-mattermost.example/hooks/your-webhook-id
      - OPENAI_API_KEY=your_openai_api_key_here
      - MODEL_NAME=gpt-4o
      - LOG_LEVEL=info
    ports:
      - "3000:3000"
    restart: unless-stopped

替换占位符：
- https://your-mattermost.example/hooks/your-webhook-id → 替换为您在步骤 1 中获取的 Mattermost Webhook URL
- your_openai_api_key_here → 替换为您的 OpenAI API 密钥（可选；也可使用其他 LLM 提供商如 OpenRouter）
启动服务：

docker-compose up -d

方法二：本地运行

克隆仓库：

git clone https://github.com/nousresearch/hermes-agent.git
cd hermes-agent

安装依赖：

npm install

创建 .env 文件：

MATTERMOST_WEBHOOK_URL=YOUR_MATTERMOST_WEBHOOK_URL
OPENAI_API_KEY=your-openai-api-key
MODEL_NAME=gpt-4o
LOG_LEVEL=info
PORT=3000

启动应用：

npm run start

步骤 3：配置机器人行为

Hermes Agent 支持多种交互模式，可通过环境变量或命令行参数进行配置。

常用配置项

环境变量	说明
`MATTERMOST_WEBHOOK_URL`	Mattermost Incoming Webhook URL
`OPENAI_API_KEY`	OpenAI API Key（支持 OpenRouter、Anthropic 等）
`MODEL_NAME`	使用的模型名称（如 `gpt-4o`, `claude-3-opus`）
`LOG_LEVEL`	日志级别（`debug`, `info`, `warn`, `error`）
`ENABLE_COMMANDS`	是否启用命令功能（默认 `true`）
`COMMAND_PREFIX`	命令前缀（默认 `@hermes`）

示例命令

在 Mattermost 频道中输入以下内容以测试：

@hermes 你好，能帮我总结一下最近的会议记录吗？

或

@hermes 请用 Markdown 格式生成一份项目计划表。

步骤 4：验证与调试

在 Mattermost 频道中发送一条测试消息。
检查 Hermes Agent 的日志输出是否收到请求并返回响应。
若无响应，请检查：
- Webhook URL 是否正确
- 网络是否可达（确保防火墙允许外部访问）
- API 密钥是否有效
- 日志中是否有错误信息

可选：自定义机器人外观

您可以通过修改 Webhook 的 username 和 icon_url 来美化机器人显示效果。

在 docker-compose.yml 或 .env 中添加：

MATTERMOST_USERNAME=Hermes Bot
MATTERMOST_ICON_URL=https://example.com/hermes-icon.png

💡 提示：建议使用透明背景的 PNG 图片以获得最佳视觉效果。

进阶功能

多频道支持：通过配置多个 Webhook 或使用事件路由实现跨频道响应。
权限控制：结合 Mattermost 的角色权限系统限制特定用户调用机器人。
持久化上下文：启用会话记忆功能（需额外配置数据库）。

故障排除

问题	解决方案
机器人不响应	检查 Webhook URL 是否正确，确认服务正在运行
API 调用失败	验证 API 密钥有效性，检查网络连接
响应格式错误	查看日志中的 JSON 结构是否符合 Mattermost 要求
无法发送图片/文件	确保模型支持多媒体输出，且客户端支持渲染

✅ 完成！现在您已成功将 Hermes Agent 部署为 Mattermost 机器人，可以开始智能协作了！

如需更多帮助，请访问 Hermes Agent 官方文档或加入我们的 Discord 社区。"

Mattermost 设置

Hermes Agent 作为机器人与 Mattermost 集成，让您可以通过私信或团队频道与 AI 助手聊天。Mattermost 是一个自托管的开源 Slack 替代品——您在自己的基础设施上运行它，完全掌控数据。该机器人通过 Mattermost 的 REST API（v4）和 WebSocket 连接，实时处理消息事件，经由 Hermes Agent 处理管道（包括工具调用、记忆和推理），并实时响应。支持文本、文件附件、图片以及斜杠命令。

无需外部 Mattermost 库——适配器使用 aiohttp，该库已是 Hermes 的依赖项。

在设置之前，先了解大家最关心的问题：Hermes 在您的 Mattermost 实例中会如何表现。

Hermes 的行为表现

上下文	行为
私信 (DMs)	Hermes 对每条消息都会回复。无需 `@mention`。每个私信对话拥有独立会话。
公开/私有频道	Hermes 仅在被 `@mention` 时才回应。未被提及的消息将被忽略。
线程 (Threads)	若启用，Hermes 将在您的消息下方以线程形式回复。线程上下文与主频道隔离。
多人共享频道	默认情况下，Hermes 为频道内的每位用户保留独立的会话历史。两人在同一频道聊天时不会共享同一对话记录，除非您显式禁用此行为。

tip

若希望 Hermes 以嵌套线程形式回复（即在您原始消息下生成子回复），请设置 MATTERMOST_REPLY_MODE=thread。默认值为 off，表示直接在频道内发送平铺消息。

Mattermost 中的会话模型

默认情况下：

每个私信对话拥有独立会话
每个线程拥有独立会话命名空间
每个共享频道中的用户拥有独立会话

这由 config.yaml 控制：

group_sessions_per_user: true

仅当您明确希望整个频道共享一个统一对话时，才将其设为 false：

group_sessions_per_user: false

共享会话适用于协作型频道，但也意味着：

用户之间共享上下文增长和 token 成本
一个人执行长时间、高负载的任务可能导致他人上下文膨胀
一人正在进行的操作可能中断另一人后续的提问

本指南将引导您完成完整设置流程——从在 Mattermost 上创建机器人账户，到发送第一条消息。

第一步：启用机器人账户

在创建机器人前，必须在 Mattermost 服务器上启用机器人账户功能。

使用 系统管理员 身份登录 Mattermost。
进入 系统控制台 → 集成 → 机器人账户。
将 启用机器人账户创建 设为 true。
点击保存。

info

若您没有系统管理员权限，请联系您的 Mattermost 管理员为您启用机器人账户并创建一个。

第二步：创建机器人账户

在 Mattermost 中点击左上角的 ☰ 菜单 → 集成 → 机器人账户。
点击 添加机器人账户。
填写以下信息：
- 用户名：例如 hermes
- 显示名称：例如 Hermes Agent
- 描述：可选
- 角色：Member 即可
点击 创建机器人账户。
Mattermost 将显示 机器人令牌。立即复制。

仅显示一次

机器人令牌仅在创建时显示一次。若丢失，需从机器人账户设置中重新生成。切勿公开分享或提交至 Git —— 拥有此令牌者将拥有对机器人的完全控制权。

请将令牌妥善保存（如密码管理器）。您将在第 5 步中使用。

tip

您也可以使用 个人访问令牌 代替机器人账户。进入 个人资料 → 安全 → 个人访问令牌 → 创建令牌。如果您希望 Hermes 以您的身份发布消息而非独立机器人，则此方式更合适。

第三步：将机器人加入频道

机器人需要是您希望其响应的频道成员：

打开目标频道。
点击频道名称 → 添加成员。
搜索您的机器人用户名（如 hermes）并添加。

对于私信，只需打开与机器人的直接消息即可——它将立即能够回复。

第四步：查找您的 Mattermost 用户 ID

Hermes Agent 使用您的 Mattermost 用户 ID 来控制谁可以与机器人互动。查找方法如下：

点击您的头像（左上角）→ 个人资料。
在个人资料弹窗中，您的用户 ID 会显示出来——点击即可复制。

您的用户 ID 是一个 26 位字母数字字符串，例如 3uo8dkh1p7g1mfk49ear5fzs5c。

warning

您的用户 ID 不是您的用户名。用户名是出现在 @ 后面的部分（如 @alice）。用户 ID 是 Mattermost 内部使用的长字符标识符。

替代方法：您也可通过 API 获取用户 ID：

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-mattermost-server/api/v4/users/me | jq .id

tip

获取 频道 ID：点击频道名称 → 查看信息。ID 显示在信息面板中。若您想手动设置主页频道，将需要此 ID。

第五步：配置 Hermes Agent

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

运行引导式设置命令：

hermes gateway setup

提示时选择 Mattermost，然后粘贴您的服务器地址、机器人令牌和用户 ID。

方式 B：手动配置

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

# Required
MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=***
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c

# Multiple allowed users (comma-separated)
# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e

# Optional: reply mode (thread or off, default: off)
# MATTERMOST_REPLY_MODE=thread

# Optional: respond without @mention (default: true = require mention)
# MATTERMOST_REQUIRE_MENTION=false

# Optional: channels where bot responds without @mention (comma-separated channel IDs)
# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2

可选的行为设置在 ~/.hermes/config.yaml 中：

group_sessions_per_user: true

group_sessions_per_user: true 可确保在共享频道和线程中，每位参与者的上下文保持隔离

启动网关

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

hermes gateway

机器人应在几秒内连接至您的 Mattermost 服务器。向其发送一条消息——无论是私信还是已添加机器人的频道——进行测试。

tip

您可以将 hermes gateway 在后台运行，或作为 systemd 服务长期运行。详情请参阅部署文档。

主页频道

您可以指定一个“主页频道”，让机器人主动发送消息（如定时任务输出、提醒和通知）。有两种设置方式：

使用斜杠命令

在任意机器人所在的频道中输入 /sethome。该频道将成为主页频道。

手动配置

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

MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn

将 ID 替换为实际的频道 ID（点击频道名称 → 查看信息 → 复制 ID）。

回复模式

MATTERMOST_REPLY_MODE 设置控制 Hermes 的回复方式：

模式	行为
`off`（默认）	Hermes 以普通用户方式在频道中发送平铺消息。
`thread`	Hermes 在您的原始消息下方以线程形式回复。当来回交流频繁时，有助于保持频道整洁。

在您的 ~/.hermes/.env 中设置：

MATTERMOST_REPLY_MODE=thread

提及行为

默认情况下，机器人仅在被 @mentioned 时才会在频道中回复。您可更改此行为：

变量	默认值	描述
`MATTERMOST_REQUIRE_MENTION`	`true`	设为 `false` 可使机器人在频道中响应所有消息（私信始终有效）。
`MATTERMOST_FREE_RESPONSE_CHANNELS`	(无)	逗号分隔的频道 ID 列表，即使 `require_mention` 为 true，机器人也会在这些频道中无需提及即响应。

在 Mattermost 中查找频道 ID：打开频道，点击频道名称栏，查看 URL 或频道详情中的 ID。

当机器人被 @mentioned 时，提及部分会在处理前自动移除。

故障排除

机器人不响应消息

原因：机器人不在该频道中，或 MATTERMOST_ALLOWED_USERS 不包含您的用户 ID。

解决方法：将机器人添加至频道（频道名称 → 添加成员 → 搜索机器人）。确认您的用户 ID 已包含在 MATTERMOST_ALLOWED_USERS 中。重启网关。

403 Forbidden 错误原因：机器人令牌无效，或机器人在频道中没有发帖权限。

解决方法：检查 MATTERMOST_TOKEN 文件中的 .env 是否正确。确保机器人账户未被停用。确认机器人已添加至目标频道。若使用个人访问令牌，请确保您的账户具备相应权限。

WebSocket 断开 / 重连循环

原因：网络不稳定、Mattermost 服务器重启，或 WebSocket 连接存在防火墙/代理问题。

解决方法：适配器会自动以指数退避方式重连（2秒 → 60秒）。请检查服务器的 WebSocket 配置 —— 反向代理（如 nginx、Apache）需配置 WebSocket 升级头。确认防火墙未阻止 Mattermost 服务器上的 WebSocket 连接。

对于 nginx，确保配置中包含：

location /api/v4/websocket {
    proxy_pass http://mattermost-backend;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 600s;
}

启动时提示“认证失败”

原因：令牌或服务器地址不正确。

解决方法：验证 MATTERMOST_URL 是否指向您的 Mattermost 服务器（请包含 https://, no trailing slash). Check that ）。确认 MATTERMOST_TOKEN` 有效 —— 可通过 curl 测试：

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-server/api/v4/users/me

如果返回结果包含机器人的用户信息，则令牌有效。若返回错误，请重新生成令牌。

机器人显示离线

原因：Hermes 网关未运行，或未能成功连接。

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

“用户不允许” / 机器人无视您

原因：您的用户 ID 未在 MATTERMOST_ALLOWED_USERS 列表中。

解决方法：将您的用户 ID 添加至 MATTERMOST_ALLOWED_USERS 的 ~/.hermes/.env 文件中，并重启网关。注意：用户 ID 是一个 26 位的字母数字字符串，而非您的 @username。

安全性

warning

始终设置 MATTERMOST_ALLOWED_USERS 以限制可与机器人交互的用户。若未设置，网关默认拒绝所有用户，作为安全措施。仅添加您信任的用户 ID —— 被授权的用户将拥有对代理全部功能的完全访问权限，包括工具调用和系统访问。

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

注意事项

自托管友好：适用于任何自托管的 Mattermost 实例，无需 Mattermost Cloud 账户或订阅。
无额外依赖：适配器使用 aiohttp 处理 HTTP 和 WebSocket，该组件已随 Hermes Agent 一并提供。
团队版兼容：支持 Mattermost 团队版（免费）和企业版。

前提条件​

步骤 1：创建 Mattermost 应用集成​

步骤 2：部署 Hermes Agent​

方法一：使用 Docker（推荐）​

方法二：本地运行​

步骤 3：配置机器人行为​

常用配置项​

示例命令​

步骤 4：验证与调试​

可选：自定义机器人外观​

进阶功能​

故障排除​

如需更多帮助，请访问 Hermes Agent 官方文档 或加入我们的 Discord 社区。"​

Mattermost 设置

Hermes 的行为表现​

Mattermost 中的会话模型​

第一步：启用机器人账户​

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

第三步：将机器人加入频道​

第四步：查找您的 Mattermost 用户 ID​

第五步：配置 Hermes Agent​

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

方式 B：手动配置​

启动网关​

主页频道​

使用斜杠命令​

手动配置​

回复模式​

提及行为​

故障排除​

机器人不响应消息​

403 Forbidden 错误原因：机器人令牌无效，或机器人在频道中没有发帖权限。​

WebSocket 断开 / 重连循环​

启动时提示“认证失败”​

机器人显示离线​

“用户不允许” / 机器人无视您​

安全性​

注意事项​

前提条件

步骤 1：创建 Mattermost 应用集成

步骤 2：部署 Hermes Agent

方法一：使用 Docker（推荐）

方法二：本地运行

步骤 3：配置机器人行为

常用配置项

示例命令

步骤 4：验证与调试

可选：自定义机器人外观

进阶功能

故障排除

如需更多帮助，请访问 Hermes Agent 官方文档或加入我们的 Discord 社区。"

Hermes 的行为表现

Mattermost 中的会话模型

第一步：启用机器人账户

第二步：创建机器人账户

第三步：将机器人加入频道

第四步：查找您的 Mattermost 用户 ID

第五步：配置 Hermes Agent

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

方式 B：手动配置

启动网关

主页频道

使用斜杠命令

手动配置

回复模式

提及行为

故障排除

机器人不响应消息

403 Forbidden 错误原因：机器人令牌无效，或机器人在频道中没有发帖权限。

WebSocket 断开 / 重连循环

启动时提示“认证失败”

机器人显示离线

“用户不允许” / 机器人无视您

安全性

注意事项