setup-slack-channel

Set up a Slack Channel for a local Channels agent

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:

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.

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.

Done means three things, all verified

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

1. The Slack app is installed in a workspace, and the bot is a member of the channel you will test in.
2. The managed Channel reports online — from controls.status() in the process, or Online in the dashboard. Not "the runtime started."
3. 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/[email protected] and @copilotkit/[email protected]. 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.

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.

Phase 0 — Establish the route and the contract

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:

1. 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.

2. examples/OpenTag in this repo, if present. It is a submodule, so a plain clone leaves it empty:

   git submodule update --init examples/OpenTag
   

3. Neither → have the developer clone it, and work from there:

   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.

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 or 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.

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.

1. 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.
2. Which Slack workspace the app gets installed into. Never assume the one their browser session happens to be signed into.
3. 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.
4. 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.

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.

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

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.

1. 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.
2. 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.
3. 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.

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

Full detail in references/slack-workspace-and-app.md. The shape:

1. Create a new app from the manifest the wizard generated. Change the display name so it is obviously a dev app.
2. 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.
3. 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.
4. 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.

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

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.

Phase 4 — Configure and start the runtime

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:

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.

Phase 5 — Verify, in order

1. 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.
2. 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.
3. 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.

Phase 6 — Optional live E2E

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.

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.

Rationalizations

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.

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.