Discord

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Thiết lập nhanh

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
cat > discord.patch.json5 <<'JSON5'
{
  channels: {
    discord: {
      enabled: true,
      token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
    },
  },
}
JSON5
openclaw config patch --file ./discord.patch.json5 --dry-run
openclaw config patch --file ./discord.patch.json5
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 không gian làm việc 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: phản hồi đến từ Discord sẽ quay lại Discord.
• Metadata guild/kênh Discord được thêm vào prompt của mô hình như ngữ cảnh không đáng tin cậy, không phải tiền tố phản hồi hiển thị cho người dùng. Nếu mô hình sao chép phong bì đó trở lại, OpenClaw sẽ loại bỏ metadata đã sao chép khỏi phản hồi đi và khỏi ngữ cảnh phát lại trong tương lai.
• Theo mặc định (session.dmScope=main), trò chuyện trực tiếp dùng chung phiên chính của tác nhân (agent:main:main).
• Kênh guild là các khóa phiên cô lập (agent:<agentId>:discord:channel:<channelId>).
• Tin nhắn riêng nhóm 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 cô lập (agent:<agentId>:discord:slash:<userId>), đồng thời vẫn mang CommandTargetSessionKey tới phiên hội thoại được định tuyến.
• Việc gửi thông báo cron/Heartbeat chỉ văn bản tới Discord dùng câu trả lời cuối hiển thị cho trợ lý một lần. Payload media và thành phần có cấu trúc vẫn là nhiều tin nhắn khi tác nhân phát ra nhiều payload có thể gửi.

​

Kênh diễn đàn

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

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"

​

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 duy nhất
• Loại chọn: string, user, role, mentionable, channel

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

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

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

​

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 tác tử dựa trên vai trò

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

​

Lệnh native và xác thực lệnh

• commands.native mặc định là "auto" và được bật cho Discord.
• Ghi đè theo kênh: channels.discord.commands.native.
• commands.native=false xóa rõ ràng các lệnh native Discord đã đăng ký trước đó.
• Xác thực lệnh native dùng cùng danh sách cho phép/chính sách Discord như xử lý thông điệp bình thường.
• Lệnh vẫn có thể hiển thị trong giao diện Discord cho người dùng không được ủy quyền; việc thực thi vẫn áp dụng 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: "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",
      },
    },
  },
}

​

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
• presence: setPresence

​

Giao diện người dùng components v2

• channels.discord.ui.components.accentColor đặt màu nhấn dùng bởi các container component của Discord (hex).
• Đặt theo từng tài khoản bằng channels.discord.accounts.<id>.ui.components.accentColor.
• embeds bị bỏ qua khi có components v2.

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

​

Thoại

​

Kênh thoại

1. Bật Message Content Intent trong Discord Developer Portal.
2. Bật Server Members Intent khi dùng danh sách cho phép theo vai trò/người dùng.
3. Mời bot với phạm vi bot và applications.commands.
4. Cấp quyền Connect, Speak, Send Messages và Read Message History trong kênh thoại đích.
5. Bật lệnh gốc (commands.native hoặc channels.discord.commands.native).
6. Cấu hình channels.discord.voice.

/vc join channel:<voice-channel-id>
/vc status
/vc leave

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        model: "openai/gpt-5.4-mini",
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "onyx" },
        },
      },
    },
  },
}

• voice.tts chỉ ghi đè messages.tts cho phát lại thoại.
• voice.model chỉ ghi đè LLM dùng cho phản hồi kênh thoại Discord. Để trống để kế thừa mô hình tác nhân được định tuyến.
• STT dùng tools.media.audio; voice.model không ảnh hưởng đến phiên âm.
• Các lượt bản ghi thoại suy ra 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ông cụ chỉ dành cho chủ sở hữu (ví dụ gateway và cron).
• Thoại được bật theo mặc định; đặt channels.discord.voice.enabled=false để tắt runtime thoại và intent Gateway GuildVoiceStates.
• channels.discord.intents.voiceStates có thể ghi đè rõ ràng đăng ký intent trạng thái thoại. Để trống để intent đi theo voice.enabled.
• voice.daveEncryption và voice.decryptionFailureTolerance được chuyển tiếp vào tùy chọn tham gia của @discordjs/voice.
• Mặc định của @discordjs/voice là daveEncryption=true và decryptionFailureTolerance=24 nếu chưa đặt.
• OpenClaw cũng theo dõi lỗi giải mã nhận và tự khôi phục bằng cách rời/tham gia lại kênh thoại sau các 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) sau khi cập nhật, hãy thu thập báo cáo phụ thuộc và nhật ký. Dòng @discordjs/voice đi kèm có bản sửa lỗi padding thượng nguồn từ discord.js PR #11449, vốn đã đóng issue discord.js #11419.

• Ghi PCM của Discord được chuyển đổi thành tệp WAV tạm.
• tools.media.audio xử lý STT, ví dụ openai/gpt-4o-mini-transcribe.
• Bản phiên âm được gửi qua luồng nhận và định tuyến Discord thông thường.
• voice.model, khi được đặt, chỉ ghi đè LLM phản hồi cho lượt kênh thoại này.
• voice.tts được hợp nhất đè lên messages.tts; âm thanh kết quả được phát trong kênh đã tham gia.

​

Tin nhắn thoạ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 từ chối văn bản + tin nhắn thoại trong cùng một payload).
• Chấp nhận mọi định dạng âm thanh; 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,
          },
        },
      },
    },
  },
}

​

Tham chiếu cấu hình

​

An toàn và vận hành

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

​

Liên quan