/setup-slack-channel

name: setup-slack-channel
description: Use for the PROVIDER half of getting a locally running CopilotKit Channels agent to answer in Slack, when no Slack app exists yet — setting up a Channels bot in Slack for the first time, creating the Slack app and its tokens, attaching it to a managed Intelligence Channel, or when a Channel reports setup_required, sits at "Waiting for runtime", the Channel is Online but a Slack mention gets no reply, or a Slack app was built with Socket Mode instead of an Intelligence Request URL. Scoped to an OpenTag checkout, or the OpenTag example inside a channels-sdk clone — the phases assume those conventions (app/channel.tsx, app/env.ts, INTELLIGENCE_CHANNEL_NAME, a local agent on port 8123) and do not describe a project scaffolded by copilotkit init, which already ships its own channel host. If the Slack app and Channel already exist and the question is about declaring or customising the Channel in code, use the copilotkit-channels skill instead.
version: 1.1.0

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:

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

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.

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` rep