Discord

​

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

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

​

Model runtime

• Gateway sở hữu kết nối Discord.
• Định tuyến phản hồi mang tính xác định: phản hồi đầu vào từ Discord sẽ quay lại Discord.
• Siêu dữ liệu guild/kênh Discord được thêm vào prompt của mô hình dưới dạng ngữ cảnh không đáng tin cậy, không phải tiền tố phản hồi hiển thị với người dùng. Nếu mô hình sao chép phong bì đó trở lại, OpenClaw sẽ loại bỏ siêu dữ liệu đã 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), cuộc trò chuyện trực tiếp dùng chung phiên chính của agent (agent:main:main).
• Kênh guild là các khóa phiên biệt lập (agent:<agentId>:discord:channel:<channelId>).
• DM 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 biệt lập (agent:<agentId>:discord:slash:<userId>), trong khi vẫn mang CommandTargetSessionKey tới phiên hội thoại đã định tuyến.
• Việc gửi thông báo cron/heartbeat chỉ có văn bản tới Discord dùng câu trả lời cuối cùng hiển thị với assistant một lần. Payload phương tiện và thành phần có cấu trúc vẫn là nhiều tin nhắn khi agent phát ra nhiều payload có thể gửi.

​

Kênh diễn đàn

• Gửi tin nhắn tới cha diễn đàn (channel:<forumId>) để tự động tạo luồng. Tiêu đề luồng dùng dòng không rỗ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.

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ỏ tới 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

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

{
  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 agent 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 gốc 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 bỏ qua việc đăng ký và dọn dẹp lệnh slash Discord trong khi 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.
• Lệnh vẫn có thể hiển thị trong giao diện Discord với người dùng chưa được ủy quyền; khi thực thi vẫn áp dụng xác thực OpenClaw và trả về “not authorized”.

• ephemeral: true

​

Chi tiết tính năng

{
  channels: {
    discord: {
      suppressEmbeds: false,
    },
  },
}

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

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

• 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

​

UI components v2

• channels.discord.ui.components.accentColor đặt màu nhấn được các container component Discord sử dụng (hex).
• Đặt theo từng tài khoản với channels.discord.accounts.<id>.ui.components.accentColor.
• channels.discord.agentComponents.ttlMs kiểm soát thời gian các callback component Discord đã gửi còn được đăng ký (mặc định 1800000, tối đa 86400000). Đặt theo từng tài khoản với channels.discord.accounts.<id>.agentComponents.ttlMs.
• embeds bị bỏ qua khi components v2 có mặt.
• Bản xem trước URL thuần bị tắt theo mặc định. Đặt suppressEmbeds: false trên một hành động tin nhắn khi một liên kết gửi đi duy nhất nên được mở rộng.

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

​

Giọng nó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 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

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

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        model: "openai/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",
          speakerVoice: "cedar",
        },
      },
    },
  },
}

• voice.tts chỉ ghi đè messages.tts cho phát giọng nói stt-tts. Các chế độ realtime dùng voice.realtime.speakerVoice.
• voice.mode điều khiển đường dẫn hội thoại. Mặc định là agent-proxy: một giao diện giọng nói realtime 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 thực chất cho OpenClaw agent được định tuyến thông qua openclaw_agent_consult, rồi 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 realtime trò chuyện trực tiếp trong khi vẫn cung cấp openclaw_agent_consult cho bộ não OpenClaw.
• voice.agentSession điều khiển cuộc hội thoại OpenClaw nào nhận các lượt giọng nó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>" } để kênh thoại hoạt động 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 #maintainers.
• voice.model ghi đè bộ não OpenClaw agent cho phản hồi thoại Discord và các lượt tham vấn realtime. Để trống để kế thừa mô hình agent được định tuyến. Trường này tách biệt với voice.realtime.model.
• voice.followUsers cho phép bot tham gia, di chuyển và rời thoại Discord cùng các người dùng đã chọn. Xem Theo dõi người dùng trong thoại để biết quy tắc hành vi và ví dụ.
• agent-proxy định tuyến lời nói qua discord-voice, giữ nguyên quyền chủ sở hữu/công cụ thông thường cho người nói và phiên đích nhưng ẩn công cụ tts của agent 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 OpenClaw agent trước các câu trả lời thực chất (voice.realtime.consultPolicy: "always"). Trong chế độ always mặc định đó, lớp realtime không tự động nói phần đệm trước câu trả lời tham vấn; nó thu và phiên âm lời nói, rồi nói câu trả lời OpenClaw đã định tuyến. Nếu nhiều câu trả lời tham vấn bắt buộc hoàn tất khi Discord vẫn đang phát câu trả lời đầu tiên, các câu trả lời có lời nói chính xác sau đó sẽ đượ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 việc phiên âm.
• Trong các chế độ realtime, voice.realtime.provider, voice.realtime.model và voice.realtime.speakerVoice cấu hình phiên âm thanh realtime. 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/gpt-5.5".
• Các chế độ giọng nói realtime mặc định đưa các tệp hồ sơ nhỏ IDENTITY.md, USER.md và SOUL.md vào hướng dẫn của nhà cung cấp realtime để các lượt trực tiếp nhanh giữ cùng danh tính, nền tảng người dùng và persona như OpenClaw agent được định tuyến. Đặt voice.realtime.bootstrapContextFiles thành một tập con để tùy chỉnh điều này, hoặc [] để tắt. Các tệp bootstrap realtime được hỗ trợ chỉ giới hạn ở những tệp hồ sơ đó; AGENTS.md vẫn ở trong ngữ cảnh agent thông thường. Ngữ cảnh hồ sơ được chèn không thay thế openclaw_agent_consult cho công việc workspace, dữ kiện hiện tại, tra cứu bộ nhớ hoặc hành động có công cụ hỗ trợ.
• Trong chế độ realtime agent-proxy của OpenAI, đặt voice.realtime.requireWakeName: true để giữ thoại realtime Discord im lặng cho đến khi bản phiên âm bắt đầu hoặc kết thúc bằng tên đánh thức. Các tên đánh thức được cấu hình phải gồm một hoặc hai từ. Nếu voice.realtime.wakeNames chưa được đặt, OpenClaw dùng name của agent được định tuyến cộng với OpenClaw, rồi dự phòng về id agent cộng với OpenClaw. Cổng tên đánh thức tắt tự động phản hồi của nhà cung cấp realtime, định tuyến các lượt được chấp nhận qua đường dẫn tham vấn OpenClaw agent, và đưa ra một lời xác nhận ngắn khi tên đánh thức ở đầu được nhận diện từ phiên âm từng phần trước khi bản phiên âm cuối cùng đến.
• Nhà cung cấp realtime OpenAI chấp nhận tên sự kiện Realtime 2 hiện tại và các alias cũ tương thích với Codex cho sự kiện âm thanh đầu ra và phiên âm, nên các snapshot 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 điều khiển việc các sự kiện bắt đầu nói của người nói Discord có ngắt phát lại realtime đang hoạt động hay không. Nếu chưa đặt, nó tuân theo thiết lập ngắt âm thanh đầu vào của nhà cung cấp realtime.
• voice.realtime.minBargeInAudioEndMs điều khiển thời lượng phát lại trợ lý tối thiểu trước khi barge-in realtime của 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 lên cho thiết lập loa nhiều vọng.
• 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.providers.openai.speakerVoice. cedar là một lựa chọn có âm sắc nam tính tốt trên mô hình TTS OpenAI hiện tại.
• Các ghi đè systemPrompt theo kênh của Discord áp dụng cho 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ừ allowFrom của Discord (hoặc dm.allowFrom) cho các lệnh bị chặn theo chủ sở hữu và hành động kênh. Khả năng hiển thị công cụ agent tuân theo chính sách công cụ đã cấu hình cho phiên được định tuyến.
• Thoại Discord là tùy chọn bật cho 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à Gateway intent GuildVoiceStates.
• channels.discord.intents.voiceStates có thể ghi đè rõ ràng việc đăng ký intent trạng thái thoại. Để trống để intent tuân 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 tham gia kênh được cấu hình cuối cùng cho guild đó.
• voice.allowedChannels là một allowlist 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 khi 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 } đã liệt kê. Đặt thành mảng rỗng để từ chối mọi lượt tham gia thoại Discord. Nếu Discord di chuyển bot ra ngoài allowlist, OpenClaw rời kênh đó và tham gia lại đích auto-join đã cấu hình khi có sẵn.
• 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 dùng codec libopus-wasm đi kèm để nhận thoại Discord và phát lại PCM thô realtime. Nó phân phối một bản dựng WebAssembly libopus được ghim và không yêu cầu addon opus native.
• voice.connectTimeoutMs điều khiển thời gian chờ Ready ban đầu của @discordjs/voice cho các lần thử /vc join và auto-join. Mặc định: 30000.
• voice.reconnectGraceMs điều khiển 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 giọng nó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 âm thanh, 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 kết thúc cho lượt tiếp theo. Các chế độ realtime chuyển tiếp sự kiện người nói bắt đầu nói dưới dạng tín hiệu barge-in đến nhà cung cấp realtime.
• Trong các chế độ realtime, tiếng vọng từ loa vào mic mở có thể trông giống barge-in 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 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 realtime 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 điều khiển thời gian OpenClaw chờ sau khi Discord báo người nói đã dừng trước khi hoàn tất đoạn âm thanh đó cho STT. Mặc định: 2000; tăng giá trị này nếu Discord tách các khoảng ngừng bình thường thành bản phiên âm từng phần rời rạc.
• Khi ElevenLabs là nhà cung cấp TTS đã chọn, phát lại thoại Discord dùng TTS streaming và bắt đầu từ luồng phản hồi của nhà cung cấp. Nhà cung cấp không hỗ trợ streaming sẽ dự phòng về đường dẫn tệp tạm đã tổng hợp.
• OpenClaw cũng theo dõi 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ỗ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 đi kèm bao gồm bản sửa padding upstream từ PR discord.js #11449, đã đóng issue discord.js #11419.
• Các sự kiện nhận The operation was aborted là dự kiến khi OpenClaw hoàn tất một đ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 bản phiên âm STT một dòng có giới hạn cho mỗi đoạn người nói được chấp nhận, nên việc gỡ lỗi hiển thị cả phía người dùng và phía phản hồi agent mà không đổ văn bản phiên âm không giới hạn.
• Trong chế độ agent-proxy, 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 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 cần hành động như “be right back” hoặc “bye”. Log hiển thị forced agent consult skipped reason=... khi điều này ngăn một câu trả lời xếp hàng đã cũ.

​

Theo dõi người dùng trong thoại

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        followUsersEnabled: true,
        followUsers: ["discord:123456789012345678"],
        allowedChannels: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
      },
    },
  },
}

• followUsers chấp nhận ID người dùng Discord thô và các giá trị discord:<id>. OpenClaw chuẩn hóa cả hai dạng trước khi khớp sự kiện trạng thái thoại.
• followUsersEnabled mặc định là true khi followUsers được cấu hình. Đặt thành false để giữ danh sách đã lưu nhưng dừng theo dõi thoại tự động.
• Khi một người dùng được theo dõi tham gia kênh thoại được phép, OpenClaw tham gia kênh đó. Khi người dùng di chuyển, OpenClaw di chuyển cùng họ. Khi người dùng được theo dõi đang hoạt động ngắt kết nối, OpenClaw rời đi.
• Nếu nhiều người dùng được theo dõi ở cùng một guild và người dùng được theo dõi đang hoạt động rời đi, OpenClaw chuyển đến kênh của một người dùng được theo dõi khác trước khi rời guild. Nếu vài người dùng được theo dõi di chuyển cùng lúc, sự kiện trạng thái thoại được quan sát mới nhất sẽ thắng.
• allowedChannels vẫn áp dụng. Một người dùng được theo dõi trong kênh không được phép sẽ bị bỏ qua, và phiên do follow sở hữu sẽ chuyển đến một người dùng được theo dõi khác hoặc rời đi.
• OpenClaw đối chiếu các sự kiện trạng thái thoại bị bỏ lỡ khi khởi động và theo một khoảng thời gian có giới hạn. Đối chiếu lấy mẫu các guild đã cấu hình và giới hạn số lượt tra cứu REST mỗi lần chạy, nên các danh sách followUsers rất lớn có thể cần nhiều hơn một khoảng thời gian để hội tụ.
• Nếu Discord hoặc quản trị viên di chuyển bot trong khi nó đang theo dõi một người dùng, OpenClaw dựng lại phiên thoại và giữ quyền sở hữu follow khi đích đến được phép. Nếu bot bị di chuyển ra ngoài allowedChannels, OpenClaw rời đi và tham gia lại đích đã cấu hình khi có.
• Khôi phục nhận DAVE có thể rời và tham gia lại cùng kênh sau nhiều lỗi giải mã lặp lại. Các phiên do follow sở hữu giữ quyền sở hữu follow qua đường dẫn khôi phục đó, nên một lần ngắt kết nối sau đó của người dùng được theo dõi vẫn sẽ rời kênh.

• Dùng followUsers cho thiết lập cá nhân hoặc vận hành viên nơi bot nên tự động ở trong thoại khi bạn ở đó.
• Dùng autoJoin cho bot phòng cố định cần hiện diện ngay cả khi không có người dùng được theo dõi nào ở trong thoại.
• Dùng /vc join cho các lần tham gia một lần hoặc phòng nơi sự hiện diện thoại tự động sẽ gây bất ngờ.

• Nhật ký nhận giọng nói hiển thị discord voice: opus decoder: libopus-wasm.
• Phát lại thời gian thực mã hóa PCM stereo thô 48 kHz sang Opus bằng cùng gói libopus-wasm được đóng gói kèm trước khi chuyển các gói tin cho @discordjs/voice.
• Phát lại tệp và luồng nhà cung cấp chuyển mã sang PCM stereo thô 48 kHz bằng ffmpeg, sau đó dùng libopus-wasm cho luồng gói Opus gửi đến Discord.

• Bản ghi PCM của 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 chép lời được gửi qua luồ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 giọng nói ẩn công cụ tts của agent và yêu cầu trả về văn bản, vì giọng nói Discord sở hữu 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 hỗ trợ phát trực tiếp cấp dữ liệu trực tiếp cho trình phát, nếu không tệp âm thanh tạo ra sẽ được phát trong kênh đã tham gia.

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        model: "openai/gpt-5.5",
        followUsersEnabled: true,
        followUsers: ["123456789012345678"],
        realtime: {
          provider: "openai",
          model: "gpt-realtime-2",
          speakerVoice: "cedar",
        },
      },
    },
  },
}

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

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

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

• 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 đó.

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

• Khi tham gia: discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=...
• Khi bắt đầu thời gian thực: discord voice: realtime bridge starting ... autoRespond=false interruptResponse=false bargeIn=false minBargeInAudioEndMs=...
• Khi có âm thanh loa: 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 hoàn tất phản hồi thời gian thực: 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=..., tiếp theo là discord voice: realtime exact speech dequeued reason=player-idle ...
• Khi phát hiện chen ngang: discord voice: realtime barge-in detected source=speaker-start ... hoặc discord voice: realtime barge-in detected source=active-speaker-audio ..., tiếp theo 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, tiếp theo 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 chen ngang bị tắt: discord voice: realtime capture ignored during playback (barge-in disabled) ...
• Khi phát lại nhàn rỗi: discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0

1. realtime audio playback started nghĩa là Discord đã bắt đầu phát âm thanh của trợ lý. Cầu nối bắt đầu đếm các đoạn đầu ra của trợ lý, byte PCM Discord, byte thời gian thực của nhà cung cấp, và thời lượng âm thanh tổng hợp từ thời điểm này.
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 không ở đâ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ật với một 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. Nó bao gồm outputAudioMs, outputActive, và playbackChunks để bạn có thể thấy lượng âm thanh trợ lý thực sự đã phát 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 đã ghi. 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ào tới được 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 trợ lý và kích hoạt logic chen ngang.

• outputAudioMs: thời lượng âm thanh trợ lý do nhà cung cấp thời gian thực tạo trước dòng nhật ký.
• audioMs: thời lượng âm thanh trợ lý mà OpenClaw đã đếm trước khi phát lại dừng.
• elapsedMs: thời gian đồ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ừ giọng nó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 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 ghi cuối cùng và lúc lượt nói đóng.

• 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 chỉ ra 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 một lần bắt đầu nói nhưng không có âm thanh nào tới OpenClaw. Đó có thể là sự kiện giọng nói Discord nhất 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ó chen ngang 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 trước đó.
• capture ignored during playback (barge-in disabled) nghĩa là OpenClaw cố ý loại bỏ đầu vào trong khi âm thanh 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.

​

Tin nhắn thoại

• Cung cấp đường dẫn tệp cục bộ (URL sẽ 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).
• 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 doctor
openclaw channels status --probe
openclaw logs --follow

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

{
  channels: {
    defaults: {
      botLoopProtection: {
        maxEventsPerWindow: 20,
        windowSeconds: 60,
        cooldownSeconds: 60,
      },
    },
    discord: {
      // Optional Discord-wide override. Account blocks override individual
      // fields and inherit omitted fields from here.
      botLoopProtection: {
        maxEventsPerWindow: 4,
      },
      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 a Mantis Discord mention with the configured user id.
            Mantis: "MANTIS_DISCORD_USER_ID",
          },
          botLoopProtection: {
            // Allow up to five messages per minute before suppressing the pair.
            maxEventsPerWindow: 5,
            windowSeconds: 60,
            cooldownSeconds: 90,
          },
        },
      },
    },
  },
}

​

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 nguyên tắc đặ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