Slack
1. Slack App 配置
-
访问 Slack API
-
创建新应用（或使用现有应用）
- 选择 从空白应用开始（"Blank app"）
- 输入 App Name 和选择 Workspace
-
获取应用凭证：
- Client ID（在 Basic Information → App Credentials 中）
- Client Secret（在 Basic Information → App Credentials 中）
2. 配置 App-Level Tokens
- 在 Basic Information → App-Level Tokens 中，点击 "Generate Token and Scopes"
- 输入 Token 名称（如
connection_token） - 添加
connections:write、authorizations:read和app_configurations:writescopes - 点击 "Generate"
- 复制生成的
xapp-...格式的 Token
3. 配置 OAuth & Permissions
Slack 限制必须是 HTTPS，如无 可跳过该配置，采用方式一 绑定使用
在 Slack App 管理页面 → OAuth & Permissions 中：
3.1 添加 Redirect URLs
https://your-domain:port/agent/api/slack-oauth/callback
示例：
- 本地开发：http://localhost:3000/api/slack-oauth/callback
- 测试环境：https://your-test-domain.com/agent/api/slack-oauth/callback
- 生产环境：https://your-domain.com/agent/api/slack-oauth/callback
注意：
- 协议必须匹配（HTTPS）
- 如果不是默认端口（80/443），需要带上端口号
- 支持配置多个回调地址（开发/测试/生产）
3.2 配置 User Token Scopes
在 OAuth & Permissions → Scopes → User Token Scopes 中添加：
identity.basic- 获取用户基本信息（必需）identity.email- 获取用户邮箱（可选）
注意：添加或者修改 Scopes 后需要重新安装应用到 Workspace。
3.3 配置 Bot Token Scopes
在 OAuth & Permissions → Scopes → Bot Token Scopes 中添加：
chat:write- 发送消息app_mentions:read- 读取 @ 提及channels:history- 读取频道历史消息channels:read- 读取频道信息groups:history- 读取私有频道历史消息im:history- 读取私信历史消息im:read- 读取私信信息files:write-上传、编辑和删除文件files:read- 查看共享的文件
4. 配置 App Home 和机器人
- 在 App Home → Show Tabs 中启用：
- Home Tab - 用户可以在 Home 中与 Bot 交互
- Message Tab - Bot 的私信对话界面
勾选：Allow users to send Slash commands and messages from the messages tab
- 在 Interactivity & Shortcuts 中启用 Interactivity
- 在 Socket Mode 中启用 Socket Mode（如果使用 WebSocket 连接）
5. 添加 Event Subscriptions
- 在 Event Subscriptions 中启用 Enable Events。
- 在 Subscribe to bot events 中添加
app_mention，用于接收公开或私有频道中 @App 发起的新任务。 - 添加
message.channels和message.groups，用于接收公开/私有频道 thread 中的等待回答和继续执行回复。 - 保留
message.im，用于接收私信消息。如还需要多人私信，可额外添加message.mpim并授予对应历史消息权限。
Socket Mode、事件与交互检查：
- App-Level Token 至少授予
connections:write，并开启 Enable Socket Mode。 - Bot Token Scopes 至少包含
chat:write、app_mentions:read、channels:history、groups:history、im:history、files:read和files:write。 - 必须开启 Interactivity；Socket Mode 下无需公网 Request URL，但消息表单、Modal 提交和继续执行仍依赖 Interactivity。
- 修改 OAuth Scopes 或 Bot Events 后必须重新安装 App 到 Workspace；重新生成 App-Level Token 后，还要同步更新渠道配置中的 App Token。
6. 安装应用到 Workspace
在 OAuth & Permissions 页面点击 "Install to Workspace" 按钮，授权应用访问 Workspace。
使用流程
方式一：绑定码模式（推荐）
Slack 支持通过绑定码在群聊中绑定账号，适合在团队内部推广使用。
用户绑定流程
- 用户登录系统
- 点击左下角用户头像，打开菜单
- 找到"Slack"行，点击"获取绑定码"按钮
- 系统生成一个 6 位绑定码（如
FRT12H），有效期 10 分钟 - 用户在 Slack 中向机器人发送私信：
+bind FRT12H - 绑定成功后，Slack 中显示"绑定成功"提示
解绑流程
- 点击左下角用户头像，打开菜单
- 找到"Slack"行，点击"解绑"按钮
- 确认解绑操作
- 解绑成功，菜单中显示"未绑定"状态
方式二：OAuth 授权模式
通过浏览器授权完成绑定。
用户绑定流程
- 用户登录系统
- 点击左下角用户头像，打开菜单
- 找到"Slack"行，点击"绑定"按钮
- 跳转到 Slack 授权页面
- 用户确认授权（选择 Workspace）
- 自动跳转回系统，显示"绑定成功"
- 关闭授权窗口，原页面自动刷新，菜单中显示"已绑定"状态
用户解绑流程
- 点击左下角用户头像，打开菜单
- 找到"Slack"行，点击"解绑"按钮
- 确认解绑操作
- 解绑成功，菜单中显示"未绑定"状态
自定义命令
Slack 机器人支持以下命令（所有命令以 + 开头）：
| 命令 | 说明 | 示例 |
|---|---|---|
+bind <CODE> | 使用绑定码绑定账号（6位大写字母+数字） | +bind FRT12H |
+new | 开启新会话，清除当前会话历史 | 发送 +new |
+agent <名称> <消息> | 给指定名称的 Agent 发消息 | +agent rhea 你好 |
+agent <消息> | 给系统默认 Agent 发消息 | +agent 你好 |
说明：
- 不以
+开头的消息直接发送给系统默认 Agent +bind命令用于绑定码模式，未绑定的用户需要先绑定才能使用其他功能+new命令会清除当前会话，重新开始- Agent 名称必须是用户有权限访问的 Agent
- 命令参数大小写敏感
- 绑定码字符集排除了易混淆字符（I/O/0/1）
群聊消息分发
群聊消息分发可以让同一个 Slack App 按规则把不同问题交给不同的 Agent 或 Team。一个「群聊空间」对应当前 Workspace，配置对该 Workspace 中已安装此 App 的频道生效。只有已绑定 Agentic Engine 账号、并在频道中明确 @App 的成员才能发起任务。
管理员配置
- 确认 Socket Mode、Event Subscriptions 和 Interactivity 已启用；Bot Events 至少包含
app_mention、message.channels、message.groups和message.im，修改 scopes 后重新安装 App 到 Workspace。 - 把 App 邀请到需要使用的公开频道或私有频道。私有频道中若 App 不是成员，即使配置正确也无法接收消息。
- 进入「管理后台 → 渠道管理」，在对应 Slack 渠道上打开「消息分发」，选择 Workspace，并配置默认 Agent/Team。
- 按需添加最多 19 条规则。每条规则选择一个 Agent/Team，填写必填的「调用指令」，还可以填写最多 10 个关键词，然后打开启用开关并保存。
- 在频道中发送
@App +help做验收，确认能力清单和线程回复均正常。
| 配置项 | 规则 |
|---|---|
| 默认 Agent/Team | 启用前必须配置；未指定调用指令、且未命中关键词时使用。 |
| 调用指令 | 必填，1～32 个字符；可使用字母、数字、- 和 _，不能使用系统保留命令。大小写以及全角、半角差异不视为不同指令。 |
| 关键词 | 可不填；每条规则最多 10 个，每个 2～32 个字符。多个关键词同时命中时优先更长的关键词；同长度无法唯一判断时回到默认 Agent/Team。 |
| 可选范围 | 可选择已启用且可运行的系统/企业 Agent，以及当前企业的 Team；个人 Agent 不会出现在群聊分发候选中。 |
频道中的使用方式
| 用途 | 示例 | 说明 |
|---|---|---|
| 查看可用能力 | @App +help@App 能力清单 | 列出默认项、调用指令和关键词；无权限或当前不可运行的能力不会展示。 |
| 指定 Agent/Team | @App +analysis 分析本周数据 | analysis 为管理员配置的调用指令。也可以发送 @App @analysis 分析本周数据。 |
| 按关键词分发 | @App 帮我检查埋点方案 | 正文命中关键词时交给对应 Agent/Team；未命中时使用默认项。 |
| 取消任务 | @App +cancel | 必须整条消息精确发送。已输出正文保留，并另外发送一条取消确认。 |
| 兼容旧写法 | @App +agent analysis 分析本周数据 | 仍可使用，但推荐直接使用 +analysis。 |
线程回复：普通新任务必须先 @App。任务已经在某个 thread 中等待回答时，可以按提示直接回复该 thread，无需再次 @；没有等待任务的普通频道消息会被忽略。
命令边界：群聊分发不支持 +new；私聊仍支持 +new、+agent 和 +cancel。
公开上下文与个人数据：系统只使用近期明确 @App 并实际进入处理的公开频道轮次作为参考；未 @App 的普通消息、其他频道、私聊和个人记忆不会混入。历史内容只作为不可信参考，当前这条消息才是本轮指令。
常见问题
1. 用户菜单中没有显示 Slack 绑定选项
原因：
- Slack 渠道未配置或未启用
- Channel 表中没有 type='slack' 的记录
- config 字段缺少 clientId 或 clientSecret
解决方案：
- 检查渠道管理中是否有 Slack 渠道
- 确认渠道已启用
- 确认 config 字段包含 clientId 和 clientSecret
2. 点击绑定后跳转失败
错误提示：获取授权链接失败
解决方案：
- 检查 Slack App 的 Client ID 和 Client Secret 是否正确
- 确认 Slack App 已安装到 Workspace
- 检查后端日志，查看具体错误信息
3. 授权后回调失败
错误提示：回调地址校验失败 或 state 校验失败
解决方案：
- 确认 Slack App 配置的 Redirect URLs 包含当前访问的回调地址
- 检查协议（HTTP/HTTPS）和端口是否匹配
- 确认没有跨域问题
4. 绑定失败
错误提示：该 Slack 账号已被其他用户绑定
解决方案：
- 一个 Slack 账号只能绑定一个系统用户
- 如需更换绑定，先在原账号解绑
5. 生产环境白名单校验失败
错误提示：生产环境必须配置 ALLOWED_ORIGINS 或 非法来源
解决方案：
- 配置
ALLOWED_ORIGINS环境变量 - 确保 origin 在白名单中
- 多个域名用逗号分隔
相关文档
相关页面与下一步