​

Discord (Bot API)

​

Thiết lập nhanh

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set channels.discord.enabled true --strict-json
openclaw gateway

{
  channels: {
    discord: {
      enabled: true,
      token: {
        source: "env",
        provider: "default",
        id: "DISCORD_BOT_TOKEN",
      },
    },
  },
}

DISCORD_BOT_TOKEN=...

openclaw pairing list discord
openclaw pairing approve discord <CODE>

​

Khuyến nghị: Thiết lập workspace guild

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

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

​

Mô hình runtime

• Gateway sở hữu kết nối Discord.
• Định tuyến phản hồi là xác định: Discord inbound phản hồi lại Discord.
• Theo mặc định (session.dmScope=main), các cuộc trò chuyện trực tiếp chia sẻ phiên chính của agent (agent:main:main).
• Các kênh guild là khóa phiên riêng biệt (agent:<agentId>:discord:channel:<channelId>).
• Group DMs bị bỏ qua theo mặc định (channels.discord.dm.groupEnabled=false).
• Lệnh slash gốc chạy trong các phiên lệnh riêng biệt (agent:<agentId>:discord:slash:<userId>), trong khi vẫn mang CommandTargetSessionKey đến phiên trò chuyện được định tuyến.

​

Kênh diễn đàn

• Gửi tin nhắn đến cha diễn đàn (channel:<forumId>) để tự động tạo chủ đề. Tiêu đề chủ đề sử dụng dòng không rỗng đầu tiên của tin nhắn của bạn.
• Sử dụng openclaw message thread create để tạo chủ đề trực tiếp. Không truyền --message-id cho các kênh diễn đàn.

openclaw message send --channel discord --target channel:<forumId> \
  --message "Tiêu đề chủ đề\nNội dung bài đăng"

openclaw message thread create --channel discord --target channel:<forumId> \
  --thread-name "Tiêu đề chủ đề" --message "Nội dung bài đăng"

​

Thành phần tương tác

• text, section, separator, actions, media-gallery, file
• Hàng hành động cho phép tối đa 5 nút hoặc một menu chọn đơn
• Các loại chọn: string, user, role, mentionable, channel

• Các khối file phải trỏ đến tham chiếu đính kèm (attachment://<filename>)
• Cung cấp đính kèm qua media/path/filePath (tệp đơn); sử dụng media-gallery cho nhiều tệp
• Sử dụng filename để ghi đè tên tải lên khi nó nên khớp với tham chiếu đính kèm

• Thêm components.modal với tối đa 5 trường
• Các loại trường: text, checkbox, radio, select, role-select, user-select
• OpenClaw tự động thêm nút kích hoạt

{
  channel: "discord",
  action: "send",
  to: "channel:123456789012345678",
  message: "Văn bản dự phòng tùy chọn",
  components: {
    reusable: true,
    text: "Chọn một đường dẫn",
    blocks: [
      {
        type: "actions",
        buttons: [
          {
            label: "Phê duyệt",
            style: "success",
            allowedUsers: ["123456789012345678"],
          },
          { label: "Từ chối", style: "danger" },
        ],
      },
      {
        type: "actions",
        select: {
          type: "string",
          placeholder: "Chọn một tùy chọn",
          options: [
            { label: "Tùy chọn A", value: "a" },
            { label: "Tùy chọn B", value: "b" },
          ],
        },
      },
    ],
    modal: {
      title: "Chi tiết",
      triggerLabel: "Mở biểu mẫu",
      fields: [
        { type: "text", label: "Người yêu cầu" },
        {
          type: "select",
          label: "Ưu tiên",
          options: [
            { label: "Thấp", value: "low" },
            { label: "Cao", value: "high" },
          ],
        },
      ],
    },
  },
}

​

Kiểm soát truy cập và định tuyến

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

​

Định tuyến agent dựa trên vai trò

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

​

Thiết lập Developer Portal

​

Lệnh gốc và xác thực lệnh

• commands.native mặc định là "auto" và được kích hoạt cho Discord.
• Ghi đè theo kênh: channels.discord.commands.native.
• commands.native=false rõ ràng xóa các lệnh gốc Discord đã đăng ký trước đó.
• Xác thực lệnh gốc sử dụng cùng danh sách cho phép/chính sách Discord như xử lý tin nhắn bình thường.
• Lệnh có thể vẫn hiển thị trong giao diện Discord cho người dùng không được ủy quyền; thực thi vẫn thực thi xác thực OpenClaw và trả về “không được ủy quyền”.

• ephemeral: true

​

Chi tiết tính năng

{
  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_...", // tùy chọn; cần thiết cho các hệ thống riêng tư
      },
    },
  },
}

{
  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",
      },
    },
  },
}

​

Công cụ và cổng hành động

• nhắn tin: sendMessage, readMessages, editMessage, deleteMessage, threadReply
• phản ứng: react, reactions, emojiList
• kiểm duyệt: timeout, kick, ban
• hiện diện: setPresence

​

Giao diện Components v2

• channels.discord.ui.components.accentColor đặt màu nhấn được sử dụng bởi các container thành phần Discord (hex).
• Đặt theo tài khoản với channels.discord.accounts.<id>.ui.components.accentColor.
• embeds bị bỏ qua khi các thành phần v2 có mặt.

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

​

Kênh giọng nói

• Kích hoạt lệnh gốc (commands.native hoặc channels.discord.commands.native).
• Cấu hình channels.discord.voice.
• Bot cần quyền Kết nối + Nói trong kênh giọng nói mục tiêu.

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

• voice.tts ghi đè messages.tts chỉ cho phát lại giọng nói.
• Bản ghi giọng nói xác định trạng thái chủ sở hữu từ Discord allowFrom (hoặc dm.allowFrom); người nói không phải chủ sở hữu không thể truy cập các công cụ chỉ dành cho chủ sở hữu (ví dụ: gateway và cron).
• Giọng nói được bật theo mặc định; đặt channels.discord.voice.enabled=false để vô hiệu hóa nó.
• voice.daveEncryption và voice.decryptionFailureTolerance truyền qua các tùy chọn tham gia @discordjs/voice.
• Mặc định của @discordjs/voice là daveEncryption=true và decryptionFailureTolerance=24 nếu không được đặt.
• OpenClaw cũng theo dõi các lỗi giải mã nhận và tự động khôi phục bằng cách rời khỏi/tham gia lại kênh giọng nói sau khi gặp lỗi lặp lại trong một khoảng thời gian ngắn.
• Nếu nhật ký nhận liên tục hiển thị DecryptionFailed(UnencryptedWhenPassthroughDisabled), đây có thể là lỗi nhận @discordjs/voice upstream được theo dõi trong discord.js #11419.

​

Tin nhắn giọng nói

• Cung cấp đường dẫn tệp cục bộ (URL bị từ chối).
• Bỏ qua nội dung văn bản (Discord không cho phép văn bản + tin nhắn giọng nói trong cùng một payload).
• Bất kỳ định dạng âm thanh nào đều được chấp nhận; OpenClaw chuyển đổi sang OGG/Opus khi cần.

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

​

Khắc phục sự cố

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

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

​

Tham chiếu cấu hình

• Tham chiếu cấu hình - Discord

• khởi động/xác thực: enabled, token, accounts.*, allowBots
• chính sách: groupPolicy, dm.*, guilds.*, guilds.*.channels.*
• lệnh: commands.native, commands.useAccessGroups, configWrites, slashCommand.*
• hàng đợi sự kiện: eventQueue.listenerTimeout (ngân sách listener), eventQueue.maxQueueSize, eventQueue.maxConcurrency
• worker inbound: inboundWorker.runTimeoutMs
• trả lời/lịch sử: replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
• giao hàng: textChunkLimit, chunkMode, maxLinesPerMessage
• phát trực tiếp: streaming (bí danh cũ: streamMode), draftChunk, blockStreaming, blockStreamingCoalesce
• phương tiện/lặp lại: mediaMaxMb, retry
  • mediaMaxMb giới hạn tải lên Discord outbound (mặc định: 8MB)
• hành động: actions.*
• hiện diện: activity, status, activityType, activityUrl
• giao diện người dùng: ui.components.accentColor
• tính năng: threadBindings, bindings[] cấp cao nhất (type: "acp"), pluralkit, execApprovals, intents, agentComponents, heartbeat, responsePrefix

​

An toàn và hoạt động

• Xem token bot như bí mật (DISCORD_BOT_TOKEN được ưu tiên trong môi trường giám sát).
• Cấp quyền Discord ít nhất.
• Nếu triển khai/trạng thái lệnh bị lỗi thời, khởi động lại gateway và kiểm tra lại với openclaw channels status --probe.

​

Liên quan

• Ghép nối
• Định tuyến kênh
• Định tuyến đa agent
• Khắc phục sự cố
• Lệnh Slash