> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# Mattermost 机器人

> 配置 Mattermost 机器人入口，并控制频道、令牌和审计边界。

Mattermost 机器人用于把艾维斯能力接入自托管 Mattermost 协作环境。上线前应把它当作受控消息入口来配置：只接收已批准团队、频道或命令触发的请求，只返回当前用户或频道允许访问的知识和工具结果，并保留可审计的请求记录。

## 适用场景

| 场景         | 建议                                                                                |
| ---------- | --------------------------------------------------------------------------------- |
| 公开频道问答     | 使用 Outgoing Webhook，把触发词限制在一个或几个已批准公开频道。                                          |
| 私有频道或私聊问答  | 使用自定义 Slash Command。Mattermost 官方文档说明 Slash Command 可用于公开频道、私有频道和 Direct Message。 |
| 固定机器人身份发帖  | 创建 Bot Account，并使用机器人访问令牌调用 Mattermost REST API。                                  |
| 生产 ChatOps | 使用独立 Mattermost 机器人账号、独立 webhook 或 command，并绑定独立艾维斯工作区和访问范围。                      |
| 敏感知识问答     | 先验证 Mattermost 来源频道、用户和艾维斯访问群组，不把机器人配置成绕过权限的共享代理。                                 |

## 接入方式选择

| Mattermost 能力                       | 适合用途                                           | 注意事项                                               |
| ----------------------------------- | ---------------------------------------------- | -------------------------------------------------- |
| Outgoing Webhook                    | 监听公开频道消息或触发词，并把消息 POST 到艾维斯回调地址。               | 官方文档说明 Outgoing Webhook 支持公开频道；如果留空频道或触发词，触发范围会变宽。 |
| Custom Slash Command                | 用户输入 `/aivis 问题` 后把请求发送到艾维斯。                   | 可用于私有频道和私聊，并支持命令自动补全。                              |
| Bot Account + Personal Access Token | 艾维斯需要主动调用 Mattermost REST API 发帖、回帖或访问频道信息时使用。 | 使用非管理员 bot 账号，不复用 System Admin 或个人账号 token。        |

通常建议先使用 **Custom Slash Command** 做最小闭环：触发范围清晰、用户意图明确，也更适合私有频道和 Direct Message。只有需要监听公开频道自然语言消息时，再使用 Outgoing Webhook。

## 管理边界

| 项目 | 建议                                                                                 |
| -- | ---------------------------------------------------------------------------------- |
| 入口 | 只绑定已批准的 Mattermost 站点、团队、频道、Slash Command 或 Outgoing Webhook。                      |
| 身份 | 使用专用 Bot Account 或专用集成账号，不复用管理员个人令牌。                                               |
| 响应 | 根据 Mattermost 来源、艾维斯用户/群组、Agent、知识库和工具权限控制可返回内容。                                   |
| 回调 | 回调 URL 应使用 HTTPS；如果部署在内网，按 Mattermost 官方要求配置可信内部连接。                                |
| 运维 | 记录 Mattermost Site URL、team/channel、command/webhook token、bot token、网络策略、负责人和轮换时间。 |

## 配置前检查

* 已确认 Mattermost Server 版本和部署方式，且当前账号有权限进入 **Product menu > Integrations** 或系统管理员可代为配置。
* 已确认服务器已启用所需集成能力：Outgoing Webhooks、Custom Slash Commands、Personal Access Tokens 或 Bot Accounts。
* 已准备可供 Mattermost 访问的艾维斯 HTTPS 回调 URL。
* 已明确机器人允许服务的团队、频道、用户范围、默认 Agent、知识范围和工具范围。
* 已决定使用 Outgoing Webhook、Custom Slash Command，还是额外使用 Bot Account / Personal Access Token。
* 所有 token 只保存到受保护配置中，不写入公开文档、Agent 指令、工单、截图或聊天记录。

## 配置数据获取入口

| 配置数据                   | 获取方式                                                                                                                                                                                                                                                                                                                                                                 |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Mattermost Site URL    | 使用 Mattermost 站点根地址，例如 `https://mattermost.example.com`。艾维斯后端需要能访问该地址，用户浏览器也应能打开来源链接。                                                                                                                                                                                                                                                                                |
| Outgoing Webhook Token | 在 Mattermost 打开 **Product menu > Integrations > Outgoing Webhooks**，创建 webhook 后复制 Token。可参考 [Mattermost Developers：Outgoing webhooks](https://developers.mattermost.com/integrate/webhooks/outgoing/)。                                                                                                                                                              |
| Slash Command Token    | 在 **Product menu > Integrations > Slash Commands** 创建自定义命令后复制生成的 token。可参考 [Mattermost Developers：Custom slash commands](https://developers.mattermost.com/integrate/slash-commands/custom/)。                                                                                                                                                                        |
| Bot Account Token      | 在 **System Console > Integrations > Bot Accounts** 启用 bot 账号创建，再从 **Integrations > Bot Accounts** 创建专用机器人并复制生成 token。可参考 [Mattermost Developers：Bot accounts](https://developers.mattermost.com/integrate/reference/bot-accounts/)。                                                                                                                                  |
| Personal Access Token  | 若使用普通集成账号，先在系统控制台启用 Personal Access Tokens，再在该账号 **Profile > Security > Personal Access Tokens** 创建。可参考 [Mattermost Developers：Personal access tokens](https://developers.mattermost.com/integrate/reference/personal-access-token/)。                                                                                                                                |
| Team / Channel ID      | 从 Mattermost 频道链接、API 返回值或系统管理信息中确认；上线前记录 team、channel、channel display name 和 owner，避免只凭频道显示名配置。                                                                                                                                                                                                                                                                     |
| 集成开关                   | 在 **System Console > Integrations > Integration Management** 检查 Outgoing Webhooks、Custom Slash Commands 和 Personal Access Tokens；Bot Accounts 在 **System Console > Integrations > Bot Accounts** 中检查。可参考 [Mattermost 管理文档：Integrations configuration settings](https://docs.mattermost.com/administration-guide/configure/integrations-configuration-settings.html)。 |

## 配置 Outgoing Webhook

如果希望机器人监听公开频道中的触发词，可在 Mattermost 创建 Outgoing Webhook：

1. 打开 **Product menu > Integrations > Outgoing Webhooks**。
2. 点击 **Add Outgoing Webhook**，填写名称和描述。
3. 选择请求内容类型。建议使用 `application/json`，便于艾维斯按结构化请求解析。
4. 选择一个明确的公开频道，或设置一个清晰的触发词，例如 `aivis`。
5. 在 **Callback URLs** 中填写艾维斯提供的回调 URL 并保存。
6. 复制 Mattermost 生成的 Token，回到艾维斯机器人配置页填写。

Outgoing Webhook 的频道或触发词不要留得过宽。官方文档说明，如果频道为空，触发词会在团队的全部公开频道生效；如果触发词为空，则会响应所选公开频道的全部消息。

## 配置 Slash Command

如果希望用户明确通过 `/aivis` 调用机器人，或需要支持私有频道和私聊，建议创建自定义 Slash Command：

1. 打开 **Product menu > Integrations > Slash Commands**。
2. 点击 **Add Slash Command**。
3. 设置命令标题、描述和唯一触发词，例如 `aivis`。触发词不要包含 `/` 或空格。
4. 将 **Request URL** 设置为艾维斯回调 URL。
5. 将请求方法设置为 `POST`。
6. 按需开启 autocomplete，并填写参数提示，例如 `[问题]`。
7. 保存后复制生成的 token，回到艾维斯机器人配置页填写。

## 配置 Bot Account

只有在艾维斯需要主动调用 Mattermost REST API 发帖、回帖、发私信或查询频道信息时，才需要 Bot Account 或 Personal Access Token。

1. 在系统控制台确认已启用 **Bot Accounts** 和必要的 **Personal Access Tokens**。
2. 创建专用 Bot Account，例如 `aivis-bot`，不要授予 System Admin，除非经过单独安全评审。
3. 把 bot 加入允许服务的 team 和 channel。
4. 复制生成的 bot access token，并填入艾维斯受保护凭据。
5. 在测试频道发送一条由 bot 发出的最小回复，确认身份、频道和权限符合预期。

## 在艾维斯中配置

在艾维斯管理后台打开 Mattermost 机器人配置页，按所选接入方式填写：

| 艾维斯字段                   | Mattermost 来源                                  | 说明                                                                  |
| ----------------------- | ---------------------------------------------- | ------------------------------------------------------------------- |
| Mattermost 站点地址         | Mattermost Site URL                            | 用于生成来源链接或调用 Mattermost API。                                         |
| 回调 URL                  | 艾维斯生成                                          | 复制到 Outgoing Webhook 的 Callback URLs 或 Slash Command 的 Request URL。 |
| Webhook / Command Token | Mattermost Outgoing Webhook 或 Slash Command 生成 | 用于校验请求确实来自 Mattermost。                                              |
| Bot Access Token        | Bot Account 或 Personal Access Token            | 仅在需要主动调用 Mattermost REST API 时填写。                                   |
| 允许的 Team / Channel      | Mattermost team、channel 或内部审批记录                | 限定机器人可以响应的来源。                                                       |
| 默认 Agent / 知识范围         | 艾维斯配置                                          | 决定机器人默认调用哪些知识和工具。                                                   |

保存后，确认机器人开关为已启用，并记录回调 URL、Mattermost 集成名称、token owner 和负责人。

## 验证

1. 在测试频道或私聊中发送一条普通问题，确认机器人能回复。
2. 如果使用 Outgoing Webhook，测试触发词和非触发词，确认只有预期消息会触发。
3. 如果使用 Slash Command，测试 `/aivis 问题`、空参数和异常参数。
4. 使用未授权频道、未授权用户或未绑定 Agent 的问题测试拒绝路径。
5. 在艾维斯追踪中确认 Mattermost 来源、team、channel、user、触发方式、响应结果和错误信息可审计。
6. 轮换 webhook token、command token 或 bot token 后，重新保存艾维斯配置并重复测试。

## 常见问题排查

| 现象                             | 优先检查项                                                             |
| ------------------------------ | ----------------------------------------------------------------- |
| Mattermost 中没有 Integrations 菜单 | 系统管理员是否启用了对应集成能力，或当前用户是否被允许创建集成。                                  |
| Outgoing Webhook 没有触发          | 频道是否为公开频道，触发词是否匹配，频道或触发词是否被配置得过窄。                                 |
| Slash Command 无响应              | Request URL 是否为艾维斯回调 URL，请求方法是否为 `POST`，Mattermost 服务端是否能访问该地址。   |
| 艾维斯收到请求但校验失败                   | Webhook / Command Token 是否填错，是否复制了 token ID 而不是真实 token，是否包含多余空格。 |
| Bot 无法发帖                       | Bot 是否已加入目标 team/channel，token 是否有效，是否具备向目标频道发帖的权限。               |
| 私有频道或 DM 不可用                   | 不要用 Outgoing Webhook；改用 Slash Command 或 Bot Account + REST API。   |
| 搜索结果包含不该看到的内容                  | 调整艾维斯访问群组、默认 Agent、知识范围或 Mattermost 来源白名单。                        |

## 安全与维护建议

* 为生产、测试和演示环境使用不同 Mattermost 集成和 token。
* 不使用 System Admin 个人 token 作为机器人凭据。
* Outgoing Webhook、Slash Command 和 Bot Account token 都应定期轮换，并记录 token owner。
* 关闭长期不用的 webhook、command 或 bot account 后，再停用艾维斯侧机器人。
* 频道、团队、owner 或访问范围变更后，重新验证拒绝路径和追踪记录。

## 官方参考

* [Mattermost Developers：Bot accounts](https://developers.mattermost.com/integrate/reference/bot-accounts/)
* [Mattermost Developers：Personal access tokens](https://developers.mattermost.com/integrate/reference/personal-access-token/)
* [Mattermost Developers：Outgoing webhooks](https://developers.mattermost.com/integrate/webhooks/outgoing/)
* [Mattermost Developers：Slash commands](https://developers.mattermost.com/integrate/slash-commands/)
* [Mattermost Developers：Custom slash commands](https://developers.mattermost.com/integrate/slash-commands/custom/)
* [Mattermost 管理文档：Integrations configuration settings](https://docs.mattermost.com/administration-guide/configure/integrations-configuration-settings.html)

## 相关页面

* [智能体](/aivis/agents/agents)
* [用户、群组与角色](/aivis/governance/users-and-groups)
* [追踪](/aivis/governance/tracing)