setup-slack-channel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Set up a Slack Channel for a local Channels agent

为本地Channels代理设置Slack通道

Take a developer from a code checkout to a working local Slack agent. Five separate systems have to line up, and they are owned by four different parties:

System	Who owns it	Where you work on it
Slack workspace	Workspace owner / app manager	Slack, in a browser
Slack app + its tokens	The developer	api.slack.com, in a browser
Intelligence project, API key, Channel, Slack adapter	The developer	The Intelligence dashboard, in a browser
Local Channels runtime	The developer	This repo, in the shell
AG-UI agent backend	The developer	This repo, in the shell

引导开发者从代码检出到搭建可运行的本地Slack代理。需要协调五个独立系统，分属四个不同主体：

系统	归属方	操作位置
Slack工作区	工作区所有者/应用管理员	浏览器端Slack界面
Slack应用及其令牌	开发者	浏览器端api.slack.com界面
智能项目、API密钥、通道、Slack适配器	开发者	浏览器端智能控制面板界面
本地Channels运行时	开发者	本代码仓库的终端环境
AG-UI代理后端	开发者	本代码仓库的终端环境

How delivery actually works — two legs, two mechanisms

交付原理——两个环节，两种机制

Getting this wrong is the most expensive mistake available here, because a misconfigured Slack app installs cleanly and answers nothing.

Leg	Mechanism	What authenticates it
Slack → Intelligence	Slack posts events over HTTPS to an Intelligence-hosted Request URL: `https://intelligence.copilotkit.ai/api/channels/adapters/slack/events`	The app's signing secret, held by Intelligence
Intelligence → your runtime	Your runtime dials out to the realtime gateway over a websocket	`INTELLIGENCE_API_KEY`

Two consequences:

No tunnel and no public URL of your own is needed — but not because of Socket Mode. It is because Intelligence owns the public URL, and because the second leg is outbound from your machine.
Socket Mode is off, and there is no
xapp-
app-level token in this workflow at all. A managed Slack app needs
```
socket_mode_enabled: false
```
and a
```
request_url
```
. If you create the app with Socket Mode on and no Request URL, no event ever reaches Intelligence.

The Slack adapter form in Intelligence therefore asks for exactly two values: the bot token (

xoxb-

) and the signing secret. Nothing else.

Most of this workflow happens in a browser, not a shell. The supported path for v1 is the Intelligence browser experience.

copilotkit channels

does list commands for Channel creation, adapter attach, and key issuance — do not use them here; they are not hardened for this workflow yet. Never invent a command name to fill a gap, and if you are unsure whether a command covers something, check its

--help

rather than guessing.

Drive that browser yourself. That is the default here, not a bonus. Check what you actually have before Phase 0 and say which it is — never assume either way.

If you have no browser or computer-use tool, ask the developer to install one before you start. Work out which harness you are running in and name the single route that applies rather than reciting all of them: Claude Code and Codex each ship their own browser support and enable it differently, and most other harnesses take a general browser-use MCP server such as Playwright MCP. If you are not sure what your harness supports, look it up before you guess. Tell them what it buys — driving turns this into typing three secrets, while the fallback is roughly fifteen manual browser steps. Only if they decline, walk them through those steps one action at a time.

配置错误是最容易导致损失的问题，因为配置错误的Slack应用能正常安装，但无法响应任何请求。

环节	机制	认证方式
Slack → Intelligence	Slack通过HTTPS将事件发送至Intelligence托管的请求URL： `https://intelligence.copilotkit.ai/api/channels/adapters/slack/events`	应用的签名密钥，由Intelligence保管
Intelligence → 你的运行时	你的运行时通过WebSocket主动连接实时网关	`INTELLIGENCE_API_KEY`

由此产生两个结论：

无需隧道或自有公网URL——并非因为Socket Mode，而是因为Intelligence持有公网URL，且第二个环节由你的机器主动发起连接。
Socket Mode需关闭，本流程中完全不需要
xapp-
级别的应用令牌。托管Slack应用需要设置
```
socket_mode_enabled: false
```
并配置
```
request_url
```
。如果创建应用时开启Socket Mode且未设置请求URL，事件将永远无法送达Intelligence。

因此，Intelligence中的Slack适配器表单仅需两个值：机器人令牌（

xoxb-

）和签名密钥，无需其他内容。

本流程大部分操作在浏览器中完成，而非终端。v1版本的推荐路径是使用Intelligence浏览器界面。

copilotkit channels

命令包含通道创建、适配器关联和密钥生成功能——请勿在此流程中使用；这些命令尚未针对本流程优化。不要自行臆造命令名称填补空白，若不确定命令是否覆盖需求，请查看

--help

说明而非猜测。

请自行操作浏览器，这是默认方式，而非额外选项。在第0阶段前确认当前已有资源，明确所处状态——切勿随意假设。

若没有浏览器或计算机工具，请让开发者先安装相关工具再开始。确定当前使用的工具环境，并说明适用的唯一路径，而非罗列所有可能：Claude Code和Codex各有专属浏览器支持，启用方式不同；多数其他工具依赖通用浏览器MCP服务器（如Playwright MCP）。若不确定工具支持情况，请先查询再猜测。告知开发者该操作的价值：浏览器驱动模式只需输入三个密钥，而手动操作需约15步。只有当开发者拒绝时，才逐步引导手动操作。

Done means three things, all verified

完成标准——需同时满足三项验证

Do not report success until all three hold. Any one alone is a false positive.

The Slack app is installed in a workspace, and the bot is a member of the channel you will test in.
The managed Channel reports
online
— from
```
controls.status()
```
in the process, or Online in the dashboard. Not "the runtime started."
A real human mention got a real reply in Slack.

Gate 2 is where agents fail.

await controls.ready()

resolves on

setup_required

too — that state is documented as "a valid degraded state, not a failure." A runtime with no Slack connection at all starts cleanly, prints its listening line, returns HTTP 200 on

/api/copilotkit/info

, and answers nothing.

/api/copilotkit/info

reports license and runtime info, not channel state, so a 200 there is not evidence of anything Slack-related.

The SDK behaviors asserted here were verified against the currently published

@copilotkit/channels@0.6.0

and

@copilotkit/runtime@1.65.0

. A starter may pin something older or newer, and this API is moving fast. If a claim here contradicts what you observe, trust the installed package and re-read it — do not argue with the runtime.

必须全部满足以下三项才能报告成功，任何单一条件达标均为假阳性。

Slack应用已安装至工作区，且机器人已加入测试用通道。
托管通道显示
online
状态——可通过进程中的
```
controls.status()
```
或控制面板查看，而非“运行时已启动”。
真实用户在Slack中提及机器人后收到真实回复。

第2项是最容易失败的环节。

await controls.ready()

在

setup_required

状态下也会返回——该状态被定义为“有效的降级状态，而非失败”。完全未连接Slack的运行时也能正常启动、打印监听信息、在

/api/copilotkit/info

返回HTTP 200，但无法响应任何请求。

/api/copilotkit/info

仅报告许可证和运行时信息，不包含通道状态，因此200响应不能证明Slack相关配置正常。

本文档中的SDK行为已针对当前发布的

@copilotkit/channels@0.6.0

和

@copilotkit/runtime@1.65.0

验证。初始项目可能锁定了更早或更新的版本，且API迭代速度较快。若本文档内容与实际观测结果矛盾，请以已安装的包为准，重新阅读相关文档——不要与运行时行为争论。

Scope — read before planning

范围——规划前必读

In scope: production CopilotKit Intelligence; a managed Channel; a dedicated Slack app created from a manifest; a local runtime and agent.

Out of scope in v1. These are hard limits, not defaults to weigh:

Do not switch to a direct Slack adapter (
```
adapters: [slack({ botToken, appToken })]
```
). Not as a fallback, not to save time, not because the dashboard is confusing. See the prohibitions below — this is the single most common way this workflow goes wrong.
Do not reuse, reinstall, or modify a Slack app that is already installed and in use. Create a dedicated one.
Do not deploy anything (Railway or otherwise).
Do not target internal or dev Intelligence environments.
Do not enumerate the Slack workspace, search channels, or request scopes beyond the manifest.

适用范围：生产环境CopilotKit Intelligence；托管通道；通过清单创建的专属Slack应用；本地运行时和代理。

v1版本不支持以下场景，这些是硬性限制，而非可权衡的默认选项：

请勿切换至直接Slack适配器（
```
adapters: [slack({ botToken, appToken })]
```
）。无论作为备选方案、节省时间还是因为控制面板混淆，都不允许。请查看下文的禁止事项——这是本流程最常见的错误原因。
请勿复用、重新安装或修改已安装并在使用的Slack应用。请创建专属应用。
请勿部署至任何平台（如Railway）。
请勿针对内部或开发环境的Intelligence。
请勿枚举Slack工作区、搜索通道或请求清单以外的权限范围。

Phase 0 — Establish the route and the contract

第0阶段——确定路径与约定

First, check whether Phases 1–2 are already done for you. Some organizations run a dedicated dev bot alongside their production one and hand developers a ready-made environment file — the Slack app, the Channel, and the adapter already exist, and the dev bot comes online only while someone runs it locally.

Ask: is there an existing dev bot and a provided config for this, or am I setting one up from scratch?

If a config is provided, skip Phases 1 and 2 entirely: put the provided values in

.env

(the developer retrieves them from their team's secret-sharing channel — never ask them to paste the contents here), install, and run. Do not create a new Slack app, and do not create a Channel. Phases 3–5 still apply, and the three success gates are unchanged.

Otherwise, pick the starter, in this order:

An OpenTag checkout — the developer's cwd is one, or they name one. This is the most likely path. Detect it: a
```
slack-app-manifest.yaml
```
plus
```
app/channel.tsx
```
at the root.
examples/OpenTag
in this repo, if present. It is a submodule, so a plain clone leaves it empty:
bash
```
git submodule update --init examples/OpenTag
```
Neither → have the developer clone it, and work from there:
bash
```
git clone https://github.com/CopilotKit/OpenTag.git
```

Whichever you land on, treat that checkout as the source of truth. Do not carry facts between checkouts — versions, env var names, and registered handlers differ between OpenTag revisions, which is why the next step reads them rather than assuming them.

Then read the app's own environment contract instead of assuming variable names. They differ between apps, and so does the vocabulary for the same concept: OpenTag uses

INTELLIGENCE_CHANNEL_NAME

, the Channels SDK README's quickstart calls it

CHANNEL_CODE

, and it is also referred to as the Channel's slug. All of them mean the

name

passed to

createChannel()

, which must match the Channel in the dashboard character for character. Read the app's parser; do not guess which word this codebase uses.

bash

cat .env.example
grep -rn "process.env" app/env.ts server.ts 2>/dev/null
grep -n "onMention\|onMessage\|onCommand\|createChannel(" app/channel.tsx

Record, and state back to the developer: the exact env var names, the Channel name the code will declare, and which handlers are registered.

Know what the managed adapter does not deliver. The generated manifest declares no
slash_commands
, so slash commands never arrive. It does enable

interactivity

, and the managed ingress handles

block_actions

— so HITL buttons and selects do fire. What it does not handle is

view_submission

, so modals do not. As shipped, a managed Slack Channel receives mentions, messages, reactions, and interactive component clicks — not slash commands and not modal submissions. An app registering

onCommand

onModalSubmit

will compile, start, report

online

, and never fire those handlers on the managed path. OpenTag registers

onModalSubmit

and ships four commands; none of those work here, though its buttons do. Say this up front rather than letting the developer debug it, and do not invent a Request URL for commands to fill the gap.

That last one decides what "working" even looks like. Turn routing is not symmetric: a mentioned turn goes to

onMention

if registered and otherwise falls back to

onMessage

, while a non-mentioned turn goes only to

onMessage

. So an app registering just

onMention

— which is what OpenTag does — answers channel mentions, and may silently do nothing for any turn Intelligence does not flag as a mention. Verify with a channel mention first; it is the path every starter registers. Details in

references/troubleshooting.md

首先，检查第1-2阶段是否已完成。部分组织会在生产机器人之外运行专属开发机器人，并为开发者提供现成的环境文件——Slack应用、通道和适配器已配置完成，仅当本地运行时才会启动开发机器人。

询问开发者：是否已有现成的开发机器人和配置文件，还是需要从头搭建？

若提供了配置文件，直接跳过第1-2阶段：将提供的值填入

.env

（开发者从团队的密钥共享通道获取——切勿要求在此粘贴内容），安装并运行。无需创建新Slack应用或通道。第3-5阶段仍适用，三项成功标准不变。

否则，按以下顺序选择初始项目：

OpenTag检出项目——开发者当前工作目录是该项目，或明确指定该项目。这是最常见的路径。识别特征：根目录下存在
```
slack-app-manifest.yaml
```
和
```
app/channel.tsx
```
。
本仓库中的
examples/OpenTag
（若存在）。这是一个子模块，普通克隆会使其为空：
bash
```
git submodule update --init examples/OpenTag
```
以上都不是 → 让开发者克隆OpenTag仓库，并基于该仓库操作：
bash
```
git clone https://github.com/CopilotKit/OpenTag.git
```

无论选择哪个项目，均以该检出项目为唯一依据。不要在不同项目间传递信息——不同OpenTag版本的环境变量名称、已注册处理器可能不同，因此下一步需读取项目自身内容，而非假设。

然后读取应用自身的环境变量约定，而非假设变量名称。不同应用的变量名称可能不同，甚至同一概念的表述也可能不同：OpenTag使用

INTELLIGENCE_CHANNEL_NAME

，Channels SDK快速入门文档称其为

CHANNEL_CODE

，也被称为通道的slug。这些均指向

createChannel()

中传入的

name

参数，必须与控制面板中的通道名称完全一致。请读取应用的解析代码，不要猜测当前代码库使用的名称。

bash

cat .env.example
grep -rn "process.env" app/env.ts server.ts 2>/dev/null
grep -n "onMention\|onMessage\|onCommand\|createChannel(" app/channel.tsx

记录并告知开发者：精确的环境变量名称、代码中声明的通道名称、已注册的处理器类型。

明确托管适配器不支持的功能。生成的清单未声明**

slash_commands

，因此斜杠命令永远无法送达。适配器启用了
interactivity
，托管入口会处理
block_actions
——因此人工介入（HITL）按钮和选择器可正常触发**。但适配器不处理

view_submission

，因此模态框无法正常工作。默认情况下，托管Slack通道会接收提及、消息、反应和交互式组件点击事件——不包括斜杠命令和模态框提交。注册了

onCommand

或

onModalSubmit

的应用可正常编译、启动、显示

online

状态，但这些处理器在托管路径下永远不会触发。OpenTag注册了

onModalSubmit

并包含四个命令——这些在本流程中均无法使用，但按钮功能正常。请提前告知开发者，避免其自行调试，且请勿为命令自定义请求URL填补空白。

最后一点决定了“正常工作”的定义。路由逻辑不对称：被提及的消息会先触发已注册的

onMention

，否则回退至

onMessage

；而未被提及的消息仅触发

onMessage

。因此，仅注册

onMention

的应用（如OpenTag）会响应通道提及，对于Intelligence未标记为提及的消息可能无任何响应。请先通过通道提及验证；这是所有初始项目都注册的路径。详情请查看

references/troubleshooting.md

。

Decide these with the developer before you open a browser

打开浏览器前与开发者确认以下事项

Driving does not mean deciding. These are the developer's calls, all cheap to ask now and expensive to change later. Ask for them in one exchange, then proceed without coming back.

The bot's display name. The wizard derives the Channel Code from it, and that Code is what
```
createChannel({ name })
```
declares and what they type as
```
/invite @<code>
```
. Slack bot names are workspace-wide, so a collision blocks the install. Suggest one, but do not settle it yourself — this is the bot's identity in their workspace.
Which Slack workspace the app gets installed into. Never assume the one their browser session happens to be signed into.
Which channel to test in. Gate 3 is a real mention getting a real reply, so it has to be somewhere they can post and somewhere a bot reply is welcome.
Whether this is throwaway or something they will keep, if they have not already said. It decides whether a sandbox workspace is fine.

State the answers back before Phase 1. If they defer one, say what you are defaulting to rather than silently picking.

浏览器驱动不代表自行决策。这些是开发者的决定，现在询问成本低，后续修改成本高。请一次性询问所有问题，然后推进流程，无需反复确认。

机器人显示名称。向导会据此生成通道Code，该Code是
```
createChannel({ name })
```
中声明的名称，也是开发者输入
```
/invite @<code>
```
时使用的名称。Slack机器人名称是工作区全局的，若存在冲突会阻止安装。可提供建议，但不要自行决定——这是机器人在工作区的标识。
Slack工作区。切勿假设浏览器当前登录的工作区就是目标工作区。
测试通道。第3项成功标准是真实提及收到回复，因此需选择开发者可发帖且机器人回复受欢迎的通道。
该应用是临时使用还是长期保留（若开发者未说明）。这决定了是否可使用沙箱工作区。

在进入第1阶段前重复上述答案。若开发者推迟某一决策，请说明默认选择，而非自行默默决定。

Then take one authorization

获取一次性授权

Name the whole sequence it covers: production Intelligence, a dedicated Slack app built from the wizard's generated manifest, installed into the workspace they named, the Channel created, the Slack adapter attached, and a project-scoped API key issued.

One yes covers all of it. Do not re-ask per page, per goal, or per click — a run that stops at every control is slower than the manual path it replaced, which is the whole reason driving is the default. After this, stop only for a secret the developer types themselves, for a decision above that they deferred, or for something this authorization did not cover.

Those two blocks are different things and both are required. The decisions are inputs you cannot invent; the authorization is permission you only need once. Collapsing the second does not license skipping the first.

说明授权涵盖的完整流程：生产环境Intelligence、通过向导生成的清单创建专属Slack应用、安装至指定工作区、创建通道、关联Slack适配器、生成项目级API密钥。

一次同意即可覆盖所有操作。请勿在每个页面、每个目标或每次点击前重新询问——频繁停顿的流程比手动操作更慢，这正是浏览器驱动模式成为默认选项的原因。获得授权后，仅在以下情况停止：开发者自行输入密钥、之前推迟的决策需要确认、或授权未覆盖的操作。

以上两个步骤是不同的，且均为必需。决策是输入项，无法自行臆造；授权是权限，只需获取一次。不要将两者混淆。

Phase 1 — Workspace, and start the Channel wizard to get the manifest

第1阶段——准备工作区，启动通道向导获取清单

The Channel comes first, because the Channel generates the Slack app's manifest. Do not hand-write one, and do not use the starter's

slack-app-manifest.yaml

— see the prohibition below.

Use the workspace the developer named in Phase 0. If they have no usable one → create a free workspace, or a Slack Developer Program sandbox. Never test in a workspace where an unapproved bot would be disruptive.
In the Intelligence dashboard, start Create a channel. Enter the Display name the developer chose in Phase 0 — do not substitute your own. The wizard derives the Code from it — lowercase kebab-case, and the Code is what
```
createChannel({ name })
```
must declare. Select Slack.
Advance to Setup. That step contains a generated manifest ("Copy manifest" / "View manifest YAML") already pointed at the right Request URL, plus the two credential fields you will fill in Phase 3. Nothing is saved until you finish, so leave this tab open.

Read the wizard's own warning before you install anything: Slack bot names and slash commands are workspace-wide. If either generated name is already in use, choose a more specific Channel display name before installing. A collision here blocks the install, so resolve it by renaming the Channel, not the manifest.

Full detail in

references/intelligence-channel.md

先创建通道，因为通道会生成Slack应用的清单。请勿手动编写清单，也不要使用初始项目的

slack-app-manifest.yaml

——请查看下文的禁止事项。

使用开发者在第0阶段指定的工作区。若没有可用工作区 → 创建免费工作区或Slack开发者程序沙箱。切勿在不允许未批准机器人的工作区测试。
在Intelligence控制面板中，启动创建通道。输入开发者在第0阶段选择的显示名称——不要自行替换。向导会据此生成Code（小写短横线格式），该Code必须与
```
createChannel({ name })
```
中声明的名称一致。选择Slack。
进入设置步骤。该步骤包含生成的清单（“复制清单”/“查看清单YAML”），已指向正确的请求URL，以及第3阶段需要填写的两个凭证字段。完成前不会保存任何内容，请保持该标签页打开。

安装前请阅读向导自身的警告：Slack机器人名称和斜杠命令是工作区全局的。若生成的名称已被占用，请在安装前选择更具体的通道显示名称。 若存在冲突会阻止安装，请通过重命名通道解决，而非修改清单。

详情请查看

references/intelligence-channel.md

。

Phase 2 — Create and install the Slack app from that manifest

第2阶段——通过向导生成的清单创建并安装Slack应用

Full detail in

references/slack-workspace-and-app.md

. The shape:

Create a new app from the manifest the wizard generated. Change the display name so it is obviously a dev app.
Install it. Installing is the gated step — by default only Workspace Owners review app requests, and they may appoint app managers to do so too. Creating the app is normally not gated, so create it while any install request is pending rather than waiting.
Collect two values: the
```
xoxb-
```
bot token (OAuth & Permissions) and the signing secret (Basic Information → App Credentials). They go to Intelligence — never into this repo. There is no
xapp-
token in this workflow.
Invite the bot to the channel the developer named in Phase 0:
```
/invite @<code>
```
. The developer runs this — you cannot invite a bot on their behalf, and the CLI cannot verify the invitation either.

详情请查看

references/slack-workspace-and-app.md

。流程如下：

通过向导生成的清单创建新应用。修改显示名称，使其明显为开发应用。
安装应用。安装是需要审批的步骤——默认仅工作区所有者可审核应用请求，也可指定应用管理员审核。创建应用通常无需审批，因此可在等待安装请求审批的同时创建应用。
收集两个值：
```
xoxb-
```
格式的机器人令牌（OAuth & Permissions页面）和签名密钥（Basic Information → App Credentials页面）。这些值需填入Intelligence——切勿存入本代码仓库。本流程中完全不需要
xapp-
令牌。
将机器人邀请至开发者在第0阶段指定的通道：
```
/invite @<code>
```
。该操作由开发者执行——你无法代表其邀请机器人，CLI也无法验证邀请状态。

Phase 3 — Finish the Channel: adapter credentials and API key

第3阶段——完成通道配置：适配器凭证与API密钥

Back in the open wizard tab. Browser work, in the developer's own session. Four things must line up: Channel Code matches what the code declares, the Slack adapter reports connected, Channel and API key in the same project, endpoints left at their production defaults.

The developer types the bot token and signing secret into the Setup step themselves, then Review → create. Then issue a project-scoped API key and have them paste it into

.env

These are consequential mutations in a live dashboard, so read the page before you act and never click a control you have not read. But reading is not a reason to check in: the Phase 0 authorization already covers this sequence, so work straight through it and report what you changed rather than asking before each control.

回到打开的向导标签页，在开发者的浏览器会话中操作。需确保四项内容一致：通道Code与代码中声明的名称匹配、Slack适配器显示已连接、通道与API密钥属于同一项目、端点保持生产环境默认值。

开发者自行将机器人令牌和签名密钥输入设置步骤，然后点击“审核→创建”。生成项目级API密钥，并让开发者将其粘贴至

.env

文件。

这些操作会在实时控制面板中产生重要变更，因此操作前请阅读页面内容，切勿点击未阅读的控件。但阅读无需反复确认：第0阶段的授权已涵盖整个流程，因此可直接完成操作并告知变更内容，无需每次操作前询问。

Phase 4 — Configure and start the runtime

第4阶段——配置并启动运行时

Full detail in

references/local-runtime.md

The developer puts

INTELLIGENCE_API_KEY

into

.env

themselves. Verify by presence, never by printing. Then start the agent backend, then the runtime — and start it with logs turned up, because the runtime's logger defaults to

error

while every Channel lifecycle breadcrumb is emitted at

warn

bash

LOG_LEVEL=debug pnpm runtime

channel "<name>" requires setup

in that output means Phase 2 is incomplete. It is the single highest-value line in this entire workflow, and at the default log level it is written and discarded.

详情请查看

references/local-runtime.md

。

开发者自行将

INTELLIGENCE_API_KEY

填入

.env

文件。仅验证是否存在，切勿打印内容。然后启动代理后端，再启动运行时——启动时需调高日志级别，因为运行时日志默认级别为

error

，而所有通道生命周期信息均以

warn

级别输出：

bash

LOG_LEVEL=debug pnpm runtime

输出中的

channel "<name>" requires setup

表示第2阶段未完成。这是整个流程中最有价值的日志行，默认日志级别下会被写入后丢弃。

Phase 5 — Verify, in order

第5阶段——按顺序验证

```
controls.status()
```
→
```
overall: "online"
```
. If the app does not already assert this, add the assertion —
```
examples/OpenTag
```
's
```
server.ts
```
calls
```
ready()
```
and never checks status, which is exactly how a broken setup looks healthy.
The dashboard shows the Channel Online while the process runs. Its Runtime panel should read Connected. Ignore the Agent run column — it reads
```
—
```
even after a turn completes successfully, so it is not a health signal.
The developer sends a real mention from their own Slack account and reports the reply.

Step 3 is theirs. Do not post to Slack on their behalf, and do not substitute reading the workspace with a Slack tool for a genuine round trip. If a mention produces nothing, go to

references/troubleshooting.md

— diagnose by layer, do not start changing configuration.

```
controls.status()
```
→
```
overall: "online"
```
。若应用未包含该断言，请添加——
```
examples/OpenTag
```
的
```
server.ts
```
仅调用
```
ready()
```
而未检查状态，这正是错误配置看似正常的原因。
控制面板显示通道在运行时启动后处于Online状态。运行时面板应显示_已连接_。忽略代理运行列——即使成功处理请求后仍显示
```
—
```
，因此不是健康信号。
开发者使用自己的Slack账号发送真实提及，并报告回复情况。

第3项由开发者执行。请勿代表其发帖，也不要使用Slack工具替代真实的往返测试。若提及无响应，请查看

references/troubleshooting.md

——按层级诊断，不要随意修改配置。

Phase 6 — Optional live E2E

第6阶段——可选的实时端到端测试

Only after a real mention works.

references/optional-e2e.md

. This is the one place Slack tokens legitimately enter

.env

, because the harness drives the Slack API directly as a test client.

仅在真实提及测试通过后执行。详情请查看

references/optional-e2e.md

。这是Slack令牌可合法存入

.env

的唯一场景，因为测试工具会直接驱动Slack API作为测试客户端。

Never do these

禁止事项

Never switch to a direct Slack adapter to get unblocked. It moves platform credentials into the app, abandons managed delivery's retries/dedup/ordering, still requires an Intelligence key, and means you validated a different architecture than the one the developer asked about. If the managed path is blocked, say it is blocked and say why.

Never create the Slack app from the starter's own
slack-app-manifest.yaml
. OpenTag's manifest sets

socket_mode_enabled: true

and declares no
request_url
, which is the shape for a direct adapter, not a managed Channel. An app created from it installs cleanly, shows green in Slack, and delivers nothing to Intelligence forever. Use the manifest the Channel wizard generates. The same applies to

assets/slack-app-manifest.yaml

in this skill — it is kept only as a reference for the direct-adapter shape.

Never reuse a production or shared Slack app. One Slack app has exactly one event-subscription Request URL. Pointing an existing app at your Channel's URL redirects that app's entire event stream away from whatever was serving it — you do not observe production traffic, you hijack it, and real users get answered by an in-progress agent on a laptop. Slack offers no way to scope delivery to one channel or one user. Pasting a manifest over an installed app also forces reinstallation and rotates its tokens, breaking every existing consumer.

Never ask for a secret in chat, and never print one. Full ownership table and handling rules in

references/secrets-and-credentials.md

Never use the runtime API key to probe Intelligence HTTP endpoints. It is a project-scoped activation key, not a dashboard session; dashboard endpoints reject it, and a response body could carry platform tokens.

Never mutate the environment to make progress feel faster. No

pnpm install

, no killing processes you did not start, no editing

.env

for the developer, without naming the change and getting a yes.

切勿切换至直接Slack适配器解决问题。这会将平台凭证移入应用，放弃托管交付的重试/去重/排序机制，仍需Intelligence密钥，且验证的架构与开发者需求不符。若托管路径受阻，请说明受阻原因。

切勿通过初始项目的
slack-app-manifest.yaml
创建Slack应用。OpenTag的清单设置

socket_mode_enabled: true

且未声明**

request_url

**，这是_直接_适配器的配置，而非托管通道。通过该清单创建的应用可正常安装、在Slack中显示绿色状态，但永远无法将事件送达Intelligence。请使用通道向导生成的清单。本技能中的

assets/slack-app-manifest.yaml

同理——仅作为直接适配器配置的参考，不适用于托管通道。

切勿复用生产环境或共享Slack应用。一个Slack应用仅有一个事件订阅请求URL。将现有应用指向你的通道URL会将该应用的所有事件流从原服务重定向——你不会观测到生产流量，而是劫持了流量，真实用户会收到笔记本电脑上正在调试的代理回复。Slack不支持将事件交付范围限定为单个通道或用户。通过清单覆盖已安装应用也会强制重新安装并轮换令牌，破坏所有现有使用者。

切勿在聊天中索要密钥，也不要打印密钥。完整的归属表和处理规则请查看

references/secrets-and-credentials.md

。

切勿使用运行时API密钥探测Intelligence HTTP端点。这是项目级激活密钥，而非控制面板会话密钥；控制面板端点会拒绝该密钥，且响应体可能包含平台令牌。

切勿修改环境以加快进度。未经说明并获得同意，请勿执行

pnpm install

、终止未启动的进程或为开发者编辑

.env

。

Rationalizations

常见误区解析

Thought	Reality
"They're on a deadline, the direct adapter is faster"	You would be validating a different architecture and handing them credentials in the wrong place. Deadline pressure is when scope discipline matters most.
"The dashboard is confusing, code is more reliable"	The confusion is the developer's actual problem. Solving it in code hides it.
"The prod Slack app is already installed, so reusing it saves the approval"	Repointing its Request URL hijacks that app's whole event stream. The approval exists because installs affect other people.
"It's just for testing / just for a minute"	An app has one events URL. While yours is set, production is not receiving its events at all.
"The starter ships a manifest, so I'll create the app from that"	It sets `socket_mode_enabled: true` with no `request_url` — the direct-adapter shape. The app will install green and never deliver. Use the wizard's manifest.
"I need to generate an `xapp-` app-level token"	There is no `xapp-` token in this workflow and nowhere to put one. The adapter takes a bot token and a signing secret.
"The runtime started and `/info` returns 200, so we're connected"	`ready()` resolves on `setup_required` and `/info` reports license state. Neither says anything about Slack.
" `ready()` resolved without throwing, so the Channel is online"	It resolves on `setup_required` by design. Read `status()` .
"I'll check the Channel state with the API key"	Dashboard endpoints reject a project key. Use `status()` or the dashboard.
"Let me just read `.env` to see what's configured"	Read `.env.example` for names; check `.env` only for presence, and never quote a value.
"I'll send the test mention myself to save a round trip"	The success criterion is a real human mention. Posting for them proves less and acts on their behalf in their workspace.
"No reply — let me try changing the config"	Diagnose by layer first. `LOG_LEVEL=debug` names the failure in one line.

错误想法	实际情况
"他们赶工期，直接适配器更快"	你将验证不同的架构，并将凭证存放在错误的位置。赶工期时更需要严格遵守范围限制。
"控制面板太混乱，代码更可靠"	混乱本身就是开发者的实际问题。通过代码解决会掩盖问题。
"生产Slack应用已安装，复用可节省审批时间"	修改其请求URL会劫持该应用的所有事件流。审批机制存在的原因是安装会影响其他用户。
"只是测试用/只用一会儿"	一个应用仅有一个事件URL。在你的URL生效期间，生产环境完全无法接收事件。
"初始项目自带清单，我用它创建应用"	该清单设置 `socket_mode_enabled: true` 且无 `request_url` ——是直接适配器的配置。应用会正常安装但永远无法交付事件。请使用向导生成的清单。
"我需要生成 `xapp-` 级别的应用令牌"	本流程中完全不需要 `xapp-` 令牌，也没有存放位置。适配器仅需机器人令牌和签名密钥。
"运行时已启动， `/info` 返回200，说明已连接"	`ready()` 在 `setup_required` 状态下也会返回， `/info` 仅报告许可证状态。两者均无法证明Slack配置正常。
" `ready()` 未抛出错误，说明通道已在线"	设计上 `ready()` 在 `setup_required` 状态下会返回。请查看 `status()` 。
"我用API密钥检查通道状态"	控制面板端点会拒绝项目级密钥。请使用 `status()` 或控制面板。
"我看看 `.env` 里配置了什么"	请查看 `.env.example` 获取变量名称；仅检查 `.env` 是否存在对应变量，切勿引用具体值。
"我自己发测试提及节省往返时间"	成功标准是真实用户提及。代表其发帖证明的内容更少，且在其工作区代表其操作。
"无回复——我改改配置试试"	请先按层级诊断。 `LOG_LEVEL=debug` 会在一行日志中说明失败原因。

Red flags — stop

危险信号——立即停止

You are about to type
```
adapters: [slack(
```
or add
```
SLACK_BOT_TOKEN
```
to
```
.env
```
for anything other than the Phase 6 harness.
You are about to create the Slack app from the starter's manifest, or from any manifest with
```
socket_mode_enabled: true
```
and no
```
request_url
```
.
You are about to look for an app-level token,
```
connections:write
```
, or a Socket Mode toggle. None of them belong to a managed Channel.
You are about to open or screenshot the app's Install App page. It renders the bot token in plain text; reading it captures a live credential.
You are about to say "connected", "working", or "done" without all three gates.
You are about to ask the developer to paste a token, or you are about to echo one.
You are about to click a dashboard control you have not read.
You are about to
```
pnpm install
```
, kill a process, or edit
```
.env
```
unasked.
You have spent many tool calls deriving how managed Channels work. Stop — it is in this skill and its references.

准备输入
```
adapters: [slack(
```
或为第6阶段测试工具以外的场景添加
```
SLACK_BOT_TOKEN
```
至
```
.env
```
准备通过初始项目的清单，或任何设置
```
socket_mode_enabled: true
```
且无
```
request_url
```
的清单创建Slack应用
准备寻找应用级令牌、
```
connections:write
```
权限或Socket Mode开关。这些均不属于托管通道
准备打开或截图应用的安装应用页面。该页面会明文显示机器人令牌；查看会获取有效凭证
准备在未满足三项成功标准的情况下声称“已连接”“正常工作”或“完成”
准备要求开发者粘贴令牌，或准备打印令牌
准备点击未阅读的控制面板控件
准备未经询问执行
```
pnpm install
```
、终止进程或编辑
```
.env
```
花费大量时间研究托管通道的工作原理。请停止——相关内容已包含在本技能及其参考文档中

References

参考文档

Read the reference for the phase you are actually in — not all of them up front. Each is self-contained, and reading six files before saying anything to the developer is how this workflow gets slow.

File	Read it when
`references/intelligence-channel.md`	Phases 1 and 3 — wizard, Code, adapter, project, key
`references/slack-workspace-and-app.md`	Phase 2 — workspace, install, bot token, signing secret
`references/secrets-and-credentials.md`	Any time a credential is in play
`references/local-runtime.md`	Phase 4 — env, agent, runtime, startup, ports
`references/optional-e2e.md`	Phase 6 — the live Slack harness
`references/troubleshooting.md`	Anything fails, or a mention gets no reply
`assets/slack-app-manifest.yaml`	Reference only — the direct-adapter shape. Not for a managed Channel.

请在对应阶段阅读相关参考文档——无需提前阅读所有文档。每个文档都是独立的，提前阅读六个文档会拖慢流程。

文件	阅读时机
`references/intelligence-channel.md`	第1、3阶段——向导、Code、适配器、项目、密钥
`references/slack-workspace-and-app.md`	第2阶段——工作区、安装、机器人令牌、签名密钥
`references/secrets-and-credentials.md`	涉及凭证的任何场景
`references/local-runtime.md`	第4阶段——环境变量、代理、运行时、启动、端口
`references/optional-e2e.md`	第6阶段——实时Slack测试工具
`references/troubleshooting.md`	任何失败场景，或提及无响应的情况
`assets/slack-app-manifest.yaml`	仅作参考——直接适配器的配置，不适用于托管Channel。