Slack インテグレーションを設定

このガイドでは、Control Center にアプリを作らせる方法と、自分でアプリを構築する方法のいずれかで、Slack を Control Center ワークスペースに接続する手順を説明します。

初めての実行をガイド付きで進める場合は、Slack をワークスペースにブリッジを参照してください。

前提条件

Control Center ワークスペースでの owner または admin ロール — チャットアプリの接続はワークスペース設定の変更です
Slack ワークスペースでアプリを作成してインストールする権限
公開到達可能なものは何も不要です。接続は外向き（Socket Mode）なので、サーバーにはインバウンドポートもトンネルもドメインも要りません

アプリを用意する 3 つの方法

方法	用意するもの	Control Center が行うこと
ガイド付き	アプリ設定トークン（`xoxe-…`）	適切なスコープ、イベント、Socket Mode、スラッシュコマンドを備えてアプリを作成し、Slack に API がない 2 つの手順を提示します
Slack で作成	なし	同じ設定を事前入力して Slack を開きます。ワークスペースを選んで確定します
手動	完成したアプリのトークン	それらを検証して接続します

ガイド付きの方法だけが、アプリを Control Center から管理可能なまま残します。これがチャットボットをカスタマイズを可能にするものです。Slack で作成したアプリは、後から接続ダイアログで設定トークンを貼り付けることで、管理対象のアプリに昇格できます。

「Control Center の Slack アプリをインストール」ボタンは意図的にありません。配布型の Slack アプリをインストールするには共有クライアントシークレットが必要で（Slack には PKCE がありません）、さらに Socket Mode はアプリのイベントをその接続全体にランダムに分散します — つまり 1 つの共有アプリは、あなたのワークスペースのメッセージを他人のサーバーに届けてしまいます。そのため各ワークスペースは自前のアプリを持ち、これら 3 つの方法は、その手間にどれだけかけずに済むかという話です。

オプション A: Control Center にアプリを作らせる

api.slack.com/apps でアプリ設定トークンのペアを生成し、refresh トークン（xoxe-…）をコピーします
Control Center で 設定 → ワークスペース → 全般 に移動し、チャットブリッジカードまでスクロールします
Slack のブロックで アプリを作ってもらう をクリックします
トークンを貼り付け、アプリ名、ボット名、説明、スラッシュコマンドを調整し、アプリを作成 をクリックします
ダイアログに表示される残り 2 つの手順を、それぞれ Slack へのリンクとしてたどります:
- Basic Information → App-Level Tokens: connections:write スコープを持つトークン（xapp-…）を生成します
- Install App: ワークスペースにインストールし、Bot User OAuth Token（xoxb-…）をコピーします
認証情報を貼り付け をクリックし、接続に進みます

設定トークンは使用のたびにローテーションされます。Control Center はその都度ローテーション後の値を保存するので、もう一度貼り付ける必要はありません。

オプション B: Slack で作成する（事前入力済み）

同じアプリを、設定トークンなしで作ります — Slack の作成画面が、マニフェスト全体を入力済みの状態で開きます。

Control Center で 設定 → ワークスペース → 全般 に移動し、チャットブリッジカードまでスクロールします
Slack のブロックで アプリを作ってもらう をクリックします
アプリ名、ボット名、説明、スラッシュコマンドを調整します — これらはリンクとともに渡されます
Slack で作成 をクリックします。ブラウザで Slack のアプリ作成ページが、設定を事前入力した状態で開きます
Slack ワークスペースを選んで確定します。スコープ、イベント、Socket Mode、スラッシュコマンドはすでに正しく設定されています
Control Center に戻り、ダイアログに表示される残り 2 つの手順をたどります:
- 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 はすべて空のままにします。Socket Mode と webhook 配信の両方を求めるマニフェストを Slack は拒否します。

ボットトークンのスコープ (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 タブを有効にし、書き込み可能なままにしておくと、メンバーがボットに DM を送れるようになります。

トークン: connections:write を持つアプリレベルトークンを生成し、アプリをインストールしてボットユーザー OAuth トークンをコピーします。

接続

設定 → ワークスペース → 全般 に移動し、チャットブリッジカードまでスクロールします
Slack のブロックで Slack を接続 をクリックします
フィールドを入力します:

フィールド	値	Slack での場所
ボットユーザー OAuth トークン	`xoxb-…`	OAuth & Permissions → Bot User OAuth Token
アプリレベルトークン	`xapp-…`	Basic Information → App-Level Tokens（`connections:write`）
アプリ設定リフレッシュトークン（任意）	`xoxe-…`	api.slack.com/apps のアプリ設定トークンのペア

各値のプレフィックスは、何かが送信される前に両側で検証されるため、間違った欄に貼り付けた値はどちらでも同じ文言で拒否されます。

接続をクリックします

Control Center は何かを保存する前に、Slack の auth.test でボットトークンを検証するため、タイプミスは静かに動かないソケットになるのではなく、あなたに報告されます。アプリレベルトークンはソケットを開くことでしか確認できないため、不正なものは少し後に同じ行の接続エラーとして現れます。

任意のアプリ設定トークンがなくても、接続は問題なく機能します — ただ、Control Center からボットを編集することはできません。

接続すると何が行われるか

資格情報を、ワークスペース自身のディレクトリの、データベースの隣に、所有者のみが読める形で保存します。クライアントへ返送されることはありません
このワークスペース用に Socket Mode 接続を 1 つ開き、メンション、Slack スレッドの返信、DM、スラッシュコマンドの受信を開始します
以前にブリッジされていたすべての Slack スレッドを再び有効にするので、再接続しても既存の会話が孤立せず継続されます
チャットアプリを持たないワークスペースには何のコストもかかりません。ソケットもタイマーもトラフィックもありません

ボットの資格情報は、プロバイダーごとに <dataDir>/<workspaceId>/chat_credentials/ にあるプレーンな JSON ファイル 1 つで、アトミックに書き込まれ、所有者のみに制限されます。これは見落としではなく意図的なものです。ワークスペースを削除するとそのディレクトリがリンク解除されるのでトークンも一緒に消え、workspace.export とバックアップはディレクトリではなく workspace.db をコピーするため、他人に引き渡したワークスペースが生きたボットトークンを内部に持ち込むことはありません。その裏返しとして、ワークスペースを別の場所に復元するときは、そこで Slack に再接続する必要があります。

ブリッジへのアクセスはワークスペースのメンバーシップであり、トークンの所持ではありません。Slack アカウントは、書き込み権限を持つメンバーである Control Center ユーザーにリンクされている必要があります。接続、切断、ガイド付きセットアップ、セットアップリンク、ボットのカスタマイズは、すべて管理者に限定されています。

確認

Slack の行にはステータスタグが表示されます: 稼働中、接続中…、接続エラー（その横に Slack 自身のエラーが表示されます）、または未接続です。エンドツーエンドで確認するには:

Slack でボットをチャンネルに招待します: /invite @your-bot-name
依頼とともにボットにメンションします
Slack のスレッド返信が現れ、Control Center に対応するスペースが現れます

ブリッジを使いたいメンバーは、それぞれ自分のアカウントをリンクします — Slack アカウントをリンクを参照してください。

Slack での返信の表示

ストリーミングされるテキストの上に、手順ごとに 1 行を持つ 1 つのグループ化されたカードが置かれます。セットアップは 1 行で、そのタイトルは 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… 行の思考は短い 1 行であり、トランスクリプトではありません。カードの View in Control Center はデスクトップアプリで会話全体を開きます — リンクはあなた自身の Control Center サーバーを指し、そのサーバーがブラウザをアプリに引き渡します。

クリックしても何も起こらない場合、そのメッセージを送ったサーバーに、クリックしたマシンから到達できません（たとえばループバック専用のサーバーをスマートフォンからクリックした場合）。またはそこに Control Center が動作していません。到達可能なアドレスを持たないサーバーは、どこにも通じないボタンではなく、ボタンのないカードを送ります。

トークンをローテーションする

接続ダイアログに新しい値を貼り付け直し、接続をクリックします。接続すると、このワークスペースで動作していた接続が置き換えられるので、ソケットは新しい資格情報で張り直されます。

2 つの必須トークンは、接続のたびに存在している必要があります。任意のアプリ設定トークンは、欄を空のままにすると保存済みの値を保つので、ボットトークンをローテーションしてもアプリを編集する能力を失うことはありません。

切断

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 には、そのロールが読み取り専用であると伝えられます。ブリッジは、帰属できない相手の代わりに作業を開始することはありません
ワークスペースにエージェントはありますか？ エージェントがない場合、メッセージは保存されますが、応答する相手がいません

チャンネルでは応答するが、通常のメッセージを無視する

これは意図した動作です。DM 以外では、ブリッジはボットにメンションしたメッセージ、またはすでに所有している Slack スレッド内の返信にしか反応しません。それ以外はすべて他人の会話です。

返信がストリーミングされず、1 つの大きなメッセージとして届く

行には「この Slack アプリではライブストリーミングがオフです — 返信は 1 つのメッセージとして届きます。」と表示されます。Slack のストリーミング返信には有料プランの Agents & AI Apps 機能が必要で、Slack がそれを拒否すると、ブリッジはその接続の生涯にわたって要求をやめ、代わりに返信をまとめて投稿します。失われるものはありません — トランスクリプト全体は常に Control Center にあります。

ストリーミングには Slack スレッドのアンカーも必要なので、伸びていく先の Slack スレッドがない返信はまとめて投稿されます。タスクカードはどちらの場合も届きます。まとめて投稿される返信では、すでに完成したカードが同じメッセージに載ります。

返信の上にカードがない

Slack のタスクカードは、ストリーミングと同じ新しい Agents & AI Apps サーフェスの一部であり、Slack は呼び出し時にしか拒否しません。拒否した場合、Control Center はその接続の生涯にわたって返信を保持し、カードを破棄します — ステータス行のない回答は、回答のないステータス行より優れています。

「ボットを編集するには、Control Center にアプリ設定トークンが必要です」

ボットをカスタマイズ の行は、接続にアプリ設定トークンがないため無効になっています。これは手動で作成したアプリや Slack で作成 したアプリでは想定どおりです — Slack は Control Center にどのアプリかを伝えていません。api.slack.com/apps でトークンのペアを生成し、リフレッシュトークンを入力して再接続してください。

長い回答が途中で切れる

Slack は 1 つのメッセージを 40,000 文字に制限しているため、ブリッジは 39,000 文字で切り詰め、Control Center へのポインタを付け加えます — 短くなった返信は、Slack に完全に拒否される返信より優れています。全文は常にスペースのトランスクリプトにあります。