Discord

Sẵn sàng cho DM và các kênh guild thông qua Gateway chính thức của Discord.

Thiết lập nhanh

Bạn cần tạo một ứng dụng mới có bot, thêm bot vào máy chủ của bạn, rồi ghép nối bot đó với OpenClaw. Chúng tôi khuyến nghị thêm bot vào máy chủ riêng của chính bạn. Nếu bạn chưa có máy chủ, hãy tạo một máy chủ trước (chọn Create My Own > For me and my friends).

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" },},},}JSON5openclaw config patch --file ./discord.patch.json5 --dry-runopenclaw config patch --file ./discord.patch.json5openclaw gateway

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

DISCORD_BOT_TOKEN=...

{channels: {discord: {enabled: true,accounts: {personal: {  token: { source: "env", provider: "default", id: "DISCORD_PERSONAL_TOKEN" },  applicationId: "111111111111111111",},work: {  token: { source: "env", provider: "default", id: "DISCORD_WORK_TOKEN" },  applicationId: "222222222222222222",},},},},}

openclaw pairing list discordopenclaw pairing approve discord <CODE>

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

Sau khi DM hoạt động, bạn có thể thiết lập máy chủ Discord của mình như một workspace đầy đủ, nơi mỗi kênh có phiên agent riêng với ngữ cảnh riêng. Cách này được khuyến nghị cho máy chủ riêng chỉ có bạn và bot của bạn.

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

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

Bây giờ hãy tạo một vài kênh trên máy chủ Discord của bạn và bắt đầu chat. Agent của bạn có thể thấy tên kênh, và mỗi kênh có phiên cô lập riêng — nên bạn có thể thiết lập #coding, #home, #research, hoặc bất kỳ thứ gì phù hợp với quy trình làm việc của mình.

Model runtime

• Gateway sở hữu kết nối Discord.
• Định tuyến trả lời có tính xác định: các phản hồi đầu vào từ Discord được trả về Discord.
• Siêu dữ liệu guild/kênh Discord được thêm vào lời nhắc mô hình dưới dạng ngữ cảnh không đáng tin cậy, không phải tiền tố trả lời hiển thị với người dùng. Nếu mô hình sao chép lại phần bao này, OpenClaw sẽ loại bỏ siêu dữ liệu đã sao chép khỏi các phản hồi gửi đi và khỏi ngữ cảnh phát lại trong tương lai.
• Theo mặc định (session.dmScope=main), các cuộc 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 tách biệt (agent:<agentId>:discord:channel:<channelId>).
• DM nhóm bị bỏ qua theo mặc định (channels.discord.dm.groupEnabled=false).
• Các lệnh slash gốc chạy trong các phiên lệnh tách biệt (agent:<agentId>:discord:slash:<userId>), trong khi vẫn mang CommandTargetSessionKey đến phiên hội thoại được định tuyến.
• Việc gửi thông báo Cron/Heartbeat chỉ có văn bản đến Discord sử dụng câu trả lời cuối cùng hiển thị với trợ lý một lần. Các tải phương tiện 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 tải có thể gửi.

Kênh diễn đàn

Kênh diễn đàn và kênh phương tiện của Discord chỉ chấp nhận bài đăng trong luồng. OpenClaw hỗ trợ hai cách để tạo chúng:

• Gửi tin nhắn đến diễn đàn cha (channel:<forumId>) để tự động tạo một luồng. Tiêu đề luồng dùng dòng không trống đầu tiên trong tin nhắn của bạ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.

Ví dụ: gửi đến diễn đàn cha để tạo một luồng

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

Ví dụ: tạo một luồng diễn đàn rõ ràng

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

Diễn đàn cha không chấp nhận thành phần Discord. Nếu bạn cần thành phần, hãy gửi đến chính luồng đó (channel:<threadId>).

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

OpenClaw hỗ trợ vùng chứa thành phần Discord v2 cho tin nhắn của tác nhân. Dùng công cụ tin nhắn với tải components. Kết quả tương tác được định tuyến trở lại tác nhân dưới dạng tin nhắn đầu vào thông thường và tuân theo các cài đặt Discord replyToMode hiện có.

Các khối được hỗ trợ:

• 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
• Kiểu chọn: string, user, role, mentionable, channel

Theo mặc định, thành phần chỉ dùng một lần. Đặt components.reusable=true để cho phép nút, menu chọn và biểu mẫu được dùng nhiều lần cho đến khi chúng hết hạn.

Để giới hạn người có thể nhấp một nút, hãy đặt allowedUsers trên nút đó (ID người dùng Discord, thẻ hoặc *). Khi được cấu hình, người dùng không khớp sẽ nhận một thông báo từ chối tạm thời.

Các lệnh slash /model và /models mở một bộ chọn mô hình tương tác với các danh sách thả xuống nhà cung cấp, mô hình và runtime tương thích, cộng với một bước Gửi. /models add đã không còn được khuyến nghị và giờ trả về thông báo ngừng dùng thay vì đăng ký mô hình từ chat. Phản hồi của bộ chọn là tạm thời và chỉ người dùng gọi lệnh mới có thể sử dụng. Menu chọn của Discord bị giới hạn ở 25 tùy chọn, vì vậy hãy thêm các mục provider/* vào agents.defaults.models khi bạn muốn bộ chọn chỉ hiển thị các mô hình được khám phá động cho những nhà cung cấp đã chọn, chẳng hạn như openai-codex hoặc vllm.

Tệp đính kèm:

• 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 đó cần khớp với tham chiếu tệp đính kèm

Biểu mẫu modal:

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

Ví dụ:

{  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

{accessGroups: {operators: {  type: "message.senders",  members: {    "*": ["global-owner-id"],    discord: ["discord:123456789012345678"],    telegram: ["987654321"],  },},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:operators"],},},}

{accessGroups: {maintainers: {  type: "discord.channelAudience",  guildId: "1456350064065904867",  channelId: "1456744319972282449",  membership: "canViewChannel",},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:maintainers"],},},}

{accessGroups: {maintainers: {  type: "discord.channelAudience",  guildId: "1456350064065904867",  channelId: "1456744319972282449",},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:maintainers", "discord:123456789012345678"],},},}

{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 nhân dựa trên vai trò

Dùng bindings[].match.roles để định tuyến thành viên guild Discord đến các tác nhân khác nhau theo ID vai trò. Binding dựa trên vai trò chỉ chấp nhận ID vai trò và được đánh giá sau binding ngang hàng hoặc cha-ngang hàng và trước binding chỉ theo guild. Nếu một binding cũng đặt các trường khớp khác (ví dụ peer + guildId + roles), tất cả các trường đã cấu hình phải khớp.

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

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

• commands.native mặc định là "auto" và được bật cho Discord.
• Ghi đè theo từng kênh: channels.discord.commands.native.
• commands.native=false bỏ qua việc đăng ký và dọn dẹp lệnh slash của Discord trong quá trình khởi động. Các lệnh đã đăng ký trước đó có thể vẫn hiển thị trong Discord cho đến khi bạn xóa chúng khỏi ứng dụng Discord.
• Xác thực lệnh gốc dùng cùng danh sách cho phép/chính sách Discord như xử lý tin nhắn thông thường.
• Các lệnh vẫn có thể hiển thị trong UI Discord với 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".

Xem Lệnh slash để biết danh mục lệnh và hành vi.

Cài đặt lệnh slash mặc định:

• ephemeral: true

Chi tiết tính năng

{channels: {discord: {  streaming: {    mode: "progress",    progress: {      label: "auto",      maxLines: 8,      toolProgress: true,    },  },},},}

{  "channels": {    "discord": {      "streaming": {        "mode": "progress",        "progress": {          "toolProgress": true,          "commandText": "status"        }      }    }  }}

{session: {threadBindings: {  enabled: true,  idleHours: 24,  maxAgeHours: 0,},},channels: {discord: {  threadBindings: {    enabled: true,    idleHours: 24,    maxAgeHours: 0,    spawnSessions: true,    defaultSpawnContext: "fork",  },},},}

{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: {  mentionAliases: {    Vladislava: "123456789012345678",  },  accounts: {    ops: {      mentionAliases: {        OpsLead: "234567890123456789",      },    },  },},},}

{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

Hành động tin nhắn Discord bao gồm nhắn tin, quản trị kênh, kiểm duyệt, hiện diện và hành động siêu dữ liệu.

Ví dụ cốt lõi:

• 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

Hành động event-create chấp nhận tham số image tùy chọn (URL hoặc đường dẫn tệp cục bộ) để đặt ảnh bìa cho sự kiện đã lên lịch.

Cổng hành động nằm dưới channels.discord.actions.*.

Hành vi cổng mặc định:

UI Components v2

OpenClaw dùng Discord components v2 cho phê duyệt thực thi và dấu mốc xuyên ngữ cảnh. Hành động tin nhắn Discord cũng có thể chấp nhận components cho UI tùy chỉnh (nâng cao; yêu cầu dựng payload component qua công cụ discord), trong khi embeds cũ vẫn khả dụng nhưng không được khuyến nghị.

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

Ví dụ:

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

Giọng nói

Discord có hai bề mặt giọng nói riêng biệt: kênh thoại thời gian thực (cuộc trò chuyện liên tục) và tệp đính kèm tin nhắn thoại (định dạng xem trước dạng sóng). Gateway hỗ trợ cả hai.

Kênh thoại

Danh sách kiểm tra thiết lập:

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 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.

Dùng /vc join|leave|status để điều khiển phiên. Lệnh sử dụng tác tử mặc định của tài khoản và tuân theo cùng các quy tắc danh sách cho phép và chính sách nhóm như các lệnh Discord khác.

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

Để kiểm tra quyền hiệu dụng của bot trước khi tham gia, chạy:

openclaw channels capabilities --channel discord --target channel:<voice-channel-id>

Ví dụ tự động tham gia:

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai-codex/gpt-5.5",        autoJoin: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],        allowedChannels: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],        daveEncryption: true,        decryptionFailureTolerance: 24,        connectTimeoutMs: 30000,        reconnectGraceMs: 15000,        realtime: {          provider: "openai",          model: "gpt-realtime-2",          voice: "cedar",        },      },    },  },}

Ghi chú:

• voice.tts chỉ ghi đè messages.tts cho phát lại giọng nói stt-tts. Các chế độ thời gian thực dùng voice.realtime.voice.
• voice.mode kiểm soát luồng hội thoại. Mặc định là agent-proxy: một giao diện giọng nói thời gian thực xử lý thời điểm lượt nói, ngắt lời và phát lại, ủy quyền công việc nội dung cho tác tử OpenClaw được định tuyến thông qua openclaw_agent_consult, và xử lý kết quả như một lời nhắc Discord được nhập từ người nói đó. stt-tts giữ luồng STT theo lô cũ cộng với TTS. bidi cho phép mô hình thời gian thực trò chuyện trực tiếp đồng thời cung cấp openclaw_agent_consult cho bộ não OpenClaw.
• voice.agentSession kiểm soát cuộc hội thoại OpenClaw nào nhận các lượt thoại. Để trống để dùng phiên riêng của kênh thoại, hoặc đặt { mode: "target", target: "channel:<text-channel-id>" } để biến kênh thoại thành phần mở rộng micrô/loa của một phiên kênh văn bản Discord hiện có, chẳng hạn như #maintainers.
• voice.model ghi đè bộ não tác tử OpenClaw cho phản hồi thoại Discord và các lượt tham vấn thời gian thực. Để trống để kế thừa mô hình tác tử được định tuyến. Nó tách biệt với voice.realtime.model.
• agent-proxy định tuyến lời nói qua discord-voice, giúp giữ nguyên ủy quyền chủ sở hữu/công cụ bình thường cho người nói và phiên đích nhưng ẩn công cụ tts của tác tử vì thoại Discord sở hữu việc phát lại. Theo mặc định, agent-proxy cấp cho lượt tham vấn quyền truy cập công cụ tương đương đầy đủ với chủ sở hữu đối với người nói là chủ sở hữu (voice.realtime.toolPolicy: "owner") và ưu tiên mạnh việc tham vấn tác tử OpenClaw trước các câu trả lời có nội dung (voice.realtime.consultPolicy: "always"). Trong chế độ mặc định always đó, lớp thời gian thực không tự động nói phần đệm trước câu trả lời tham vấn; nó ghi lại và phiên âm lời nói, sau đó nói câu trả lời OpenClaw đã được định tuyến. Nếu nhiều câu trả lời tham vấn bắt buộc hoàn tất trong khi Discord vẫn đang phát câu trả lời đầu tiên, các câu trả lời lời nói chính xác sau đó được xếp hàng cho đến khi phát lại rảnh thay vì thay thế lời nói giữa câu.
• Trong chế độ stt-tts, STT dùng tools.media.audio; voice.model không ảnh hưởng đến phiên âm.
• Trong các chế độ thời gian thực, voice.realtime.provider, voice.realtime.model và voice.realtime.voice cấu hình phiên âm thanh thời gian thực. Với OpenAI Realtime 2 cộng với bộ não Codex, dùng voice.realtime.model: "gpt-realtime-2" và voice.model: "openai-codex/gpt-5.5".
• Nhà cung cấp thời gian thực OpenAI chấp nhận tên sự kiện Realtime 2 hiện tại và các bí danh tương thích Codex kiểu cũ cho sự kiện âm thanh đầu ra và bản phiên âm, để các bản chụp nhà cung cấp tương thích có thể lệch mà không làm mất âm thanh trợ lý.
• voice.realtime.bargeIn kiểm soát việc sự kiện bắt đầu nói của người nói Discord có ngắt phát lại thời gian thực đang hoạt động hay không. Nếu chưa đặt, nó làm theo thiết lập ngắt âm thanh đầu vào của nhà cung cấp thời gian thực.
• voice.realtime.minBargeInAudioEndMs kiểm soát thời lượng phát lại tối thiểu của trợ lý trước khi một lần chen lời thời gian thực OpenAI cắt ngắn âm thanh. Mặc định: 250. Đặt 0 để ngắt ngay trong phòng ít vọng, hoặc tăng giá trị này cho các thiết lập loa nhiều vọng.
• Đối với giọng OpenAI khi phát lại trên Discord, đặt voice.tts.provider: "openai" và chọn một giọng Text-to-speech trong voice.tts.openai.voice hoặc voice.tts.providers.openai.voice. cedar là một lựa chọn nghe nam tính tốt trên mô hình TTS OpenAI hiện tại.
• Các ghi đè systemPrompt Discord theo từng kênh áp dụng cho các lượt bản phiên âm thoại của kênh thoại đó.
• Các lượt bản phiên âm 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ác công cụ chỉ dành cho chủ sở hữu (ví dụ gateway và cron).
• Thoại Discord là tùy chọn bật thêm đối với cấu hình chỉ văn bản; đặt channels.discord.voice.enabled=true (hoặc giữ một khối channels.discord.voice hiện có) để bật lệnh /vc, runtime thoại và ý định Gateway GuildVoiceStates.
• channels.discord.intents.voiceStates có thể ghi đè rõ ràng việc đăng ký ý định trạng thái thoại. Để trống để ý định đi theo trạng thái bật thoại hiệu lực.
• Nếu voice.autoJoin có nhiều mục cho cùng một guild, OpenClaw sẽ tham gia kênh được cấu hình cuối cùng cho guild đó.
• voice.allowedChannels là một danh sách cho phép cư trú tùy chọn. Để trống để cho phép /vc join vào bất kỳ kênh thoại Discord được ủy quyền nào. Khi được đặt, /vc join, tự động tham gia lúc khởi động và các lần di chuyển trạng thái thoại của bot bị giới hạn trong các mục { guildId, channelId } được liệt kê. Đặt thành mảng rỗng để từ chối mọi lần tham gia thoại Discord. Nếu Discord di chuyển bot ra ngoài danh sách cho phép, OpenClaw rời kênh đó và tham gia lại đích tự động tham gia đã cấu hình khi có.
• voice.daveEncryption và voice.decryptionFailureTolerance được truyền qua các 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 mặc định dùng bộ giải mã opusscript thuần JS cho nhận thoại Discord. Gói gốc tùy chọn @discordjs/opus bị bỏ qua theo chính sách cài đặt pnpm của repo để các cài đặt thông thường, các làn Docker và các bài kiểm thử không liên quan không biên dịch addon gốc. Các máy chủ hiệu năng thoại chuyên dụng có thể chọn dùng bằng OPENCLAW_DISCORD_OPUS_DECODER=native sau khi cài đặt addon gốc.
• voice.connectTimeoutMs kiểm soát thời gian chờ Ready ban đầu của @discordjs/voice cho /vc join và các lần tự động tham gia. Mặc định: 30000.
• voice.reconnectGraceMs kiểm soát thời gian OpenClaw chờ một phiên thoại đã ngắt kết nối bắt đầu kết nối lại trước khi hủy nó. Mặc định: 15000.
• Trong chế độ stt-tts, phát lại thoại không dừng chỉ vì một người dùng khác bắt đầu nói. Để tránh vòng lặp phản hồi, OpenClaw bỏ qua việc thu giọng nói mới trong khi TTS đang phát; hãy nói sau khi phát lại hoàn tất cho lượt tiếp theo. Các chế độ thời gian thực chuyển tiếp lượt bắt đầu nói của người nói dưới dạng tín hiệu chen lời đến nhà cung cấp thời gian thực.
• Trong các chế độ thời gian thực, tiếng vọng từ loa vào micrô đang mở có thể trông giống như chen lời và ngắt phát lại. Với các phòng Discord nhiều vọng, đặt voice.realtime.providers.openai.interruptResponseOnInputAudio: false để ngăn OpenAI tự động ngắt khi có âm thanh đầu vào. Thêm voice.realtime.bargeIn: true nếu bạn vẫn muốn các sự kiện bắt đầu nói của người nói Discord ngắt phát lại đang hoạt động. Cầu nối thời gian thực OpenAI bỏ qua các lần cắt ngắn phát lại ngắn hơn voice.realtime.minBargeInAudioEndMs vì nhiều khả năng là vọng/nhiễu và ghi log là đã bỏ qua thay vì xóa phát lại Discord.
• voice.captureSilenceGraceMs kiểm soát thời gian OpenClaw chờ sau khi Discord báo rằng một người nói đã dừng trước khi hoàn tất phân đoạn âm thanh đó cho STT. Mặc định: 2500; tăng giá trị này nếu Discord tách các khoảng dừng bình thường thành các bản phiên âm từng phần bị ngắt đoạn.
• Khi ElevenLabs là nhà cung cấp TTS được chọn, phát lại thoại Discord dùng TTS truyền phát và bắt đầu từ luồng phản hồi của nhà cung cấp. Các nhà cung cấp không hỗ trợ truyền phát sẽ quay lại đường dẫn tệp tạm đã tổng hợp.
• OpenClaw cũng theo dõi các lỗi giải mã khi nhận và tự động khôi phục bằng cách rời/tham gia lại kênh thoại sau nhiều lần lỗi lặp lại trong một khoảng thời gian ngắn.
• Nếu log 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à log. Dòng @discordjs/voice được đóng gói bao gồm bản sửa padding thượng nguồn từ PR discord.js #11449, đã đóng issue discord.js #11419.
• Các sự kiện nhận The operation was aborted là bình thường khi OpenClaw hoàn tất một phân đoạn người nói đã thu; chúng là chẩn đoán chi tiết, không phải cảnh báo.
• Log thoại Discord chi tiết bao gồm bản xem trước phiên âm STT một dòng có giới hạn cho mỗi phân đoạn người nói được chấp nhận, để việc gỡ lỗi hiển thị cả phía người dùng và phía phản hồi của tác tử mà không đổ văn bản phiên âm không giới hạn.
• Trong chế độ agent-proxy, phương án dự phòng tham vấn bắt buộc bỏ qua các mảnh bản phiên âm có khả năng chưa hoàn chỉnh, chẳng hạn như văn bản kết thúc bằng ... hoặc một từ nối ở cuối như and, cộng với các câu kết rõ ràng không yêu cầu hành động như “quay lại ngay” hoặc “tạm biệt”. Log hiển thị forced agent consult skipped reason=... khi điều này ngăn một câu trả lời cũ trong hàng đợi.

Thiết lập opus gốc cho bản checkout từ mã nguồn:

pnpm installmise exec node@22 -- pnpm discord:opus:install

Dùng Node 22 cho Gateway khi bạn muốn addon gốc dựng sẵn macOS arm64 từ thượng nguồn. Nếu bạn dùng runtime Node khác, trình cài đặt chọn dùng có thể cần chuỗi công cụ dựng từ nguồn node-gyp cục bộ.

Sau khi cài đặt addon gốc, khởi động Gateway bằng:

OPENCLAW_DISCORD_OPUS_DECODER=native pnpm gateway:watch

Log thoại chi tiết sẽ hiển thị discord voice: opus decoder: @discordjs/opus. Nếu không có env chọn dùng, hoặc nếu addon gốc bị thiếu hoặc không thể tải trên máy chủ, OpenClaw ghi log discord voice: opus decoder: opusscript và tiếp tục nhận thoại qua phương án dự phòng thuần JS.

Pipeline STT cộng với TTS:

• Thu PCM Discord được chuyển đổi thành tệp tạm WAV.
• tools.media.audio xử lý STT, ví dụ openai/gpt-4o-mini-transcribe.
• Bản phiên âm được gửi qua đường vào và định tuyến Discord trong khi LLM phản hồi chạy với chính sách đầu ra thoại ẩn công cụ tts của tác tử và yêu cầu văn bản trả về, vì thoại Discord sở hữu việc phát lại TTS cuối cù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; các nhà cung cấp có khả năng truyền phát sẽ cấp trực tiếp cho trình phát, nếu không tệp âm thanh kết quả sẽ được phát trong kênh đã tham gia.

Ví dụ phiên kênh thoại agent-proxy mặc định:

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai-codex/gpt-5.5",        realtime: {          provider: "openai",          model: "gpt-realtime-2",          voice: "cedar",        },      },    },  },}

Khi không có khối voice.agentSession, mỗi kênh thoại sẽ có phiên OpenClaw được định tuyến riêng. Ví dụ, /vc join channel:234567890123456789 nói chuyện với phiên của kênh thoại Discord đó. Mô hình thời gian thực chỉ là giao diện thoại phía trước; các yêu cầu nội dung được chuyển cho tác tử OpenClaw đã cấu hình. Nếu mô hình thời gian thực tạo bản phiên âm cuối cùng mà không gọi công cụ tham vấn, OpenClaw buộc tham vấn như một phương án dự phòng để mặc định vẫn hoạt động như đang nói chuyện với tác tử.

Ví dụ STT cộng với TTS kiểu cũ:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "stt-tts",        model: "openai/gpt-5.4-mini",        tts: {          provider: "openai",          openai: {            model: "gpt-4o-mini-tts",            voice: "cedar",          },        },      },    },  },}

Ví dụ bidi thời gian thực:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "bidi",        model: "openai-codex/gpt-5.5",        realtime: {          provider: "openai",          model: "gpt-realtime-2",          voice: "cedar",          toolPolicy: "safe-read-only",          consultPolicy: "always",        },      },    },  },}

Thoại dưới dạng phần mở rộng của một phiên kênh Discord hiện có:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "agent-proxy",        model: "openai-codex/gpt-5.5",        agentSession: {          mode: "target",          target: "channel:123456789012345678",        },        realtime: {          provider: "openai",          model: "gpt-realtime-2",          voice: "cedar",        },      },    },  },}

Trong chế độ agent-proxy, bot tham gia kênh thoại đã cấu hình, nhưng các lượt tác tử OpenClaw dùng phiên và tác tử được định tuyến bình thường của kênh đích. Phiên thoại thời gian thực nói kết quả trả về vào lại kênh thoại. Tác tử giám sát vẫn có thể dùng các công cụ tin nhắn bình thường theo chính sách công cụ của nó, bao gồm gửi một tin nhắn Discord riêng nếu đó là hành động phù hợp.

Các dạng đích hữu ích:

• target: "channel:123456789012345678" định tuyến qua một phiên kênh văn bản Discord.
• target: "123456789012345678" được xử lý như một đích kênh.
• target: "dm:123456789012345678" hoặc target: "user:123456789012345678" định tuyến qua phiên tin nhắn trực tiếp đó.

Ví dụ OpenAI Realtime nhiều vọng:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "bidi",        model: "openai-codex/gpt-5.5",        realtime: {          provider: "openai",          model: "gpt-realtime-2",          voice: "cedar",          bargeIn: true,          minBargeInAudioEndMs: 500,          consultPolicy: "always",          providers: {            openai: {              interruptResponseOnInputAudio: false,            },          },        },      },    },  },}

Dùng cấu hình này khi mô hình nghe thấy âm thanh phát lại của chính nó trên Discord qua mic đang mở, nhưng bạn vẫn muốn ngắt nó bằng cách nói. OpenClaw ngăn OpenAI tự động ngắt khi có âm thanh đầu vào thô, trong khi bargeIn: true cho phép các sự kiện bắt đầu nói của loa Discord và âm thanh của người nói đã hoạt động hủy các phản hồi thời gian thực đang hoạt động trước khi lượt thu âm tiếp theo đến OpenAI. Các tín hiệu ngắt lời rất sớm có audioEndMs thấp hơn minBargeInAudioEndMs được xem là có khả năng là tiếng vọng/nhiễu và bị bỏ qua để mô hình không bị ngắt ngay ở khung phát lại đầu tiên.

Nhật ký thoại dự kiến:

• Khi tham gia: discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=...
• Khi thời gian thực khởi động: discord voice: realtime bridge starting ... autoRespond=false interruptResponse=false bargeIn=false minBargeInAudioEndMs=...
• Khi có âm thanh từ người nói: discord voice: realtime speaker turn opened ..., discord voice: realtime input audio started ... outputAudioMs=... outputActive=..., và discord voice: realtime speaker turn closed ... chunks=... discordBytes=... realtimeBytes=... interruptedPlayback=...
• Khi bỏ qua lời nói cũ: discord voice: realtime forced agent consult skipped reason=incomplete-transcript ... hoặc reason=non-actionable-closing ...
• Khi phản hồi thời gian thực hoàn tất: discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=...
• Khi dừng/đặt lại phát lại: discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• Khi tham vấn thời gian thực: discord voice: realtime consult requested ... voiceSession=... supervisorSession=... question=...
• Khi agent trả lời: discord voice: agent turn answer ...
• Khi xếp hàng lời nói chính xác: discord voice: realtime exact speech queued ... queued=... outputAudioMs=... outputActive=..., theo sau là discord voice: realtime exact speech dequeued reason=player-idle ...
• Khi phát hiện ngắt lời: discord voice: realtime barge-in detected source=speaker-start ... hoặc discord voice: realtime barge-in detected source=active-speaker-audio ..., theo sau là discord voice: realtime barge-in requested reason=... outputAudioMs=... outputActive=...
• Khi ngắt thời gian thực: discord voice: realtime model interrupt requested client:response.cancel reason=barge-in, theo sau là discord voice: realtime model audio truncated client:conversation.item.truncate reason=barge-in audioEndMs=... hoặc discord voice: realtime model interrupt confirmed server:response.done status=cancelled ...
• Khi bỏ qua tiếng vọng/nhiễu: discord voice: realtime model interrupt ignored client:conversation.item.truncate.skipped reason=barge-in audioEndMs=0 minAudioEndMs=250
• Khi tắt ngắt lời: discord voice: realtime capture ignored during playback (barge-in disabled) ...
• Khi phát lại đang rảnh: discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0

Để gỡ lỗi âm thanh bị cắt, hãy đọc nhật ký thoại thời gian thực như một dòng thời gian:

1. realtime audio playback started nghĩa là Discord đã bắt đầu phát âm thanh của trợ lý. Từ thời điểm này, cầu nối bắt đầu đếm các đoạn đầu ra của trợ lý, byte PCM của Discord, byte thời gian thực của nhà cung cấp và thời lượng âm thanh tổng hợp.
2. realtime speaker turn opened đánh dấu một người nói Discord trở nên hoạt động. Nếu phát lại đã hoạt động và bargeIn được bật, điều này có thể được theo sau bởi barge-in detected source=speaker-start.
3. realtime input audio started đánh dấu khung âm thanh thực tế đầu tiên nhận được cho lượt nói đó. outputActive=true hoặc outputAudioMs khác 0 tại đây nghĩa là mic đang gửi đầu vào trong khi phát lại của trợ lý vẫn đang hoạt động.
4. barge-in detected source=active-speaker-audio nghĩa là OpenClaw đã thấy âm thanh người nói trực tiếp trong khi phát lại của trợ lý đang hoạt động. Điều này hữu ích để phân biệt một lần ngắt thực sự với sự kiện bắt đầu nói của Discord không có âm thanh hữu ích.
5. barge-in requested reason=... nghĩa là OpenClaw đã yêu cầu nhà cung cấp thời gian thực hủy hoặc cắt ngắn phản hồi đang hoạt động. Nhật ký này bao gồm outputAudioMs, outputActive, và playbackChunks để bạn có thể thấy thực tế đã phát bao nhiêu âm thanh của trợ lý trước khi bị ngắt.
6. realtime audio playback stopped reason=... là điểm đặt lại phát lại Discord cục bộ. Lý do cho biết ai đã dừng phát lại: barge-in, player-idle, provider-clear-audio, forced-agent-consult, stream-close, hoặc session-close.
7. realtime speaker turn closed tóm tắt lượt đầu vào đã thu. chunks=0 hoặc hasAudio=false nghĩa là lượt nói đã mở nhưng không có âm thanh dùng được đến cầu nối thời gian thực. interruptedPlayback=true nghĩa là lượt đầu vào đó chồng lấp với đầu ra của trợ lý và kích hoạt logic ngắt lời.

Các trường hữu ích:

• outputAudioMs: thời lượng âm thanh của trợ lý do nhà cung cấp thời gian thực tạo ra trước dòng nhật ký.
• audioMs: thời lượng âm thanh của trợ lý mà OpenClaw đã đếm trước khi phát lại dừng.
• elapsedMs: thời gian theo đồng hồ thực giữa lúc mở và đóng luồng phát lại hoặc lượt nói.
• discordBytes: byte PCM stereo 48 kHz được gửi đến hoặc nhận từ thoại Discord.
• realtimeBytes: byte PCM theo định dạng nhà cung cấp được gửi đến hoặc nhận từ nhà cung cấp thời gian thực.
• playbackChunks: các đoạn âm thanh của trợ lý được chuyển tiếp đến Discord cho phản hồi đang hoạt động.
• sinceLastAudioMs: khoảng cách giữa khung âm thanh người nói được thu cuối cùng và lúc lượt nói đóng.

Các mẫu thường gặp:

• Bị cắt ngay lập tức với source=active-speaker-audio, outputAudioMs nhỏ và cùng người dùng ở gần thường cho thấy tiếng vọng loa đi vào mic. Tăng voice.realtime.minBargeInAudioEndMs, giảm âm lượng loa, dùng tai nghe, hoặc đặt voice.realtime.providers.openai.interruptResponseOnInputAudio: false.
• source=speaker-start theo sau bởi speaker turn closed ... hasAudio=false nghĩa là Discord đã báo bắt đầu nói nhưng không có âm thanh nào đến OpenClaw. Đó có thể là sự kiện thoại Discord tạm thời, hành vi cổng nhiễu, hoặc một client bật mic trong chốc lát.
• audio playback stopped reason=stream-close mà không có ngắt lời gần đó hoặc provider-clear-audio nghĩa là luồng phát lại Discord cục bộ kết thúc ngoài dự kiến. Kiểm tra các nhật ký nhà cung cấp và trình phát Discord ngay trước đó.
• capture ignored during playback (barge-in disabled) nghĩa là OpenClaw cố ý bỏ đầu vào trong khi âm thanh của trợ lý đang hoạt động. Bật voice.realtime.bargeIn nếu bạn muốn lời nói ngắt phát lại.
• barge-in ignored ... outputActive=false nghĩa là VAD của Discord hoặc nhà cung cấp đã báo có lời nói, nhưng OpenClaw không có phát lại đang hoạt động để ngắt. Điều này không nên cắt âm thanh.

Thông tin xác thực được phân giải theo từng thành phần: xác thực tuyến LLM cho voice.model, xác thực STT cho tools.media.audio, xác thực TTS cho messages.tts/voice.tts, và xác thực nhà cung cấp thời gian thực cho voice.realtime.providers hoặc cấu hình xác thực thông thường của nhà cung cấp.

Tin nhắn thoại

Tin nhắn thoại Discord hiển thị bản xem trước dạng sóng và yêu cầu âm thanh OGG/Opus. OpenClaw tự động tạo dạng sóng, nhưng cần ffmpeg và ffprobe trên máy chủ Gateway để kiểm tra và chuyể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 từ chối văn bản + tin nhắn thoại trong cùng payload).
• Mọi định dạng âm thanh đề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 doctoropenclaw channels status --probeopenclaw logs --follow

{channels: {discord: {  accounts: {    default: {      eventQueue: {        listenerTimeout: 120000,      },    },  },},},}

{channels: {discord: {  accounts: {    mantis: {      // Mantis listens to other bots only when they mention her.      allowBots: "mentions",    },    molty: {      // Molty listens to all bot-authored Discord messages.      allowBots: true,      mentionAliases: {        // Lets Molty write "@Mantis" and send a real Discord mention.        Mantis: "MANTIS_DISCORD_USER_ID",      },    },  },},},}

Tài liệu tham khảo cấu hình

Tài liệu tham khảo chính: Tài liệu tham khảo cấu hình - Discord.

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 nguyên tắc ít đặc quyền nhất.
• 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