KNOWLEDGE BASE · OpenClaw教程

OpenClaw 与 Discord 完美联动：频道与心跳机制全解析

在使用 OpenClaw 与 Discord 联动时，许多用户都会遇到一个令人困惑的问题：明明收到了心跳信号，但消息却没有按照 session_id 推送到对应的频道。这其实是由于混淆了 Discord 网关层和 OpenClaw 应用层两个不同的系统所导致的。理解这两者之间的关系，对于正确配置和使用至关重要。

首先，我们需要明确几个关键概念。在 Discord 中，Server 也被称为 Guild，它下面包含多个文本频道（Channel），而每个频道内还可以有子线程（Thread）。此外，DM 指的是与用户的私聊，不属于 Guild 的范畴。而在 OpenClaw 中，消息并不是直接绑定在 Discord 的 UI 结构上，而是通过 Session Key 进行映射。例如，DM 通常会进入 main（默认）或 per-channel-peer（可配置）的会话中，而 Guild 频道则通常按 agent::discord:channel: 的格式进行隔离。

在配置文件中，你可能会看到类似以下的设置：'channels': {'CHANNEL_ID_CODE_LAB': {'allow': true, 'requireMention': false}, 'CHANNEL_ID_BRAINSTORM': {'allow': true, 'requireMention': false}}。这里的含义是允许特定的用户在指定的频道中触发机器人的能力，而 'requireMention': false 表示在该范围内不需要 @bot 也可以触发。这些设置主要解决的是“谁能在什么频道触发什么能力”的问题，而不是心跳信号的发送目标。

关于心跳信号，OpenClaw 和 Discord 都有各自的心跳机制。Discord Gateway 的心跳（op1/op11）主要用于断线恢复（Resume），而 OpenClaw 的心跳则是定时发送的 agent turn。OpenClaw 的心跳是否外发，以及发到哪个渠道，取决于配置中的 agents.defaults.heartbeat.session（运行上下文在哪个 Session）、agents.defaults.heartbeat.target（发送目标渠道，如 discord/last/none）和 agents.defaults.heartbeat.to（发送给谁，例如 channel: 或 user:）。简单来说，session 决定“在哪里思考”，而 target + to 则决定“往哪里发消息”。

如果你正在使用多频道分区和独立 Session 的配置思路，那么你已经走在了正确的道路上。例如，#code-lab 频道可以用于实操和执行任务，开放 read/exec/web_fetch 工具；而 #brainstorm 频道则适合讨论，建议减少高风险工具的使用；#moltbook-feed 频道可以用于通知和订阅汇总，减少交互频率。这种结构特别适合 OpenClaw 的使用场景，可以根据频道的职责进行策略性的配置，而不是依赖临时的 prompt。

以下是一个可以直接使用的配置模板：{'session': {'dmScope': 'per-channel-peer'}, 'channels': {'discord': {'token': '$', 'heartbeat': {'showOk': true, 'showAlerts': true}, 'guilds': {'GUILD_ID_REDACTED': {'requireMention': false, 'users': ['USER_ID_REDACTED'], 'tools': {'allow': ['read', 'exec', 'web_fetch'], 'deny': []}, 'channels': {'CHANNEL_ID_CODE_LAB': {'allow': true, 'requireMention': false}, 'CHANNEL_ID_BRAINSTORM': {'allow': true, 'requireMention': false}}}}}, 'agents': {'defaults': {'heartbeat': {'every': '30m', 'session': 'agent:YOUR_AGENT_ID:heartbeat', 'target': 'discord', 'to': 'channel:YOUR_CHANNEL_ID'}}}}。这个配置做了三件事：DM 不再全部挤进 main（降低上下文串线），heartbeat 用独立 session 跑（不污染日常对话），heartbeat 固定发 #code-lab 或你指定的频道。

如果你不想手动修改 JSON，可以使用一键命令版进行配置：openclaw config set agents.defaults.heartbeat.target 'discord'，openclaw config set agents.defaults.heartbeat.to 'channel:YOUR_CHANNEL_ID'，openclaw config set channels.discord.heartbeat.showOk true --json，openclaw config set session.dmScope 'per-channel-peer'，openclaw config set agents.defaults.heartbeat.session 'agent:YOUR_AGENT_ID:heartbeat'，openclaw system event --text 'heartbeat test' --mode now。如果你想静默运行，不发外部消息，可以将 target 设置为 'none'。

最后，关于 Bot 的添加与权限配置，建议在 Discord Developer Portal 中创建 Bot 并复制 Token，然后打开必要的 Intents，如 Guild Messages、Direct Messages 和 Message Content 等。在 OAuth2 中邀请 Bot 到目标 Guild，并授予 View Channels、Send Messages 和 Read Message History 等权限。建议采用最小权限原则，不要一开始就授予 Administrator 权限。在 OpenClaw 侧，最小配置包括设置 channels.discord.token 或环境变量 DISCORD_BOT_TOKEN，以及配置 channels.discord.guilds..channels..allow=true。如果需要免 @ 触发，可以将 requireMention 设置为 false。

📖 原文链接：https://studyopenclaw.cn/?p=2758

OpenClaw 知识库 · OpenClaw教程