权限与授权

botmux 的权限回答两个问题:谁能跟 bot 说话(canTalk,对话权)和谁能改动会话状态(canOperate,操作权,如 /cd、/restart、/close、点卡片按钮)。授权手段有好几层,从「指定几个管理员」到「整群随便问」都有,本文把它们一次讲清。

授权分层

层级谁能用生效范围额度 / 有效期操作权写入入口
管理员 allowedUsers名单内指定成员该 bot 的所有群与私聊长期有效,手动维护对话 + 操作botmux setup、编辑 bots.json、群内 /botconfig set allowedUsers
访客(单群) chatGrants被授权的指定成员(人或 bot)仅授权时选定的那一个群;话题群按 oc_ 群生效,群内全部话题统一放开默认 3 条消息 / 1 小时,批准时可改仅对话@bot /grant @某人 授权卡、Dashboard 成员批量授权
访客(全局) globalGrants指定成员任意群同上,可带额度与有效期仅对话owner 主动授权卡上的「全局授权对话」
整群放开 allowedChatGroups群内所有人(与具体 sender 无关;退群即自动失权,新人进群立即生效)单个群无额度、无期限,直到显式收回仅对话群内裸 /grant、Dashboard「整群一键授权」
Oncall群内所有人单个群恒放行、恒不限额仅对话;新话题直接进入绑定目录、跳过选仓/oncall bind <目录>、Dashboard oncall 开关
私聊开放 p2pOpen飞书应用「可用范围」内的所有人仅私聊—仅对话Bot 配置 / bots.json
开放模式任何人全部—对话 + 操作上述名单全部未配置时的兜底状态,不建议长期使用

补充:

  • 正常 onboarding 创建的 bot 都会把 owner 写进 allowedUsers,因此默认是限制态 bot,只有名单内的人能用。
  • 团队信任腿(同团队 peer bot / team bot / 平台团队成员)只授予对话权,不在本文展开,见 角色与团队。
  • 字段级说明见 bots.json 配置 · 权限与授权。

常用操作对照

我想做什么怎么做
让整个群都能问(不想要额度)群里 @bot /grant(或 /grant all);收回用裸 /revoke。话题群里按 oc_ 群生效,对全部话题有效
只给某几个人开通,先试用几条@bot /grant @张三 @李四,bot 回一张授权卡,默认每人 3 条 / 1 小时
直接指定条数@bot /grant @张三 20,每人各 20 条;时长仍在卡片上选
在卡上细调有效期五选一:1 小时 / 8 小时 / 1 天 / 7 天 / 永久;消息额度填 1–1000 的整数,留空表示不限。任一条件先到即自动收回
收回某人的授权@bot /revoke @张三:清掉其本群访客授权、全局访客授权;若对方同时在 allowedUsers 管理员名单里,也会一并移除(回执注明作用域)。撤 owner 本人、或撤到 bot 再无管理员的操作会被拒绝
值班群即问即答、不选仓库/oncall bind ~/projects/foo,见 Oncall 模式
在 Dashboard 里批量操作「群组」页 → 该群「管理」弹层:成员批量授权(多选成员,一次最多 50 人,写入前实时校验仍在群,可选额度与时长)与整群一键授权

只有 owner / 管理员(allowedUsers)能执行 /grant、/revoke、oncall 开关与 /card、/cot、/mention-mode 等管理命令;访客只能对话。

入群不等于授权

把 bot 拉进一个群,本身不会写任何授权名单。 bot 收到「被加入群聊」事件后不会自动放开该群的对话权:

  • 限制态 bot(配过 owner / 白名单,onboarding 出来的 bot 都属此类):非名单成员在群里 @ bot 发言会被拒绝,bot 自动给 owner 发一张授权申请卡,owner 一键批准后该成员才能用(批准后刚才那条消息还会自动重放,不用再发一遍)。
  • 只有完全未配任何白名单的开放模式 bot 才是谁都能用(包括操作权),这是兜底状态,不是「拉群」带来的。
  • 「进群自动开工」(autoStartOnGroupJoin)也不是授权:它还有一道闸——群内必须至少有一名 allowedUsers 成员,bot 才会自动建会话。

想精确控制「谁能把 bot 拉进群」属于飞书平台侧能力(应用可用范围 / 群添加权限),见文末 FAQ。

黑名单 blockedUsers

黑名单是** sender 维度的全局否决**,在 Bot 配置页(Dashboard「Bot 配置」)维护,也可在群组成员弹层里快捷拉黑:

  • 群聊、私聊都生效;一个人被拉黑后,在任何 oncall 群、整群放开群、团队群里都被否决。
  • 否决腿排在 oncall、整群放开、访客授权、团队信任等所有放行腿之前,不存在「换个群又能用」。
  • 被拉黑的人发言被拦时不会再给 owner 发授权申请卡,避免持续骚扰审批人。
  • owner / 管理员不可被拉黑,写入口直接拒绝(防自锁)。
  • 黑名单只管「对话权」;消息监听器(让 bot 按规则自动盯消息的功能)的匹配范围是独立配置,不受黑名单影响。

授权申请卡

限制态 bot 下,未授权者在群里明确 @ bot 而被对话闸挡住时,默认自动发一张申请卡给 owner(autoGrantRequestCards,默认开启;Bot 配置里可关,关闭后静默拦截)。

  • 申请卡上可「授权本群对话」或「拒绝」,额度与有效期在卡上直接改。
  • owner 主动发的 @bot /grant @某人 卡片还多一个「全局授权对话」按钮(任意群生效)。
  • 批准后触发本次申请的原始消息会自动重放进会话,申请人无需再 @ 一遍。
  • 待审批期间有节流,不会被同一人的消息刷屏。
  • 私聊(p2p)被拒默认是静默的:私聊里没有 owner 在场,把申请卡回给陌生人本人既无法操作又会暴露 owner,因此不发卡。
  • 申请卡转投 owner 私聊(grantRequestToOwnerDm,默认关闭):打开后,会话里没有任何管理员能点卡时,申请卡改发到主 owner 的私聊——包括群里查不到管理员(比如关掉了 autoInviteOwnerOnGroupAdd、owner 不进群)和私聊被挡两种情况。申请人只收到一句不含 owner 身份的中性回执;owner 批准或拒绝后,结果会回告到原会话;额度用尽后对方再发消息会自动重新申请。群里有管理员、或查群成员失败时仍按原样在群里发卡。转投私聊另有 owner 维度的总量节流(每小时 20 张,发送失败不占名额);超出或发送失败时不发卡(群里已确认没有管理员,回落群内只会是一张没人能点的卡),下一条消息再重试。群聊路径每次都要查一次群成员(60 秒缓存),应用缺少群成员读取权限(im:chat.members:read)或群成员超过 2000 人(拿不到完整名单)时,会按原样在群里发卡。开关:Dashboard「Bot 配置 → 授权与额度」、bots.json 或 /botconfig set grantRequestToOwnerDm on。

常见疑问

  • oncall 和裸 /grant 什么区别? 都只给对话权、都不给操作权。区别:oncall 恒放行、恒不限额,同时把群绑定到一个工作目录(新话题跳过选仓);/grant 只放开对话,不绑目录。
  • 怎么只给某人 3 条额度? @bot /grant @某人 直接发卡,默认就是 3 条 / 1 小时;条数也可在命令后带数字或在卡上改。
  • 每个新成员都要 owner 批吗? 不一定:整群放开(裸 /grant)或 oncall 后群里任何人即问即用;要保留门槛才走逐人授权与申请卡。

更多问答见 FAQ / 排错;@ 机器人的策略(什么时候必须 @)见 @ 策略。