Slack

ZeroClaw エージェントを Slack ボットとして実行しましょう。このガイドでは、その手順を段階的に説明します。最後には、ユーザーがメッセージを送信したり @メンションしたりすると応答するボットがワークスペースに導入されます。

エージェントと対話できるユーザー

受信側の送信者は、バインドされたエージェントに対して解決されたピアセットに照らして制御されます。これはエージェントが所属する peer_groups 設定から導出されます。照合では先頭の @ を取り除き、チャネルのネイティブな送信者識別子に対して大文字・小文字を区別せずに行われます。空のセットはすべてを拒否し、"*" を含むセットはすべてを受け入れます。それ以外の場合は、リストに記載された外部ピア（およびピアエージェント）のみが受け入れられます。これはゲートウェイのペアリング（gateway.require_pairing）とは別物であり、ペアリングはチャットチャネルの送信者ではなく HTTP/WebSocket クライアントを認証します。

slack のピアグループは channel を slack に設定し、許可する送信者を external_peers に列挙し（slack の場合は Slack のユーザー ID。["*"] は誰でも受け付けます）、エージェント間ディスパッチ用にピア agents をオプションで指定し、ignore のブロックリスト、output_modality（mirror、voice、または text）を指定します。フィールドのリファレンスについては Peer Groups を参照してください。

この設定の場所:

クイックスタート

Slack には2つのトークンが必要です。bot token（ボットが発言に使用するトークン）と app token（公開URLをホストせずにボットを接続できるようにするトークン）です。どちらも同じアプリページから取得できます。

1. Slack アプリを作成する

1. api.slack.com/apps にアクセスし、Create New App -> From scratch をクリックします。
2. 名前を付けてワークスペースを選択し、Create App をクリックします。

2. ボットに必要な権限を追加する

1. 左側のサイドバーで、OAuth & Permissions を開きます。
2. Scopes -> Bot Token Scopes で、app_mentions:read、channels:history、chat:write、channels:read を追加します。(ダイレクトメッセージを使いたい場合は im:history と im:write も追加します。)

3. Socket Modeを有効にしてアプリトークンを取得する

1. 左側のサイドバーで Socket Mode を開き、オンに切り替えます。
2. Slack から アプリレベルトークン の作成を求められます。トークンに名前を付け、connections:write スコープを付与して、Generate をクリックします。
3. xapp- で始まるトークンをコピーしてください。これがあなたの app_token です。

ソケットモードを使用すると、ボットが Slack への送信接続を保持できるため、公開 Webhook URL やポートフォワーディングは必要ありません。これが簡単な方法です。

4. アプリをインストールしてボットトークンを取得する

1. サイドバーの Install App を開き、Install to Workspace をクリックして Allow を選択します。
2. OAuth & Permissions に戻り、xoxb- で始まる Bot User OAuth Token をコピーします。これがあなたの bot_token です。

5. ZeroClaw に両方のトークンを伝える

どちらのトークンも機密情報なので、暗号化するインターフェイスを介して設定してください:

channels.slack.<alias>.bot_token はシークレットです。 暗号化して保存され、平文の config.toml には保存されません。書き込み時に暗号化される以下のいずれかの方法で設定してください:

zeroclaw config set channels.slack.<alias>.bot_token    # マスク入力のプロンプトを表示し、暗号化して保存

app_token も同様に設定します（手順3で取得した xapp- トークンです）。

環境変数による代替手段。 両方のトークンは、設定ファイルの代わりにデーモンの環境から指定できます。bot_token は ZEROCLAW_SLACK_BOT_TOKEN、次に SLACK_BOT_TOKEN から解決され、app_token は ZEROCLAW_SLACK_APP_TOKEN、次に SLACK_APP_TOKEN から解決されます。設定ファイル内の値は環境よりも優先されます。これにより、（環境変数を注入するシークレットマネージャーなどのために）設定の読み込みに失敗することなく、config.toml から bot_token を完全に省略できます。

6. ボットを招待してテストする

Slack でチャンネルを開き、/invite @YourBotName と入力します。次にメッセージを送信するか、ボットを @-メンションします。ZeroClaw を起動すると (zeroclaw service restart または zeroclaw daemon)、返信が来るはずです。返信がない場合は、トラブルシューティングを参照してください。

設定

ライブスキーマから導出された完全なフィールド一覧です。基本的なSocketモードのBotでは、bot_tokenとapp_tokenのみを設定します。

zeroclaw config set channels.slack.<alias>.app_token    # マスクされた入力、暗号化して保存

export ZEROCLAW_channels__slack__<alias>__app_token=

zeroclaw config set channels.slack.<alias>.approval_timeout_secs <value>

export ZEROCLAW_channels__slack__<alias>__approval_timeout_secs=

zeroclaw config set channels.slack.<alias>.bot_token    # マスクされた入力、暗号化して保存

export ZEROCLAW_channels__slack__<alias>__bot_token=

zeroclaw config set channels.slack.<alias>.cancel_reaction <value>

export ZEROCLAW_channels__slack__<alias>__cancel_reaction=

zeroclaw config set channels.slack.<alias>.channel_ids <value>

export ZEROCLAW_channels__slack__<alias>__channel_ids=

zeroclaw config set channels.slack.<alias>.draft_update_interval_ms <value>

export ZEROCLAW_channels__slack__<alias>__draft_update_interval_ms=

zeroclaw config set channels.slack.<alias>.excluded_tools <value>

export ZEROCLAW_channels__slack__<alias>__excluded_tools=

zeroclaw config set channels.slack.<alias>.interrupt_on_new_message <value>

export ZEROCLAW_channels__slack__<alias>__interrupt_on_new_message=

zeroclaw config set channels.slack.<alias>.mention_only <value>

export ZEROCLAW_channels__slack__<alias>__mention_only=

zeroclaw config set channels.slack.<alias>.proxy_url <value>

export ZEROCLAW_channels__slack__<alias>__proxy_url=

zeroclaw config set channels.slack.<alias>.reply_min_interval_secs <value>

export ZEROCLAW_channels__slack__<alias>__reply_min_interval_secs=

zeroclaw config set channels.slack.<alias>.reply_queue_depth_max <value>

export ZEROCLAW_channels__slack__<alias>__reply_queue_depth_max=

zeroclaw config set channels.slack.<alias>.stream_drafts <value>

export ZEROCLAW_channels__slack__<alias>__stream_drafts=

zeroclaw config set channels.slack.<alias>.strict_mention_in_thread <value>

export ZEROCLAW_channels__slack__<alias>__strict_mention_in_thread=

zeroclaw config set channels.slack.<alias>.thread_context_max_messages <value>

export ZEROCLAW_channels__slack__<alias>__thread_context_max_messages=

zeroclaw config set channels.slack.<alias>.thread_replies <value>

export ZEROCLAW_channels__slack__<alias>__thread_replies=

zeroclaw config set channels.slack.<alias>.use_markdown_blocks <value>

export ZEROCLAW_channels__slack__<alias>__use_markdown_blocks=

ソケットモード vs HTTP

app_token が設定されている場合、ボットは Socket Mode を使用します。Slack へ接続を確立するため、公開 URL は不要です。これは推奨される構成であり、上記のクイックスタートで使用しているものです。app_token がない場合、Slack は HTTP 経由でボットに到達する必要があり、公開イベントエンドポイントのホスティングが必要となり、セットアップも増え、セキュリティ対策もより多く必要になります。

スレッドとコンテキスト

Slackの会話がスレッド内で行われる場合、そのスレッドはそれ自体が1つの会話になります。ZeroClawはスレッドごとに固有のセッションキーを生成するため、各スレッドは独立したコンテキストウィンドウと履歴を保持します。あるスレッドのメッセージが別のスレッドに漏れることはなく、エージェントが兄弟スレッドの過去のやり取りを見ることもありません。Slackでは、これはthread_repliesによって制御されます。オンの場合、トップレベルのメッセージがスレッドを開き、各スレッドが個別の会話になります。オフの場合、返信はチャンネルのルートに投稿され、履歴はスレッドではなく送信者とターゲットをキーとして管理されます。

• 分離こそが要点です。 各スレッドのコンテキストは自己完結しています。スレッドの外部に漏れることはなく、スレッドの外部からも何も漏れ込みません。並列スレッドは別々の会話状態を保持するため、無関係なタスクが互いに混ざり合うことはありません。
• 長いスレッドはコンテキストを増大させます。 スレッドはアクティブな間、履歴を蓄積していくため、非常に長いスレッドは他の長い会話と同様に、最終的にはモデルのコンテキストウィンドウを埋め尽くします。リセットするには新しいスレッドを開始してください。
• 処理中の作業はスレッドごとにスコープされます。 あるスレッドで新しいメッセージが届いても、別のスレッドで処理中の応答がキャンセルされることはありません。各スレッドのタスクは独立して動作します。

任意のサーフェスにスレッドの動作を設定します:

zeroclaw config set channels.slack.<alias>.thread_replies true     # スレッドの返信を有効化
zeroclaw config set channels.slack.<alias>.thread_replies false    # チャンネルルートでの返信

strict_mention_in_thread はこれをさらに厳格にします。true の場合、ボットはスレッド内で自身が @メンションされたメッセージにのみ応答し、参加しているスレッド内のすべてのメッセージに返信することはなくなります。

既存のスレッドでZeroClawが処理する最初のメッセージでは、以前の返信を取得し、上限付きの [Thread context] ブロックを先頭に付加するため、エージェントはそれまでのやり取りを踏まえて回答できます。thread_context_max_messages は、取得ウィンドウ内で利用可能な以前のメッセージのうち、最新のものをいくつ含めるかを制御し、時系列順を維持します。デフォルトは 0、最大値は 50 で、0 にするとこの自動ハイドレーションが無効になります。有効にするには、0以外の値を明示的に設定します。

1 回のハイドレーションでは、HTTP 429 応答後の再試行を含め、conversations.replies の試行は合計で最大 3 回です。リクエスト予算が残っている間、ZeroClaw は再試行する前に Slack の Retry-After 値に従って待機します。長いスレッドにまだ別のページがある場合、ZeroClaw は上限付きの部分コンテキストを使用し、省略マーカーを追加して、スレッドをハイドレーション済みとして記録します。これにより、後続の返信でスキャンが再開されることはありません。Slack API の失敗によって現在のメッセージが破棄されることはありません。ハイドレーションをスキップして予約を解放するため、次に条件を満たす返信で再試行できます。

メンションと書式

• mention_only: true の場合、ボットは @メンションされたメッセージのみに応答し、混雑したチャンネルでは静かにします。
• use_markdown_blocks: Slack Block Kit 形式で返信をレンダリングし、よりリッチなレイアウトを実現します。プレーンテキストにする場合はオフにします。

ストリーミング

Slack は stream_drafts ブール値を使用して応答をストリーミングします。

• false（デフォルト）: エージェントが終了すると、返信全体が1つのメッセージとして投稿されます。
• true: ボットはプレースホルダーを即座に投稿し、回答がストリーミングされるにつれてその場で編集します。draft_update_interval_ms が編集のペースを調整します。Slack がレート制限する場合は値を上げてください。

任意のサーフェスに設定します:

zeroclaw config set channels.slack.<alias>.stream_drafts <value>

draft_update_interval_ms はストリーミングドラフトを編集する頻度を制御し（Slack が編集をレート制限する場合は値を上げてください）、cancel_reaction は処理中の返信をキャンセルするためにユーザーがリアクションできる絵文字を設定します。

トラブルシューティング

関連項目も参照してください

• エージェントと通信できる対象（ピアグループ）
• Discord
• チャンネルの概要