botmux 文档
  • 简体中文

      • @ 策略（mention-mode）

      普通群里，bot 默认只回应明确 @ 它的消息。@ 策略控制「什么时候可以不 @」，是普通群人类消息的路由规则；它不管授权——免 @ 不等于免权限，没有对话权的人照样会被拦（见权限与授权）。

      四个模式

      模式语义
      always（默认）多人群里必须 @ 本 bot 才回应
      topic顶层消息仍要 @；在本 bot 已拥有的话题内回复免 @（普通群的共享话题、话题群里归它的话题都算）
      never全免 @：群里任何有对话权的人发消息都回，包括没 @ 的顶层新消息（会直接新建/续接会话）。适合专人专用群、值班群
      ambient和 never 一样免 @，但当一条消息 @ 了其他具体成员（人或 bot）且没 @ 本 bot 时让路静默——那是在点名叫别人。@所有人 不算点名，仍然回应。适合多 bot / 多人群里的「默认应答者」
      • 两个层级：bot 级默认 regularGroupMentionMode（Dashboard「Bot 配置 → 群聊 @ 策略」），群级覆盖 chatMentionModes（群内命令设置）；群级优先。
      • 仅普通群可设：私聊天然不需要 @；话题群本就是话题形态，命令会回「无需设置」；/group 建的会话群由 bot 自动管理，拒绝修改。

      命令

      在普通群里发（多 bot 群需 @ 到具体 bot）：

      @bot /mention-mode always
@bot /mention-mode topic
@bot /mention-mode never
@bot /mention-mode ambient
@bot /mention-mode status
      • 查询（status 或不带参数）只要有对话权即可；修改需要操作权（owner / allowedUsers）。
      • 群级设置立即生效，只影响这一个群，不动 bot 级默认。

      配置单人单机器人群的免 @ 例外

      仅有 1 个人类和 1 个 bot 的群默认免 @。要让这类群也遵循 @ 策略，在对应 bot 的 bots.json 条目中配置：

      {
  "regularGroupMentionMode": "always",
  "soloGroupMentionBypass": false,
  "chatSoloGroupMentionBypass": {
    "oc_example": true
  }
}
      • soloGroupMentionBypass：bot 级开关，缺省 / true 保持原有免 @ 行为；false 关闭这一例外。
      • chatSoloGroupMentionBypass：按群覆盖，显式 true / false 优先于 bot 级开关；删除该群条目恢复继承。上例仅 oc_example 保留免 @ 例外，其余群关闭。若只想关闭一个群，保留 bot 默认值，在此映射中将目标群设为 false。
      • 手动修改后执行 botmux restart 生效。开关覆盖普通群和话题群的新建、已有会话，不影响私聊；现有对话权限和「@ 其他成员时让路」的规则继续生效。

      关闭例外后，有效 @ 策略（群级优先）决定是否回应：always 要求 @，topic 仍允许已拥有话题内免 @ 续聊，never / ambient 保持各自语义。普通顶层文字、图片等未 @ 消息在 always / topic 下不会仅因群人数少而触发会话。

      消息监听器、免 @ 命令、替身、入群 / 新话题自动开工等显式触发配置独立生效；此开关仅关闭人数带来的隐式例外。需要严格按 @ 触发时，设为 false、将目标群的 @ 策略设为 always，并检查该群是否另外启用了这些触发方式。

      选了 always，为什么它还是不 @ 就回？——8 个免 @ 例外

      「必须 @」是默认主规则，但代码里有一组并列的免 @ 条款，命中任意一条就回应。觉得「它怎么不听话」时，基本都是下面这些情况：

      1. 续接已归本 bot 的话题回复：这条回复所在的话题，上游路由已经判定是冲本 bot 来的（内部标记 replyRootId，典型场景是话题内回复被折叠回群会话），直接放行，不再重复过 @ 闸。
      2. 替身触发：该群开了替身模式（/substitute），消息 @ 了配置的替身对象时，配置方 bot 会代答。
      3. 消息监听器命中：在 Dashboard「角色」里配的消息监听规则一旦匹配，就按规则触发——这条不看 @ 策略、也不看常规对话权限，是独立机制（监听器有自己的发送者过滤）。
      4. 模式是 never：bot 级默认或本群被设成了全免 @。
      5. 模式是 ambient 且这条消息没 @ 别人。
      6. 模式是 topic 且消息在它拥有的话题内。
      7. 免 @ 斜杠命令：配置过 commandTriggers 的命令（如某些群配的 /solve）在普通群里裸发也触发（顶层或群内话题均可）；它只放开白名单内的命令，不等于全群免 @。
      8. 1 人 1 bot 群：默认无需 @，可通过上述 soloGroupMentionBypass / chatSoloGroupMentionBypass 关闭。启用时按群人数判定；@ 了别的成员时该例外立即失效，防止刚拉进新 bot 的缓存窗口里老 bot 抢话。

      除消息监听器（第 3 条）外，其余条款都以发送者有对话权为前提。多 bot 群里想避免互相抢话，优先用 ambient：谁被点名谁应答。

      相关：回复落到新话题还是当前会话由 /reply-mode 控制，见斜杠命令。