Discord（Bot API）

连接 Discord。Bot token 与服务器设置。状态：通过官方 Discord bot 网关支持私聊与服务器文本频道。

快速设置（入门）

创建 Discord 机器人并复制 Bot Token。
在 Discord 应用设置中启用 Message Content Intent（若使用白名单或名称查询，再启用 Server Members Intent）。
为 Moltbot 设置 token：
- 环境变量：DISCORD_BOT_TOKEN=...
- 或配置：channels.discord.token: "..."。
- 若两者都设，以配置为准（环境变量仅作默认账号回退）。
用消息权限将机器人邀请到你的服务器（若只要私聊可建私有服务器）。
启动网关。
私聊默认配对；首次联系时批准配对码。

最小配置：


{
  channels: {
    discord: {
      enabled: true,
      token: "YOUR_BOT_TOKEN"
    }
  }
}

目标

通过 Discord 私聊或服务器频道与 Moltbot 对话。
私聊并入 agent 主会话（默认 agent:main:main）；服务器频道独立为 agent:<agentId>:discord:channel:<channelId>（显示名用 discord:<guildSlug>#<channelSlug>）。
群组私聊默认忽略；通过 channels.discord.dm.groupEnabled 启用，可选 channels.discord.dm.groupChannels 限制。
保持确定性路由：回复始终发回消息来源频道。

工作原理

创建 Discord 应用 → Bot，启用所需 intents（私聊 + 服务器消息 + 消息内容），获取 Bot Token。
用在你打算使用的频道所需的读/发消息权限邀请机器人到服务器。
用 channels.discord.token（或回退用 DISCORD_BOT_TOKEN）配置 Moltbot。
运行网关；有 token 且 channels.discord.enabled 不为 false 时自动启动 Discord 频道（先看配置，再回退环境变量）。
- 若偏好环境变量，设 DISCORD_BOT_TOKEN（配置块可选）。
私聊：投递时用 user:<id>（或 <@id> 提及）；所有轮次进入共享的 main 会话。裸数字 ID 歧义会被拒绝。
服务器频道：投递用 channel:<channelId>。默认需 @ 提及，可按服务器或频道设置。
私聊：默认通过 channels.discord.dm.policy（默认 "pairing"）保护。未知发件人收到配对码（1 小时后过期）；用 moltbot pairing approve discord <code> 批准。
- 保持旧「对所有人开放」：设 channels.discord.dm.policy="open" 且 channels.discord.dm.allowFrom=["*"]。
- 硬白名单：设 channels.discord.dm.policy="allowlist" 并在 channels.discord.dm.allowFrom 中列出发件人。
- 忽略所有私聊：设 channels.discord.dm.enabled=false 或 channels.discord.dm.policy="disabled"。
群组私聊默认忽略；通过 channels.discord.dm.groupEnabled 启用，可选 channels.discord.dm.groupChannels 限制。
可选服务器规则：用 guild id（推荐）或 slug 作键设置 channels.discord.guilds，内含每频道规则。
可选原生命令：commands.native 默认 "auto"（Discord/Telegram 开，Slack 关）。用 channels.discord.commands.native: true|false|"auto" 覆盖；false 会清除已注册命令。文本命令由 commands.text 控制，须以单独 /... 消息发送。用 commands.useAccessGroups: false 跳过命令的访问组检查。
- 完整命令列表与配置：斜杠命令
可选服务器上下文历史：设 channels.discord.historyLimit（默认 20，回退到 messages.groupChat.historyLimit）在回复 @ 提及时包含最近 N 条服务器消息。设 0 禁用。
表态：agent 可通过 discord 工具触发表态（受 channels.discord.actions.* 控制）。
- 表态移除语义见表态。
- 仅当当前频道为 Discord 时暴露 discord 工具。
原生命令使用独立会话键（agent:<agentId>:discord:slash:<userId>），而非共享的 main 会话。

说明：名称 → id 解析使用服务器成员搜索，需 Server Members Intent；若机器人无法搜索成员，请用 id 或 <@id> 提及。说明：slug 为小写、空格替换为 -。频道名 slug 不含前导 #。说明：服务器上下文的 [from:] 行包含 author.tag + id，便于 @ 回复。

配置写入

默认允许 Discord 写入由 /config set|unset 触发的配置更新（需 commands.config: true）。禁用方式：


{
  channels: { discord: { configWrites: false } }
}

如何创建自己的机器人

这是在「Discord Developer Portal」中为在服务器（guild）频道（如 #help）运行 Moltbot 的设置。

1) 创建 Discord 应用与 Bot 用户

Discord Developer Portal → Applications → New Application
在你的应用中：
- Bot → Add Bot
- 复制 Bot Token（即填入 DISCORD_BOT_TOKEN 的内容）

2) 启用 Moltbot 需要的 Gateway Intents

除非显式启用，Discord 会阻止「privileged intents」。在 Bot → Privileged Gateway Intents 中启用：

Message Content Intent（多数服务器中读取消息文本必需；否则会看到「Used disallowed intents」或机器人连上但不响应消息）
Server Members Intent（推荐；部分成员/用户查询及服务器内白名单匹配需要）

一般不需要 Presence Intent。

3) 生成邀请链接（OAuth2 URL Generator）

应用中：OAuth2 → URL Generator → Scopes

✅ bot
✅ applications.commands（原生命令必需）

Bot Permissions（最小基线）

✅ View Channels
✅ Send Messages
✅ Read Message History
✅ Embed Links
✅ Attach Files
✅ Add Reactions（可选但推荐）
✅ Use External Emojis / Stickers（可选；按需）

除非在调试且完全信任机器人，否则避免 Administrator。复制生成的 URL，打开后选择服务器并安装机器人。

4) 获取 ID（服务器/用户/频道）

Discord 处处用数字 id；Moltbot 配置建议用 id。

Discord（桌面/网页）→ User Settings → Advanced → 启用 Developer Mode
右键：
- 服务器名 → Copy Server ID（guild id）
- 频道（如 #help）→ Copy Channel ID
- 你的用户 → Copy User ID

5) 配置 Moltbot

Token

通过环境变量设置 Bot Token（服务器上推荐）：

DISCORD_BOT_TOKEN=...

或通过配置：


{
  channels: {
    discord: {
      enabled: true,
      token: "YOUR_BOT_TOKEN"
    }
  }
}

多账号：使用 channels.discord.accounts，每账号单独 token 并可设 name。共享模式见配置。

白名单与频道路由

示例「单服务器、只允许我、只允许 #help」：


{
  channels: {
    discord: {
      enabled: true,
      dm: { enabled: false },
      guilds: {
        "YOUR_GUILD_ID": {
          users: ["YOUR_USER_ID"],
          requireMention: true,
          channels: {
            help: { allow: true, requireMention: true }
          }
        }
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1
      }
    }
  }
}

说明：

requireMention: true 表示机器人仅在被人 @ 时回复（共享频道推荐）。
agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns）在服务器消息中也算作 @ 提及。
多 agent 覆盖：在 agents.list[].groupChat.mentionPatterns 上设每 agent 规则。
若配置了 channels，未列出的频道默认拒绝。
用 "*" 频道条目对所有频道应用默认；显式频道条目覆盖通配符。
主题继承父频道配置（白名单、requireMention、skills、prompts 等），除非显式加入主题频道 id。
默认忽略机器人发出的消息；设 channels.discord.allowBots=true 可允许（自己的消息仍被过滤）。
警告：若允许回复其他机器人（channels.discord.allowBots=true），请用 requireMention、channels.discord.guilds.*.channels.<id>.users 白名单和/或 AGENTS.md、SOUL.md 中的护栏避免机器人间回环。

6) 验证是否正常

启动网关。
在服务器频道发送：@Krill hello（或你的机器人名称）。
若无反应：见下方 故障排查。

故障排查

先运行：moltbot doctor 和 moltbot channels status --probe（可操作警告与快速检查）。
「Used disallowed intents」：在 Developer Portal 中启用 Message Content Intent（及通常 Server Members Intent），然后重启网关。
机器人连上但从不回复服务器频道：
- 缺少 Message Content Intent，或
- 机器人缺少频道权限（View/Send/Read History），或
- 配置要求 @ 提及但你没 @，或
- 服务器/频道白名单拒绝了该频道/用户。
requireMention: false 仍无回复：channels.discord.groupPolicy 默认为 allowlist；设为 "open" 或在 channels.discord.guilds 下添加服务器条目（可选在 channels.discord.guilds.<id>.channels 下列出频道以限制）。
- 若只设了 DISCORD_BOT_TOKEN 且从未建 channels.discord 段，运行时会默认 groupPolicy 为 open。可加 channels.discord.groupPolicy、channels.defaults.groupPolicy 或服务器/频道白名单收紧。
requireMention 必须写在 channels.discord.guilds（或具体频道）下。顶层的 channels.discord.requireMention 会被忽略。
权限检查（channels status --probe）只检查数字频道 ID。若用 slug/名称作 channels.discord.guilds.*.channels 的键，检查无法验证权限。
私聊不工作：channels.discord.dm.enabled=false、channels.discord.dm.policy="disabled"，或你尚未被批准（channels.discord.dm.policy="pairing"）。

能力与限制

私聊与服务器文本频道（主题视为独立频道；不支持语音）。
输入中尽力发送；消息分块使用 channels.discord.textChunkLimit（默认 2000）并按行数拆分长回复（channels.discord.maxLinesPerMessage，默认 17）。
可选按换行分块：设 channels.discord.chunkMode="newline" 在按长度分块前按空行（段落边界）拆分。
文件上传受 channels.discord.mediaMaxMb 限制（默认 8 MB）。
默认服务器回复需 @ 提及，避免机器人刷屏。
消息引用另一条消息时注入回复上下文（引用内容 + id）。
原生回复主题默认关闭；用 channels.discord.replyToMode 与回复标签启用。

重试策略

出站 Discord API 在 429 限速时按 Discord 的 retry_after（若有）重试，带指数退避与抖动。通过 channels.discord.retry 配置。见重试策略。

配置


{
  channels: {
    discord: {
      enabled: true,
      token: "abc.123",
      groupPolicy: "allowlist",
      guilds: {
        "*": {
          channels: {
            general: { allow: true }
          }
        }
      },
      mediaMaxMb: 8,
      actions: {
        reactions: true,
        stickers: true,
        emojiUploads: true,
        stickerUploads: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        channels: true,
        voiceStatus: true,
        events: true,
        moderation: false
      },
      replyToMode: "off",
      dm: {
        enabled: true,
        policy: "pairing", // pairing | allowlist | open | disabled
        allowFrom: ["123456789012345678", "steipete"],
        groupEnabled: false,
        groupChannels: ["clawd-dm"]
      },
      guilds: {
        "*": { requireMention: true },
        "123456789012345678": {
          slug: "friends-of-clawd",
          requireMention: false,
          reactionNotifications: "own",
          users: ["987654321098765432", "steipete"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["search", "docs"],
              systemPrompt: "Keep answers short."
            }
          }
        }
      }
    }
  }
}

确认表态由全局的 messages.ackReaction 与 messages.ackReactionScope 控制。用 messages.removeAckAfterReply 在机器人回复后清除确认表态。

dm.enabled：设 false 忽略所有私聊（默认 true）。
dm.policy：私聊访问控制（推荐 pairing）。"open" 需 dm.allowFrom=["*"]。
dm.allowFrom：私聊白名单（用户 id 或名称）。用于 dm.policy="allowlist" 及 dm.policy="open" 校验。向导接受用户名并在机器人能搜索成员时解析为 id。
dm.groupEnabled：启用群组私聊（默认 false）。
dm.groupChannels：群组私聊频道 id 或 slug 的可选白名单。
groupPolicy：服务器频道处理（open|disabled|allowlist）；allowlist 需频道白名单。
guilds：以 guild id（推荐）或 slug 为键的每服务器规则。
guilds."*"：无显式条目时应用的默认每服务器设置。
guilds.<id>.slug：用于显示名的可选友好 slug。
guilds.<id>.users：可选每服务器用户白名单（id 或名称）。
guilds.<id>.tools：频道覆盖缺失时使用的可选每服务器工具策略覆盖（allow/deny/alsoAllow）。
guilds.<id>.toolsBySender：服务器级可选每发件人工具策略覆盖（频道覆盖缺失时生效；支持 "*" 通配符）。
guilds.<id>.channels.<channel>.allow：groupPolicy="allowlist" 时允许/拒绝该频道。
guilds.<id>.channels.<channel>.requireMention：该频道的 @ 提及门控。
guilds.<id>.channels.<channel>.tools：可选每频道工具策略覆盖（allow/deny/alsoAllow）。
guilds.<id>.channels.<channel>.toolsBySender：频道内可选每发件人工具策略覆盖（支持 "*" 通配符）。
guilds.<id>.channels.<channel>.users：可选每频道用户白名单。
guilds.<id>.channels.<channel>.skills：技能过滤（省略=全部，空=无）。
guilds.<id>.channels.<channel>.systemPrompt：该频道额外系统提示（与频道主题合并）。
guilds.<id>.channels.<channel>.enabled：设 false 禁用该频道。
guilds.<id>.channels：频道规则（键为频道 slug 或 id）。
guilds.<id>.requireMention：每服务器 @ 提及要求（可按频道覆盖）。
guilds.<id>.reactionNotifications：表态系统事件模式（off、own、all、allowlist）。
textChunkLimit：出站文本分块大小（字符）。默认 2000。
chunkMode：length（默认）仅在超过 textChunkLimit 时拆分；newline 在按长度分块前按空行（段落边界）拆分。
maxLinesPerMessage：每条消息软性最大行数。默认 17。
mediaMaxMb：入站媒体保存到磁盘的上限。
historyLimit：回复 @ 提及时作为上下文的最近服务器消息数（默认 20；回退到 messages.groupChat.historyLimit；0 禁用）。
dmHistoryLimit：私聊历史轮次上限。每用户覆盖：dms["<user_id>"].historyLimit。
retry：出站 Discord API 调用的重试策略（attempts、minDelayMs、maxDelayMs、jitter）。
actions：每动作工具门控；省略则全部允许（设 false 禁用）。
- reactions（含 react + 已读表态）
- stickers、emojiUploads、stickerUploads、polls、permissions、messages、threads、pins、search
- memberInfo、roleInfo、channelInfo、voiceStatus、events
- channels（创建/编辑/删除频道与分类及权限）
- roles（角色添加/移除，默认 false）
- moderation（timeout/kick/ban，默认 false）

表态通知使用 guilds.<id>.reactionNotifications：

off：无表态事件。
own：仅机器人自己消息上的表态（默认）。
all：所有消息上的所有表态。
allowlist：来自 guilds.<id>.users 在所有消息上的表态（空列表则禁用）。

工具动作默认

动作组	默认	说明
reactions	启用	React + 列出表态 + emojiList
stickers	启用	发送贴纸
emojiUploads	启用	上传表情
stickerUploads	启用	上传贴纸
polls	启用	创建投票
permissions	启用	频道权限快照
messages	启用	读/发/编辑/删除
threads	启用	创建/列表/回复
pins	启用	固定/取消固定/列表
search	启用	消息搜索（预览功能）
memberInfo	启用	成员信息
roleInfo	启用	角色列表
channelInfo	启用	频道信息与列表
channels	启用	频道/分类管理
voiceStatus	启用	语音状态查询
events	启用	列表/创建定时活动
roles	禁用	角色添加/移除
moderation	禁用	Timeout/kick/ban

replyToMode：off（默认）、first 或 all。仅当模型输出包含回复标签时生效。

回复标签

要请求主题回复，模型可在输出中包含一个标签：

[[reply_to_current]] — 回复触发的 Discord 消息。
[[reply_to:<id>]] — 回复上下文/历史中的指定消息 id。当前消息 id 会以 [message_id: …] 追加到提示；历史条目已含 id。

行为由 channels.discord.replyToMode 控制：

off：忽略标签。
first：仅第一条出站分块/附件为回复。
all：每条出站分块/附件均为回复。

白名单匹配说明：

allowFrom/users/groupChannels 接受 id、名称、标签或 <@id> 提及。
支持前缀 discord:/user:（用户）和 channel:（群组私聊）。
用 * 表示任意发件人/频道。
存在 guilds.<id>.channels 时，未列出的频道默认拒绝。
省略 guilds.<id>.channels 时，白名单服务器内所有频道允许。
要不允许任何频道：设 channels.discord.groupPolicy: "disabled"（或保持空白名单）。
配置向导接受「服务器/频道」名称（公开+私密）并在可能时解析为 ID。
启动时 Moltbot 将白名单中的频道/用户名称解析为 ID（当机器人能搜索成员时）并记录映射；无法解析的保持原样。

原生命令说明：

注册的命令与 Moltbot 的聊天命令一致。
原生命令遵守与私聊/服务器消息相同的白名单（channels.discord.dm.allowFrom、channels.discord.guilds、每频道规则）。
斜杠命令在 Discord UI 中可能对未白名单用户仍可见；Moltbot 在执行时强制白名单并回复「not authorized」。

工具动作

Agent 可调用 discord，动作包括：

react / reactions（添加或列出表态）
sticker、poll、permissions
readMessages、sendMessage、editMessage、deleteMessage
读/搜/固定工具 payload 包含规范化的 timestampMs（UTC 毫秒）和 timestampUtc，以及原始 Discord timestamp。
threadCreate、threadList、threadReply
pinMessage、unpinMessage、listPins
searchMessages、memberInfo、roleInfo、roleAdd、roleRemove、emojiList
channelInfo、channelList、voiceStatus、eventList、eventCreate
timeout、kick、ban

Discord 消息 id 会出现在注入的上下文中（[discord message id: …] 及历史行），便于 agent 指定目标。表情可为 unicode（如 ✅）或自定义表情语法如 <:party_blob:1234567890>。

安全与运维

将 Bot Token 当密码保管；在受管主机上优先用 DISCORD_BOT_TOKEN 环境变量或收紧配置文件权限。
只授予机器人所需权限（通常为 Read/Send Messages）。
若机器人卡住或被限速，在确认无其他进程占用该 Discord 会话后重启网关（moltbot gateway --force）。