Discord

Documentation Index

Fetch the complete documentation index at: https://docs2.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=...

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

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

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
• Kiểu 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 đó 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
• 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

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

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

• 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

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

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

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

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

OPENCLAW_DISCORD_OPUS_DECODER=native pnpm gateway:watch

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

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

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

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

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

• 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-codex/gpt-5.5",
        realtime: {
          provider: "openai",
          model: "gpt-realtime-2",
          voice: "cedar",
          bargeIn: true,
          minBargeInAudioEndMs: 500,
          consultPolicy: "always",
          providers: {
            openai: {
              interruptResponseOnInputAudio: false,
            },
          },
        },
      },
    },
  },
}

• 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

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.

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

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

​

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

​

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