Slack
1. Slack Appの設定
-
Slack APIにアクセスします
-
新しいアプリを作成します（または既存のアプリを使用します）
- 空のアプリから作成（"Blank app"）を選択します
- App Nameを入力し、Workspaceを選択します
-
アプリの認証情報を取得します：
- Client ID（Basic Information → App Credentials内）
- Client Secret（Basic Information → App Credentials内）
2. App-Level Tokensの設定
- Basic Information → App-Level Tokensで、"Generate Token and Scopes"をクリックします
- Token名を入力します（例：
connection_token） connections:write、authorizations:readとapp_configurations:writeのscopesを追加します- "Generate"をクリックします
- 生成された
xapp-...形式のTokenをコピーします
3. OAuth & Permissionsの設定
SlackではHTTPSが必須です。HTTPSがない場合はこの設定をスキップし、方式1の連携方法を使用してください
Slack Appの管理ページ → OAuth & Permissionsで：
3.1 Redirect URLsの追加
https://your-domain:port/agent/api/slack-oauth/callback
例：
- ローカル開発：http://localhost:3000/api/slack-oauth/callback
- テスト環境：https://your-test-domain.com/agent/api/slack-oauth/callback
- 本番環境：https://your-domain.com/agent/api/slack-oauth/callback
注意：
- プロトコルが一致している必要があります（HTTPS）
- デフォルトポート（80/443）以外の場合は、ポート番号を含める必要があります
- 複数のコールバックURL（開発／テスト／本番）を設定できます
3.2 User Token Scopesの設定
OAuth & Permissions → Scopes → User Token Scopesで、次を追加します：
identity.basic- ユーザーの基本情報の取得（必須）identity.email- ユーザーのメールアドレスの取得（任意）
注意：Scopesを追加または変更した後は、アプリをWorkspaceに再インストールする必要があります。
3.3 Bot Token Scopesの設定
OAuth & Permissions → Scopes → Bot Token Scopesで、次を追加します：
chat:write- メッセージの送信app_mentions:read- @メンションの読み取りchannels:history- チャンネルの履歴メッセージの読み取りchannels:read- チャンネル情報の読み取りgroups:history- プライベートチャンネルの履歴メッセージの読み取りim:history- ダイレクトメッセージの履歴の読み取りim:read- ダイレクトメッセージの情報の読み取りfiles:write-ファイルのアップロード、編集、削除files:read- 共有されたファイルの表示
4. App Homeとボットの設定
- App Home → Show Tabsで、次を有効にします：
- Home Tab - ユーザーがHomeでBotとやり取りできます
- Message Tab - Botとのダイレクトメッセージの会話画面
次の項目にチェックを入れます：Allow users to send Slash commands and messages from the messages tab
- Interactivity & ShortcutsでInteractivityを有効にします
- Socket ModeでSocket Modeを有効にします（WebSocket接続を使用する場合）
5. Event Subscriptionsの追加
- Event SubscriptionsでEnable Eventsを有効にします。
- Subscribe to bot eventsに
app_mentionを追加します。パブリックチャンネルまたはプライベートチャンネルで@Appによって開始された新しいタスクを受信するために使用します。 message.channelsとmessage.groupsを追加します。パブリック／プライベートチャンネルのスレッドで、回答待ちへの返信や実行を継続するための返信を受信するために使用します。message.imは残しておきます。ダイレクトメッセージの受信に使用します。複数人のダイレクトメッセージも必要な場合は、message.mpimを追加し、対応する履歴メッセージの権限を付与します。
Socket Mode、イベントとインタラクションのチェック：
- App-Level Tokenには少なくとも
connections:writeを付与し、Enable Socket Modeをオンにします。 - Bot Token Scopesには、少なくとも
chat:write、app_mentions:read、channels:history、groups:history、im:history、files:read、files:writeを含めます。 - Interactivityは必ずオンにしてください。Socket ModeではパブリックなRequest URLは不要ですが、メッセージフォーム、Modalの送信、実行の継続は引き続きInteractivityに依存します。
- OAuth ScopesまたはBot Eventsを変更した後は、AppをWorkspaceに再インストールする必要があります。App-Level Tokenを再生成した後は、チャネル設定のApp Tokenも合わせて更新してください。
6. アプリをWorkspaceにインストール
OAuth & Permissionsページで"Install to Workspace"ボタンをクリックし、アプリにWorkspaceへのアクセスを許可します。
使い方の流れ
方式1：連携コードモード（推奨）
Slackでは、連携コードを使ってグループチャットでアカウントを連携できます。チーム内での展開に適しています。
ユーザーの連携手順
- ユーザーがシステムにログインします
- 左下のユーザーアバターをクリックしてメニューを開きます
- 「Slack」の行を見つけ、「連携コードを取得」ボタンをクリックします
- システムが6桁の連携コード（例：
FRT12H）を生成します。有効期間は10分です - ユーザーがSlackでボットにダイレクトメッセージを送信します：
+bind FRT12H - 連携に成功すると、Slackに「連携完了」のメッセージが表示されます
連携解除の手順
- 左下のユーザーアバターをクリックしてメニューを開きます
- 「Slack」の行を見つけ、「連携解除」ボタンをクリックします
- 連携解除の操作を確認します
- 連携が解除され、メニューに「未連携」ステータスが表示されます
方式2：OAuth認証モード
ブラウザで認証して連携を完了します。
ユーザーの連携手順
- ユーザーがシステムにログインします
- 左下のユーザーアバターをクリックしてメニューを開きます
- 「Slack」の行を見つけ、「連携」ボタンをクリックします
- Slackの認証ページに移動します
- ユーザーが認証を確認します（Workspaceを選択）
- 自動的にシステムに戻り、「連携完了」と表示されます
- 認証ウィンドウを閉じると元のページが自動的に更新され、メニューに「連携済み」ステータスが表示されます
ユーザーの連携解除手順
- 左下のユーザーアバターをクリックしてメニューを開きます
- 「Slack」の行を見つけ、「連携解除」ボタンをクリックします
- 連携解除の操作を確認します
- 連携が解除され、メニューに「未連携」ステータスが表示されます
カスタムコマンド
Slackボットは次のコマンドに対応しています（すべてのコマンドは+で始まります）：
| コマンド | 説明 | 例 |
|---|---|---|
+bind <CODE> | 連携コードでアカウントを連携（6桁の英大文字+数字） | +bind FRT12H |
+new | 新しい会話を開始し、現在の会話履歴をクリアする | +newを送信 |
+agent <名称> <消息> | 指定した名前のAgentにメッセージを送信 | +agent rhea 你好 |
+agent <消息> | システムのデフォルトAgentにメッセージを送信 | +agent 你好 |
説明：
+で始まらないメッセージは、システムのデフォルトAgentに直接送信されます+bindコマンドは連携コードモードで使用します。未連携のユーザーは、先に連携しないと他の機能を使用できません+newコマンドは現在の会話をクリアし、最初からやり直します- Agent名は、ユーザーがアクセス権限を持つAgentである必要があります
- コマンドの引数は大文字と小文字が区別されます
- 連携コードの文字セットからは、紛らわしい文字（I/O/0/1）が除外されています
グループチャットのメッセージ振り分け
グループチャットのメッセージ振り分けを使用すると、同じSlack Appがルールに従って、さまざまな質問をそれぞれ異なるAgentまたはTeamに渡すことができます。1つの「チャットスペース」は現在のWorkspaceに対応し、設定はそのWorkspace内でこのAppがインストールされているチャンネルに適用されます。Agentic Engineアカウントを連携済みで、チャンネル内でAppを明示的に@メンションしたメンバーのみがタスクを開始できます。
管理者による設定
- Socket Mode、Event Subscriptions、Interactivityが有効になっていることを確認します。Bot Eventsには少なくとも
app_mention、message.channels、message.groups、message.imを含め、scopesを変更した後はAppをWorkspaceに再インストールします。 - 使用するパブリックチャンネルまたはプライベートチャンネルにAppを招待します。プライベートチャンネルでAppがメンバーでない場合は、設定が正しくてもメッセージを受信できません。
- 「システム管理 → チャンネル管理」に進み、対象のSlackチャネルで「メッセージ振り分け」を開いてWorkspaceを選択し、既定のAgent/Teamを設定します。
- 必要に応じて最大19件のルールを追加します。各ルールでAgent/Teamを1つ選択し、必須の「呼び出しコマンド」を入力します。キーワードも最大10個まで入力できます。その後、有効化スイッチをオンにして保存します。
- チャンネルで
@App +helpを送信して動作を確認し、機能一覧とスレッドでの返信が正常であることを確認します。
| 構成項目 | ルール |
|---|---|
| 既定の Agent/Team | 有効化する前に設定が必要です。呼び出しコマンドが指定されておらず、キーワードにも一致しない場合に使用されます。 |
| 呼び出しコマンド | 必須、1～32文字。英字、数字、-、_ を使用できます。システムの予約コマンドは使用できません。大文字・小文字や全角・半角の違いは、別のコマンドとして扱われません。 |
| キーワード | 入力は任意です。各ルール最大10個、1個あたり2～32文字。複数のキーワードが同時に一致した場合は、長いキーワードが優先されます。同じ長さで一意に判断できない場合は、既定の Agent/Team に戻ります。 |
| 選択可能な範囲 | 有効かつ実行可能なシステム/企業Agent、および現在の企業のTeamを選択できます。個人Agentはグループチャット振り分けの候補に表示されません。 |
チャンネルでの使い方
| 用途 | 例 | 説明 |
|---|---|---|
| 利用可能な機能を確認 | @App +help@App 能力清单 | 既定の対象、呼び出しコマンド、キーワードを一覧表示します。権限がない機能や現在実行できない機能は表示されません。 |
| Agent/Teamを指定 | @App +analysis 分析本周数据 | analysisは管理者が設定した呼び出しコマンドです。@App @analysis 分析本周数据と送信することもできます。 |
| キーワードで振り分け | @App 帮我检查埋点方案 | 本文がキーワードに一致した場合は対応するAgent/Teamに渡され、一致しない場合は既定の項目が使用されます。 |
| タスクを取消 | @App +cancel | メッセージ全体をこのとおり正確に送信する必要があります。出力済みの本文は残り、取消の確認メッセージが別途送信されます。 |
| 旧形式との互換 | @App +agent analysis 分析本周数据 | 引き続き使用できますが、+analysisを直接使用することをお勧めします。 |
スレッドでの返信：通常の新規タスクは、まずAppを@メンションする必要があります。タスクがすでにスレッド内で回答を待っている場合は、案内に従ってそのスレッドに直接返信でき、再度@メンションする必要はありません。待機中のタスクがない通常のチャンネルメッセージは無視されます。
コマンドの範囲：グループチャット振り分けでは+newは使用できません。ダイレクトメッセージでは引き続き+new、+agent、+cancelを使用できます。
公開コンテキストと個人データ：システムが参考にするのは、最近Appを明示的に@メンションし、実際に処理されたパブリックチャンネルのターンのみです。Appを@メンションしていない通常のメッセージ、他のチャンネル、ダイレクトメッセージ、ユーザーメモリが混ざることはありません。履歴の内容は信頼できない参考情報としてのみ扱われ、現在のメッセージがこのターンの指示となります。
よくある質問
1. ユーザーメニューにSlack連携の項目が表示されない
原因：
- Slack チャネルが未設定か無効です
- Channelテーブルにtype='slack'のレコードがありません
- configフィールドにclientIdまたはclientSecretがありません
解決方法：
- チャネル管理にSlackチャネルがあるか確認します
- チャネルが有効になっていることを確認します
- configフィールドにclientIdとclientSecretが含まれていることを確認します
2. 連携をクリックした後、遷移に失敗する
エラーメッセージ：認証 URL の取得に失敗しました
解決方法：
- Slack AppのClient IDとClient Secretが正しいか確認します
- Slack AppがWorkspaceにインストールされていることを確認します
- バックエンドのログで具体的なエラーメッセージを確認します
3. 認証後のコールバックに失敗する
エラーメッセージ：「コールバックURLの検証に失敗しました」または「stateの検証に失敗しました」
解決方法：
- Slack Appに設定したRedirect URLsに、現在アクセスしているコールバックURLが含まれていることを確認します
- プロトコル（HTTP/HTTPS）とポートが一致しているか確認します
- クロスドメインの問題がないことを確認します
4. 連携に失敗する
エラーメッセージ：この Slack アカウントは他ユーザーに紐付いています
解決方法：
- 1つのSlackアカウントは、1人のシステムユーザーにのみ連携できます
- 連携先を変更する場合は、先に元のアカウントで連携を解除します
5. 本番環境のホワイトリスト検証に失敗する
エラーメッセージ：「本番環境ではALLOWED_ORIGINSの設定が必要です」または「不正なオリジン」
解決方法：
ALLOWED_ORIGINS環境変数を設定します- originがホワイトリストに含まれていることを確認します
- 複数のドメインはカンマで区切ります
関連ドキュメント
関連ページと次のステップ
- 他のプラットフォームの接続手順を確認する：チャンネル管理。
- チャネル接続と連携の全体的な流れを確認する：チャネルの概要と連携。
- 使用するAgentを設定する：Agent。
- プラットフォーム内での会話の使い方を確認する：会話。