OpenClawをSlackと連携させる方法

Slackでの自動応答や通知を実装しようとすると、APIの設定やイベントのハンドリングでつまずくことがよくあります。特に、リアルタイムな双方向通信を安定して維持するのは、開発者にとって手間のかかる作業です。

OpenClawを使えば、SlackのDMやチャンネルとの連携をシンプルに構築できます。デフォルトのSocket Modeを利用すれば、複雑なネットワーク設定を気にすることなく、すぐにボットを動かし始めることが可能です。

必要なもの

Slack App
Bot Token (xoxb-...)
App Token (xapp-...)
Signing Secret（HTTPモードの場合）

クイックスタート

最も推奨されるSocket Modeを使用して、5分で連携を完了させる手順を説明します。

1. Slackアプリとトークンの準備

Slackのアプリ設定画面で以下の設定を行います。

Socket Modeを有効にする
connections:write 権限を持つ App Token (xapp-...) を作成する
アプリをインストールし、 Bot Token (xoxb-...) をコピーする

2. OpenClawの設定

設定ファイル（json5）に以下の内容を記述します。

{
  channels: {
    slack: {
      enabled: true,
      mode: "socket",
      appToken: "xapp-...",
      botToken: "xoxb-...",
    },
  },
}

環境変数で設定することも可能です。

SLACK_APP_TOKEN=xapp-...
SLACK_BOT_TOKEN=xoxb-...

3. イベントの購読

以下のボットイベントを購読するように設定してください。

app_mention
message.channels, message.groups, message.im, message.mpim
reaction_added, reaction_removed
member_joined_channel, member_left_channel
channel_rename
pin_added, pin_removed

また、DMを機能させるためにApp Homeの Messages Tab を有効にしてください。

4. Gatewayの起動

設定が完了したら、以下のコマンドで起動します。

openclaw gateway

HTTP Events API mode を使用する場合

特定の要件でHTTPモードが必要な場合は、以下の設定を行ってください。

Slackアプリの設定でモードをHTTPに変更し、Signing Secretをコピーします。
Event Subscriptions、Interactivity、Slash commandのRequest URLをすべて同じWebhookパス（デフォルトは /slack/events）に設定します。
OpenClawを以下のように設定します。

{
  channels: {
    slack: {
      enabled: true,
      mode: "http",
      botToken: "xoxb-...",
      signingSecret: "your-signing-secret",
      webhookPath: "/slack/events",
    },
  },
}

※複数のアカウントでHTTPモードを利用する場合は、衝突を避けるためにアカウントごとに固有の webhookPath を割り当ててください。

トラブルシューティング

設定中に問題が発生した場合は、以下のドキュメントを確認してください。

Channel troubleshooting: チャンネルをまたいだ診断や修復のためのプレイブックが用意されています。

不明な点がある場合は、AI Setup Assistant に質問してください。

次のステップ

Pairing: Slack DMのペアリングモードについて
Slash commands: ネイティブコマンドの挙動とカタログ
Channel troubleshooting: 診断と修復の手順

Slack アプリを開発していると、どのトークンをどこに設定すべきか、あるいは特定のチャンネルだけにアプリの動作を制限するにはどうすればいいのか、といった問題に直面することがあります。セキュアで管理しやすいアプリを構築するために、認証モデルとルーティングの仕組みを整理しておきましょう。

必要なもの

設定を始める前に、以下の情報が揃っているか確認してください。

botToken および appToken (Socket Mode を使用する場合)
botToken および signingSecret (HTTP Mode を使用する場合)
userToken (xoxp-... / オプション)

クイックスタート

最短でアプリを動作させるための Token 設定とアクセス制御の手順です。

1. Token model の設定

利用する接続モードに合わせてトークンを構成します。

Socket Mode: botToken と appToken が必須です。
HTTP Mode: botToken と signingSecret が必須です。

環境変数を利用する場合、SLACK_BOT_TOKEN と SLACK_APP_TOKEN はデフォルトのアカウントにのみ適用されます。個別の設定（Config）でトークンを指定した場合は、環境変数よりも設定値が優先されます。

[!TIP] アクションの実行やディレクトリの読み取りには userToken を優先するように設定できます。ただし、書き込み処理については botToken が優先されます。userToken による書き込みは、userTokenReadOnly: false かつ botToken が利用できない場合にのみ許可されます。

2. DM ポリシーの制御

channels.slack.dm.policy を使用して、ダイレクトメッセージ（DM）へのアクセスを管理します。

pairing (デフォルト)
allowlist
open (dm.allowFrom に "*" を含める必要があります)
disabled

DM 内でのペアリングを承認するには、以下のコマンドを実行します。

openclaw pairing approve slack <code>

3. チャンネルポリシーの制御

channels.slack.groupPolicy でチャンネルの扱いを決定します。

open: すべてのチャンネルを対象にします。
allowlist: 特定のチャンネルのみを許可します（channels.slack.channels で指定）。
disabled: チャンネルでの動作を無効にします。

4. メンションとユーザーの制限

デフォルトでは、チャンネル内のメッセージはメンションによってゲート（制限）されています。反応させるためのソースは以下の通りです。

明示的なアプリへのメンション (<@botId>)
メンションの正規表現パターン (agents.list[].groupChat.mentionPatterns または messages.groupChat.mentionPatterns)
ボットへのスレッド返信による暗黙的な挙動

特定のチャンネルごとに、requireMention、users (許可リスト)、allowBots、skills などの詳細なコントロールが可能です。

トラブルシューティング

設定中に遭遇する可能性のある挙動と解決策です。

設定が反映されない: channels.slack の設定が完全に欠落しており（環境変数のみのセットアップ）、かつ channels.defaults.groupPolicy が未設定の場合、ランタイムはフォールバックとして groupPolicy="open" を適用し、警告ログを出力します。
チャンネル名が解決できない: チャンネルの許可リストや DM の許可リストのエントリは、トークンの権限が許可する範囲内で起動時に解決されます。解決できないエントリは、設定されたままの状態で保持されます。

さらに詳しい設定や個別のユースケースについては、AI Setup Assistant に質問してください。

次のステップ

Slackを外部システムやエージェントと連携させる際、ユーザーからの入力をどう受け取り、どうレスポンスを返すかは非常に重要なポイントです。コマンドが期待通りに動かなかったり、スレッドの文脈が途切れてしまったりすると、ユーザー体験は一気に損なわれてしまいます。

チャットインターフェース特有の挙動を正しく制御し、スムーズなやり取りを実現するための設定方法を見ていきましょう。

必要なもの

このガイドの内容を実装するには、以下の準備が必要です。

Slack APIのアクセス権限と基本的なアプリケーション設定
システム構成ファイル（channels.slack セクション）へのアクセス権限

クイックスタート

まずは最小限の設定で Slack コマンドを動かしてみましょう。

ネイティブコマンドの有効化: Slack 固有のフラグを true に設定します。
```
channels.slack.commands.native: true
```
Slack側での登録: Slack の管理画面で、使用したいスラッシュコマンド（例: /openclaw）を登録します。
動作確認: これで Slack から直接コマンドを叩けるようになります。デフォルトでは ephemeral: true なので、実行者本人にのみレスポンスが表示されます。

Commands and slash behavior

Slack におけるコマンドの挙動にはいくつか注意点があります。特に、他のチャネルで有効な設定が Slack では無効な場合があります。

Native mode の注意点: Slack では、commands.native: "auto" を設定してもネイティブコマンドは有効になりません。必ず channels.slack.commands.native: true（またはグローバルの commands.native: true）を明示的に指定してください。
コマンドの登録: ネイティブコマンドを有効にした後は、Slack 側で対応するスラッシュコマンド（/<command> 名）を登録する必要があります。
フォールバック: ネイティブコマンドを有効にしない場合は、channels.slack.slashCommand を介して、単一の構成済みスラッシュコマンドを実行できます。

デフォルトのスラッシュコマンド設定

デフォルトでは以下の値が適用されます：

enabled: false
name: "openclaw"
sessionPrefix: "slack:slash"
ephemeral: true

スラッシュコマンドのセッションは、agent:<agentId>:slack:slash:<userId> という独立したキーを使用しますが、コマンドの実行自体はターゲットとなる会話セッション（CommandTargetSessionKey）に対してルーティングされます。

Threading, sessions, and reply tags

Slack の会話形式（DM、チャネル、グループ）に応じて、セッションのルーティングが異なります。

ルーティングの分類: DM は direct、公開・非公開チャネルは channel、マルチパーソンDM（MPIM）は group としてルーティングされます。
DMの集約: デフォルトの session.dmScope=main 設定では、Slack の DM はエージェントのメインセッションに集約されます。
チャネルセッション: チャネルごとに agent:<agentId>:slack:channel:<channelId> という形式で管理されます。
スレッドの扱い: スレッドへの返信は、必要に応じて :thread:<threadTs> というサフィックスが付与されたスレッドセッションを作成できます。デフォルトの channels.slack.thread.historyScope は thread で、thread.inheritParent は false です。

返信モードの制御

channels.slack.replyToMode を使用して、返信の挙動を off | first | all から選択できます（デフォルトは off）。これは channels.slack.replyToModeByChatType を使って、チャットタイプ（direct/group/channel）ごとに細かく制御することをおすすめします。

また、手動で返信先を指定するタグもサポートされています：

[[reply_to_current]]
[[reply_to:<id>]]

Media, chunking, and delivery

メディアの扱いやメッセージの分割についても、Slack の制限に合わせた調整が可能です。

Inbound attachments

Slack にアップロードされたファイルは、トークン認証されたフローを通じてプライベート URL からダウンロードされます。サイズ制限内であれば、メディアストアに書き込まれます。

サイズ制限: デフォルトの受信サイズ上限は 20MB です。これは channels.slack.mediaMaxMb で変更可能です。

Outbound text and files

テキスト分割: channels.slack.textChunkLimit（デフォルト 4000文字）で分割されます。
分割モード: channels.slack.chunkMode="newline" を設定すると、段落優先でメッセージを分割するため、読みやすさが向上します。
ファイル送信: Slack の upload API を使用します。スレッド返信（thread_ts）も含めることができます。

Delivery targets

明示的な送信先指定には、以下のターゲットを使用するのがベストプラクティスです。

user:<id> （DM用）
channel:<id> （チャネル用）

Actions and gates

Slack 上でのアクション（メッセージ操作やリアクションなど）は、channels.slack.actions.* で制御できます。現在、以下のグループが利用可能です。

グループ	デフォルト設定
messages	enabled
reactions	enabled
pins	enabled
memberInfo	enabled
emojiList	enabled

Events and operational behavior

Slack 内で発生する様々なイベントは、自動的にシステムイベントにマッピングされます。これにより、メッセージの編集や削除、リアクションの追加、チャネルへの参加・脱退などをトリガーにした処理が可能になります。

チャネル情報の変更: channel_id_changed イベントが発生した際、configWrites が有効であればチャネル構成キーを自動的に移行できます。
メタデータの活用: チャネルのトピックや目的（purpose）などのメタデータは、ルーティングコンテキストに注入して活用することができます。

トラブルシューティング

コマンドが反応しない: commands.native: "auto" を使用していませんか？ Slack では channels.slack.commands.native: true と明示的な登録が必要です。
ファイルが届かない: ファイルサイズが 20MB を超えていないか確認してください。必要に応じて channels.slack.mediaMaxMb を調整します。
セッションが混ざる: DM とチャネルでセッションキーの構造が異なります。特定のユーザーとの対話を維持したい場合は、session.dmScope の設定を見直してください。

詳細な設定やトラブルシューティングについては、AI Setup Assistant も活用してください。

次のステップ

Slack アプリを開発していると、どの権限（Scope）が必要で、どこで設定を管理すればいいのか迷うことがあります。特に Manifest の記述や権限の過不足は、アプリが正しく動かない原因になりやすく、デバッグに時間がかかってしまいます。

ここでは、OpenClaw を Slack に接続するために必要な設定をまとめました。

必要なもの

Slack アプリの管理権限
セットアップ用の Manifest ファイル

クイックスタート

OpenClaw を Slack に接続するための Manifest 設定例を紹介します。以下の JSON を Slack の App Manifest エディタに貼り付けることで、必要な機能を一括でセットアップできます。

{
  "display_information": {
    "name": "OpenClaw",
    "description": "Slack connector for OpenClaw"
  },
  "features": {
    "bot_user": {
      "display_name": "OpenClaw",
      "always_online": false
    },
    "app_home": {
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "slash_commands": [
      {
        "command": "/openclaw",
        "description": "Send a message to OpenClaw",
        "should_escape": false
      }
    ]
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "chat:write",
        "channels:history",
        "channels:read",
        "groups:history",
        "im:history",
        "mpim:history",
        "users:read",
        "app_mentions:read",
        "reactions:read",
        "reactions:write",
        "pins:read",
        "pins:write",
        "emoji:read",
        "commands",
        "files:read",
        "files:write"
      ]
    }
  },
  "settings": {
    "socket_mode_enabled": true,
    "event_subscriptions": {
      "bot_events": [
        "app_mention",
        "message.channels",
        "message.groups",
        "message.im",
        "message.mpim",
        "reaction_added",
        "reaction_removed",
        "member_joined_channel",
        "member_left_channel",
        "channel_rename",
        "pin_added",
        "pin_removed"
      ]
    }
  }
}

オプション：User-token Scopes

もし channels.slack.userToken を設定する場合は、以下の読み取り用 Scope を設定してください。

channels:history, groups:history, im:history, mpim:history
channels:read, groups:read, im:read, mpim:read
users:read, reactions:read
pins:read, emoji:read
search:read（Slack の検索読み取りに依存する場合）

設定に迷ったときは、AI Setup Assistant で質問してみてください。

次のステップ

---
title: Slack Gateway Troubleshooting Guide
description: Slack連携がうまく動作しない時のチェックリストと解決策をまとめました。
---

Slack Gatewayを設定したのに、ボットが反応してくれない。そんな経験はありませんか？設定項目が多くて、どこに原因があるのか分からなくなるのは開発者なら誰もが通る道です。

せっかくのツールも動かなければ意味がありません。スムーズに動作させるための診断ポイントを整理しました。

## 必要なもの

トラブルシューティングを始める前に、以下の準備ができているか確認してください。

- Slack Appの認証情報（botToken, appToken, signingSecret）
- OpenClaw CLI がインストールされている環境
- 編集可能な設定ファイル

## クイックスタート

まずは、現状を把握するための最短ルートを試しましょう。以下のコマンドを順番に実行して、エラーの兆候を探します。

1. **全体診断を実行する**
   ```bash
   openclaw doctor

リアルタイムでログを確認する
Terminal window
```
openclaw logs --follow
```
チャンネルのステータスをプローブする
Terminal window
```
openclaw channels status --probe
```

トラブルシューティング

よくある問題と、その解決のために確認すべき項目です。

チャンネルで返信がない場合

ボットがチャンネル内にいるのに反応しない時は、以下の項目を順番にチェックしてください。

groupPolicy の設定
チャンネルの allowlist (channels.slack.channels)
requireMention が有効になっていないか
チャンネルごとの users allowlist

DM（ダイレクトメッセージ）が無視される場合

個人チャットで反応がない場合は、以下の設定を見直します。

channels.slack.dm.enabled
channels.slack.dm.policy
pairing の承認状態、または allowlist のエントリ

ペアリングの状態を確認するには、このコマンドを使います。

openclaw pairing list slack

Socket Mode が接続されない場合

Socket Mode を利用している場合は、Slack App の設定画面と設定ファイルの整合性を確認してください。

botToken と appToken が正しいか
Slack App の設定で Socket Mode が有効（Enablement）になっているか

HTTP Mode でイベントを受信できない場合

HTTP Mode（Webhook）を利用している場合は、外部からの疎通を確認します。

signing secret が正しいか
webhookPath の設定
Slack 側の Request URLs (Events, Interactivity, Slash Commands) が正しいか
HTTP アカウントごとにユニークな webhookPath が割り当てられているか

Native/Slash Commands が実行されない場合

コマンドが反応しない時は、まず「どのモード」を使いたいのかを明確にしましょう。

Native Command Mode: channels.slack.commands.native: true を設定し、Slack 側で対応する Slash Command を登録しているか
Single Slash Command Mode: channels.slack.slashCommand.enabled: true を使用しているか

あわせて、commands.useAccessGroups やチャンネル・ユーザーの allowlist も確認ポイントです。

Configuration reference pointers

さらに詳細な設定が必要な場合は、以下のリファレンスを参照してください。

Configuration reference - Slack

特に注目すべき Slack 関連のフィールドは以下の通りです。

Mode/Auth: mode, botToken, appToken, signingSecret, webhookPath, accounts.*
DM Access: dm.enabled, dm.policy, dm.allowFrom, dm.groupEnabled, dm.groupChannels
Channel Access: groupPolicy, channels.*, channels.*.users, channels.*.requireMention
Threading/History: replyToMode, replyToModeByChatType, thread.*, historyLimit, dmHistoryLimit, dms.*.historyLimit
Delivery: textChunkLimit, chunkMode, mediaMaxMb
Ops/Features: configWrites, commands.native, slashCommand.*, actions.*, userToken, userTokenReadOnly

解決しない場合は、AI Setup Assistant も活用してみてください。

次のステップ

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。