Discord セットアップ
Discord Bot セットアップガイド¶
MarionetteとDiscordを連携するには、Discord Developer Portalでアプリケーションを作成し、Bot Tokenを取得する必要があります。
このページでは、その手順を最初から説明します。
1. Discord Developer Portal にアクセス¶
Discord Developer Portal にアクセスし、Discordアカウントでログインしてください。
2. アプリケーションを作成¶
- 右上の 「New Application」 ボタンをクリック
- アプリケーション名を入力（例:
Marionette Bot） - 利用規約に同意し、「Create」 をクリック
作成後、アプリケーションの General Information ページが表示されます。
Application ID を控える¶
General Information ページの Application ID をコピーしてください。
これが Marionette の設定画面で入力する Application ID です。
Public Key について
同じページに Public Key も表示されていますが、Marionette の Discord 連携では不要です。
Application ID のみ控えてください。
3. Bot を作成して Token を取得¶
- 左メニューの 「Bot」 をクリック
- 「Reset Token」 ボタンをクリック（初回は「Add Bot」の場合もあります）
- 表示された Token をコピーしてください
Token の取り扱い
Bot Tokenは**パスワードと同等の機密情報**です。
他人に共有したり、Git にコミットしたりしないでください。
Tokenが漏洩した場合は、即座に「Reset Token」で再生成してください。
Bot の設定¶
同じ Bot ページで、以下の設定を行います:
- Privileged Gateway Intents のセクションで、以下を ON にしてください:
- Message Content Intent -- メッセージ内容の取得に必須
- Server Members Intent -- メンバー情報の取得に必要（Bot一覧表示等）
Intents について
Message Content Intent が OFF のままだと、Botがメッセージの中身を読み取れません。
必ず ON にしてください。
4. Bot をサーバーに招待¶
- 左メニューの 「OAuth2」 をクリック
- 「OAuth2 URL Generator」 セクションで以下を設定:
- SCOPES:
botにチェック - BOT PERMISSIONS: 以下にチェック
- Send Messages
- Read Message History
- View Channels
- Use Slash Commands
- SCOPES:
- 生成された URL をコピーしてブラウザで開く
- Botを追加したいサーバーを選択し、「認証」 をクリック
5. Marionette に設定を入力¶
管理画面の左メニュー 「外部連携」→「Bot管理」 を開き、Discordを選択します。
接続設定¶
| 項目 | 入力する値 |
|---|---|
| Bot Token | 手順3で取得したToken |
| Application ID | 手順2で控えたApplication ID |
入力後、「設定保存」 をクリックしてから 「接続」 ボタンを押してください。
ステータスが「接続中」に変われば成功です。
スラッシュコマンド (/marionette)¶
接続設定で 「スラッシュコマンド (/marionette)」 のチェックを有効にすると、Discord上で以下のコマンドが利用可能になります。
| コマンド | 説明 | 使い方 |
|---|---|---|
| reset-session | 会話履歴をリセットして新しいセッションを開始 | /marionette reset-session rule:<ルール名> |
| set-state | stateの値を更新 | /marionette set-state rule:<ルール名> state_name:<state名> value:<値> |
| get-state | stateの値を表示 | /marionette get-state rule:<ルール名> state_name:<state名> |
| list-state | state名の一覧を表示 | /marionette list-state rule:<ルール名> |
ruleにはルーティングルール名を指定します（オートコンプリート対応）set-stateのvalueは JSON 形式（例:"hello"や{"key": 123}）で指定できますget-state/list-stateは、該当ルールでセッションが開始されている場合のみ利用可能です
ルーティングルールの設定¶
接続後、「ルール追加」 でルーティングルールを作成します。
基本的なルール例: メンションで会話¶
| 設定項目 | 値 |
|---|---|
| ルール名 | メンション応答 |
| トリガータイプ | mention |
| チャンネル | 全チャンネル |
| Drama | 使用したいDramaを選択 |
| 優先度 | 50 |
この設定で、Discordサーバー内のどのチャンネルでも @Bot名 こんにちは のようにメンションすると、選択したDramaが応答します。
キーワード検知の例¶
| 設定項目 | 値 |
|---|---|
| ルール名 | 困りごと検知 |
| トリガータイプ | keyword |
| キーワード | 困った, 助けて, help |
| チャンネル | 全チャンネル |
| Drama | ヘルプ用Dramaを選択 |
| 優先度 | 10（mentionより先に評価される） |
6. 動作確認¶
- Discordサーバーのテキストチャンネルで
@Bot名 こんにちはとメンション - Botが応答すれば成功
- Botの返答に**リプライ**することで会話を継続できます
トリガータイプ一覧¶
| タイプ | 説明 | 会話の継続方法 |
|---|---|---|
| mention | Botがメンションされた時に反応 | Botの返答にリプライ |
| keyword | 特定キーワードを含む発言に反応（mentionと同じ扱い） | Botの返答にリプライ |
| dm | ダイレクトメッセージに反応（1対1 / グループDM） | DM内で自動継続 |
| slash_command | スラッシュコマンド /marionette の実行に反応 | コマンド実行ごとに新規トリガー |
| bot_message | 他のBotの発言に反応（AI同士の対話用） | Botの返答にリプライ |
変数マッピングについて¶
各ルールで、Discord側の情報をDrama内の data や states に渡すことができます。
設定例¶
| Discord変数 | dataに追加 | statesに追加 |
|---|---|---|
user.display_name | user_name | |
message.content | user_message | |
channel.members | participants |
- dataに追加:
event.triggerのmessage_dataとしてDramaに渡されます。Dramaのdata変数でアクセスできます。 - statesに追加: セッション開始時に
state.setとして設定されます。Dramaのstates変数でアクセスできます。
利用可能なDiscord変数¶
| 変数名 | 型 | 説明 |
|---|---|---|
user.id | string | DiscordユーザーID |
user.name | string | ユーザー名 |
user.display_name | string | サーバー表示名（ニックネーム） |
user.avatar_url | string | アバター画像URL |
user.roles | string[] | ロール名の配列 |
user.is_bot | bool | Botかどうか |
user.joined_at | string | サーバー参加日時 |
message.content | string | メッセージ本文 |
message.id | string | メッセージID |
message.attachments | object[] | 添付ファイル情報 |
message.timestamp | string | 送信日時 |
channel.id | string | チャンネルID |
channel.name | string | チャンネル名 |
channel.type | string | text / dm / group_dm |
channel.topic | string | チャンネルトピック |
channel.members | object[] | 参加メンバー一覧（DM/グループDM） |
channel.member_count | int | メンバー数 |
guild.id | string | サーバーID |
guild.name | string | サーバー名 |
guild.member_count | int | サーバー総メンバー数 |
Bot発言への応答（AI同士の対話）¶
bot_message トリガーを使うと、他のBotの発言に反応できます。
無限ループ防止のため、以下の安全装置を設定してください:
| 設定項目 | 推奨値 | 説明 |
|---|---|---|
| 応答確率 | 70% | 毎回反応せず、確率的にスキップ |
| 最大ターン数 | 50 | 1セッションあたりの上限 |
| 応答間隔 | 3秒 | 連続応答の防止 |
トラブルシューティング¶
Botが応答しない¶
- 接続状態を確認: 管理画面で「接続中」になっているか
- Message Content Intent: Discord Developer Portalで ON になっているか
- ルールの確認: 有効なルールが存在し、Drama が設定されているか
- チャンネル権限: Botにそのチャンネルでのメッセージ送信権限があるか
Token が無効¶
- Discord Developer Portal で Token を再生成し、再入力してください
- Token の前後に余分な空白が入っていないか確認してください
「discord.py is required」エラー¶
サーバー環境に discord.py がインストールされていません: