Discord (Bot API)

Trạng thái: sẵn sàng cho DM và guild text channel thông qua Discord bot gateway chính thức.

Cài đặt nhanh (dành cho người mới)

Tạo Discord bot và copy bot token.
Trong cài đặt Discord app, bật Message Content Intent (và Server Members Intent nếu các bạn dự định dùng allowlist hoặc tra cứu tên).
Đặt token cho OpenClaw:
- Env: DISCORD_BOT_TOKEN=...
- Hoặc config: channels.discord.token: "...".
- Nếu đặt cả hai, config sẽ được ưu tiên (env fallback chỉ dành cho default-account).
Mời bot vào server với quyền gửi tin nhắn (tạo private server nếu các bạn chỉ muốn dùng DM).
Khởi động Gateway.
Truy cập DM mặc định là pairing; phê duyệt pairing code khi liên hệ lần đầu.

Config tối thiểu:

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

Mục tiêu

Trò chuyện với OpenClaw qua Discord DM hoặc guild channel.
Chat trực tiếp sẽ gộp vào session chính của Agent (mặc định agent:main:main); guild channel được tách riêng thành agent:<agentId>:discord:channel:<channelId> (tên hiển thị dùng discord:<guildSlug>#<channelSlug>).
Group DM bị bỏ qua mặc định; bật qua channels.discord.dm.groupEnabled và tùy chọn giới hạn bằng channels.discord.dm.groupChannels.
Giữ routing xác định: phản hồi luôn quay về channel mà tin nhắn đến.

Cách hoạt động

Tạo Discord application → Bot, bật các intent cần thiết (DM + guild messages + message content), và lấy bot token.
Mời bot vào server với quyền cần thiết để đọc/gửi tin nhắn ở nơi các bạn muốn dùng.
Cấu hình OpenClaw với channels.discord.token (hoặc DISCORD_BOT_TOKEN làm fallback).
Chạy Gateway; nó sẽ tự động khởi động Discord channel khi có token (config trước, env fallback) và channels.discord.enabled không phải false.
- Nếu các bạn thích dùng env var, đặt DISCORD_BOT_TOKEN (config block là tùy chọn).
Chat trực tiếp: dùng user:<id> (hoặc mention <@id>) khi gửi; tất cả lượt chat sẽ vào session main chung. ID số thuần túy sẽ bị từ chối vì không rõ ràng.
Guild channel: dùng channel:<channelId> để gửi. Mention được yêu cầu mặc định và có thể đặt theo từng guild hoặc từng channel.
Chat trực tiếp: bảo mật mặc định qua channels.discord.dm.policy (mặc định: "pairing"). Người gửi không xác định sẽ nhận pairing code (hết hạn sau 1 giờ); phê duyệt qua openclaw pairing approve discord <code>.
- Để giữ hành vi cũ “mở cho mọi người”: đặt channels.discord.dm.policy="open" và channels.discord.dm.allowFrom=["*"].
- Để dùng allowlist cứng: đặt channels.discord.dm.policy="allowlist" và liệt kê người gửi trong channels.discord.dm.allowFrom.
- Để bỏ qua tất cả DM: đặt channels.discord.dm.enabled=false hoặc channels.discord.dm.policy="disabled".
Group DM bị bỏ qua mặc định; bật qua channels.discord.dm.groupEnabled và tùy chọn giới hạn bằng channels.discord.dm.groupChannels.
Quy tắc guild tùy chọn: đặt channels.discord.guilds với key là guild id (khuyên dùng) hoặc slug, kèm quy tắc từng channel.
Lệnh native tùy chọn: commands.native mặc định là "auto" (bật cho Discord/Telegram, tắt cho Slack). Ghi đè bằng channels.discord.commands.native: true|false|"auto"; false sẽ xóa các lệnh đã đăng ký trước đó. Lệnh text được kiểm soát bởi commands.text và phải gửi dưới dạng tin nhắn /... độc lập. Dùng commands.useAccessGroups: false để bỏ qua kiểm tra access-group cho lệnh.
- Danh sách lệnh đầy đủ + config: Slash commands
Lịch sử context guild tùy chọn: đặt channels.discord.historyLimit (mặc định 20, fallback về messages.groupChat.historyLimit) để bao gồm N tin nhắn guild gần nhất làm context khi trả lời mention. Đặt 0 để tắt.
Reaction: Agent có thể kích hoạt reaction qua tool discord (được kiểm soát bởi channels.discord.actions.*).
- Ngữ nghĩa xóa reaction: xem /tools/reactions.
- Tool discord chỉ được hiển thị khi channel hiện tại là Discord.
Lệnh native dùng session key riêng biệt (agent:<agentId>:discord:slash:<userId>) thay vì session main chung.

Lưu ý: Phân giải tên → id dùng guild member search và yêu cầu Server Members Intent; nếu bot không thể tìm kiếm member, hãy dùng id hoặc mention <@id>. Lưu ý: Slug là chữ thường với khoảng trắng được thay bằng -. Tên channel được slug hóa không có # ở đầu. Lưu ý: Dòng [from:] trong guild context bao gồm author.tag + id để dễ dàng trả lời có ping.

Ghi config

Mặc định, Discord được phép ghi cập nhật config được kích hoạt bởi /config set|unset (yêu cầu commands.config: true).

Tắt bằng:

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

Cách tạo bot của riêng bạn

Đây là hướng dẫn thiết lập “Discord Developer Portal” để chạy OpenClaw trong guild channel (server) như #help.

1) Tạo Discord app + bot user

Discord Developer Portal → Applications → New Application
Trong app của bạn:
- Bot → Add Bot
- Copy Bot Token (đây là cái các bạn đặt vào DISCORD_BOT_TOKEN)

2) Bật các gateway intent mà OpenClaw cần

Discord chặn “privileged intent” trừ khi các bạn bật chúng một cách rõ ràng.

Trong Bot → Privileged Gateway Intents, bật:

Message Content Intent (bắt buộc để đọc nội dung tin nhắn trong hầu hết guild; không có nó các bạn sẽ thấy “Used disallowed intents” hoặc bot sẽ kết nối nhưng không phản ứng với tin nhắn)
Server Members Intent (khuyên dùng; bắt buộc cho một số tra cứu member/user và khớp allowlist trong guild)

Các bạn thường không cần Presence Intent.

3) Tạo invite URL (OAuth2 URL Generator)

Trong app của bạn: OAuth2 → URL Generator

Scope

✅ bot
✅ applications.commands (bắt buộc cho native command)

Bot Permissions (baseline tối thiểu)

✅ View Channels
✅ Send Messages
✅ Read Message History
✅ Embed Links
✅ Attach Files
✅ Add Reactions (tùy chọn nhưng khuyên dùng)
✅ Use External Emojis / Stickers (tùy chọn; chỉ nếu các bạn muốn)

Tránh Administrator trừ khi các bạn đang debug và hoàn toàn tin tưởng bot.

Copy URL được tạo, mở nó, chọn server của bạn, và cài đặt bot.

4) Lấy các id (guild/user/channel)

Discord dùng numeric id ở mọi nơi; config OpenClaw ưu tiên id.

Discord (desktop/web) → User Settings → Advanced → bật Developer Mode
Nhấp chuột phải:
- Tên server → Copy Server ID (guild id)
- Channel (ví dụ #help) → Copy Channel ID
- User của bạn → Copy User ID

5) Cấu hình OpenClaw

Token

Đặt bot token qua env var (khuyên dùng trên server):

DISCORD_BOT_TOKEN=...

Hoặc qua config:

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

Hỗ trợ multi-account: dùng channels.discord.accounts với token từng account và name tùy chọn. Xem gateway/configuration cho pattern chung.

Allowlist + channel routing

Ví dụ “single server, chỉ cho phép mình, chỉ cho phép #help”:

{
  channels: {
    discord: {
      enabled: true,
      dm: { enabled: false },
      guilds: {
        YOUR_GUILD_ID: {
          users: ["YOUR_USER_ID"],
          requireMention: true,
          channels: {
            help: { allow: true, requireMention: true },
          },
        },
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

Lưu ý:

requireMention: true nghĩa là bot chỉ trả lời khi được mention (khuyên dùng cho shared channel).
agents.list[].groupChat.mentionPatterns (hoặc messages.groupChat.mentionPatterns) cũng được tính là mention cho guild message.
Ghi đè multi-agent: đặt pattern từng agent trên agents.list[].groupChat.mentionPatterns.
Nếu có channels, bất kỳ channel nào không được liệt kê sẽ bị từ chối mặc định.
Dùng entry channel "*" để áp dụng mặc định cho tất cả channel; entry channel rõ ràng sẽ ghi đè wildcard.
Thread kế thừa config channel cha (allowlist, requireMention, skill, prompt, v.v.) trừ khi các bạn thêm thread channel id một cách rõ ràng.
Tin nhắn do bot tạo bị bỏ qua mặc định; đặt channels.discord.allowBots=true để cho phép chúng (tin nhắn của chính bot vẫn bị lọc).
Cảnh báo: Nếu các bạn cho phép trả lời bot khác (channels.discord.allowBots=true), hãy ngăn vòng lặp trả lời bot-to-bot bằng requireMention, allowlist channels.discord.guilds.*.channels.<id>.users, và/hoặc guardrail rõ ràng trong AGENTS.md và SOUL.md.

6) Xác minh hoạt động

Khởi động Gateway.
Trong server channel của bạn, gửi: @Krill hello (hoặc tên bot của bạn).
Nếu không có gì xảy ra: xem Troubleshooting bên dưới.

Troubleshooting

Đầu tiên: chạy openclaw doctor và openclaw channels status --probe (cảnh báo có thể thực hiện + kiểm tra nhanh).
“Used disallowed intents”: bật Message Content Intent (và có thể Server Members Intent) trong Developer Portal, sau đó khởi động lại Gateway.
Bot kết nối nhưng không bao giờ trả lời trong guild channel:
- Thiếu Message Content Intent, hoặc
- Bot thiếu quyền channel (View/Send/Read History), hoặc
- Config của bạn yêu cầu mention và bạn không mention nó, hoặc
- Allowlist guild/channel của bạn từ chối channel/user.
requireMention: false nhưng vẫn không trả lời:
channels.discord.groupPolicy mặc định là allowlist; đặt thành "open" hoặc thêm guild entry dưới channels.discord.guilds (tùy chọn liệt kê channel dưới channels.discord.guilds.<id>.channels để giới hạn).
- Nếu các bạn chỉ đặt DISCORD_BOT_TOKEN và không bao giờ tạo section channels.discord, runtime sẽ mặc định groupPolicy thành open. Thêm channels.discord.groupPolicy, channels.defaults.groupPolicy, hoặc allowlist guild/channel để khóa nó lại.
requireMention phải nằm dưới channels.discord.guilds (hoặc một channel cụ thể). channels.discord.requireMention ở top level bị bỏ qua.
Kiểm tra quyền (channels status --probe) chỉ kiểm tra numeric channel ID. Nếu các bạn dùng slug/tên làm key channels.discord.guilds.*.channels, kiểm tra không thể xác minh quyền.
DM không hoạt động: channels.discord.dm.enabled=false, channels.discord.dm.policy="disabled", hoặc bạn chưa được phê duyệt (channels.discord.dm.policy="pairing").
Exec approval trong Discord: Discord hỗ trợ button UI cho exec approval trong DM (Allow once / Always allow / Deny). /approve <id> ... chỉ dành cho forwarded approval và sẽ không giải quyết button prompt của Discord. Nếu các bạn thấy ❌ Failed to submit approval: Error: unknown approval id hoặc UI không bao giờ hiện lên, hãy kiểm tra:
- channels.discord.execApprovals.enabled: true trong config của bạn.
- Discord user ID của bạn được liệt kê trong channels.discord.execApprovals.approvers (UI chỉ được gửi cho approver).
- Dùng các button trong DM prompt (Allow once, Always allow, Deny).
- Xem Exec approvals và Slash commands cho luồng approval và command rộng hơn.

Khả năng & giới hạn

DM và guild text channel (thread được xử lý như channel riêng biệt; voice không được hỗ trợ).
Typing indicator được gửi best-effort; message chunking dùng channels.discord.textChunkLimit (mặc định 2000) và chia phản hồi dài theo số dòng (channels.discord.maxLinesPerMessage, mặc định 17).
Newline chunking tùy chọn: đặt channels.discord.chunkMode="newline" để chia theo dòng trống (ranh giới đoạn văn) trước khi chia theo độ dài.
Upload file được hỗ trợ lên đến channels.discord.mediaMaxMb đã cấu hình (mặc định 8 MB).
Phản hồi guild được kiểm soát bởi mention mặc định để tránh bot ồn ào.
Reply context được inject khi tin nhắn tham chiếu tin nhắn khác (nội dung được trích dẫn + id).
Native reply threading tắt mặc định; bật bằng channels.discord.replyToMode và reply tag.

Retry policy

Các cuộc gọi Discord API outbound retry khi gặp rate limit (429) dùng Discord retry_after khi có sẵn, với exponential backoff và jitter. Cấu hình qua channels.discord.retry. Xem Retry policy.

Config

{
  channels: {
    discord: {
      enabled: true,
      token: "abc.123",
      groupPolicy: "allowlist",
      guilds: {
        "*": {
          channels: {
            general: { allow: true },
          },
        },
      },
      mediaMaxMb: 8,
      actions: {
        reactions: true,
        stickers: true,
        emojiUploads: true,
        stickerUploads: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        channels: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off",
      dm: {
        enabled: true,
        policy: "pairing", // pairing | allowlist | open | disabled
        allowFrom: ["123456789012345678", "steipete"],
        groupEnabled: false,
        groupChannels: ["openclaw-dm"],
      },
      guilds: {
        "*": { requireMention: true },
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          reactionNotifications: "own",
          users: ["987654321098765432", "steipete"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["search", "docs"],
              systemPrompt: "Keep answers short.",
            },
          },
        },
      },
    },
  },
}

Ack reaction được kiểm soát toàn cục qua messages.ackReaction + messages.ackReactionScope. Dùng messages.removeAckAfterReply để xóa ack reaction sau khi bot trả lời.

dm.enabled: đặt false để bỏ qua tất cả DM (mặc định true).
dm.policy: kiểm soát truy cập DM (pairing khuyên dùng). "open" yêu cầu dm.allowFrom=["*"].
dm.allowFrom: allowlist DM (user id hoặc tên). Được dùng bởi dm.policy="allowlist" và để xác thực dm.policy="open". Wizard chấp nhận username và phân giải chúng thành id khi bot có thể tìm kiếm member.
dm.groupEnabled: bật group DM (mặc định false).
dm.groupChannels: allowlist tùy chọn cho group DM channel id hoặc slug.
groupPolicy: kiểm soát xử lý guild channel (open|disabled|allowlist); allowlist yêu cầu channel allowlist.
guilds: quy tắc từng guild với key là guild id (khuyên dùng) hoặc slug.
guilds."*": cài đặt mặc định từng guild được áp dụng khi không có entry rõ ràng.
guilds.<id>.slug: slug thân thiện tùy chọn dùng cho tên hiển thị.
guilds.<id>.users: allowlist user từng guild tùy chọn (id hoặc tên).
guilds.<id>.tools: ghi đè tool policy từng guild tùy chọn (allow/deny/alsoAllow) được dùng khi thiếu ghi đè channel.
guilds.<id>.toolsBySender: ghi đè tool policy từng sender tùy chọn ở cấp guild (áp dụng khi thiếu ghi đè channel; hỗ trợ wildcard "*").
guilds.<id>.channels.<channel>.allow: cho phép/từ chối channel khi groupPolicy="allowlist".
guilds.<id>.channels.<channel>.requireMention: kiểm soát mention cho channel.
guilds.<id>.channels.<channel>.tools: ghi đè tool policy từng channel tùy chọn (allow/deny/alsoAllow).
guilds.<id>.channels.<channel>.toolsBySender: ghi đè tool policy từng sender tùy chọn trong channel (hỗ trợ wildcard "*").
guilds.<id>.channels.<channel>.users: allowlist user từng channel tùy chọn.
guilds.<id>.channels.<channel>.skills: bộ lọc skill (bỏ qua = tất cả skill, rỗng = không có).
guilds.<id>.channels.<channel>.systemPrompt: system prompt bổ sung cho channel (kết hợp với channel topic).
guilds.<id>.channels.<channel>.enabled: đặt false để tắt channel.
guilds.<id>.channels: quy tắc channel (key là channel slug hoặc id).
guilds.<id>.requireMention: yêu cầu mention từng guild (có thể ghi đè từng channel).
guilds.<id>.reactionNotifications: chế độ reaction system event (off, own, all, allowlist).
textChunkLimit: kích thước text chunk outbound (ký tự). Mặc định: 2000.
chunkMode: length (mặc định) chỉ chia khi vượt quá textChunkLimit; newline chia theo dòng trống (ranh giới đoạn văn) trước khi chia theo độ dài.
maxLinesPerMessage: số dòng tối đa mềm mỗi tin nhắn. Mặc định: 17.
mediaMaxMb: giới hạn media inbound được lưu vào đĩa.
historyLimit: số tin nhắn guild gần đây để bao gồm làm context khi trả lời mention (mặc định 20; fallback về messages.groupChat.historyLimit; 0 tắt).
dmHistoryLimit: giới hạn lịch sử DM theo lượt user. Ghi đè từng user: dms["<user_id>"].historyLimit.
retry: retry policy cho cuộc gọi Discord API outbound (attempts, minDelayMs, maxDelayMs, jitter).
pluralkit: phân giải tin nhắn proxied PluralKit để system member xuất hiện như sender riêng biệt.
actions: kiểm soát tool từng action; bỏ qua để cho phép tất cả (đặt false để tắt).
- reactions (bao gồm react + đọc reaction)
- stickers, emojiUploads, stickerUploads, polls, permissions, messages, threads, pins, search
- memberInfo, roleInfo, channelInfo, voiceStatus, events
- channels (tạo/sửa/xóa channel + category + permission)
- roles (thêm/xóa role, mặc định false)
- moderation (timeout/kick/ban, mặc định false)
execApprovals: exec approval DM chỉ dành cho Discord (button UI). Hỗ trợ enabled, approvers, agentFilter, sessionFilter.

Reaction notification dùng guilds.<id>.reactionNotifications:

off: không có reaction event.
own: reaction trên tin nhắn của chính bot (mặc định).
all: tất cả reaction trên tất cả tin nhắn.
allowlist: reaction từ guilds.<id>.users trên tất cả tin nhắn (danh sách rỗng tắt).

Hỗ trợ PluralKit (PK)

Bật tra cứu PK để tin nhắn proxied phân giải thành system + member cơ bản. Khi bật, OpenClaw dùng member identity cho allowlist và gắn nhãn sender là Member (PK:System) để tránh ping Discord vô tình.

{
  channels: {
    discord: {
      pluralkit: {
        enabled: true,
        token: "pk_live_...", // tùy chọn; bắt buộc cho private system
      },
    },
  },
}

Lưu ý allowlist (bật PK):

Dùng pk:<memberId> trong dm.allowFrom, guilds.<id>.users, hoặc users từng channel.
Tên hiển thị member cũng được khớp theo tên/slug.
Tra cứu dùng original Discord message ID (tin nhắn pre-proxy), nên PK API chỉ phân giải nó trong cửa sổ 30 phút.
Nếu tra cứu PK thất bại (ví dụ: private system không có token), tin nhắn proxied được xử lý như tin nhắn bot và bị loại bỏ trừ khi channels.discord.allowBots=true.

Mặc định tool action

Nhóm action	Mặc định	Ghi chú
reactions	enabled	React + list reaction + emojiList
stickers	enabled	Gửi sticker
emojiUploads	enabled	Upload emoji
stickerUploads	enabled	Upload sticker
polls	enabled	Tạo poll
permissions	enabled	Snapshot quyền channel
messages	enabled	Đọc/gửi/sửa/xóa
threads	enabled	Tạo/liệt kê/trả lời
pins	enabled	Pin/unpin/liệt kê
search	enabled	Tìm kiếm tin nhắn (tính năng xem trước)
memberInfo	enabled	Thông tin member
roleInfo	enabled	Danh sách role
channelInfo	enabled	Thông tin channel + liệt kê
channels	enabled	Quản lý channel/category
voiceStatus	enabled	Tra cứu trạng thái voice
events	enabled	Liệt kê/tạo scheduled event
roles	disabled	Thêm/xóa role
moderation	disabled	Timeout/kick/ban

replyToMode: off (mặc định), first, hoặc all. Chỉ áp dụng khi model bao gồm reply tag.

Reply tag

Để yêu cầu threaded reply, model có thể bao gồm một tag trong output:

[[reply_to_current]] — trả lời tin nhắn Discord kích hoạt.
[[reply_to:<id>]] — trả lời message id cụ thể từ context/history. Message id hiện tại được thêm vào prompt dưới dạng [message_id: …]; entry history đã bao gồm id.

Hành vi được kiểm soát bởi channels.discord.replyToMode:

off: bỏ qua tag.
first: chỉ chunk/attachment outbound đầu tiên là reply.
all: mọi chunk/attachment outbound đều là reply.

Lưu ý khớp allowlist:

allowFrom/users/groupChannels chấp nhận id, tên, tag, hoặc mention như <@id>.
Prefix như discord:/user: (user) và channel: (group DM) được hỗ trợ.
Dùng * để cho phép bất kỳ sender/channel nào.
Khi có guilds.<id>.channels, các channel không được liệt kê sẽ bị từ chối mặc định.
Khi bỏ qua guilds.<id>.channels, tất cả channel trong guild được allowlist sẽ được cho phép.
Để cho phép không có channel, đặt channels.discord.groupPolicy: "disabled" (hoặc giữ allowlist rỗng).
Configure wizard chấp nhận tên Guild/Channel (public + private) và phân giải chúng thành ID khi có thể.
Khi khởi động, OpenClaw phân giải tên channel/user trong allowlist thành ID (khi bot có thể tìm kiếm member) và log mapping; entry chưa phân giải được giữ nguyên như đã nhập.

Lưu ý native command:

Các lệnh đã đăng ký phản ánh chat command của OpenClaw.
Native command tuân theo allowlist giống như DM/guild message (channels.discord.dm.allowFrom, channels.discord.guilds, quy tắc từng channel).
Slash command vẫn có thể hiển thị trong Discord UI cho user không có trong allowlist; OpenClaw thực thi allowlist khi thực thi và trả lời “not authorized”.

Tool action

Agent có thể gọi discord với các action như:

react / reactions (thêm hoặc liệt kê reaction)
sticker, poll, permissions
readMessages, sendMessage, editMessage, deleteMessage
Payload tool đọc/tìm kiếm/pin bao gồm timestampMs chuẩn hóa (UTC epoch ms) và timestampUtc cùng với Discord timestamp thô.
threadCreate, threadList, threadReply
pinMessage, unpinMessage, listPins
searchMessages, memberInfo, roleInfo, roleAdd, roleRemove, emojiList
channelInfo, channelList, voiceStatus, eventList, eventCreate
timeout, kick, ban

Discord message id được hiển thị trong context được inject ([discord message id: …] và dòng history) để Agent có thể nhắm mục tiêu chúng. Emoji có thể là unicode (ví dụ: ✅) hoặc cú pháp custom emoji như <:party_blob:1234567890>.

An toàn & vận hành

Xử lý bot token như mật khẩu; ưu tiên env var DISCORD_BOT_TOKEN trên host được giám sát hoặc khóa quyền file config.
Chỉ cấp cho bot các quyền cần thiết (thường là Read/Send Messages).
Nếu bot bị kẹt hoặc bị rate limit, khởi động lại Gateway (openclaw gateway --force) sau khi xác nhận không có process nào khác sở hữu Discord session.