bots.json 配置
~/.botmux/bots.json 是机器人的配置文件。文件是一个数组,每一项是一个 bot;每个 bot 由一个独立的 daemon 进程运行。
只填 larkAppId 和 larkAppSecret 就能跑起来,其余字段都是可选的,按需再加。
怎么改配置
三种方式改的是同一份 bots.json,按顺手的来:
第一次创建 bot 可以用 botmux setup,它会交互式地帮你生成这份文件。
配置文件位置:先看
BOTS_CONFIG环境变量指定的路径,没设置时用~/.botmux/bots.json。
本页只讲「每个 bot 自己的设置」。自动更新、空闲清理、会话环境变量的全局层这类整台机器共用的开关在 ~/.botmux/config.json,见全局设置。

示例
最小配置:
两个 bot,一个跑 Claude Code、一个跑 Codex:
想做 X → 改哪个字段
必填
可选的 brand 说明这个应用属于哪个平台:feishu(默认,中国版飞书)或 lark(国际版 Lark)。接口地址、授权链接都按它来。botmux setup 会自动识别并写入;一个 bot 绑定一个租户,要换平台就重新配一个 bot。
CLI 与模型
群级新话题默认模型
groupDefaultModels 让同一个 bot 在不同群里默认用不同模型:
更推荐在 Dashboard「群组管理 → 新话题默认模型」里按 Bot 设置,保存后不用重启。
- 新话题创建时记下当时的群模型。之后改群配置只影响新话题,老话题重启、恢复时仍用创建时的模型。
- 每种 CLI 单独记,话题换成另一种 CLI 时不会把 Claude 的模型名传给 Codex。
- 优先级:触发时显式指定的模型 > 新话题记下的群模型 > 同 CLI 的 Bot 模型 > CLI 自己的默认。
- 私聊、普通群里整群共用的会话、外部接管(adopt)的会话不用这个设置。
TraeX 原生子代理(nativeSubagentRuntime)
只影响 TraeX 原生 spawn_agent 新建的子代理,不改父代理自己。model 和 reasoningEffort 两项各自可选:
- 不写某一项:沿用子代理请求里的原值。
- 写成
{ "mode": "custom", "value": "..." }:固定用这个值。 - 两项都不写:直接删掉整个字段。
inherit不是有效模式。
切换到其它 CLI 时会自动删除这个字段。
额度用完自动交接
quotaFallbackBot 让 daemon 在当前 CLI 确认额度用完时,在原会话里真实 @ 一个备用 Bot 接手。它不会再调用已经没额度的主模型,也不改原有的额度提示卡片。

几点要知道:
- 备用 Bot 必须是本机配置过、而且当前就在这个群里的 Bot。其它机器上的 Bot、自己、不在群里的 Bot 都会被跳过。
- 普通群会话交接到原群,话题会话交接到原话题;备用 Bot 自己读历史来接上下文。
- 同一个源 Bot、同一种额度类型,5 分钟内只交接一次。daemon 重启时不会补发之前的交接。
- 保存时会检查交接链,拒绝自己交给自己,也拒绝
A → B → C → A这样的环。手改文件引入了环时,botmux start/restart会跳过环里的 Bot,其余照常启动;Dashboard 会标出这些没启动的 Bot,可以直接在「高级 → 额度耗尽交接」里修好。

Codex 兼容发行版
有些 CLI 是 Codex 的独立发行版:参数、交互、会话恢复和登录方式都和 Codex 一样,只是二进制和版本线不同。这类 CLI 不需要新的 cliId,保留 cliId: "codex",再用 cliRuntime 说明它是谁:
更省事的做法是在 Dashboard「Bot 配置 → 常用 → Agent 配置」里选「自定义兼容版」,填好后保存(就是本页开头那张截图)。
注意:
cliRuntime目前只支持cliId: "codex",不能和wrapperCli一起用。- 手写配置时要同时写一个和
executable完全相同的cliPathOverride(如上例)。这是给旧版 botmux 降级用的;缺了或不一致会直接校验失败。Dashboard 保存时会自动写好。 - 只有
cliPathOverride的老配置照常能用。Dashboard 会把它显示为只读兼容状态,可以迁移到「自定义兼容版」。 - 会话创建时会记住当时用的发行版。只改模型只影响新会话;切换 CLI、发行版或 wrapper 时,botmux 会关掉还在用旧启动方式的活跃会话,避免它们之后恢复到错误的二进制上。
接入 GLM / 第三方服务商
想让一个 bot 跑 GLM Coding Plan(或其它 Anthropic 兼容服务商),另一个 bot 继续跑官方 Claude,给前者配 env:
- GLM 国内站把地址换成
https://open.bigmodel.cn/api/anthropic。 - Codex 这类 OpenAI 协议的 CLI,填
OPENAI_BASE_URL/OPENAI_API_KEY。 - 每个 bot 的
env只注入到它自己的会话,不会串到别的 bot。 - 值是明文存在
bots.json和进程环境里的,不是密钥保险箱。飞书里查配置会打码,Dashboard 默认打码,只有本机 owner 能点开看原文。 - 改完对新会话生效。
更多环境变量的玩法(全局层、去掉某个变量、严格继承)见下方会话环境变量。
Codex App 纯净输入(实验性)
默认情况下,botmux 会把发言人、附件路径等上下文和用户原话拼在一起发给 Codex App,所以 App 里看到的用户消息比较杂。开启 codexAppCleanInput 后,App 里的用户消息只保留原话,上下文改走隐藏的 additionalContext。
或写进配置:
- 只对 botmux 管理、实际跑
codex-app的会话生效;/adopt接管的外部会话不受影响。 - 需要 Codex CLI
>= 0.135;版本太旧或识别不出时,自动用原来的拼接方式。 - 如果 Codex App 明确拒绝这些实验字段,botmux 会用原来的方式重试一次,并在这次运行期间关掉纯净模式。网络、超时等普通错误不会自动重试,避免重复执行。
- 从下一条派发给 Codex 的消息开始生效,不改写已经排队或正在执行的消息,也不改历史。
- 这只是让 App 里看起来整洁,不是隐私擦除:上下文仍可能留在原始会话记录里。
Codex App 浏览器桥接(实验性)
botmux 用 app-server 协议运行 Codex 时,拿不到 Codex App 内置的 Chrome 工具。codexBrowser 补上这一块:开启后,新会话可以通过本机已安装的 Codex 浏览器插件操作 Chrome / Edge。可以在 Dashboard「Bot 配置 → 高级 → Codex App」里开关。
完整写法:
使用前提和边界:
- 同一个系统用户的 Chrome / Edge 里要装好并启用 Codex 浏览器扩展,还要装 Codex 桌面端附带的浏览器运行时。运行时装在非默认位置时,用环境变量
BOTMUX_CODEX_NODE_REPL_PATH指定。 - 站点访问、上传、下载等需要确认的操作会变成飞书授权卡,只有能和 bot 对话的人能点「本会话允许 / 始终允许 / 拒绝」。拒绝、超时或 daemon 不可达都按拒绝处理。
- 工具不开放任意 JavaScript、raw CDP、cookie、local storage、浏览历史或剪贴板。需要输入密码的安全登录流程不会降级成普通飞书卡片。
- 已经在跑的会话要重启或重新恢复才会加载新的工具。
- 不能和
existingAppServer、sandbox、readIsolation一起用,冲突时启动直接报错。
工作目录
会话与运行
等待提醒与无进展提醒
longTaskReminder:任务实际执行超过指定时长仍未结束时,在原群聊或话题发送独立提醒卡片。Dashboard「Bot 配置 → 消息卡片 → 长任务卡片提醒」提供开关和保存按钮,保存后立即生效。
- 默认关闭;首次提醒阈值和后续间隔分别默认 10 分钟,均支持 1–10080 的整数分钟。
- 从 CLI 实际接收任务并开始执行的时间计时,排队和空闲时间不计入;后续消息和正常进度不会重置已运行任务的计时。
- 每 30 秒检查一次;首次达到阈值后提醒,之后从上次成功投递起按间隔提醒,不补发错过的周期。发送失败一分钟后重试,同一未确认通知复用投递 ID。
- 任务完成、取消、worker 停止或会话关闭后停止提醒。每轮任务独立计时;支持普通群、私聊和话题,文档评论和无 IM 会话不发送。
- 保持静默任务、会议驱动任务和已抑制执行轮次的辅助卡片限制;提醒不会触发普通回答的
outbound.sendhook。 - 偏好会持久保存,执行计时只使用当前存活 worker 的真实观测,不从旧会话或历史日志猜测。daemon 重启后,没有重新观测到执行开始的旧任务不会提醒。
sessionOwnerReminder:会话停在某个需要人处理的状态、而且一直没变化时,每隔一段时间在原话题里 @ 一次会话 owner。
- 只对按话题划分的会话生效(话题群、普通群里的话题、
p2pMode: "thread"的私聊);整群或整个私聊共用一个会话时不提醒。会话要有 owner。 - 状态一直不变时,每隔
intervalMinutes提醒一次;状态变化或会话里有新消息时重新计时。 - 免打扰从开始时间(含)生效,在结束时间恢复。免打扰期间继续跟踪会话状态和活动,结束后的下一次扫描会发送仍符合条件的到期提醒。
- 手写时须提供
enabled、intervalMinutes、text和states。填写quietHours时须提供其中的三个字段,且开始和结束时间不能相同。配置无效时,整个提醒配置视为未设置。
noProgressNotify:一轮任务长时间没有可确认的新进展时,发一条提醒卡片。它只是提醒,不会重启、中断或重试任务。
- Codex App 不用配就默认开启;Codex CLI 要写
{"cliEnabled": true}。其它 CLI 不受影响。 timeoutMs从下一个 worker 进程起生效。会话在等人回复(问答卡、终端选项、agent 请求处理)时,Codex CLI 的提醒会暂停计时。
权限与授权
完整的权限模型见权限与授权。
文件沙盒与凭据
详细说明见文件沙盒。
ZMX 后端没法执行文件沙盒,开着沙盒的配置组合会直接拒绝启动,见 ZMX 后端。
受保护的本地 MCP 能力
本地 stdio MCP 服务可以在插件私有的 mcp/index.json 中申请一个可选受保护能力。能力 ID 对 Botmux 是不透明数据;通用说明使用非业务 fixture:
Streamable HTTP MCP 服务不能申请 protectedCapability,同时声明两者的插件描述会被拒绝。插件描述不提供密钥来源、主体策略或隔离规则;这些绑定只来自机器级配置。
在 bots.json 中,plugins 数组只负责为当前 Bot 启用已安装插件:
不要在 bots.json 中保存受保护能力绑定、密钥来源、密钥值或灰度状态。运维人员在机器级 ~/.botmux/config.json 中绑定不透明能力 ID:
省略 enabled 时默认关闭,JSON 布尔值 true 启用绑定,布尔值 false 关闭绑定。字符串 "true"、数字 1 等非布尔值会使整条能力记录被拒绝。secret 只支持 { "source": "file", "path": "<Home 相对路径>" };路径以 daemon 账户的可信 Home 为根,不接受绝对路径、.、.. 或软链。运维人员预先创建当前用户拥有、精确权限为 0600 的非空普通文件,文件大小最多 64 KiB。Botmux 不会修复不安全文件,也不会在 daemon 启动时捕获或缓存密钥;每次新 worker fork 前现读文件,并逐级固定目录 fd 后以 no-follow 打开,拒绝中间路径或叶子的软链及替换竞态重定向。
密钥只经一次性 fd 通道提供给获准 MCP,不进入 argv、通用环境或日志。文件轮换对下一次 worker fork 生效,已运行 MCP 保留本次启动获得的密钥,需重建该会话才能更新。每个有效配置的 secret 文件自动加入所有相关会话的沙箱 deny,即使 Bot 未启用匹配插件或能力关闭;额外 protectedHomePaths 仍按匹配插件生效。redactEnv 以及无效旧 source: "env" 记录中可辨识的合法变量名会按当前配置从 worker、模型和插件通用环境清除;旧环境来源不会授权写能力。修改机器配置沿用全局配置的短缓存刷新规则。
MCP 进程启动时,如果能力已关闭或未 provision、插件不在 allowedPluginIds 中、配置的隔离前提不满足,或 daemon 无法提供一次性通道,Botmux 会改用不带受保护密钥文件描述符的普通 stdio transport 启动服务。服务仍可启动并提供只读工具;该连接上的 tools/call 不会收到 botmuxTrustedPrincipal 或 botmuxGrantedCapabilities,插件必须对受保护写入失败关闭。
principal 是每次 tools/call 的授权条件,不是 MCP 进程启动条件。如果全局绑定、插件 allowlist、隔离前提和 daemon 通道在启动时均已成功,长驻 MCP 进程可能已持有一次性密钥,即使后续某次调用缺少所需的已验证真人主体或其它调用级授权条件。Botmux 会在该次调用中省略 botmuxTrustedPrincipal 和 botmuxGrantedCapabilities,插件必须拒绝受保护写入。插件必须在每一次受保护写操作中重新校验 botmuxTrustedPrincipal 以及 botmuxGrantedCapabilities 是否包含当前能力 ID,不得把上一轮主体、能力或授权结果缓存到进程级状态后复用;任一字段缺失、不匹配或过期都必须失败关闭。只要匹配的插件已启用,即使能力本身关闭,配置的隔离路径和环境变量清理仍然生效。
迁移旧环境密钥时,先把密钥写入上述安全文件并将配置改为 source: "file",再从 daemon 启动源移除旧变量并重启 daemon;仅 delete process.env 不能擦除旧进程的 /proc/<pid>/environ。新增或改变密钥文件路径前,须先结束并重建旧 CLI 会话,使新的文件 deny 生效;不要仅靠热更新撤回旧进程访问。建议固定路径后以安全文件原子替换轮换。存在受保护文件或其它需隔离的身份配置时,裸宿主 one-shot 自动标题生成会跳过并保留占位标题,不影响会话正文的读取能力。
同一个 stdio MCP 子进程重启后,一次性密钥通道目前不会再次交付,受保护工具会退回只读;需重建会话恢复。不同出站策略收集入口的用户错误提示尚待统一。
按触发人身份调用 CLI(triggerUserAuth)
默认关闭。 打开后,这个 Bot 会话里的 lark-cli / bytedcli 用「发这条消息的人」自己的授权调用,而不是本机的登录态。适合多人共用一个 Bot:谁发的消息,就以谁的身份读文档、查日程、调内部平台。
三种开法任选一种,新会话生效(已有会话 /restart 后生效):
- Dashboard:「Bot 配置 → 权限与安全 → 按触发人鉴权」,打开「按触发人身份调用 CLI」,勾选要覆盖的工具。
- 飞书里(管理员):
/botconfig set triggerUserAuth {"enabled":true,"tools":["lark-cli","bytedcli"]};关闭用/botconfig unset triggerUserAuth。 - bots.json:
规则:
- 只有
enabled写成true才算开。tools不写表示覆盖全部工具;写了不认识的工具名会直接报错,不会悄悄降级。 - 可选
capabilities按能力逐项开关:lark-user(飞书用户身份,lark-cli --as user)、bytecloud(ByteCloud:bytedcli、codebase、git push、bitscli / bits-cli,同一个开关)、meego(仅bytedcli meego,独立的meegle命令不受管)。写了不认识的值会直接报错。不写时由tools推导(lark-cli→lark-user,bytedcli→bytecloud+meego)。bytecloud/meego没开时对应命令保持原生:直接用这台机器自己的登录态,botmux 不做任何干预。lark-user没开时要分两种:只写tools的旧配置(不写capabilities)行为与上游一致,lark-cli --as user仍用当轮触发人自己的授权;只有显式写了capabilities且不含lark-user时,lark-cli --as user才原生执行——用这台机器自己的 lark-cli 配置和登录,botmux 不注入凭据、不发授权请求(botmux auth request对 lark-cli 返回lark_user_auth_disabled)。 - 没授权过的人调用时,命令会被拒绝,拒绝信息里附带授权链接。AI 也会自己用
botmux auth request把链接发给这个人(见 Agent 自助发起授权),或者让他在话题里发/login。授权完成后重试即可。 - 绝不会退回到 Bot 或其他人的身份代跑,也没有「退回机器登录态」的选项。旧配置里的
fallback字段会被忽略。bytedcli没有 Bot 身份,没授权就是失败。 - 可选字段:
credentialSource(auto默认 /platform只用中心化平台 /local只用本机扫码)、delegateOnMention(默认true,见 @ 交接带上发起人身份)、allowSpeakerSwitch(默认false:设为true后,多人话题里才能在某一条命令前加BOTMUX_AS=<open_id>用本轮另一位发言人的身份执行;默认关闭时BOTMUX_AS一律被拒)、gitHost(让该代码平台的 git 推送也按当轮身份鉴权)。
升级注意:旧格式授权要重新 /login
v3.20 起,botmux 自己保存的飞书用户授权按「应用 + 授权人」分文件存(~/.botmux/data/user-token-<appId>-<openId>.json)。之前的旧文件(user-token-<appId>.json、user-token.json)看不出是谁授权的,凡是需要「以某个具体的人」调用飞书接口的地方都不再使用它。
只剩旧格式授权的 Bot,这些用户身份能力会失效。由本人在话题里重新发一次 /login 即可恢复。注意 /login 只是补上授权文件,按触发人身份调用 CLI 仍要按上面的方法单独打开。
卡片与终端
卡片长什么样、每个开关的效果见实时流式卡片。
Dashboard 的「Bot 配置 → 消息卡片 → 实时卡片按钮」可以直接勾选要显示的按钮:

答复卡页脚
页脚是答复卡底部那一行小字:签名、模型、用量、发送给谁、语音按钮等。每一块都能单独开关,可以在 Dashboard「Bot 配置 → 消息卡片」里设置,也可以用 /botconfig set <字段> on|off。

- 关掉总开关不会清空各项设置,重新打开后恢复原样。所有块都关了或没内容时,整个页脚和分隔线都会省略。
- 修改对之后的新答复生效,已发出的卡片不变。手改
bots.json后要重启 daemon。
最终答复反馈
feedback.enabled: true 后,最终答复卡上会出现三个按钮(默认是「结论可用 / 有效推进 / 结论有误」),对应三种固定含义 positive / progress / negative。按钮文字、样式、顺序、点「有误」后的原因选项和说明框都能自定义。
可以在 Dashboard「Bot 配置 → 消息卡片 → 最终回答反馈」里可视化编辑,或用 /botconfig set feedback '<json>'。反馈数据默认存在本机的 botmux-feedback.sqlite,Dashboard「反馈分析」页可以查看;想换成 PostgreSQL 或迁移数据,见反馈数据存储与迁移。实现细节见 docs/feedback-capability-current-implementation.md。
回复投递与 Prompt 注入
转写回复(replyDelivery: "transcript")
Doubao 默认就是 transcript(它的工具命令跑在账号级常驻进程里,模型自己 botmux send 容易发错话题,详见多 CLI 适配器)。其它 CLI 默认 send,模型要自己执行 botmux send 才能把答复发到飞书。改成 transcript 后,botmux 自动从 CLI 的会话记录里取本轮最后一段回答发出去,模型直接作答就行。
开启后有三个变化:
- 系统提示里不再教模型用
botmux send。确实需要发附件、跨 bot @ 时,模型可以通过内置的botmux-sendskill 自己找到用法。 - 每轮不再附带
<botmux_reminder>提醒。 - 私聊,或只有管理员和这个 bot 的 1 对 1 群里,消息不再包
<user_message>壳和<sender/>标签,模型看到的就是原文。
支持的 CLI:Claude Code、Codex、TraeX、CoCo、Hermes、MTR、Pi、Oh My Pi、ebsd、Grok、Cursor、Doubao。Antigravity 只在零注入模式下采集回答,显式设置会被拒绝;如果写好后又把 CLI 换成不支持的,运行时自动回到 send,不会丢答复。Cursor 和 Doubao 在 sandbox: "scratch" 下不支持 transcript(设置被拒,默认值运行时回到 send);oncall 沙盒不受影响。
- 每轮的提醒和外壳从下一轮起变化;系统提示是会话启动时定的,已经在跑的会话要
/restart才换。 - 代价:1 对 1 会话没有了
<user_message>/<sender>结构,/adopt不再把它认作 botmux 自己的会话。 - Dashboard 里「转写回复模式」开关改的就是这个字段,当前 CLI 不支持时开关是灰的。
关掉发言人标签(senderTag: false)
关掉后模型就不知道是谁在说话了:多人会话里分不清发言人,也没法按人称呼。适合会把标签内容抄进回复的 CLI,或不想把每条消息的身份写进 CLI 记录的场景。
- 从下一轮生效,不改已排队的消息和历史。
botmux send --mention-back(@ 回本轮发消息的人)不受影响,它用的是 daemon 自己记录的触发人。- 代价:Dashboard 的会话洞察没法再从标签判断发言人类型,
/adopt识别 botmux 会话时少了一条线索。 - Dashboard 里「发言人标签」开关改的就是这个字段。
隐藏开发机地址(hideLocalAddresses)
飞书用户在自己的客户端里看回复,打不开开发机上的文件和本机服务。bot 给别人用时可以打开这个开关;只给自己用、需要在回复里看到排障路径的保持默认关闭。
默认关闭时,回复和卡片原样发出,提示里也不加相关规则。开启后:
- 模型的回复(
botmux send、自动转发的最终答复、动态单卡、思考过程消息、文档评论回复)发到飞书前,开发机上的绝对路径、file://这类本地协议和本机服务地址会被替换:工作目录里的源码换成仓库相对路径,其它换成「【内部文件】」;技能链接只保留名称。/dev/null、/proc这类不指向用户文件的系统路径保留。 - 系统提示里加一条完整规则(每个会话一次),每轮提醒里加一句,要求模型不放这类地址,文件改用附件或真实可访问的链接。
- 卡片按钮或链接指向本机地址时整条拒发,模型会收到
LOCAL_ADDRESS_OUTBOUND_REJECTED;botmux 自己生成的 Web 终端、Dashboard 链接照常发送。 - 回复处理和每轮提醒立即生效;系统提示里的完整规则从下一个新会话起生效。
- Dashboard「Bot 配置 → 消息卡片 → 开发机地址」里的开关改的就是这个字段。
零注入模式(promptInjection: "none")
适合「主 bot 派活、子 bot 专心执行」的多 Agent 流水线,或者你就是不想让 botmux 往 prompt 里加任何东西。
开启方式:
- Dashboard:「Bot 配置 → 高级」里开启「零注入」。
bots.json:在对应 bot 上写"promptInjection": "none";改回"default"或删掉字段就恢复。
开启后:
- 只传任务原文和附件:不加 botmux 的系统提示、每轮提醒、身份信息、角色、白板、记忆和技能目录。CLI 自己的系统提示和项目里的
AGENTS.md照常由 CLI 处理。 - 自动回传答复:从 CLI 的会话记录里取最终答复发回飞书,默认 @ 本轮发任务的人;答复里点名群里其它 bot(如
@Reviewer)会自动换成真正的飞书 @。 - 支持的 CLI:Claude Code、Codex、TraeX、CoCo、Hermes、MTR、Pi、Oh My Pi、ebsd、Grok、Cursor、Doubao、Antigravity。后端限本机的 tmux / pty / zellij / herdr / zmx(Antigravity 不支持 zmx);Cursor、Antigravity 不支持
scratch沙盒。暂不支持远端后端和 v3 工作流。
技术细节见 docs/zero-prompt-injection.md。
主动开工
默认 bot 只在被 @ 时才开工。下面这些字段让它主动一点,都可以在 Dashboard「Bot 配置 → 常用 → 默认工作目录」下的「主动开工」里设置。
groupJoinCommand 的执行方式和 Hooks 一样:
- 不经过 shell,要用管道、重定向就写成
bash -c '…';只带最少的环境变量(不含应用密钥)。 - stdin 收到 JSON:
{event:"chat.bot_added", larkAppId, chatId, operatorOpenId, emittedAt};也可以读环境变量BOTMUX_JOIN_CHAT_ID/BOTMUX_JOIN_LARK_APP_ID/BOTMUX_JOIN_OPERATOR_OPEN_ID。 - 10 分钟没结束会被强制结束。
上线欢迎语(welcomeMessage)
填一段文字,机器人首次成功上线后会私聊主管理员(见 ownerOpenId)一次。用 botmux setup add / botmux setup edit 的 --welcome-message "…" 或 --welcome-message-file <文件> 设置,edit 传 --welcome-message - 清空;Dashboard 里暂时不能改。--welcome-message 的值始终按原文发送,以 @ 开头也不会当成文件路径。
- 发送记录在 daemon 数据目录的
welcome-sent/<AppID>.json,发过之后重启不再发,改欢迎语内容也不会重发。删掉这个文件可以让它重发,但距上次发送不到 1 小时的会被飞书去重。 - 发送失败、还解析不到主管理员时不影响启动,下次启动重试。
- core-only(
apiOnly)bot 和多副本部署(BOTMUX_COORDINATION_MODE=primary,各副本不共享发送记录)不发送,daemon 日志里会写明原因。
群消息监听
让 bot 盯住群里的消息:符合条件的消息不用 @ 也会自动拉起一个会话去处理。典型用途是告警处理:监控系统本来就有自己的机器人往群里发告警,把 bot 拉进这个群、开启监听,每条告警都会自动开工排查,不用另外接 Webhook。
推荐在 Dashboard「消息监听」页配置:
- 全局监听设置:一套规则,默认应用到这个 bot 加入的所有群,以后新加入的群也自动生效。
- 群聊监听设置:每个群可以选「使用全局设置」「关闭消息监听」或「自定义消息设置」。
- 可以预览最近 24 小时会命中哪些消息,也可以试运行(会在群里真实回复)。
对应 bots.json 里的两个字段:
旧字段 messageListeners(键为 chat_id)仍能读,会被当作按群的自定义规则。
一条监听配置包括:
要知道的几点:
- 只看群里的顶层消息:已有话题里的回复不处理;直接 @ bot 的消息走普通 @ 流程,不会重复触发。
- 每条命中的消息各拉起一个会话。
- 最长约 30 秒延迟:飞书会实时推送一部分消息;其它机器人发的、以及没 @ bot 的消息,靠每 30 秒一次的历史轮询补上。所以监听第三方告警机器人时,用默认的
all_except_excluded+ 包含"bot"最稳:历史接口里第三方机器人可能拿不到open_id,按open_id精确匹配会漏。 - 按文档标题匹配:只支持 HTTPS 的
docx/wiki链接。需要应用开通并发布drive:drive.metadata:readonly(读文档标题)和wiki:node:read(或wiki:wiki:readonly)权限。没权限或 bot 看不到这篇文档时,只按消息原文判断。
总结命令
- 只有显式
@机器人 /summary才会总结,不会因为关键词自动触发。Dashboard 的「/summary 总结范围」改的就是这几个字段。 - 如果之前有过一次
@同一机器人 /summary,这次只总结上次之后的消息。 - 开启
summaryMemory时,/summary后面跟的文字会被当作起点:从最近一条包含这段文字的消息开始总结;找不到就报错,不会退回更大的范围。这种显式起点可以比sinceHours更早,不想读到太旧的内容就别带起点文字。没开summaryMemory时,后面的文字只是告诉模型总结的侧重点。 - 开着沙盒、而记忆文件又在工作目录外时,要把它已存在的父目录加进
sandboxPaths.readWrite,否则写入会被沙盒拦下。
contentTriggers(旧版关键词 / 正则免 @ 触发)已经不再生效,只为兼容旧文件保留解析。新配置请用summaryRange。
花费与预算
botmux 可以按 token 用量估算每个 bot 的花费(人民币),并在月度花费越过预算线时私信提醒。
pricing:怎么算钱
- 只有配了
pricing才会算钱,写{ "usdCny": 7.2 }就能用内置价格表(Claude、GPT、Gemini 常见模型)。 - 内置表和
models里都找不到的模型不计价,不会猜一个价格。 - 统计从开启后开始累加,不回溯以前的用量。
budget:月度预算
- 提醒私信发给
ownerOpenId指定的主管理员;没配ownerOpenId时只写日志。 - 按自然月(UTC)统计,每月 1 日重置。
- 预算依赖
pricing算出的金额:没配pricing时花费一直是 0,不会触发提醒。
语音
飞书会议智能体
连着飞书的 Bot 默认就能被拉进视频会议(core-only 的 apiOnly Bot 除外),旁听会议、同步转写,按会议角色在会中发文字或说话。
准备:应用要开通 vc:meeting.bot.join:write(入会 / 离会)、vc:meeting.meetingevent:read(读会中事件)、vc:meeting.message:write(会中发文字),实时语音另需 vc:meeting.bot.realtime:write;事件订阅里要有 vc.bot.meeting_invited_v1、vc.bot.meeting_activity_v1、vc.bot.meeting_ended_v1、vc.meeting.participant_meeting_joined_v1。权限缺了,daemon 启动时会在日志里报错并私聊通知管理员;事件订阅飞书没有接口可查,daemon 只会提醒你核对,缺事件时只是收不到会议推送、不会报错。
怎么用:
- 在飞书视频会议里邀请这个 Bot 入会。
- Bot 私聊给 owner(配了
vcMeetingAgent.attentionTargetOpenId时发给这个人)发一张确认卡,默认 30 分钟内有效(inviteTtlMs可调)。 - 确认后 Bot 入会,自动建一个会议监听群同步转写;想用现有群就配
vcMeetingAgent.listenerChatId。 - 会中做什么由会议角色决定,见下一节。会议监听期间要临时让某人能给 Bot 下指令,用
/vc-auth @成员(/vc-auth revoke @成员撤销,/vc-auth list查看)。 - 想提前准备:在普通群发
/vc prepare <会议链接或会议号>,把这个群设成会议准备群,可以先补背景、预读文档,开会后复用同一个 Agent 会话(见斜杠命令)。
会中发言:
- 文字和语音默认直接发出,不逐条审批。想逐条审批,在
vcMeetingAgent.meetingConsumer里把textOutputPolicy/voiceOutputPolicy设成approval;设成deny则禁止。 - 实时语音默认开着,但只在 Bot 真要说话时才建连;关掉用
vcMeetingAgent.realtimeVoice.enabled: false。说话还需要上面的实时权限和会中的 AI 发言权限,缺了会明确报错、不会发出声音。 - 语音用语音总结里配置的引擎合成(MiniMax、火山引擎 / 豆包等)。
关闭:
- 单个 Bot:
bots.json里写"vcMeetingAgent": { "enabled": false },或在「全局设置 → 会议 Agent → 会议监听 → 会议角色预设 → 按 Bot 的会议开关」里关掉这个 Bot 的「接收会议事件」。 - 整台机器:Dashboard「全局设置 → 会议 Agent → 会议监听」关掉「允许本机使用会议监听能力」(
config.json的vcMeetingAgent.enabled: false)。已经在开的会通常会自然结束。
会议角色
bot 被拉进飞书视频会议后,可以按「会议角色」去做事,比如同步重要信息、记纪要、主持。推荐在 Dashboard「全局设置 → 会议角色预设」里管理:
- 预设由所有 bot 共享:谁被拉进会议,就由谁执行选中的角色,预设里不用指定执行的 bot。
- 内置模板:会议重要信息同步、会议纪要与行动项、会议主持、方案评审与风险挑战、访谈与需求洞察。点「使用此模板」会复制一份可以随意修改的预设,之后模板更新不会改到你的副本。
- 「按 Bot 的会议开关」里可以给每个 bot 关掉会议事件、挑一个默认角色。
角色里有两个独立的输出设置:
listener_thread 模式下,由 Agent 自己判断现在有没有值得发的新内容,botmux 只把它决定发布的正文发到飞书;格式异常时不发。
也可以在单个 bot 的 vcMeetingAgent.meetingConsumer.consumerProfiles 里手写角色,写了就不再用共享预设。手写时需要用 agentAppId 指明由哪个 bot 执行:
把角色 id 加进 defaultConsumerIds、defaultMode 设为 agents,开会时就默认启用;否则可以在会中弹出的选择卡片里手动启用。
会话环境变量(全局 / Bot 两层)

会话拿到的环境变量按这个顺序一层层叠上去,后面的覆盖前面的:
在 Dashboard 里管理:全局层在「全局设置 → 会话环境变量」,Bot 层在「Bot 配置 → 高级 → 启动环境 → 会话环境变量」。表格列出变量名、生效值和来源(宿主继承 / 全局 / 本 Bot),可以设置、覆盖、去掉、恢复继承,也能批量粘贴。默认只列本层改过的变量,继承来的收成一行「继承 N 条,展开」。凭据类的值默认打码,只有本机 owner 能点开看原文。
生效时机:改完对新会话生效,不用重启 daemon。正在跑的会话保留启动时的环境,页面会列出「仍在使用旧环境」的会话,重启这些会话即可。想看某个运行中会话实际拿到的环境,在会话抽屉里点「更多 → 查看会话环境」(只读、打码,仅 Linux)。
规则:
- 每一层里,一个变量要么「设置」要么「去掉」。「恢复继承」就是删掉本层的条目,值回落到下一层。
PATH、HOME可以覆盖,不能去掉。- 每一层的「设置」和「去掉」加起来不超过 4 KB(tmux 单条命令有长度上限)。超出时保存会被拒绝;已经超出的老配置,往小了改总是允许的。
- 对 tmux / zellij / zmx 会话,「去掉」在会话启动的最后一步执行,所以 tmux server 全局环境和 shell 启动文件带进来的同名变量也会被去掉。
- 开着 lark-cli 应用绑定时,
ZDOTDIR/BASH_ENV由 botmux 接管;开着按触发人鉴权时,GIT_ASKPASS/GIT_CONFIG_*也由它接管,这些变量在这个 bot 上不能设置或去掉。 - 老配置不用迁移:
env就是 Bot 层的「设置」;没写envUnset/sessionEnv时一切和以前一样。 - riff / mojo 后端的会话不在本机运行,只会带上本 bot 的
env,全局层和「去掉」对它们不生效。 - CLI 自己配置文件里的 env(例如 Claude 的
~/.claude/settings.json)由 CLI 启动后自己注入,不受「去掉」影响。
tmux server 的全局环境:tmux server 启动时会冻结一份全局环境,之后新建的窗格都会继承它。「全局设置 → 会话环境变量」下方会列出默认 server 和托管会话专用的 tmux -L botmux server。本机 owner 可以把某个变量从 server 全局环境里移除(要二次确认),只影响之后新建的窗格;想长期去掉,还是用上面的「去掉」。
严格进程环境继承(需显式开启)
默认(不写 envPolicy,或写 { "mode": "inherit" })会继承宿主环境,只过滤掉已知的敏感项。严格模式只放行一份精确的变量名白名单:
TRAE_HOME、CLI_EXTRA_ARGS 这类适配器变量在严格模式下也不会自动继承,需要的话要在 inherit 里列出或写进 env。
怎么设置:
- Dashboard:「Bot 配置 → 高级 → 启动环境 → 会话环境变量」上方的「继承宿主环境」。
- 命令行:
botmux env-policy set '{"mode":"strict","inherit":["HTTPS_PROXY"]}'(用--bot选 bot),unset恢复默认。 - 飞书:
/botconfig set envPolicy {"mode":"strict"}。
格式错误、未知字段、保留变量名都会直接拒绝,不会悄悄降级。
什么时候生效:下次会话冷启动时生效;命令行离线修改只改文件,daemon 下次启动时读取。daemon 重启恢复会话时,如果旧会话的策略和现在不一致,会先关掉旧会话再重新启动,确认不了就拒绝启动。CLI 已经读到的环境没法热撤回。
覆盖范围:严格模式覆盖 botmux 自己启动的 PTY、tmux、zellij、zmx 会话,以及本机 Codex / TraeX App Server 和标题生成等子进程。tmux / zellij 不再加载 launchShell 的启动文件,而是用干净环境直接启动 CLI,所以 PATH、nvm、mise 等要靠基线或你显式配置提供。没有 TERM 时默认用 xterm-256color。
不支持的情况:Herdr、Riff、Mojo、Forge 启动模式、adopt 外部进程和外部 App Server 还做不到同样的隔离,开严格模式会拒绝这些路径。CLI 自己读取的配置和凭证文件、文件权限、云端账号也不在这个策略的隔离范围内。
和网络策略一起用:如果同时配了 sandboxNetworkPolicy,代理变量(HTTP_PROXY / HTTPS_PROXY / ALL_PROXY 及小写同名)还要满足下表。严格继承只决定变量能不能传到 CLI,不等于网络放行。
上表的通用代理委托只适用于普通会话。插件已冻结受保护 HTTP 出站策略时,trusted-egress 与任务代理变量均会明确拒绝,不能反复添加该配置消除报错;模型连接使用受保护模型桥,目前仅支持 Codex。详见网络沙盒文档。
trusted-egress 不创建代理、不自动授权环境变量、不保证 CLI 会使用代理;允许代理出口不等于限制代理后的业务目标。若模型依赖代理,不能只删掉 inherit 中的代理名称来让配置通过:应显式选择可信出口并配置出口规则与部署层 ACL,或先准备可直连的模型认证、获准目标 CIDR / 端口和 DNS,再移除代理授权。tmux 等持久后端、adopt 和外部 App Server 的拒绝门禁不会因 trusted-egress 或 envPolicy 放开。
网络策略本身要求 Linux、本地 PTY 后端和 sandbox: "oncall",详见文件与网络沙盒。
自动维护的字段(不要手改)
下面这些字段由 botmux 自己写入,列出来只是方便你看懂文件:
授权库(grants.sqlite)
单人对话授权不放在 bots.json 里,而是存在 <数据目录>/grants.sqlite(默认 ~/.botmux/data/grants.sqlite):包括 chatGrants、globalGrants,以及它们的消息额度和有效期。这样多 bot 建群时 bots.json 不会越写越大。
- daemon 启动时,如果
bots.json里还有这些字段(升级前留下的、或手工写的),会并入授权库后从bots.json删掉;库里已有的同一条以库为准。第一次删除前,整份bots.json会备份成bots.json.bak-grants-v1。 - 授权只在过期时自动回收:daemon 启动时和之后每小时清理一次。要提前撤销用
/revoke或授权卡。 - 多副本模式(
BOTMUX_COORDINATION_MODE=primary)下,授权仍保存在bots.json里。不要在两种模式之间来回切换:切到 primary 后,授权库里的授权不会被读取。
