manuallatest产品手册 / Mattermost
Mattermost
本文说明如何将 Mattermost 接入 Agentic Engine。当前渠道通过 Mattermost REST API v4 发送和编辑消息，通过 WebSocket 接收消息；用户身份支持 OAuth 授权或一次性绑定码。
一、前置条件
- 拥有 Mattermost 系统管理员权限，可创建 Bot Account；如需 OAuth，还需创建 OAuth 2.0 Application。
- 拥有 Agentic Engine「管理后台 → 渠道管理」权限。
- 准备一个可供 Bot 使用的 Team 和 Channel。
- Agentic Engine 服务端能够访问 Mattermost Site URL、
/api/v4/**和/api/v4/websocket。 - 如需 OAuth 绑定，准备用户浏览器可访问的 Agentic Engine 地址；生产环境建议使用 HTTPS。
提示
支持范围：Mattermost Cloud 和自建部署均可使用；Site URL 可以包含部署子路径。
二、创建 Mattermost Bot 并获取凭证
使用 Mattermost 系统管理员账号按以下步骤操作：
- 进入 System Console → Integrations → Bot Accounts，将 Enable Bot Account Creation 设置为 true。
- 打开 Product menu → Integrations → Bot Accounts，点击 Add Bot Account。
- 填写 Bot Username、Display Name 和 Description；生产环境建议保持普通 Member 权限，按最小权限原则授权。
- 点击 Create Bot Account，立即复制生成的 Access Token。
- 将 Bot 加入需要使用的 Team 和 Channel。
警告
Bot Token 只显示一次。请立即保存到受控的密码管理系统，不要写入代码仓库、工单或聊天记录。若 Token 泄露，请在 Mattermost 中撤销并重新生成。
Bot 至少需要以下能力：
| 能力 | 用途 |
|---|---|
| 读取目标 Channel | 接收私聊、频道、私有频道和群聊中的消息。 |
| 创建 Post | 发送普通回复和最终结果。 |
| 编辑自己创建的 Post | 在同一条 Post 中展示流式回复。 |
| 读取和上传文件 | 处理用户附件，并把 Agent 生成的文件发回原频道和原 thread。 |
记录 Mattermost Site URL
记录当前 Mattermost 站点地址，例如：
Mattermost Site URL
https://chat.example.com
如果站点部署在子路径下，可填写：
https://example.com/mattermost
请勿附加 /api/v4、查询参数、fragment，或在 URL 中嵌入用户名和密码。
三、创建 OAuth 2.0 应用（可选）
OAuth 不是机器人收发消息的必需项。关闭 OAuth 后，用户仍可通过 6 位一次性绑定码完成绑定。如果希望用户点击入口后直接授权绑定，请继续配置：
- 进入 System Console → Integrations → Integration Management，将 Enable OAuth 2.0 Service Provider 设置为 true。
- 进入 Product menu → Integrations → OAuth 2.0 Applications，点击 Add OAuth 2.0 Application。
- 将 Is Public Client 设置为 No，创建 Confidential Client。
- 建议将 Is Trusted 保持为 No，让用户首次绑定时明确确认授权。
- 填写 Callback URL，保存后记录 Client ID 和 Client Secret。
Callback URL 必须与 Agentic Engine 实际访问地址完全一致：
https://your-domain/agent/api/mattermost-oauth/callback
提示
OAuth 应用按 Mattermost 实例注册。Client ID、Client Secret 与 Server URL 必须属于同一个 Mattermost 实例，不能跨实例复用。
四、在 Agentic Engine 中添加 Mattermost 渠道
管理员登录 Agentic Engine，进入「管理后台 → 渠道管理」：
- 点击「新建渠道」，渠道类型选择 Mattermost。
- 填写下列配置项。
| 配置项 | 是否必填 | 说明 |
|---|---|---|
| 渠道名称 | 必填 | 显示名称，例如「Mattermost 机器人」。 |
Server URL | 必填 | Mattermost Site URL；可以包含部署子路径，但不要包含 /api/v4。 |
Bot Token | 必填 | 创建 Bot Account 后生成的 Access Token。 |
| 启用 OAuth 绑定 | 可选 | 开启后用户优先通过浏览器授权；关闭后仍可使用一次性绑定码。 |
OAuth Client ID | 条件必填 | 启用 OAuth 时必须填写。 |
OAuth Client Secret | 条件必填 | 启用 OAuth 时必须填写。 |
| 默认模型 | 可选 | 不选择时使用系统全局默认模型。 |
| 系统提示词 | 可选 | 仅对该渠道中的 Agent 会话生效。 |
- 点击「保存」，然后打开渠道的「启用」开关。
- 确认渠道状态正常。启用时系统会调用
/api/v4/users/me校验 Bot Token 与 Bot 身份，再连接<Site URL>/api/v4/websocket。
提示
编辑 Secret：编辑已有渠道时，Bot Token 或 OAuth Client Secret 留空表示保留原值；系统不会回显已保存的 Secret。
五、用户绑定 Mattermost 账号
方式一：OAuth 授权绑定
- 用户登录 Agentic Engine，点击左下角个人菜单，选择 Mattermost。
- 浏览器打开当前 Mattermost 实例的授权页。
- 用户登录并确认授权，完成后窗口关闭，菜单中的状态变为「已绑定」。
OAuth access token 只在回调过程中短暂使用，不写入数据库，也不会替代渠道配置中的 Bot Token。
方式二：一次性绑定码
未开启 OAuth，或系统无法获取授权地址、授权地址无效、浏览器拦截授权窗口时，会自动使用绑定码：
- 点击左下角个人菜单中的 Mattermost。
- 复制弹窗中的绑定命令。
- 在 Mattermost 中私聊 Bot，发送该命令。
- Bot 回复绑定成功后，Agentic Engine 会自动刷新绑定状态。
绑定命令示例
+bind ABC234
警告
绑定码默认 10 分钟有效且只能使用一次。为避免泄露，系统不接受频道或群聊中的绑定命令；同一个 Mattermost 账号不能同时绑定给多个 Agentic Engine 用户。
解绑
- 点击左下角个人菜单，在 Mattermost 一行点击「解绑」。
- 确认后状态变为「未绑定」。如需更换 Agentic Engine 账号，请先完成原账号解绑。
六、使用方式
| 场景 | 操作说明 |
|---|---|
| 私聊 | 直接向 Bot 发送问题。 |
| 公开/私有频道与群聊 | 使用 @Bot用户名 问题内容；未 @Bot 的普通消息会被忽略。 |
| 线程 | 在已有 thread 中提问时，回复继续留在该 thread；从频道根消息提问时，Bot 以该消息为 root 创建 thread 回复。 |
| 等待用户回答 | 点击“填写回答”打开 Dialog，或按 Bot 提示直接回复文字；达到最大轮次时可点击“继续执行”或回复“继续”。 |
| 发送附件给 Agent | 私聊可直接发送附件；频道中需要在附件消息正文中 @Bot。 |
| 接收 Agent 文件 | Agent 生成的文件会作为新 Post 发回原频道和原 thread。 |
| 任务通知 | Agent Team 即时任务和定时任务可选择 Mattermost；结果发送到任务创建者已绑定账号的私聊。 |
常用命令
| 命令 | 说明 | 示例 |
|---|---|---|
+bind <CODE> | 使用一次性绑定码绑定账号。 | +bind ABC234 |
+new | 开启新会话。 | +new |
+agent <Agent名称> <问题> | 向指定 Agent 发消息。 | +agent rhea 帮我分析数据 |
频道中使用命令时仍须先 @Bot用户名。
七、故障排查
保存时提示配置无效
- Server URL 必须是完整的
http://或https://URL。 - 不要填写
/api/v4，也不要携带 query、fragment 或 URL 内嵌凭证。 - 新建渠道时 Bot Token 不能为空；编辑时留空才表示保留旧 Token。
渠道启用后离线或反复重连
- 使用同一个 Bot Token 请求
GET <Site URL>/api/v4/users/me，确认返回 Bot 用户。 - 检查 Agentic Engine 到 Mattermost 的 DNS、TLS 和网络连通性。
- 确认反向代理允许
/api/v4/websocket的 WebSocket Upgrade。 - 确认 Bot 未被删除、禁用，Token 未被撤销或重新生成。
Bot 收不到频道消息
- 确认 Bot 已加入目标 Team 和 Channel。
- 公开频道、私有频道和群聊必须正确
@Bot用户名。 - 确认渠道已经启用并处于正常状态。
能收到消息但无法回复
- 确认 Bot 具备在目标 Channel 创建 Post 的权限。
- 流式回复需要 Bot 能编辑自己创建的 Post。
- 如果使用高级权限方案，确认没有禁止成员编辑自己创建的 Post。
附件无法下载或上传
- 确认 Bot 是目标 Channel 的成员，并具备读取和上传文件的权限。
- 检查
channel.mattermost.fileUploads.enabled是否开启，以及大小、数量和超时限制。 - 默认每条消息最多处理 5 个附件、每个不超过 2 MiB；扩展名、MIME 和实际文件内容不一致时可能被拒绝。
绑定码无效
- 重新生成绑定码，并在 10 分钟内使用。
- 确认命令发送给当前租户配置的 Mattermost Bot。
- 绑定命令只能通过与 Bot 的私聊发送。
OAuth 授权失败
- 确认 Mattermost 已开启 OAuth 2.0 Service Provider，OAuth Application 使用 Confidential Client。
- 确认 Client ID、Client Secret 与 Server URL 属于同一个 Mattermost 实例。
- Callback URL 必须与 Agentic Engine 管理界面提示的地址完全一致，并包含实际 basePath。
- 将 Agentic Engine Origin 加入
ALLOWED_ORIGINS；生产环境使用 HTTPS，并确保 Cookie 安全设置与协议一致。 - 本地访问应使用真实浏览器 Origin，例如
http://localhost:3000，不要将0.0.0.0填入 OAuth Callback URL。
相关页面与下一步
这篇文档对你有帮助吗？