setup-slack-channel

ローカル Channels エージェント用の Slack チャンネルをセットアップする

開発者がコードをチェックアウトした状態から、ローカルの Slack エージェントが動作するまでを説明します。5 つの別々のシステムを連携させる必要があり、それぞれを管理するのは 4 つの異なる関係者です。

システム	管理者	作業場所
Slack ワークスペース	ワークスペースのオーナー／アプリ管理者	ブラウザー上の Slack
Slack アプリとそのトークン	開発者	ブラウザー上の api.slack.com
Intelligence プロジェクト、API キー、Channel、Slack アダプター	開発者	ブラウザー上の Intelligence ダッシュボード
ローカル Channels ランタイム	開発者	シェル上のこのリポジトリ
AG-UI エージェントのバックエンド	開発者	シェル上のこのリポジトリ

配信の実際の仕組み — 2つの経路、2つのメカニズム

ここを間違えると、最も大きな損失につながります。設定を誤った Slack アプリは正常にインストールされるのに、何も応答しないからです。

経路	メカニズム	認証に使用するもの
Slack → Intelligence	Slack は、Intelligence がホストするリクエスト URL に HTTPS でイベントを送信します：https://intelligence.copilotkit.ai/api/channels/adapters/slack/events	Intelligence が保持するアプリの 署名シークレット
Intelligence → お使いのランタイム	お使いのランタイムが WebSocket 経由でリアルタイムゲートウェイに 発信 します	CPK_INTELLIGENCE_API_KEY

これにより、次の2つの点が導かれます。

• トンネルも独自の公開 URL も必要ありません — ただし、Socket Mode が理由ではありません。Intelligence が公開 URL を所有し、2つ目の経路がご利用のマシンからの発信だからです。
• Socket Mode はオフであり、このワークフローでは xapp- のアプリレベルトークンは一切使いません。 マネージド Slack アプリでは、socket_mode_enabled: false と request_url が必要です。Socket Mode をオンにして Request URL を設定せずにアプリを作成すると、イベントは Intelligence に届きません。

そのため、Intelligence の Slack アダプターフォームで求められる値は、ボットトークン（xoxb-）と署名シークレットの2つだけです。それ以外は必要ありません。

このワークフローのほとんどはシェルではなく、ブラウザーで行います。v1 でサポートされる方法は、Intelligence のブラウザーエクスペリエンスです。 copilotkit channels にはチャンネルの作成、アダプターの接続、キーの発行を行うコマンドが表示されますが、ここでは使わないでください。このワークフロー向けの堅牢化がまだ済んでいません。不足を補うためにコマンド名を作り出さないでください。コマンドで何ができるか確信が持てない場合は、推測せずに --help を確認してください。

ブラウザーは自分で操作してください。ここではそれが標準であり、追加の利点ではありません。 フェーズ 0 の前に、実際に何が使えるかを確認して、どちらなのかを伝えてください。どちらかを決めつけてはいけません。

ブラウザーまたはコンピューター操作ツールがない場合は、作業を始める前に、開発者にインストールを依頼してください。 実行環境を特定し、該当する方法を1つだけ示してください。すべての方法を列挙してはいけません。Claude Code と Codex にはそれぞれ独自のブラウザーサポートがあり、有効化の方法も異なります。その他の環境の多くでは、Playwright MCP などの汎用ブラウザー操作用 MCP サーバーを使います。実行環境で何がサポートされているかわからない場合は、推測する前に調べてください。 それを使う利点も伝えてください。ブラウザー操作を使えば、秘密情報を3つ入力するだけで済みますが、代替手段ではブラウザーで約15手順を手動で行うことになります。開発者が断った場合に限り、その手順を1つずつ案内してください。

完了といえるのは、以下の3つすべてを確認できた場合です

3つすべてが満たされるまで、成功したと報告しないでください。どれか1つだけでは誤検知です。

1. Slack アプリがワークスペースにインストールされており、テストするチャンネルにボットが参加していること。
2. 管理対象の Channel が online を報告していること — プロセス内の controls.status() から確認するか、ダッシュボードで「Online」と表示されていること。「ランタイムが起動した」だけでは不十分です。
3. 実際の人間からのメンションに対し、Slack で実際に返信があったこと。

ゲート2でエージェントは失敗します。await controls.ready() は setup_required の場合も解決します。この状態は「失敗ではなく、有効な縮退状態」として文書化されています。Slack への接続がまったくないランタイムでも正常に起動し、待ち受け開始の行を出力し、/api/copilotkit/info に HTTP 200 を返しますが、何にも応答しません。/api/copilotkit/info が報告するのはライセンスとランタイムの情報であり、チャンネルの状態ではありません。そのため、そこでの 200 は Slack 関連の証拠にはなりません。

ここで述べている SDK の動作は、現在公開されている @copilotkit/[email protected] と @copilotkit/[email protected] で確認済みです。スターターによっては、これより古い、または新しいバージョンに固定されている場合があり、この API は急速に変化しています。ここでの説明と実際の観測結果が食い違う場合は、インストール済みパッケージを優先し、読み直してください。ランタイムと議論してはいけません。

対象範囲 — 計画を立てる前にお読みください

対象: 本番環境の CopilotKit Intelligence、管理対象の Channel、マニフェストから作成した専用 Slack アプリ、ローカルのランタイムとエージェント。

v1 の対象外。これらは検討するデフォルトではなく、厳格な制限です。

• 直接の Slack アダプターに切り替えてはいけません（adapters: [slack({ botToken, appToken })]）。フォールバックとしても、時間を節約するためとしても、ダッシュボードが分かりにくいからという理由でも使用しないでください。以下の禁止事項を参照してください — このワークフローで最もよくある失敗の原因です。
• **すでにインストールされ、使用中の Slack アプリを再利用、再インストール、変更してはいけません。**専用のアプリを作成してください。
• 何もデプロイしないでください（Railway なども含みます）。
• 内部環境または開発用の Intelligence 環境を対象にしないでください。
• Slack ワークスペースを列挙したり、チャンネルを検索したり、マニフェストで指定された範囲を超えるスコープを要求したりしないでください。

フェーズ 0 — 接続先と契約を確認する

まず、フェーズ 1〜2 がすでに完了しているか確認してください。 組織によっては、本番用のボットと並行して専用の開発用ボットを運用し、開発者に設定済みの環境ファイルを渡します。Slack アプリ、Channel、アダプターはすでに用意されており、開発用ボットは誰かがローカルで実行している間だけ起動します。

確認してください。既存の開発用ボットと設定ファイルが用意されていますか。それとも、最初からセットアップしますか？

設定ファイルが用意されている場合は、フェーズ 1 と 2 を完全にスキップします。渡された値を .env に設定し（開発者はチームの秘密情報共有チャンネルから取得します。内容をここに貼り付けるよう求めてはいけません）、インストールして実行します。新しい Slack アプリも Channel も作成しないでください。フェーズ 3〜5 は引き続き適用され、3 つの成功条件も変わりません。

それ以外の場合は、次の順にスターターを選びます。

1. OpenTag のチェックアウト — 開発者の作業ディレクトリがその中にあるか、開発者がその名前を挙げています。最も可能性の高いケースです。ルートに slack-app-manifest.yaml と app/channel.tsx があるか確認します。

2. このリポジトリに examples/OpenTag がある場合。サブモジュールなので、通常のクローンでは空のままです。

   git submodule update --init examples/OpenTag
   

3. どちらもない場合 → 開発者にクローンしてもらい、そのディレクトリで作業します。

   git clone https://github.com/CopilotKit/OpenTag.git
   

どれを選んでも、そのチェックアウトを信頼できる情報源として扱います。チェックアウト間で情報を引き継いではいけません。OpenTag のリビジョンによってバージョン、環境変数名、登録済みハンドラーが異なるため、次のステップでは推測せずに実際の内容を読み取ります。

次に、変数名を推測するのではなく、アプリ独自の環境設定の契約を確認します。同じ概念でもアプリによって呼び方が異なります。OpenTag では INTELLIGENCE_CHANNEL_NAME を使い、Channels SDK の README のクイックスタートでは CHANNEL_CODE と呼んでいます。また、Channel のスラッグとも呼ばれます。いずれも createChannel() に渡される name を指し、ダッシュボード上の Channel と一字一句同じでなければなりません。どの呼び方がこのコードベースで使われているか、アプリのパーサーを読んで確認してください。

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

正確な環境変数名、コードが宣言する Channel 名、登録されているハンドラーを記録し、開発者に伝えます。

管理対象アダプターでは対応していない機能を把握します。 生成されたマニフェストには slash_commands が宣言されていないため、スラッシュコマンドは届きません。interactivity は有効になっており、管理対象のイングレスは block_actions を処理するため、HITL のボタンとセレクトは動作します。一方、view_submission は処理しないため、モーダルは動作しません。出荷時の設定では、管理対象の Slack Channel が受け取るのはメンション、メッセージ、リアクション、インタラクティブなコンポーネントのクリックであり、スラッシュコマンドやモーダルの送信ではありません。onCommand または onModalSubmit を登録しているアプリは、コンパイルと起動が成功し、online と報告しますが、管理対象の経路ではそれらのハンドラーが一度も実行されません。OpenTag は onModalSubmit を登録し、4 つのコマンドを同梱していますが、ここではどれも動作しません。ただし、ボタンは動作します。開発者にデバッグさせてから伝えるのではなく、最初に説明してください。また、この不足を補うための Request URL をでっち上げてはいけません。

最後の点によって、「動作している」と判断する条件が決まります。ターンのルーティングは対称ではありません。メンションされたターンは、onMention が登録されていればそこに送られ、登録されていなければ onMessage にフォールバックします。一方、メンションされていないターンは onMessage にのみ送られます。そのため、OpenTag のように onMention だけを登録するアプリは、チャンネルでのメンションには応答しますが、Intelligence がメンションとして認識しないターンには何も応答しない可能性があります。まずチャンネルでメンションして動作を確認してください。すべてのスターターが登録している経路です。詳しくは references/troubleshooting.md を参照してください。

ブラウザーを開く前に、開発者と決めておくこと

操作を進めることと、判断することは別です。 以下は開発者が決めることで、今なら気軽に確認できますが、後から変更するには手間がかかります。まとめて一度に確認し、その後は戻って確認せずに進めてください。

1. ボットの表示名。 ウィザードはこの名前からチャンネルの コード を生成します。このコードは createChannel({ name }) で指定する値であり、/invite @<code> と入力するときにも使います。Slack のボット名は ワークスペース全体で一意 であるため、名前が重複するとインストールできません。候補を提案しますが、あなたが決めてください。これはワークスペース内でのボットの識別名です。
2. アプリをインストールする Slack ワークスペース。ブラウザーのセッションで現在サインインしているワークスペースを、決めつけて使ってはいけません。
3. テストに使う チャンネル。ゲート 3 では、実際のメンションに実際の返信が必要です。そのため、あなたが投稿でき、ボットの返信が歓迎されるチャンネルを選ぶ必要があります。
4. まだ伝えられていない場合、このボットは使い捨てのものか、今後も使い続ける予定か。これにより、サンドボックスのワークスペースで問題ないかが決まります。

フェーズ 1 の前に、回答を復唱して確認してください。回答を保留された項目があれば、黙って決めるのではなく、どのような既定値を使うかを伝えてください。

続いて、一度だけ承認を得る

承認の対象となる一連の作業をすべて伝えてください。すなわち、本番環境の Intelligence、ウィザードで生成したマニフェストから作成する専用の Slack アプリ、指定されたワークスペースへのインストール、チャンネルの作成、Slack アダプターの接続、プロジェクト専用 API キーの発行です。

一度の承認ですべてをカバーできます。ページごと、目的ごと、クリックごとに再確認してはいけません。操作のたびに止まって確認する実行方法では、置き換えるはずだった手動の手順より遅くなります。操作を自動で進めるのが既定となっているのは、そのためです。以降、止まってよいのは、開発者自身が入力するシークレット、上記で回答を保留された項目の判断、またはこの承認の対象外の操作が必要な場合だけです。

この二つのブロックは別々のもので、どちらも必要です。判断事項は入力情報であり、こちらで作り出すことはできません。承認は許可であり、一度だけ必要です。後者を省略しても、前者を確認せずに進めてよいことにはなりません。

フェーズ 1 — ワークスペースを選び、チャンネルウィザードを開始してマニフェストを取得する

最初にチャンネルを作成します。チャンネルから Slack アプリのマニフェストが生成されるためです。 マニフェストを手動で作成してはいけません。また、スターターに含まれる slack-app-manifest.yaml も使わないでください。以下の禁止事項を参照してください。

1. フェーズ 0 で開発者が指定したワークスペースを使います。使えるワークスペースがない場合は、無料のワークスペースまたは Slack Developer Program のサンドボックスを作成します。未承認のボットが迷惑になるワークスペースでは、決してテストしないでください。
2. Intelligence ダッシュボードで チャンネルを作成 を開始します。フェーズ 0 で開発者が選んだ表示名を入力し、独自の名前に置き換えてはいけません。ウィザードはこの名前から コード を生成します。コードは小文字のケバブケースで、createChannel({ name }) に指定する値です。Slack を選択します。
3. 設定 に進みます。このステップには、正しいリクエスト URL が設定済みの生成マニフェスト（「マニフェストをコピー」／「マニフェスト YAML を表示」）と、フェーズ 3 で入力する 2 つの認証情報フィールドがあります。完了するまで、何も保存されません。このタブは開いたままにしてください。

インストールする前に、ウィザードに表示される警告を確認してください。Slack のボット名とスラッシュコマンドは、ワークスペース全体で一意です。生成された名前のいずれかがすでに使用されている場合は、インストールする前に、より具体的なチャンネル表示名を選んでください。 ここで名前が重複するとインストールできません。マニフェストではなく、チャンネル名を変更して解決してください。

詳しくは references/intelligence-channel.md を参照してください。

フェーズ 2 — マニフェストから Slack アプリを作成してインストールする

詳細は references/slack-workspace-and-app.md を参照してください。手順は次のとおりです。

1. ウィザードで生成されたマニフェストから新しいアプリを作成します。開発用アプリだと一目でわかるように、表示名を変更します。
2. インストールします。インストールが承認を要する手順です。デフォルトでは、アプリのリクエストを審査するのはワークスペースオーナーのみですが、アプリマネージャーを任命して審査を任せることもできます。通常、アプリの作成には承認が不要なので、インストールリクエストの承認を待つ間にアプリを作成してください。
3. 2 つの値を取得します。OAuth & Permissions にある xoxb- ボットトークンと、Basic Information → App Credentials にある署名シークレットです。これらは Intelligence に登録し、このリポジトリには絶対に保存しないでください。このワークフローに xapp- トークンはありません。
4. フェーズ 0 で開発者が指定したチャンネルにボットを招待します。 /invite @<code>。これは開発者自身が実行します。代理でボットを招待することはできず、CLI でも招待を確認できません。

フェーズ 3 — チャンネルを完成させる：アダプターの認証情報と API キー

開いたままのウィザードのタブに戻ります。開発者自身のセッションでブラウザーを操作します。次の 4 点が一致している必要があります。Channel Code がコードで宣言されている値と一致すること、Slack アダプターが接続済みと表示されること、Channel と API キーが同じプロジェクトにあること、エンドポイントを本番環境のデフォルト設定のままにすることです。

開発者自身が、Setup 手順でボットトークンと署名シークレットを入力し、続いて Review → create を実行します。その後、プロジェクトスコープの API キーを発行し、.env に貼り付けてもらいます。

これらは稼働中のダッシュボードに対する重大な変更なので、**操作する前にページを読み、内容を読んでいないコントロールは絶対にクリックしないでください。**ただし、読むことは確認のために作業を止める理由にはなりません。フェーズ 0 での承認にはすでにこの一連の操作が含まれているので、各コントロールを操作する前に確認を求めず、続けて作業し、変更内容を報告してください。

フェーズ 4 — ランタイムを設定して起動する

詳細は references/local-runtime.md を参照してください。

開発者自身が CPK_INTELLIGENCE_API_KEY を .env に設定します。値を表示せず、存在することだけを確認してください。次にエージェントのバックエンドを起動し、その後ランタイムを起動します。ランタイムのロガーはデフォルトで error ですが、Channel のライフサイクルを示すログはすべて warn で出力されるため、ログレベルを上げて起動してください。

LOG_LEVEL=debug pnpm runtime

出力に channel "<name>" requires setup と表示される場合、フェーズ 2 が未完了です。これはこのワークフロー全体で最も重要な行であり、デフォルトのログレベルでは出力された後に破棄されます。

フェーズ 5 — 順番に検証する

1. controls.status() → overall: "online"。アプリがこれをまだアサートしていない場合は、アサーションを追加してください。examples/OpenTag の server.ts は ready() を呼び出した後にステータスを一切確認していません。これこそが、設定に問題があるのに正常に見えてしまう原因です。
2. プロセスの実行中に、ダッシュボードで Channel Online と表示されることを確認します。Runtime パネルには Connected と表示されている必要があります。Agent run 列は無視してください。ターンが正常に完了した後も — と表示されるため、正常性を示す指標ではありません。
3. 開発者自身が自分の Slack アカウントから実際にメンションを送り、返信があったことを報告します。

ステップ 3 は開発者が行います。代理で Slack に投稿したり、本物の往復テストの代わりに Slack ツールでワークスペースを読み取ったりしないでください。メンションに応答がない場合は、references/troubleshooting.md を参照してください。レイヤーごとに原因を診断し、設定を変更し始めないでください。

フェーズ 6 — 任意のライブ E2E テスト

実際のメンションが機能した後にのみ実施します。references/optional-e2e.md を参照してください。テストハーネスがテストクライアントとして Slack API を直接操作するため、Slack トークンを .env に保存してよいのはここだけです。

決してしてはいけないこと

行き詰まりを解消するために、Slack のダイレクトアダプターへ切り替えてはいけません。 プラットフォームの認証情報がアプリ内に移され、マネージド配信の再試行・重複排除・順序保証が放棄されます。また、引き続き Intelligence のキーが必要で、開発者が確認を求めたものとは異なるアーキテクチャを検証したことになります。マネージド経路が利用できない場合は、その旨と理由を伝えてください。

スターター自身の slack-app-manifest.yaml から Slack アプリを作成してはいけません。 OpenTag のマニフェストでは socket_mode_enabled: true が設定され、request_url は宣言されていません。これはマネージド Channel ではなく、_ダイレクト_アダプター向けの形式です。このマニフェストからアプリを作成すると、問題なくインストールでき、Slack では正常を示す緑色で表示されますが、Intelligence にはいつまでも何も配信されません。Channel ウィザードが生成するマニフェストを使用してください。このスキル内の assets/slack-app-manifest.yaml も同様です。ダイレクトアダプターの形式を参照するためだけに置かれています。

本番環境または共有の Slack アプリを再利用してはいけません。 1 つの Slack アプリに設定できるイベントサブスクリプションの Request URL は 1 つだけです。既存のアプリを Channel の URL に向けると、そのアプリのイベントストリーム全体が、現在配信を担当している先から切り替わります。本番トラフィックを観察するのではなく、乗っ取ることになり、実際のユーザーにはノート PC 上で作業中のエージェントが応答することになります。Slack では、特定のチャンネルまたはユーザー 1 人だけに配信を限定する方法はありません。インストール済みアプリにマニフェストを貼り付けると、再インストールも必要になり、トークンがローテーションされて既存の利用者すべてが動作しなくなります。

チャットでシークレットを尋ねたり、表示したりしてはいけません。 所有者の全一覧と取り扱いルールについては、references/secrets-and-credentials.md を参照してください。

ランタイム API キーで Intelligence の HTTP エンドポイントを調べてはいけません。 これはプロジェクトスコープのアクティベーションキーであり、ダッシュボードのセッションではありません。ダッシュボードのエンドポイントはこれを拒否し、レスポンス本文にプラットフォームトークンが含まれる可能性もあります。

作業を早く進めたように見せるために、環境を変更してはいけません。 pnpm install の実行、自分が起動していないプロセスの終了、開発者に代わっての .env の編集は、変更内容を説明して許可を得ない限り禁止です。

合理化

考え	実際
「相手は締め切りに追われている。直接アダプターのほうが速い」	別のアーキテクチャを検証することになり、認証情報を誤った場所に渡すことになります。締め切りのプレッシャーがあるときこそ、スコープを守ることが最も重要です。
「ダッシュボードはわかりにくい。コードのほうが確実だ」	わかりにくさこそが、開発者が実際に抱えている問題です。コードで解決すると、その問題を見えなくしてしまいます。
「本番環境の Slack アプリはすでにインストールされているから、再利用すれば承認を省ける」	その Request URL を変更すると、アプリのイベントストリーム全体を乗っ取ることになります。インストールがほかの人にも影響するため、承認が必要なのです。
「テスト用だから／ほんの1分だけだから」	アプリのイベント URL は1つだけです。あなたの URL が設定されている間、本番環境ではイベントをまったく受信できません。
「スターターにマニフェストが含まれているから、それを使ってアプリを作成しよう」	socket_mode_enabled: true が設定され、request_url はありません。これは直接アダプターの形式です。アプリは正常にインストールされますが、イベントは一切届きません。ウィザードのマニフェストを使ってください。
「xapp- アプリレベルのトークンを生成する必要がある」	このワークフローに xapp- トークンはなく、設定する場所もありません。アダプターが受け取るのはボットトークンと署名シークレットです。
「ランタイムが起動して /info が 200 を返すから、接続済みだ」	ready() は setup_required の状態でも解決し、/info はライセンス状態を報告します。どちらも Slack については何も示しません。
「ready() がエラーなく解決したから、Channel はオンラインだ」	設計上、setup_required の状態でも解決します。status() を確認してください。
「API キーで Channel の状態を確認しよう」	ダッシュボードのエンドポイントはプロジェクトキーを拒否します。status() またはダッシュボードを使ってください。
「設定を確認するために .env を読もう」	名前は .env.example で確認し、.env は値の有無だけを確認してください。値を引用してはいけません。
「往復の手間を省くため、自分でテスト用メンションを送ろう」	成功の基準は、実際の人間によるメンションです。相手の代わりに投稿しても得られる証拠は少なく、相手のワークスペースで本人になり代わって操作することになります。
「返信がない。設定を変えてみよう」	まずレイヤーごとに原因を特定してください。LOG_LEVEL=debug を使えば、失敗の原因が1行でわかります。

危険な兆候 — 停止

• Phase 6 のハーネス以外の目的で、adapters: [slack( と入力しようとしているか、.env に SLACK_BOT_TOKEN を追加しようとしています。
• スターターのマニフェスト、または socket_mode_enabled: true で request_url がないマニフェストから Slack アプリを作成しようとしています。
• アプリレベルのトークン、connections:write、または Socket Mode の切り替えを探そうとしています。これらは管理対象 Channel には不要です。
• アプリの Install App ページを開く、またはスクリーンショットを撮ろうとしています。このページにはボットトークンが平文で表示されます。それを読むと有効な認証情報を取得することになります。
• 3 つすべてのゲートを満たさずに、「接続しました」「動作しています」「完了しました」と言おうとしています。
• 開発者にトークンの貼り付けを頼もうとしているか、トークンをそのまま表示しようとしています。
• 読んでいないダッシュボードのコントロールをクリックしようとしています。
• 頼まれていないのに pnpm install を実行したり、プロセスを終了したり、.env を編集しようとしています。
• 管理対象 Channel の仕組みを調べるために多くのツール呼び出しを行っています。停止してください — このスキルとそのリファレンスに記載されています。

リファレンス

すべてを先に読むのではなく、現在のフェーズに該当するリファレンスを読んでください。 各ファイルは単独で完結しています。開発者に何かを伝える前に 6 つのファイルを読むと、このワークフローは遅くなります。

ファイル	読むタイミング
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 には使用しないでください。