# Slack 配置指南

MOI 通过 Socket Mode 长连接接入 Slack 应用。你需要在 Slack 创建应用并获得 **App ID**、**App-Level Token** 和 **Bot Token** 三个凭据。MOI 不需要公网域名、回调 URL 或工具实例。

```{note}
Slack 应用控制台的菜单位置可能随平台版本调整，请以当前页面为准；下述步骤标注了需要开启的功能、权限和要记录的凭据。
```

## 一、创建 Slack 应用

1. 打开 [Slack API Apps](https://api.slack.com/apps)，点击 **Create App**，选择 **Blank app** 并选择目标工作区。
2. 记录应用概览页的 **App ID**。

## 二、开启 Socket Mode 并订阅事件

1. 在应用配置中开启 **Socket Mode**，按提示创建 **App-Level Token**，勾选 `connections:write` 权限。该 Token 以 `xapp-` 开头。
2. 在 **Event Subscriptions** 中启用事件订阅，订阅所需的 **Bot Events**，例如 `app_mention`、`message.im`。
3. 在 **OAuth & Permissions** 的 **Bot Token Scopes** 中，按使用场景配置下表中的权限。
4. 将应用**安装到目标工作区**，获得 **Bot Token**（以 `xoxb-` 开头）。

| 使用场景 | Bot Token 权限 | 事件订阅 |
| --- | --- | --- |
| 接收用户私聊消息 | `im:history` | `message.im` |
| 接收频道中 @机器人的消息 | `app_mentions:read` | `app_mention` |
| 在会话中发送回复 | `chat:write` | 无需新增事件 |
| 读取用户发送的文件 | `files:read` | 消息所在会话对应的消息事件 |
| 将智能体生成的文件发回会话 | `files:write` | 无需新增事件 |

App-Level Token 的 `connections:write` 用于建立 Socket Mode 连接；消息接收和文件收发还需要 Bot Token 具备对应权限。权限依据见 Slack 官方说明[^slack-dm][^slack-mentions][^slack-files-read][^slack-files-write][^slack-chat]。

更改 Bot Token 权限后，按 Slack 页面提示重新安装应用并完成授权，再更新 MOI 中需要更换的 Token。

## 三、在 MOI 中建立连接

1. 在智能体卡片的**⋯**菜单中打开**IM 双向通信**。
2. 平台选择 **Slack App / Bot**，接收方式保持**长连接**。
3. 填写 **App ID**、**App-Level Token** 和 **Bot Token**。首次连接时必须填写两个 Token；编辑已有连接时，留空表示保留现有值，需要更换时填写新值并保存。
4. 为该智能体选择**运行模型**。
5. 点击**保存并继续**。MOI 提示「双向通信已保存，正在建立连接」即开始接入。

## 四、验证连接

1. 在 MOI 中确认显示**配置已保存**和**MOI 接收已启用**，再等待**连接已建立**。
2. 在 Slack 中向 Bot 发送私聊消息，或先将 Bot 邀请进入测试频道，再 @机器人发送消息。
3. 返回 MOI，确认接收状态变为**已收到真实消息**，再在原 Slack 对话或回复线程中确认收到智能体回复。

**已收到真实消息**只确认 MOI 已收到消息。没有回复时，继续检查运行模型及对应会话的执行结果，见[连接状态与问题排查](troubleshoot.md)。

## 下一步

- [连接后的使用方式](usage.md)
- [连接状态与问题排查](troubleshoot.md)

### 参考文献

[^slack-dm]: Slack. [message.im event](https://docs.slack.dev/reference/events/message.im/).
[^slack-mentions]: Slack. [app_mentions:read scope](https://docs.slack.dev/reference/scopes/app_mentions.read/).
[^slack-files-read]: Slack. [files:read scope](https://docs.slack.dev/reference/scopes/files.read/).
[^slack-files-write]: Slack. [files:write scope](https://docs.slack.dev/reference/scopes/files.write/).
[^slack-chat]: Slack. [chat:write scope](https://docs.slack.dev/reference/scopes/chat.write/).