入站和出站 Discord 消息的路由、格式化、确认与预览¶
运行时模型¶
- 网关拥有 Discord 连接。
- 回复路由是确定性的:Discord 入站回复会路由回 Discord。
- Bot 回复和绑定线程的人设回复共享 Markdown 格式化,包括 CommonMark 粗体和已配置的表格转换。
- 两条投递路径都会在格式化和提及展开之后重新应用调用方提供的字符限制。
- 转发消息快照会连同任何随附说明文字一起送达代理。转发文本不会被当作键入的命令;命令分类只使用发送者自己的消息文本。
- Discord 服务器/频道元数据会作为不可信上下文添加到模型 prompt,而不是作为用户可见的回复前缀。如果模型将该信封复制回来,OpenClaw 会从出站回复和未来的重放上下文中剥离复制的元数据。
- 默认情况下(
session.dmScope=main),私聊共享代理主会话(agent:main:main)。 - 服务器频道使用独立的会话键(
agent:<agentId>:discord:channel:<channelId>)。 - 默认忽略群组私信(
channels.discord.dm.groupEnabled=false)。 - 原生斜杠命令在独立的命令会话中运行(
agent:<agentId>:discord:slash:<userId>),同时仍携带CommandTargetSessionKey指向路由后的对话会话。 - 仅包含文本的 cron/heartbeat 公告投递到 Discord 时会合并为最终的助手可见回答,并只发送一次。当代理发出多个可投递的负载时,媒体和结构化组件负载仍会作为多条消息发送。
- 没有 Discord 消息 ID 的发送响应会保持未确认状态。排队投递会记录缺失的身份信息以便恢复,而不会报告成功或立即发送重复消息;可使用
openclaw health --verbose检查投递警告。
当较早的消息在等待处理时,同一频道中的后续消息仍会进入回复队列。Discord 消息使用持久化入站准入,因此 collect 会将排队的消息保留为独立的后续轮次,就像 followup 一样。这可以防止一条消息在另一条消息拒绝合并轮次之前就被提交。延迟一条消息会保留其持久化恢复状态。
消息行为¶
加入服务器时的介绍
当 Bot 加入一个允许的 Discord 服务器时,OpenClaw 会发送一次针对该房间的介绍。如果 Bot 能查看系统频道并发送消息,则优先使用服务器的系统频道;否则,使用第一个同时具有查看频道和发送消息权限的文本频道。如果没有符合条件的频道,则不发送介绍。
介绍会使用频道名称和主题,并在可用时使用最近的消息。读取更早的消息也需要查看消息历史权限;当该权限缺失时,OpenClaw 仍会使用频道元数据来介绍自己,而不会失败。
介绍默认启用,仅适用于新加入的服务器,且绝不会在私聊中运行。设置 channels.discord.joinIntro: false 可禁用,或设置 channels.discord.accounts.<accountId>.joinIntro 来覆盖单个账户。有关历史记录限制、目标频道选择、每房间只执行一次的行为以及不可信内容处理的详细信息,请参阅群组加入介绍。
回复标签与原生回复
Discord 支持在代理输出中使用回复标签:
[[reply_to_current]][[reply_to:<id>]]
由 channels.discord.replyToMode 控制:
off(默认):不进行隐式回复线程;显式[[reply_to_*]]标签仍会被处理first:将隐式原生回复引用附加到该轮次的第一个出站 Discord 消息all:将其附加到每个出站消息batched:仅当入站事件是去抖(debounced)的多消息批次时附加——适用于你希望主要针对模糊的突发性聊天使用原生回复,而不希望针对每一次单消息轮次都使用的情况
消息 ID 会显示在上下文/历史中,以便代理定位特定消息。对 Bot 消息的回复(包括自动化告警)会在上下文可见性允许时保留被引用文本作为不可信上下文。Bot 自身的入站事件仍会被忽略,并且被引用的自产媒体不会再次下载。 分块人设投递回执会保留为每个块选择的回复目标。
链接预览
Discord 默认会为 URL 生成富链接嵌入(embeds)。OpenClaw 默认在出站 Discord 消息上抑制这些自动生成的嵌入,因此代理发送的 URL 会保持为纯链接,除非你选择启用:
设置 `channels.discord.accounts.<id>.suppressEmbeds` 可覆盖单个账户。代理的消息工具发送也可以为单条消息传入 `suppressEmbeds: false`。显式的 Discord `embeds` 负载不会被默认链接预览设置抑制。
流式预览
OpenClaw 可以通过发送临时消息并随着文本到达而编辑它来流式输出草稿回复。Discord 预览流式输出默认为 `off`;将 `channels.discord.streaming.mode` 设置为 `partial`、`block` 或 `progress` 即可选择启用。`streamMode` 是旧版别名;运行 `openclaw doctor --fix` 将持久化配置重写为规范的嵌套 `streaming` 结构。
{
channels: {
discord: {
streaming: {
mode: "progress",
progress: {
maxLines: 8,
maxLineChars: 120,
toolProgress: false,
commentary: false,
},
},
},
},
}
- `off` 禁用 Discord 预览编辑。
- `partial` 在 token 到达时编辑单条预览消息。
- `block` 发出草稿尺寸的块;使用 `streaming.preview.chunk`(`minChars`、`maxChars`、`breakPreference`)调整大小和断点,并被限制在 `textChunkLimit` 内。显式的非 `off` 预览模式会覆盖继承的 `agents.defaults.blockStreamingDefault: "on"`;显式的 `streaming.block.enabled: true` 会覆盖预览。如果某个轮次无法使用预览,继承的分块投递仍会生效。
- `progress` 在最终投递前保留一个可编辑的状态草稿。默认情况下它是安静的:代理最新的开场白或叙述作为状态标题行,💬 评注和 🧠 推理在流式输出时显示,✅ / ▸ / ▢ 计划步骤,以及任何审批请求或失败的命令。普通工具调用不会添加行。
- 媒体、错误和显式回复的最终结果会取消待处理的预览编辑。
- `streaming.progress.toolProgress: true` 会在标题行下方添加滚动的工具日志:例如 `🛠️ Exec: running` 或 `📖 Read from notes.txt` 这样的行(默认 `false`)。每个工具行以该工具的文本图标开头。`streaming.preview.toolProgress` 控制 `partial` 和 `block` 模式下的工具行,默认值为 `true`。
- `streaming.progress.commentary`(默认 `false`)选择在临时进度草稿中加入原始助手评注。默认的开场白/叙述状态行与此选项无关。评注在显示前会被清理、保持临时性,并且不会改变最终回答的投递。
- `streaming.progress.maxLineChars` 控制每行进度预览的预算。文本会在单词边界处缩短;命令和路径细节保留有用的后缀。
- `streaming.preview.commandText` / `streaming.progress.commandText` 控制紧凑进度行中的命令/执行细节:`status`(默认,仅工具标签)或 `raw`(显式命令文本)。
显示滚动工具日志,同时隐藏原始命令/执行文本:
```json
{
"channels": {
"discord": {
"streaming": {
"mode": "progress",
"progress": {
"toolProgress": true,
"commandText": "status"
}
}
}
}
}
```
预览流式传输仅支持文本;媒体回复将回退到正常投递。
确认表情回应
状态表情回应会在整个处理过程中保持确认状态稳定。它们不会为每个工具添加表情、不活动警告或成功闪烁。实际失败会保留错误表情回应生命周期。
`ackReaction` 会在 OpenClaw 处理传入消息时发送一个确认表情。
解析顺序:
- `channels.discord.accounts.<accountId>.ackReaction`
- `channels.discord.ackReaction`
- `messages.ackReaction`
- 代理身份表情回退(`agents.entries.*.identity.emoji`,否则为 "👀")
说明:
- Discord 接受 Unicode 表情或自定义表情名称。
- 使用 `""` 可禁用某个频道或账号的表情回应。
**作用范围(`messages.ackReactionScope`):**
取值:`"all"`(私信 + 群组,包括环境房间事件)、`"direct"`(仅私信)、`"group-all"`(除环境房间事件外的所有群组消息,无私信)、`"group-mentions"`(机器人被提及时的群组;**无私信**,默认)、`"off"` / `"none"`(禁用)。
Note
默认作用范围("group-mentions")不会在私信或环境房间事件中触发确认表情回应。若要在传入的 Discord 私信和安静房间事件中获取确认表情回应,请将 messages.ackReactionScope 设置为 "all"。
出站提及别名
当代理需要为已知的 Discord 用户生成确定性的出站提及时,请使用 `mentionAliases`。键为不带前导 `@` 的句柄;值为 Discord 用户 ID。未知句柄、`@everyone`、`@here` 以及 Markdown 代码片段中的提及将保持不变。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw