Discord 交互组件 (Components v2)

使用 message 工具的 components 参数在 Discord 中发送丰富、交互式消息。这将纯文本替换为按钮、选择菜单、模态框和结构化布局。

何时使用 Components v2

当以下情况时，始终优先使用组件而非纯文本：

• - 需要用户确认 → 按钮（是/否，批准/拒绝）
• 需要用户选择 → 选择菜单（代理、优先级、选项）
• 需要结构化信息展示 → 文本块 + 分区 + 分隔线
• 需要收集表单数据 → 带文本输入、选择、复选框的模态框
• 需要视觉区分 → 强调色容器

使用纯文本的情况：

• - 简单的对话回复，无需操作
• 快速的一行回答

快速参考

components 参数是一个具有以下结构的对象：

json5
{
// 顶层字段
text: 可选的顶层文本（作为第一个 TextDisplay 渲染）,
reusable: true, // 保持按钮/选择菜单可多次点击（默认：单次使用）
container: {
accentColor: #3498db, // 左边框颜色（十六进制字符串或数字）
spoiler: false
},
// 内容块（按顺序在容器内渲染）
blocks: [
{ type: text, text: Markdown 文本块 },
{ type: section, text: 主要文本, accessory: { type: thumbnail, url: https://... } },
{ type: separator, spacing: small, divider: true },
{ type: actions, buttons: [{ label: 点击我, style: success }] },
{ type: actions, select: { type: string, placeholder: 选择..., options: [...] } },
{ type: media-gallery, items: [{ url: https://..., description: ... }] },
{ type: file, file: attachment://report.pdf }
],
// 可选的模态框表单（自动生成触发按钮）
modal: {
title: 表单标题,
triggerLabel: 打开表单,
fields: [{ type: text, label: 您的姓名 }]
}
}

快速入门 — 确认

json5
// message 工具调用
{
action: send,
channel: discord,
target: channel:频道ID,
components: {
text: 确认操作？,
reusable: false,
container: { accentColor: #3498db },
blocks: [
{
type: actions,
buttons: [
{ label: 是, style: success },
{ label: 否, style: secondary }
]
}
]
}
}

无需 custom_id — OpenClaw 会自动生成唯一 ID。当用户点击时，您会收到类似 点击了是 的消息。

与原始 Discord API 的关键区别

块类型摘要

处理交互

当用户点击按钮或选择选项时，OpenClaw 将其作为普通入站消息传递：

• - 按钮点击 → 点击了是
• 选择 → 从选择一个选项中选择了 option_a

无需特殊的回调处理 — 只需读取传入的消息文本。参见 handling.md 了解模式。

重要规则

• - 无需 custom_id — OpenClaw 自动为所有交互元素生成唯一 ID
• 无需 embeds — Components v2 和 embeds 不能共存于同一条消息中
• reusable: true — 设置此选项以允许按钮/选择菜单被多次点击
• allowedUsers — 可选地限制谁可以点击按钮（Discord 用户 ID 数组）
• Actions 块 — 必须包含 buttons 或 select 其中之一，不能同时包含两者
• 每个 actions 块最多 5 个按钮，每个 actions 块最多 1 个选择菜单

示例

参见 references/examples.md 了解完整场景：

• - 是/否确认
• 代理/选项选择
• 带操作的状态卡片
• 模态框表单收集
• 多步骤工作流