配置 Slack 应用

为 ZAI 所在的 Slack 自建应用核对权限与事件、选择接收方式、开启控制台登录，以及新增、更换或重装应用。

ZAI 通过一个 Slack 自建应用接入一个 Slack 工作区，应用名为 Z Tag，bot 显示名为 zai。一个 Slack 应用只接入一个 Slack 工作区和一套 Z Tag 服务，也不要与其他接收这个应用事件的服务共用。谁可以安装、谁可以使用，见Slack 工作区管理员须知。

从 Z Tag 提供的安装链接安装的商店版 ZAI 不需要本页的配置，见安装商店版 ZAI。

谁	做什么
Slack 应用管理者	在 Slack 的应用管理页面用 Z Tag 管理员提供的应用配置创建或更新应用，按接收方式填写地址或生成令牌，按需开启控制台登录；把下一节的值交给 Z Tag 管理员。通常就是 Z Tag 管理员本人
Slack 工作区管理员	批准并安装应用；应用配置更新后重新批准安装，见Slack 工作区管理员须知
Z Tag 管理员	提供应用配置和地址，把应用接入本组织并登记它的凭证，切换接收方式
组织 Owner / Admin	在控制台组织管理 → IM 接入查看安装状态和连接状态，见查看 IM 接入

交给 Z Tag 管理员的值

应用页面 Basic Information 的 App Credentials 里的 App ID 和 Signing Secret。
安装到工作区之后的 Bot User OAuth Token（Bot token）。
使用 Socket Mode 时：在 Basic Information 的 App-Level Tokens 里生成、带 connections:write 的令牌。
开启控制台登录时：App Credentials 里的 Client ID 与 Client Secret，见控制台登录。

应用配置与权限

Slack 应用管理者用 Z Tag 管理员提供的应用配置在 Slack 的应用管理页面创建应用。请不要手工增删其中的权限或事件：缺少权限时，用到它的功能会失败；缺少事件时 ZAI 收不到，对应功能不会生效，也不会报错。

Z Tag 新版本需要新的权限时，控制台 IM 接入 显示 需重新批准。处理顺序：Slack 应用管理者先用 Z Tag 管理员提供的新应用配置更新应用，再请 Slack 工作区管理员重新批准安装；Z Tag 管理员更新应用凭证后，IM 接入里的状态随之变化。只在 Slack 重新安装还不够。

应用申请的 Bot 权限：

功能	权限
接收频道里 `@zai` 的消息	`app_mentions:read`
读取它所在的公开频道、私人频道、群聊与私信	`channels:history` `channels:read` `groups:history` `groups:read` `im:history` `im:read` `mpim:history` `mpim:read`
发送、修改与删除自己的消息、打开私信	`chat:write` `im:write` `mpim:write`
申请但不使用：ZAI 不会自行加入频道	`channels:join`
读取与上传文件	`files:read` `files:write`
添加与读取表情回复	`reactions:read` `reactions:write`
读取工作区信息与成员资料	`team:read` `users:read`
Slack 的运行指示、停止按钮与私信里的建议提示	`assistant:write`
读取消息里分享的画布正文	`canvases:read`

前七行是必需权限。安装缺少其中任何一项时，IM 接入显示 需重新批准：ZAI 照常工作，只有用到缺失权限的功能会失败。后两行缺少时 IM 接入不提示：没有 assistant:write 时，消息列里没有 Slack 的运行指示，ZAI 改用进度消息上的停止按钮和 !stop；canvases:read 是可选权限，Slack 工作区管理员安装时可以不授予，没有它时画布只显示名称和链接，见把文件作为输入。应用不申请哪些权限，见应用能读取什么。

已经接入的应用要读取画布时，按上面的顺序处理：用新应用配置更新应用，请 Slack 工作区管理员重新批准安装并授予 canvases:read，再请 Z Tag 管理员更新应用凭证；在此之前画布照旧只显示名称和链接。

应用配置同时订阅 ZAI 需要的事件：消息与 @、表情回复、成员进出频道、频道的创建、归档、改名、删除、共享与历史批量变更、打开 App Home、卸载与撤销授权、成员资料与访客身份变化，以及运行指示上的停止等事件。

接收方式

接收方式由 Z Tag 管理员为每个应用登记，请先向对方确认；组织 Owner / Admin 也可以在控制台 IM 接入 的应用详情里看到：

Socket Mode（默认，控制台显示为 长连接）：ZAI 主动连接 Slack 接收事件和按钮点击，不需要公网地址。应用需要一个带 connections:write 的 App-Level Token，交给 Z Tag 管理员登记。
HTTP 请求地址（控制台显示为 HTTP 回调）：Slack 把事件和按钮点击发到 Z Tag 提供的地址。在应用页面的 Event Subscriptions 填写 Z Tag 管理员提供的事件地址，在 Interactivity & Shortcuts 填写交互地址。Slack 用应用的 Signing Secret 签名每个请求，ZAI 用登记的值校验。

改用 HTTP 时，先请 Z Tag 管理员把应用切换到 HTTP（新应用可以直接按 HTTP 接入），再到应用页面填写两个地址，等事件地址显示 Verified 后保存。改回 Socket Mode 时反过来：先在应用页面打开 Socket Mode；之前没有 App-Level Token 的，生成一个带 connections:write 的交给 Z Tag 管理员；再请 Z Tag 管理员切回。

两种方式都不要开启 Event Subscriptions 里的 Delayed Events。使用 HTTP 时，如果一小时内超过 95% 的投递失败，Slack 会暂停应用的事件订阅并邮件通知应用所有者；ZAI 恢复后，需要在应用页面重新启用事件订阅。

常见故障

现象	可能原因	处理
事件地址迟迟不显示 Verified	Z Tag 管理员还没有把应用切换到 HTTP，登记的 Signing Secret 不一致，或填写的地址有误	核对地址，请 Z Tag 管理员确认登记后重新验证
HTTP 方式下，所有频道和私信里 ZAI 都不回复，应用所有者收到暂停邮件	投递持续失败，Slack 暂停了事件订阅	ZAI 恢复后，在应用页面重新启用事件订阅
消息有回复，点进度消息或主动协助建议上的按钮没有反应	Interactivity 没有开启，或交互地址与 Z Tag 管理员提供的不一致	按本节核对 Interactivity & Shortcuts

IM 接入里的安装状态显示 需重新批准、需重新安装 或 已停用 时，不是接收方式的问题：前者见应用配置与权限，后两者见卸载与重新安装。

Slack 免费版的限制

每个 Slack 工作区最多安装 10 个应用，Z Tag 占用其中一个。
免费版只能查看最近一段时间的消息与文件，ZAI 读取历史、Dream 第一次整理频道记忆时也读不到更早的内容，见保存哪些数据。
Slack 的运行指示和停止按钮在部分方案或工作区设置下不可用。ZAI 会自动判断这个工作区能否使用，不能用时改用进度消息上的停止按钮与 !stop，其他功能不受影响。

谁能使用

Z Tag 不额外限制工作区里谁能使用 ZAI，访客除外；按人限制的方法和访客、Slack Connect 的规则，见Slack 工作区管理员须知。

Slack 成员用 Sign in with Slack 登录控制台，登录只读取 Slack 身份，不读取邮箱。要让成员能登录：

请 Z Tag 管理员提供包含控制台登录的应用配置，用它更新应用；这份配置会带上 Redirect URL 和 User Token Scopes openid、profile。也可以在应用页面 OAuth & Permissions 手工添加 Z Tag 管理员提供的 Redirect URL 和这两项 scope，但之后每次更新应用配置都要包含控制台登录，否则这两项会被去掉。
把应用的 Client ID 与 Client Secret 交给 Z Tag 管理员。

缺少任何一项时，Slack 成员无法登录控制台。登录时会核对账号是不是工作区的正式成员：访客和已停用的账号不能登录，会看到 这个 Slack 账号不能登录；ZAI 读不到账号资料时（例如应用已被卸载）也按这种情况处理。ZAI 在 Slack 里发出的控制台链接（!organization 回复里的 打开控制台、频道回复的页脚、审批通知）用发出它的应用登录。组织接入了多个应用时，直接打开控制台地址可能出现其他平台的登录方式；这时请成员在 Slack 里发送 @zai !organization，从回复里的 打开控制台 进入，规则见一个组织接入多个 IM。

ZAI 发出的下载链接同样用链接所在聊天的应用登录，访客和已停用的账号打不开，见下载链接的访问。

新增或更换应用

每个接入的 Slack 应用对应控制台里的一个 Workspace。Slack 工作区是 Slack 里你们团队的空间；Workspace 是 Z Tag 控制台里记录这个接入的概念，包含这个工作区里的频道、群聊、私信和它们的设置。

要让一个 Slack 工作区加入已有组织，请 Z Tag 管理员把应用接入这个组织，接入后控制台就出现它的 Workspace；不指定组织时，会新建一个组织，默认以 Slack 工作区命名。加入已有组织前，先确认两边是不是同一批人：组织层的资源与授权会自动对新 Workspace 生效，见一个组织接入多个 IM；不是同一批人的，请 Z Tag 管理员接入单独的组织。

原应用被删除，或要换成同一 Slack 工作区的另一个应用时，请 Z Tag 管理员接入新应用并指定它接手原来的 Workspace。交接在 Z Tag 管理员登记新应用时完成：

频道、聊天记录、记忆、资源授权以及 Workspace 和频道的设置都保留；
原应用正在进行的任务停止，没发出的回复不再发送，原应用随即停用；
新应用在 Slack 里是另一个 bot：要把它邀请进原来的频道，才能在频道里回复；私信直接给新应用发消息，仍对应控制台里同一个 个人范围，成员第一次打开与新应用的私信时会再收到一次欢迎；
在原消息列里回复的定时任务和事件订阅改为每次新开消息列；原 bot 发出的主动协助建议不再响应；
原 bot 发出的控制台链接仍可打开，改用新应用登录。

Workspace 不能换到另一个 Slack 工作区，也不能换成其他 IM；那样请 Z Tag 管理员新增一个 Workspace。

卸载与重新安装

在 Slack 里卸载 Z Tag 应用，或撤销它的 Bot token 后，ZAI 立即停止在这个工作区工作：进行中的任务被取消，待发的消息不再发送，卸载期间收到的消息不会在重装后补答。IM 接入的安装状态显示 已停用。定时任务、事件订阅与后台能力保持原样，但不再执行，也不补做；这段时间各项功能的变化见ZAI 被移出频道时，订阅失败原因见检查链路。
只撤销某个成员自己的授权（例如登录控制台时的授权）不影响 ZAI。
重新安装同一个应用，再请 Z Tag 管理员更新应用凭证后，ZAI 在原来的 Workspace 里恢复工作，定时任务、事件订阅与后台能力照常继续。在此之前，IM 接入显示 已停用。
IM 接入显示 需重新安装 时，Slack 拒绝了这个安装的 Bot token：ZAI 与 Slack 的连接仍在，但无法在这个工作区读写消息。请在 Slack 重新安装应用，再请 Z Tag 管理员更新应用凭证。

谁来做