Discord

ZeroClaw エージェントを Discord ボットとして実行しましょう。このガイドでは、ボットの操作経験がなくても、クリックごとに手順を説明します。最後には、サーバー内でユーザーが話しかけると返信するボットが完成します。

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

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

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

この設定の場所:

クイックスタート

5つのステップ: ボットを作成し、トークンをコピーし、2つのスイッチをオンにし、招待し、ZeroClawを起動します。

1. ボットを作成する

1. Discord Developer Portal にアクセスします。
2. New Application をクリックして名前を付け、Create をクリックします。
3. 左側のサイドバーで、Bot をクリックします。
4. Reset Token をクリックし、次に Copy をクリックします。この長い文字列が bot_token です。ステップ 3 で使用するため安全な場所に保管してください。後で再度表示することはできません（リセットのみ可能です）。

ボットトークンはボットのパスワードです。これを持っている人は誰でもあなたのボットを操作できます。公開チャットやスクリーンショットに貼り付けたり、gitにコミットしたりしないでください。

2. ボットが必要とする2つのスイッチをオンにする

Bot ページのまま、Privileged Gateway Intents までスクロールして、これらの両方をオンに切り替えます:

• ボットがユーザーの入力内容を読み取れるようにするための Message Content Intent。
• サーバーメンバーインテント を有効にすると、サーバーに参加しているメンバーを確認できるようになります。

変更を保存 をクリックします。これを省略すると、Bot は接続しても一切メッセージを受信できず、「Bot が何も反応しない」という最も多い原因になります。

3. ZeroClawにボットについて伝える

ステップ1で取得したトークンを設定に入れてください。トークンは秘密情報なので、config.toml に直接入力するのではなく、暗号化するインターフェースを通じて設定してください。

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

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

4. ボットをサーバーに招待する

1. Developer Portal に戻り、OAuth2 -> URL Generator を開きます。
2. Scopes で bot にチェックを入れます。
3. Bot Permissions で、少なくとも Send Messages、Read Message History、View Channels をチェックしてください。
4. 下部のURLをコピーしてブラウザで開き、サーバーを選択して認証します。

ボットがメンバーリストに表示されるようになります（ZeroClaw を起動するまではオフラインです）。

5. 起動とテスト

ZeroClaw を起動し（zeroclaw service restart または zeroclaw daemon）、ボットが見えるチャンネルでメッセージを送信します。返信されるはずです。返信されない場合は、トラブルシューティングに進んでください。

設定

ライブスキーマから取得した完全なフィールド一覧です。ほとんどには適切なデフォルト値が設定されており、基本的なボットでは bot_token のみを設定すれば十分です。

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

export ZEROCLAW_channels__discord__<alias>__approval_timeout_secs=

zeroclaw config set channels.discord.<alias>.archive <value>

export ZEROCLAW_channels__discord__<alias>__archive=

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

export ZEROCLAW_channels__discord__<alias>__bot_token=

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

export ZEROCLAW_channels__discord__<alias>__channel_ids=

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

export ZEROCLAW_channels__discord__<alias>__draft_update_interval_ms=

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

export ZEROCLAW_channels__discord__<alias>__excluded_tools=

zeroclaw config set channels.discord.<alias>.guild_ids <value>

export ZEROCLAW_channels__discord__<alias>__guild_ids=

zeroclaw config set channels.discord.<alias>.intents_mask <value>

export ZEROCLAW_channels__discord__<alias>__intents_mask=

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

export ZEROCLAW_channels__discord__<alias>__interrupt_on_new_message=

zeroclaw config set channels.discord.<alias>.listen_to_bots <value>

export ZEROCLAW_channels__discord__<alias>__listen_to_bots=

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

export ZEROCLAW_channels__discord__<alias>__mention_only=

zeroclaw config set channels.discord.<alias>.multi_message_delay_ms <value>

export ZEROCLAW_channels__discord__<alias>__multi_message_delay_ms=

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

export ZEROCLAW_channels__discord__<alias>__proxy_url=

zeroclaw config set channels.discord.<alias>.reaction_notifications <value>

export ZEROCLAW_channels__discord__<alias>__reaction_notifications=

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

export ZEROCLAW_channels__discord__<alias>__reply_min_interval_secs=

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

export ZEROCLAW_channels__discord__<alias>__reply_queue_depth_max=

zeroclaw config set channels.discord.<alias>.slash_command_scope <value>

export ZEROCLAW_channels__discord__<alias>__slash_command_scope=

zeroclaw config set channels.discord.<alias>.slash_commands <value>

export ZEROCLAW_channels__discord__<alias>__slash_commands=

zeroclaw config set channels.discord.<alias>.stall_timeout_secs <value>

export ZEROCLAW_channels__discord__<alias>__stall_timeout_secs=

zeroclaw config set channels.discord.<alias>.stream_mode <value>

export ZEROCLAW_channels__discord__<alias>__stream_mode=

ボットがリッスンする範囲を絞り込む

デフォルトでは、ボットは招待されたすべてのサーバーと、表示できるすべてのチャンネルでリッスンします。範囲を絞り込むには:

• guild_ids: ボットを特定のサーバー（ギルド）に制限します。空の場合はすべてを対象とします。
• channel_ids: 特定のチャンネルに限定します。空の場合はすべての表示可能なチャンネルを対象とします。

IDを確認するには、Discordで開発者モードを有効にし（ユーザー設定 -> 詳細設定）、サーバーまたはチャンネルを右クリックしてIDをコピーしてください。

スレッドとコンテキスト

Discordでの会話がスレッド内で行われる場合、そのスレッドはそれ自体が独立した会話です。ZeroClawはスレッドごとに固有のセッションキーを生成するため、各スレッドは独立したコンテキストウィンドウと履歴を持ちます。あるスレッドのメッセージが別のスレッドに混入することはなく、エージェントが兄弟スレッドの過去のやり取りを参照することもありません。Discordの場合、スレッドはネイティブのチャネルであるため、各スレッドはすでに別々の会話として扱われます。設定すべきトグルはありません。

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

アーカイブと検索

archive = true を設定すると、チャンネルはサイドカーの discord.db メモリストアを開き、目にしたすべてのメッセージを記録し、エージェントが過去の会話を検索するために使用できる discord_search ツールを登録します。履歴検索が必要ない場合はオフのままにしておいてください。どちらの場合でもボットは通常どおり返信します。

ストリーミング

Discord は stream_mode 設定を通じて応答をストリーミングします:

• off（デフォルト）: エージェントの処理が完了すると、応答全体が1つのメッセージとして投稿されます。最もシンプルで、書きかけの回答が表示されることはありません。
• partial: ボットはすぐに下書きを投稿し、回答がストリーミングされるにつれてその場で編集します。draft_update_interval_ms は編集の間隔を調整します。Discord によるレート制限が発生する場合は値を大きくしてください。
• multi_message: 各段落が個別のメッセージとして投稿され、multi_message_delay_ms で区切られます。1つの長い文章の塊になってしまうような長い回答に適しています。

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

zeroclaw config set channels.discord.<alias>.stream_mode <value>

自然に感じられる返信

• mention_only: true の場合、ボットは自身を @-メンションしたメッセージにのみ応答するため、混雑したチャンネルでは静かなままになります。
• reply_min_interval_secs: 同じ相手への返信間隔の最小値。即座の応答が機械的に感じられる場合に役立ちます。

トラブルシューティング

Discordをプラグインとして実行する（実験的機能）

上記のすべては、ZeroClaw にコンパイルされている Discord チャネルを使用しています。Discord は、プラグインレジストリの discord パッケージとして、インストール可能な WASM チャネルプラグインとしても利用できます。このプラグインはプラグインサンドボックス内で実行され、許可したホストにのみアクセスできます。実験的な機能で、テキストメッセージのみを扱います。組み込みチャネルが引き続きデフォルトです。

各ボットトークンは、組み込みチャンネルかプラグインのどちらか一方にだけ割り当ててください。両方に割り当てると、Discord はトークンで行われた各接続にすべてのイベントを配信するため、両方が毎回のメッセージに応答してしまいます。ボットをプラグインに移す前に、そのボットの [channels.discord.<alias>] テーブルを削除してください。プラグインはこのテーブルを読み取りません。

必要なもの

• .wasm コンポーネントをコンパイルするプラグインホストを備えた zeroclaw バイナリ、つまり plugins-wasm-cranelift 機能を有効にしてビルドされたバイナリです（ビルド機能を参照）。プラグインホストを含まないバイナリには zeroclaw plugin コマンドが存在しません。zeroclaw plugin install は、何かをインストールする前に、パッケージがこのホストで読み込めるかどうかを確認します。
• クイックスタートで作成したボット: そのトークン、Message Content Intent を有効にしたもの、およびサーバーに招待済みのボット。
• Discord の非公開チャンネルでは、ボット（またはそのロール）に、そのチャンネルに対する View Channel、Send Messages、Read Message History の権限が必要です。ボットが閲覧できないチャンネルについては Discord からイベントが送られず、プラグインもそれに関するログを出力しません。そのため、ボットは正常に接続されているように見えても、メッセージを一切受信しません。channel_ids にボットが閲覧できないチャンネルが指定されている場合も同様です。
• エージェントと会話することを許可された各ユーザーの数値ユーザーID。開発者モードを有効にし（ユーザー設定 -> 詳細設定）、ユーザーを右クリックしてユーザーIDをコピーをクリックしてください。

1. パッケージをインストールし、インスタンスをバインドする

インスタンスのエイリアスを選択します。ここでは main とし、そのエイリアスに紐づけてパッケージをインストールしてください:

zeroclaw plugin install discord --channel-alias main --egress declared

このコマンドは、レジストリから discord をダウンロードして検証し、[channels.plugin.main] のバインディングを書き込んで、インスタンスの設定行を作成します。--egress declared は、パッケージが宣言するホストへのアクセスを許可します。REST API 用の discord.com と、ゲートウェイ WebSocket 用の *.discord.gg です。Discord はゲートウェイおよびリジューム用のホストをこのドメイン配下で割り当てるためです。代わりに --egress none を指定すると、アクセスを許可するまで、インスタンスはネットワークに一切到達できません。

もしパッケージが既にインストールされている場合は、エイリアスだけを単独で設定してください:

zeroclaw plugin bind discord --channel-alias main --egress declared

チャンネルインスタンスのバインドでは、両方のコマンドと、それらが出力するレポートについて説明しています。

インスタンスは、パッケージ、channel ケイパビリティ、エイリアスから導出されたキーの下に設定を保持します。エイリアス main のキーは zpi1_WyJkaXNjb3JkIiwiY2hhbm5lbCIsIm1haW4iXQ で、zeroclaw plugin info discord を実行すると、バインドされたすべてのエイリアスのキーが表示されます。

2. ボットトークンを設定

トークンは秘密情報です。値をコマンドラインに含めないでください。zeroclaw config set を実行するとプロンプトが表示され、入力内容は画面に表示されずに、暗号化されて保存されます:

zeroclaw config set plugins.entries.zpi1_WyJkaXNjb3JkIiwiY2hhbm5lbCIsIm1haW4iXQ.config.bot_token

もう一つの設定はトークンと同じ .config. の下に置かれ、任意です。guild_ids と channel_ids はボットが反応する場所を絞り込みます（Narrowing where the bot listens を参照）。mention_only と listen_to_bots は true または false を取ります。ZeroClaw はプラグインのすべての設定を暗号化して保存するため、zeroclaw config set はトークンと同様に各設定の入力を求めます。秘密ではない設定をコマンドラインで指定するには --no-interactive を渡してください。リストは JSON テキストとして設定します:

zeroclaw config set --no-interactive plugins.entries.zpi1_WyJkaXNjb3JkIiwiY2hhbm5lbCIsIm1haW4iXQ.config.channel_ids '["123456789012345678"]'

3. 有効にしてエージェントにルーティングする

バインディングはプラグインシステムを有効にせず、インスタンスをエージェントに割り当てもしません。プラグインシステムを有効にするには:

zeroclaw config set plugins.enabled true

次に、応答すべきエージェントの channels リストに plugin.main を追加します。既存のチャンネルはそのまま残し、同じチャンネル上の peer group でユーザーを許可します:

[agents.assistant]
channels = ["plugin.main"]

[peer_groups.discord_plugin]
channel = "plugin.main"
external_peers = ["111111111111111111"]

プラグインは送信者を数値のユーザーIDで報告し、プラグインチャネルは送信者を完全一致で照合します。そのため、ユーザー名ではなくユーザーIDを記載してください。インスタンスを起動するには、ZeroClawを再起動してください(zeroclaw service restart)。

4. 実行できることを確認する

• zeroclaw plugin info discord は、このホストでパッケージが読み込めるかどうかを報告し、インスタンスキーを表示し、起動前にインスタンスがまだ必要としている項目を一覧表示します。
• 起動時、デーモンのチャネル一覧には plugin.main が含まれ、ゲートウェイの /health スナップショットには channel:plugin.main コンポーネントが表示されます。このコンポーネントは、プラグインのポーリングが失敗すると error を示します。それ以外の場合は、プラグイン自身のヘルスチェックに従います。ZeroClawはこのヘルスチェックを約30秒ごとに要求します。そのチェックが何を確認するかはプラグインの実装次第です。そのため、ボットがDiscordに接続されていることの確かな証拠は、許可されたユーザーからのメッセージがエージェントに届き、エージェントの返信がDiscordに表示されることです。
• 許可されたユーザーからのメッセージは、zeroclaw.channel = plugin.main を付けて channel inbound message としてログに記録されます。それ以外のユーザーからのメッセージは破棄され、error_key = plugin_channel_sender_denied を付けてログに記録されます。
• 許可（grant）の範囲外にあるホストへの接続は拒否されます。拒否された HTTP リクエストは、error_key = plugin_egress_denied、拒否されたホスト、およびそれを許可する zeroclaw config set コマンドとともにログに記録されます。拒否されたゲートウェイ接続はまだログに記録されないため、egress_hosts を変更した後にボットがオフラインのままであれば、*.discord.gg が失われた可能性が高いです。

Plugin と組み込みチャネルの違い

会話はチャンネル名ごとに保持されるため、discord.main から plugin.main に移動されたボットは新しい会話を開始します。

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

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