OpenClaw Discord 連携：ボットセットアップと Gateway Intents の解説
OpenClaw 用 Discord ボットの作成、Gateway Intents の理解、DM セキュリティポリシーの設定、ギルドチャンネルのアクセス制御に関する完全ガイドです。
OpenClaw Guides
Tutorial Authors
概要
Discord 連携を使えば、Discord ボットを通じて OpenClaw とチャットできます。DM（ダイレクトメッセージ）とギルドテキストチャンネルの両方での通信に対応しています。このガイドでは、ボットの作成、Gateway Intents の理解、DM セキュリティポリシーの設定、ギルドチャンネルのアクセス制御について、OpenClaw 公式ドキュメントに基づいて解説します。
前提条件
- OpenClaw がインストール済みで実行中であること
- Discord アカウント
- 管理者権限を持つ Discord サーバー（テスト用）
仕組み
具体的な手順に入る前に、OpenClaw が Discord メッセージをどのようにルーティングするかを理解しておくと役立ちます。
- DM 会話はデフォルトでペアリングベースのセキュリティを使用し、共有セッション（
agent:main:main）に集約されます。 - ギルドチャンネル会話はチャンネルごとに分離され、
agent:<agentId>:discord:channel:<channelId>というパターンが使用されます。 - グループ DM はデフォルトで無視されますが、
channels.discord.dm.groupEnabledで有効化できます。
有効なトークンが存在し、enabled が false でない場合、ゲートウェイは自動的に起動します。
ステップ1：Discord アプリケーションを作成
Discord Developer Portal へ移動
- Discord Developer Portal にアクセス
- New Application をクリック
- 名前を入力（例："OpenClaw Assistant"）
- Create をクリック
ボットをセットアップ
- アプリケーションで Bot タブに移動
- Add Bot → Yes, do it! をクリック
- Token の下で Copy をクリックしてボットトークンをコピー
重要： ボットトークンはパスワードと同様に扱ってください。絶対に公開しないでください。漏洩した場合は直ちに再生成してください。
ステップ2：特権 Gateway Intents を有効化
Gateway Intents は、ボットが Discord から受信するイベントを制御します。OpenClaw が正しく動作するには、特定の特権 intents が必要です。
必要な Intents
| Intent | 用途 | 必須かどうか | |--------|------|-------------| | Message Content Intent | ギルドチャンネルでメッセージテキストを読み取る | 必須 — これがないと「Used disallowed intents」エラーが表示されるか、接続はできても応答に失敗します | | Server Members Intent | メンバー検索と許可リストのマッチング | 推奨 — 許可リストベースのアクセス制御に必要です |
Developer Portal で Intents を有効化
- Developer Portal の Bot タブに移動
- Privileged Gateway Intents までスクロール
- MESSAGE CONTENT INTENT を有効化（必須）
- SERVER MEMBERS INTENT を有効化（推奨）
- Save Changes をクリック
注意： 100以上のサーバーに参加しているボットは、特権 intents を使用するために Discord の検証が必要です。
ステップ3：ボット招待 URL を生成
OAuth2 を構成
-
OAuth2 → URL Generator に移動
-
スコープを選択：
botapplications.commands（ネイティブスラッシュコマンドに必須）
-
ボット権限を選択：
View ChannelsSend MessagesRead Message HistoryEmbed LinksAttach FilesAdd Reactions（任意だが推奨）Use External Emojis（任意）
警告： アクティブにデバッグしている場合を除き、Administrator 権限の付与は避けてください。必要最小限の権限のみを付与してください。
- 生成された URL をコピー
ボットを招待
- ブラウザで URL を開く
- テストサーバーを選択
- Authorize をクリック
数値 ID を取得
Discord の開発者モードを有効にしてください（ユーザー設定 → アプリの設定 → 詳細設定 → 開発者モード）。これにより、右クリックでギルド、チャンネル、ユーザーの ID をコピーできるようになります。設定で必要になります。
ステップ4：OpenClaw を設定
オプション A：環境変数
環境変数としてトークンを設定：
export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
オプション B：設定ファイル
OpenClaw の設定ファイルにトークンを直接記述：
{
channels: {
discord: {
enabled: true,
token: "YOUR_BOT_TOKEN"
}
}
}
注意： 環境変数と設定ファイルの両方にトークンが存在する場合、設定ファイルが優先されます。
オプション C：マルチアカウント対応
複数のボットアカウントを運用する場合：
{
channels: {
discord: {
accounts: [
{ token: "BOT_TOKEN_1", name: "assistant-1" },
{ token: "BOT_TOKEN_2", name: "assistant-2" }
]
}
}
}
ステップ5：起動とテスト
OpenClaw ゲートウェイを起動または再起動：
openclaw gateway restart
チャンネルの状態を確認：
openclaw channels status --probe
問題がありそうな場合は診断を実行：
openclaw doctor
初回の DM 接触では、ボットはデフォルトでペアリングシステムを使用します。送信者は時間制限付きコード（1時間で期限切れ）を受け取り、会話を開始するにはそのコードを承認する必要があります。
DM セキュリティポリシー
OpenClaw には3つの DM アクセス制御ポリシーがあります。
ペアリング（デフォルト）
未知の送信者は、1時間で期限切れとなる時間制限付きペアリングコードを受け取ります。会話を進めるにはコードの承認が必要です。
{
channels: {
discord: {
dm: {
enabled: true,
policy: "pairing"
}
}
}
}
許可リスト
設定されたユーザー ID またはユーザー名のみが DM を送信できます：
{
channels: {
discord: {
dm: {
enabled: true,
policy: "allowlist",
allowFrom: ["123456789012345678", "username#1234"]
}
}
}
}
オープン
誰でも DM を送信できます（注意して使用してください）：
{
channels: {
discord: {
dm: {
enabled: true,
policy: "open",
allowFrom: ["*"]
}
}
}
}
ギルドチャンネルの設定
基本的なギルドアクセス制御
メンション要件付きで、ボットを特定のギルドおよびチャンネルに制限：
{
channels: {
discord: {
guilds: {
"GUILD_ID": {
requireMention: true,
channels: {
"CHANNEL_ID": {
enabled: true
}
}
}
}
}
}
}
重要：
requireMentionはギルドまたはチャンネルレベルで設定する必要があります。Discord 設定のトップレベルではありません。
チャンネルごとの設定
チャンネルごとに許可リストやスキル制限を設定できます：
{
channels: {
discord: {
guilds: {
"GUILD_ID": {
channels: {
"CHANNEL_ID_1": {
enabled: true,
requireMention: true
},
"CHANNEL_ID_2": {
enabled: true,
requireMention: false
}
}
}
}
}
}
}
設定パラメータ
メッセージ設定
| パラメータ | デフォルト | 説明 |
|-----------|-----------|------|
| textChunkLimit | 2000 | 送信メッセージチャンクあたりの最大文字数 |
| chunkMode | — | 長さ制限を適用する前に空行（段落境界）で分割する設定 |
| maxLinesPerMessage | 17 | メッセージあたりの最大行数 |
| mediaMaxMb | 8 | メディアファイルの最大サイズ（MB） |
コンテキスト履歴
{
channels: {
discord: {
historyLimit: 20 // コンテキストとして含める最近のメッセージ数（デフォルト: 20、0で無効化）
}
}
}
リプライスレッド
ネイティブリプライスレッドはデフォルトで無効です。以下で有効化できます：
{
channels: {
discord: {
replyToMode: "on" // ネイティブリプライスレッドを有効化
}
}
}
エージェントの応答でリプライタグを使用してスレッド動作を制御できます：
[[reply_to_current]]— 処理中のメッセージに返信[[reply_to:<message_id>]]— 特定のメッセージに返信
リアクション通知
ギルドごとにリアクションイベント通知を設定：
{
channels: {
discord: {
guilds: {
"GUILD_ID": {
reactionNotifications: "own" // オプション: "off", "own", "all", "allowlist"
}
}
}
}
}
ツールアクション
エージェントは discord ツールを呼び出して Discord 内でアクションを実行できます。ほとんどのアクションはデフォルトで有効ですが、ロールとモデレーションはデフォルトで無効です。
利用可能なアクション
| カテゴリ | アクション | |---------|----------| | リアクション | react, sticker, poll | | メッセージ | readMessages, sendMessage, editMessage, deleteMessage, searchMessages | | スレッド | threadCreate, threadList, threadReply | | ピン | pinMessage, unpinMessage, listPins | | チャンネル | channelInfo, channelList | | メンバー | memberInfo, roleInfo, permissions | | ロール | roleAdd, roleRemove（デフォルトで無効） | | モデレーション | timeout, kick, ban（デフォルトで無効） | | その他 | emojiList, voiceStatus, eventList, eventCreate, setPresence |
高度な機能
PluralKit サポート
有効にすると、OpenClaw はプロキシされたメッセージを元のシステムメンバーに解決し、送信者を「Member (PK:System)」と表示して、意図しない Discord へのメンションを防止します。
実行承認ボタン UI
DM 会話では、OpenClaw はツールアクションの対話的な確認のために実行承認ボタンを表示できます。
リトライ設定
送信 API 呼び出しは、Discord の retry_after ヘッダーを使用した指数バックオフにより、レート制限時に自動的にリトライされます。リトライの動作は channels.discord.retry パラメータで設定できます。
トラブルシューティング
ボットはオンラインだが応答しない
-
Message Content Intent を確認： この intent がないと、ボットは接続できてもメッセージテキストを読み取れません。Developer Portal → Bot → Privileged Gateway Intents で MESSAGE CONTENT INTENT が有効になっていることを確認してください。
-
チャンネル権限を確認： 対象チャンネルでボットに View Channels と Send Messages の権限があることを確認してください。
-
メンション要件を確認： ギルドまたはチャンネルで
requireMentionが有効になっている場合は、ボットを @メンションする必要があります。 -
ギルド/チャンネル許可リストを確認： チャンネルが許可リストの設定でブロックされていないことを確認してください。
"Used Disallowed Intents" エラー
これは、必要な intents が Developer Portal で有効化されていないことを意味します：
- Developer Portal → Bot → Privileged Gateway Intents に移動
- MESSAGE CONTENT INTENT を有効化
- 保存して OpenClaw ゲートウェイを再起動
DM が動作しない
dm.enabledがfalseに設定されていないことを確認- DM ポリシーを確認 — "allowlist" に設定されている場合、ユーザー ID が含まれていることを確認
- "pairing" ポリシーを使用している場合、ペアリングコードが期限切れになっていないか確認（制限時間は1時間）
診断コマンド
組み込みの診断ツールを使用して問題を特定：
# 完全な診断を実行 openclaw doctor # 接続プローブ付きでチャンネル状態を確認 openclaw channels status --probe
ベストプラクティス
- ボットトークンはパスワードとして扱う — 管理されたホストでは環境変数を使用し、トークンをソースコントロールにコミットしないでください。
- 必要な権限のみを付与 — アクティブにデバッグしている場合を除き、Administrator 権限は避けてください。
- ペアリングまたは許可リストの DM ポリシーを使用 — "open" ポリシーは、適切なレート制限が設定された公開ボットのみに使用してください。
- 許可リストベースのアクセス制御を使用する場合は Server Members Intent を有効化 — より信頼性の高いメンバーマッチングが可能になります。
- 活発なギルドでは
requireMentionを使用 — ボットがすべてのメッセージに応答するのを防ぎます。 - ゲートウェイがスタックした場合は
--forceで再起動：openclaw gateway restart --force。