$cd ../troubleshooting/
High🔗 Connectivity
Discord 机器人加入服务器但不读消息 — 缺失 Intents
// OpenClaw Discord 机器人显示在线、可能响应很久以前注册的斜杠命令，但完全忽略普通频道消息与 DM。这是典型的 Privileged Gateway Intent 缺口：除非在 Developer Portal 启用 Message Content Intent，Discord 不会向机器人提供消息正文。部分配置还需 Server Members Intent 以解析昵称或基于角色的路由。机器人已连接——Discord 只是不投递 OpenClaw 需要的事件。本非官方指南涵盖启用 intents、用 bot + applications.commands 范围生成新 OAuth 邀请、更新 openclaw.json 通道配置并重启 gateway，使消息处理器真正触发。
diagnose.sh
🔍 这是您的问题吗？
?机器人在 Discord 显示在线但忽略纯文本消息
?斜杠命令可能可用而普通聊天不行
?Gateway 日志显示连接正常但无消息处理器触发
?从未在 Discord Developer Portal 启用 Message Content Intent
?在启用 intents 前邀请 bot——仍用同一邀请链接
portal_intents.md
✅ 修复方法 1 — 在 Portal 启用 Privileged Gateway Intents
Portal 开关——Message Content 是常见修复点
# 浏览器：discord.com/developers/applications # 1. 选择 bot 应用 # 2. Bot → Privileged Gateway Intents # 3. 启用： # ☑ MESSAGE CONTENT INTENT（必需） # ☑ SERVER MEMBERS INTENT（若用角色/昵称） # 4. Save Changes
Token 在 OpenClaw 配置中，不要截图到公开处
# 可选：记下 Application ID（Client ID） # Bot 标签 → Token → 仅在泄露时 Reset Token # 勿分享 token；设置在 ~/.openclaw/.env： # DISCORD_BOT_TOKEN=your_token_here
invite_url.txt
✅ 修复方法 2 — 用正确 Scope 重新生成机器人邀请
更改 intent 后使用新邀请
# 生成邀请 URL（替换 CLIENT_ID） https://discord.com/api/oauth2/authorize?client_id=CLIENT_ID&permissions=2147875840&scope=bot%20applications.commands # permissions 含 Send Messages、Read History 等 # scope 须含 bot 与 applications.commands
喜欢点选可用 URL Generator
# 重新添加 bot 或踢出再邀请 # Portal 中 OAuth2 → URL Generator 等效 # 必需 scopes：bot、applications.commands # Bot 权限：Read Messages、Send Messages、 # Read Message History、Embed Links、Attach Files
openclaw.json
✅ 修复方法 3 — 更新配置并重启 Gateway
Allowlist guild/channel ID——空配置会忽略消息
// ~/.openclaw/openclaw.json — discord 通道
{
"channels": {
"discord": {
"enabled": true,
"tokenEnv": "DISCORD_BOT_TOKEN",
"guilds": {
"YOUR_GUILD_ID": {
"channels": ["YOUR_CHANNEL_ID"]
}
}
}
}
}portal 与配置变更后需重启
openclaw doctor openclaw gateway restart # 在允许频道发测试消息 # 查看日志： openclaw logs --follow | grep -i discord
💡 专业技巧：更改 Intent 后重新邀请
在 portal 切换 intent 不会 retroactive 修复旧的服务器授权。踢出机器人或使用相同 client ID 的新邀请 URL，在测试 agent 回复前先在 gateway debug 日志中确认 MESSAGE_CREATE 事件出现。
🛡️ 预防清单
- • 首次生产邀请前启用 Message Content Intent——在 runbook 中记录 portal URL
- • bot token 仅放在 ~/.openclaw/.env 或 openclaw.json——粘贴到 Discord 工单请轮换
- • 开发与生产机器人用不同 Discord Application，避免 intent 实验搞挂线上服
- • portal 变更后始终重启 gateway 并查看 GatewayIntentBits 警告
- • 100+ 服务器机器人需确认 Discord 对 privileged intents 的 verified-bot 要求
❓ 常见问题
Q1. OpenClaw Discord 需要哪些 intents？
至少：Guilds、Guild Messages、Message Content（privileged）、Direct Messages。Message Content 是最常被遗漏的——没有它 MESSAGE_CREATE 事件的 content 字段为空。若配置将 Discord 角色映射到 agent 权限或按显示名 @ 用户，Server Members Intent 有帮助。除非做 presence 感知自动化，Presence Intent 很少需要。查看您版本 Discord 通道适配器的默认 intent 集。
Q2. 测试服能读消息另一个服不能——为什么？
Intents 按应用全局生效，但 openclaw.json 的通道 allowlist 可能限制 OpenClaw 处理哪些 guild ID 或 channel ID。channels.discord.guilds 缺少 guild id 即忽略。还需确认机器人在该服频道 override 中有 Read Message History 与 View Channels。@everyone 拒绝规则会在 intent 正确时仍静默拦截 bot。
Q3. 没有 Message Content Intent 斜杠命令能用吗？
能。斜杠命令用 interaction 事件，不依赖 message content。许多用户因 /ping 有响应以为 bot「正常」，而自由文本被忽略——这几乎总是 Message Content Intent 未开。启用后重启 gateway，发 plain text hello（非斜杠）确认。
Q4. Discord 要求验证 bot 才能用 Message Content——怎么办？
Discord 对 100+ 服务器且使用 Message Content Intent 的 bot 要求身份验证。百服以下的 homelab bot 通常可直接打开开关。若遇验证墙，完成 Discord 开发者验证流程，或暂用仅斜杠/线程触发直到通过。社区 Mac Mini 部署通常低于阈值。
Q5. OpenClaw 里 Discord bot token 放哪？
在 ~/.openclaw/openclaw.json 的 channels.discord.token，或通过 tokenEnv 指向 ~/.openclaw/.env 的 DISCORD_BOT_TOKEN。切勿提交 token。portal 轮换 token 后更新配置并重启 gateway。无效 token 日志为登录失败——与 intent 问题（登录成功但消息为空）不同。
Q6. 如何在日志中确认 intents 生效？
设 log_level: debug，重启 gateway，在允许的频道发测试消息。查找带非空 content 的 MESSAGE_CREATE 或 discord:message 处理。'Received message with empty content' 或 intent bitmask 警告指回 portal 开关。官方项目：github.com/openclaw/openclaw。