Discord

​

クイックセットアップ

openclaw config set channels.discord.token '"YOUR_BOT_TOKEN"' --json
openclaw config set channels.discord.enabled true --json
openclaw gateway

{
  channels: {
    discord: {
      enabled: true,
      token: "YOUR_BOT_TOKEN",
    },
  },
}

DISCORD_BOT_TOKEN=...

openclaw pairing list discord
openclaw pairing approve discord <CODE>

​

推奨: ギルドワークスペースを用意する

{
  channels: {
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        YOUR_SERVER_ID: {
          requireMention: true,
          users: ["YOUR_USER_ID"],
        },
      },
    },
  },
}

{
  channels: {
    discord: {
      guilds: {
        YOUR_SERVER_ID: {
          requireMention: false,
        },
      },
    },
  },
}

​

ランタイムモデル

• ゲートウェイが Discord 接続を保持します。
• 応答ルーティングは決定的です。Discord から入った返信は Discord に返ります。
• デフォルトでは（session.dmScope=main）、DM はエージェントのメインセッション（agent:main:main）を共有します。
• ギルドチャンネルは独立したセッションキー（agent:<agentId>:discord:channel:<channelId>）として扱われます。
• グループ DM はデフォルトで無視されます（channels.discord.dm.groupEnabled=false）。
• ネイティブスラッシュコマンドは独立したコマンドセッション（agent:<agentId>:discord:slash:<userId>）で実行されますが、ルーティング先の会話セッションに対する CommandTargetSessionKey は保持されます。

​

フォーラムチャンネル

• forum 親（channel:<forumId>）にメッセージを送信してスレッドを自動作成する
• openclaw message thread create でスレッドを直接作成する。forum チャンネルでは --message-id を渡さないでください

openclaw message send --channel discord --target channel:<forumId> \
  --message "Topic title\nBody of the post"

openclaw message thread create --channel discord --target channel:<forumId> \
  --thread-name "Topic title" --message "Body of the post"

​

インタラクティブコンポーネント

• text、section、separator、actions、media-gallery、file
• action row では最大 5 個のボタン、または 1 個の select menu を使用できます
• select の型は string、user、role、mentionable、channel です

• file ブロックは、添付参照（attachment://<filename>）を指している必要があります
• 添付ファイルは media / path / filePath（単一ファイル）で渡します。複数ファイルには media-gallery を使用してください
• 添付参照名とアップロード名を一致させたい場合は、filename でアップロード名を上書きします

• 最大 5 フィールドまで持てる components.modal を追加できます
• フィールド型は text、checkbox、radio、select、role-select、user-select です
• OpenClaw がトリガーボタンを自動で追加します

{
  channel: "discord",
  action: "send",
  to: "channel:123456789012345678",
  message: "Optional fallback text",
  components: {
    reusable: true,
    text: "Choose a path",
    blocks: [
      {
        type: "actions",
        buttons: [
          {
            label: "Approve",
            style: "success",
            allowedUsers: ["123456789012345678"],
          },
          { label: "Decline", style: "danger" },
        ],
      },
      {
        type: "actions",
        select: {
          type: "string",
          placeholder: "Pick an option",
          options: [
            { label: "Option A", value: "a" },
            { label: "Option B", value: "b" },
          ],
        },
      },
    ],
    modal: {
      title: "Details",
      triggerLabel: "Open form",
      fields: [
        { type: "text", label: "Requester" },
        {
          type: "select",
          label: "Priority",
          options: [
            { label: "Low", value: "low" },
            { label: "High", value: "high" },
          ],
        },
      ],
    },
  },
}

​

アクセス制御とルーティング

{
  channels: {
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        "123456789012345678": {
          requireMention: true,
          ignoreOtherMentions: true,
          users: ["987654321098765432"],
          roles: ["123456789012345678"],
          channels: {
            general: { allow: true },
            help: { allow: true, requireMention: true },
          },
        },
      },
    },
  },
}

​

ロールベースのエージェントルーティング

{
  bindings: [
    {
      agentId: "opus",
      match: {
        channel: "discord",
        guildId: "123456789012345678",
        roles: ["111111111111111111"],
      },
    },
    {
      agentId: "sonnet",
      match: {
        channel: "discord",
        guildId: "123456789012345678",
      },
    },
  ],
}

​

Developer Portal の設定

​

ネイティブコマンドとコマンド認可

• commands.native のデフォルトは "auto" で、Discord では有効になります
• チャンネル単位の上書きは channels.discord.commands.native です
• commands.native=false を指定すると、以前に登録された Discord ネイティブコマンドを明示的に削除します
• ネイティブコマンドの認可には、通常メッセージ処理と同じ Discord allowlist / policy が使われます
• 権限のないユーザーにも Discord UI 上でコマンドが見えることがありますが、実行時には OpenClaw の認可が適用され、“not authorized” が返ります

• ephemeral: true

​

機能の詳細

{
  channels: {
    discord: {
      streaming: "partial",
    },
  },
}

{
  channels: {
    discord: {
      streaming: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph",
      },
    },
  },
}

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // opt-in
      },
    },
  },
}

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "discord",
        accountId: "default",
        peer: { kind: "channel", id: "222222222222222222" },
      },
      acp: { label: "codex-main" },
    },
  ],
  channels: {
    discord: {
      guilds: {
        "111111111111111111": {
          channels: {
            "222222222222222222": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}

{
  channels: {
    discord: {
      configWrites: false,
    },
  },
}

{
  channels: {
    discord: {
      proxy: "http://proxy.example:8080",
    },
  },
}

{
  channels: {
    discord: {
      accounts: {
        primary: {
          proxy: "http://proxy.example:8080",
        },
      },
    },
  },
}

{
  channels: {
    discord: {
      pluralkit: {
        enabled: true,
        token: "pk_live_...", // optional; needed for private systems
      },
    },
  },
}

{
  channels: {
    discord: {
      status: "idle",
    },
  },
}

{
  channels: {
    discord: {
      activity: "Focus time",
      activityType: 4,
    },
  },
}

{
  channels: {
    discord: {
      activity: "Live coding",
      activityType: 1,
      activityUrl: "https://twitch.tv/openclaw",
    },
  },
}

{
  channels: {
    discord: {
      autoPresence: {
        enabled: true,
        intervalMs: 30000,
        minUpdateIntervalMs: 15000,
        exhaustedText: "token exhausted",
      },
    },
  },
}

​

ツールとアクションゲート

• messaging: sendMessage、readMessages、editMessage、deleteMessage、threadReply
• reactions: react、reactions、emojiList
• moderation: timeout、kick、ban
• presence: setPresence

​

コンポーネント v2 UI

• channels.discord.ui.components.accentColor は、Discord component container で使用するアクセントカラー（16 進数）を設定します
• アカウント単位では channels.discord.accounts.<id>.ui.components.accentColor で設定します
• components v2 が存在する場合、embeds は無視されます

{
  channels: {
    discord: {
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
    },
  },
}

​

音声チャンネル

• ネイティブコマンド（commands.native または channels.discord.commands.native）を有効にする
• channels.discord.voice を設定する
• ボットに対象音声チャンネルでの Connect と Speak 権限を付与する

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
    },
  },
}

• voice.tts は音声再生に限って messages.tts を上書きします
• 音声 transcript turn の owner 判定は Discord の allowFrom（または dm.allowFrom）から導かれます。owner でない発話者は、gateway や cron などの owner 限定ツールにアクセスできません
• 音声機能はデフォルトで有効です。無効化するには channels.discord.voice.enabled=false を設定します
• voice.daveEncryption と voice.decryptionFailureTolerance は @discordjs/voice の join option にそのまま渡されます
• @discordjs/voice 側のデフォルトは、未設定時に daveEncryption=true および decryptionFailureTolerance=24 です
• OpenClaw は受信時の復号失敗も監視し、短時間に繰り返し失敗した場合は音声チャンネルから一度離脱して再参加することで自動回復を試みます
• 受信ログに DecryptionFailed(UnencryptedWhenPassthroughDisabled) が繰り返し出る場合は、上流の @discordjs/voice 受信バグである discord.js #11419 に該当している可能性があります

​

音声メッセージ

• ローカルファイルパス を指定してください（URL は拒否されます）
• テキスト本文は省略してください（Discord は同じペイロード内でテキストと音声メッセージを同時に送れません）
• 音声形式は任意です。必要に応じて OpenClaw が OGG/Opus に変換します

message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true)

​

トラブルシューティング

openclaw doctor
openclaw channels status --probe
openclaw logs --follow

{
  channels: {
    discord: {
      accounts: {
        default: {
          eventQueue: {
            listenerTimeout: 120000,
          },
          inboundWorker: {
            runTimeoutMs: 1800000,
          },
        },
      },
    },
  },
}

​

設定リファレンスの参照先

• Configuration reference - Discord

• 起動 / 認可: enabled、token、accounts.*、allowBots
• policy: groupPolicy、dm.*、guilds.*、guilds.*.channels.*
• command: commands.native、commands.useAccessGroups、configWrites、slashCommand.*
• event queue: eventQueue.listenerTimeout（listener budget）、eventQueue.maxQueueSize、eventQueue.maxConcurrency
• inbound worker: inboundWorker.runTimeoutMs
• reply / history: replyToMode、historyLimit、dmHistoryLimit、dms.*.historyLimit
• delivery: textChunkLimit、chunkMode、maxLinesPerMessage
• streaming: streaming（旧エイリアス: streamMode）、draftChunk、blockStreaming、blockStreamingCoalesce
• media / retry: mediaMaxMb、retry
  • mediaMaxMb は Discord への送信アップロード上限です（デフォルト: 8MB）
• actions: actions.*
• presence: activity、status、activityType、activityUrl
• UI: ui.components.accentColor
• features: threadBindings、トップレベルの bindings[]（type: "acp"）、pluralkit、execApprovals、intents、agentComponents、heartbeat、responsePrefix

​

セーフティと運用

• ボットトークンは機密情報として扱ってください（監視付き環境では DISCORD_BOT_TOKEN を推奨します）
• Discord 権限は最小権限で付与してください
• コマンドの deploy 状態や反映状態が古い場合は、ゲートウェイを再起動し、openclaw channels status --probe で再確認してください

​

関連

• Pairing
• Channel routing
• Multi-agent routing
• Troubleshooting
• Slash commands