设置 Slack 集成

本指南介绍如何把 Slack 连接到 Control Center 工作区——既可以由 Control Center 创建应用，也可以自行构建。

想要一次有引导的初次体验，请参见将 Slack 桥接到工作区。

前提条件

在 Control Center 工作区中拥有 owner 或 admin 角色——连接聊天应用属于工作区设置变更
有权在 Slack 工作区中创建并安装应用
不需要任何可公网访问的资源：连接是主动外连的（Socket Mode），因此服务器不需要入站端口、隧道或域名

获取应用的三种方式

方式	你需要提供	Control Center 会做什么
引导式	一个应用配置令牌（`xoxe-…`）	创建应用并配好正确的权限范围、事件、Socket Mode 和斜杠命令；把 Slack 没有提供 API 的两个步骤交给你手动完成
在 Slack 中创建	无需提供任何内容	打开 Slack 并预填相同的配置；由你选择工作区并确认
手工创建	已完成应用的令牌	校验这些令牌并建立连接

只有引导式方式还会让应用可以由 Control Center 管理，而这正是自定义聊天机器人得以实现的前提。通过 在 Slack 中创建 生成的应用，之后可以在连接对话框中粘贴一个应用配置令牌，从而提升为受管应用。

产品刻意不提供“安装 Control Center 的 Slack 应用”按钮。安装一个分发的 Slack 应用需要共享的客户端密钥（Slack 没有 PKCE），而 Socket Mode 会把同一应用的事件随机分发到它的各条连接上——因此一个共享应用会把你的工作区消息投递到别人的服务器上。所以每个工作区都拥有自己的应用，而这三种方式要解决的，正是如何把这份代价压到最低。

方式 A：让 Control Center 创建应用

在 api.slack.com/apps 生成一对应用配置令牌，并复制刷新令牌（xoxe-…）
在 Control Center 中前往 设置 → 工作区 → 通用，向下滚动到 聊天桥接 卡片
在 Slack 区块上点击 为我创建应用
粘贴令牌，调整应用名称、机器人名称、描述和斜杠命令，然后点击 创建应用
按对话框显示的两个剩余步骤操作，每一步都是一个跳转到 Slack 的链接：
- Basic Information → App-Level Tokens：生成一个带有 connections:write 权限范围的令牌（xapp-…）
- Install App：安装到工作区，并复制 Bot User OAuth Token（xoxb-…）
点击 粘贴凭据，然后继续连接

配置令牌每次使用后都会轮换。Control Center 会随手保存轮换后的值，因此你无需再次粘贴。

方式 B：在 Slack 中创建，配置已预填

同样的应用，但不需要配置令牌——Slack 会打开它自己的创建界面，整个 manifest 都已经填好。

在 Control Center 中前往 设置 → 工作区 → 通用，向下滚动到 聊天桥接 卡片
在 Slack 区块上点击 为我创建应用
调整应用名称、机器人名称、描述和斜杠命令——这些内容会随链接一起传递
点击 在 Slack 中创建。浏览器会打开 Slack 的应用创建页面，配置已预填
选择 Slack 工作区并确认。权限范围、事件、Socket Mode 和斜杠命令都已经正确
回到 Control Center，按对话框显示的两个剩余步骤操作：
- Basic Information → App-Level Tokens：生成一个带有 connections:write 权限范围的令牌（xapp-…）
- Install App：安装到工作区，并复制 Bot User OAuth Token（xoxb-…）
点击 粘贴凭据，然后继续连接

Slack 不会报告它创建的是哪个应用，因此 Control Center 无从得知应用 id，第 6 步中的链接会指向你的应用列表，而不是直接打开那个应用。自定义机器人 需要配置令牌。

方式 C：自行构建应用

在 api.slack.com/apps 创建一个应用，然后按以下方式配置。

Socket Mode：启用它，并把所有请求 URL 留空。如果一份 manifest 同时要求 Socket Mode 和 webhook 投递，Slack 会拒绝。

机器人 token 权限范围（OAuth & Permissions）：

app_mentions:read
assistant:write
channels:history
chat:write
commands
groups:history
im:history
users:read
users:read.email

事件订阅（机器人事件）：

app_home_opened
app_mention
message.channels
message.groups
message.im

正是 message.channels 和 message.groups 让已桥接的 Slack 话题中的回复能够生效。没有它们，只有第一条提及会送达。

斜杠命令：/cc（名称可以任意——桥接使用的是它最后一次被调用时所用的命令）。

App Home：启用 Messages 标签页并保持其可写，这样成员就能给机器人发私信。

令牌：生成一个带有 connections:write 权限范围的应用级令牌，然后安装应用并复制机器人用户 OAuth token。

连接

前往 设置 → 工作区 → 通用，向下滚动到 聊天桥接 卡片
在 Slack 区块上点击 连接 Slack
填写以下字段：

字段	值	在 Slack 中的位置
机器人用户 OAuth token	`xoxb-…`	OAuth & Permissions → Bot User OAuth Token
应用级 token	`xapp-…`	Basic Information → App-Level Tokens（`connections:write`）
应用配置刷新 token（可选）	`xoxe-…`	api.slack.com/apps 上的一对应用配置令牌

每个值的前缀都会在发送任何内容之前由两侧校验，因此粘贴到错误输入框里的值，无论在哪一侧，都会被同一句话拒绝。

点击连接

Control Center 会在存储任何内容之前用 Slack 的 auth.test 校验机器人 token，因此一个拼写错误会直接报告给你，而不是变成一条悄悄从不工作的套接字。应用级令牌只能通过打开套接字来验证，因此有问题的令牌会在片刻之后，以同一行上的连接错误呈现。

没有可选的应用配置 token 时，连接照常工作——只是无法从 Control Center 编辑机器人。

连接会做什么

把凭据存放在工作区自己的目录中、数据库旁边，仅属主可读。它们绝不会回传到客户端
为该工作区打开一条 Socket Mode 连接，并开始接收提及、Slack 话题回复、私信和斜杠命令
重新接管此前已桥接的每个 Slack 话题，因此重新连接会延续既有对话，而不是把它们搁置
对没有聊天应用的工作区毫无开销：没有套接字、没有定时器、没有流量

机器人凭据是每个提供方一个纯 JSON 文件，位于 <dataDir>/<workspaceId>/chat_credentials/，原子写入并收紧为仅属主可访问。这是刻意为之，而不是疏忽：删除工作区会解除该目录的链接，其中的令牌也随之而去；而 workspace.export 和备份复制的是 workspace.db——不是该目录——因此你交给别人的工作区里，绝不会夹带仍然有效的机器人令牌。由此推出的一个结果是：把工作区恢复到别处，就意味着要在那里重新连接 Slack。

对桥接的访问权来自工作区成员身份，而不是持有某个令牌。Slack 账户必须关联到一位持有可写角色的 Control Center 成员用户。连接、断开连接、引导式设置、设置链接和机器人自定义全部仅限管理员操作。

验证

Slack 行会显示一个状态标签：已连接、连接中…、连接错误（旁边是 Slack 自己的错误），或 未连接。要端到端检查：

在 Slack 中把机器人邀请到某个频道：/invite @your-bot-name
用一条请求提及它
会出现一条 Slack 话题回复，同时在 Control Center 中出现对应的空间

之后，每位想使用桥接的成员都要关联自己的账号——参见关联你的 Slack 账号。

回复在 Slack 中是什么样子

在流式输出的文字上方，是一张分组卡片，每个步骤各占一行。初始化占一行，其标题会从 Working on it… 变为 Cloning …，再变为 Starting the agent…。推理过程会新增一行 Thinking…；该步骤结束时，这一行上可以出现一句简短的思考。每个工具各占一行（Read lib/main.dart）。回答以普通文本的形式出现在卡片下方。轮次结束时卡片会变为已完成状态；运行失败、被中断或达到轮次上限时，则变为出错状态。

卡片在机器人接受提及的那一刻就打开——Working on it…——因此当工作区还在构建时，Slack 话题不会一片沉默。你在 Slack 频道中的第一次提及会创建对话，而创建对话会克隆智能体工作的仓库，所以那一行初始化信息随后会依次显示 Cloning acme/widgets…、Setting up Reviewer…、Starting the agent…，然后等智能体真正开始推理时出现一行 Thinking…。在大型仓库上，第一次初始化要花上一段时间；卡片就是让你知道它正在干活，而不是无视你的方式。同一 Slack 话题中后续的提及仍然以 Working on it… 开场，然后跳过克隆步骤，因为工作区已经存在。

整面文字墙式的推理和工具输出绝不会离开 Control Center——Thinking… 行上的思考只是一句短话，而不是完整转录。卡片上的 View in Control Center 会在桌面应用中打开完整对话——该链接指向你自己的 Control Center 服务器，由它把浏览器交给桌面应用。

如果点击后没有任何反应，说明发送该消息的服务器无法从你点击的那台机器访问（例如从手机点击一台仅侦听回环地址的服务器），或者那台机器上并没有运行 Control Center。没有可达地址的服务器发出的卡片不会带按钮，而不是带一个指向死路的按钮。

轮换令牌

在连接对话框中重新粘贴新值，然后点击连接。连接会替换该工作区上正在运行的任何连接，因此套接字会用新凭据重新拨号。

两个必需令牌在每次连接时都必须填写。可选的应用配置 token 在你把输入框留空时会保留已存储的值，因此轮换机器人 token 绝不会让你失去编辑应用的能力。

断开连接

在 Slack 行上点击 断开连接（仅限管理员）。套接字关闭，凭据被遗忘。

空间和用户关联会被刻意保留：重新连接同一个应用会恢复每一个已桥接的 Slack 话题。它们是按工作区归属的数据行，因此删除工作区时本来也会一并消失。

故障排查

该行显示“连接错误”

请阅读标签旁边显示的错误。被拒绝的凭据（invalid_auth、not_authed、token_revoked、account_inactive）属于终态——桥接会停止重试并等待新令牌，因为无限重试一个已吊销的令牌只会换来速率限制。请在连接对话框中重新粘贴令牌。

missing_scope 错误意味着应用安装时授予的权限范围少于桥接所需。补上缺失的权限范围，在 Slack 中重新安装应用，然后重新连接。

任何暂时性问题（套接字断开、Slack 打嗝）都会自行重连，采用上限为 30 秒的指数退避；Slack 例行的套接字轮换不会抬高该退避。

机器人不回应提及

机器人在频道里吗？ Slack 只会把频道消息投递给属于成员的应用程序。请运行 /invite @your-bot-name
你完成关联了吗？ 未关联的成员会在该 Slack 话题中收到一条说明如何关联的回复。参见关联你的 Slack 账号
你是该工作区中持有可写角色的成员吗？ viewer 或 guest 会被告知其角色是只读的。桥接绝不会代表一个它无法归属的人启动工作
该工作区里有智能体吗？ 没有任何智能体时，消息会被存储，却无人应答

它在频道里会回答，却忽略普通消息

这是有意为之。在私信之外，桥接只对提及机器人的消息、或它已经拥有的 Slack 话题中的回复作出反应。其他一切都属于别人的对话。

回复以一条完整消息送达，而不是流式输出

该行会显示“此 Slack 应用未开启实时流式传输——回复会作为一条消息送达。”Slack 的流式回复需要付费套餐中的 Agents & AI Apps 功能；当 Slack 拒绝该功能时，桥接会在整条连接的生命周期内不再请求，改为直接发出完整回复。什么都不会丢失——完整转录始终都在 Control Center。

流式输出还需要一个 Slack 话题锚点，因此没有 Slack 话题可供展开的回复会整条发出。无论哪种情况，任务卡片都照常送达：整条回复时，卡片搭同一条消息一起来，且已经是完成状态。

回复上方没有卡片

Slack 的任务卡片与流式输出属于同一个新的 Agents & AI Apps 界面，而 Slack 只在调用时才拒绝。一旦被拒绝，Control Center 会在整条连接的生命周期内保留回复、放弃卡片——有答案而没有状态行，胜于有状态行而没有答案。

“Control Center 需要应用配置 token 才能编辑机器人”

自定义机器人 这一行处于禁用状态，因为该连接没有应用配置 token。对于手工创建的应用，或通过 在 Slack 中创建 创建的应用，这是预期情况——Slack 从未告诉过 Control Center 它是哪个应用。请在 api.slack.com/apps 上生成一对令牌，并带上填写好的刷新令牌重新连接。

较长的回答被截断

Slack 把单条消息限制在 40,000 个字符，因此桥接会在 39,000 处截断，并追加一个指向 Control Center 的指引——缩短的回复胜于被 Slack 直接拒收的回复。完整文本始终在空间的转录里。