最佳实践
场景一 · Oncall 答疑
适合值班群、跨团队咨询、对外答疑:群里任何人 @ 机器人就能提问。
推荐步骤:
- 准备一台专用的干净机器(比如单独一台开发机)。值班同学和外部同事会让机器人跑各种命令,别让他们动到你个人的开发环境。
- 绑定项目目录:在群里发
/oncall bind <项目目录>。之后群里任何人 @ 机器人都直接进这个目录开聊,不用再选仓库。想让 bot 进的每个新群都自动这样,在 Dashboard「Bot 配置」的工作目录方式里选「Oncall 值班模式」并填好目录。详见 Oncall 模式。 - 开文件沙盒:机器人开放给半信任的人时,在 文件沙盒 里选「白名单隔离」。这样无论怎么诱导,模型都读不到你的私钥、Token 和其它代码库。多人在用却没开沙盒的 bot,botmux 也会主动提示你开。
- 写好角色(Role):角色就是给机器人的长期人设和规矩。用
/role set(只管本群)或/role team set(这个机器人在所有群的默认值)写进去。一个典型的 oncall 角色,在群里这样发(/role set后面可以换行接多行内容):
- 改代码用独立 worktree:开话题时用
/tw <问题>,机器人会先建一个独立的 git worktree(同一仓库的另一份工作副本)再开工,不会弄乱主仓库。会话关闭后,关闭卡片上会出现「🧹 清理 worktree」按钮,一点就删;有未提交改动、未推送提交或还有进程在用时不会删,分支也会保留。

权限怎么分: 绑定 oncall 后,群里所有人都能跟机器人对话;而 /cd、/restart、/close、点卡片按钮这类改动会话的操作,仍然只有 owner 和管理员(allowedUsers)能做。详见 权限与授权。
多个项目怎么办: 建多个机器人,每个 /oncall bind 到不同的项目目录,各管一摊。
在 Dashboard「角色管理」页,可以给每个群里的每个机器人可视化地配角色:

场景二 · 报警运维
让监控告警、CI、工单这类外部系统,主动把事情推给机器人处理。按你现在的告警链路,二选一:
方式一 · Webhook 推送(Dashboard「Webhook」页,详见 接入点(Webhook))
新建一个接入点,选好触发哪个机器人、投递到哪个群,就会拿到一条可以直接 curl 的地址。可以配置:
- 触发方式:新建时选「单轮对话」,机器人针对每条事件回应一次(旧版「工作流」类型已退役,不能新建)。
- 校验方式:默认是令牌(令牌就在 URL 里,一条 curl 就能触发);要更安全就换 HMAC 签名。
- 处理指令:用一段话告诉机器人收到事件该做什么,比如「判断严重程度、@ 相关 oncall、给出排查建议」。
- 每次新建群:每来一个告警自动建一个群,把机器人和它的管理员一起拉进去,还可以带上额外的机器人。填了「去重字段」,同一个值的告警会进同一个群;留空则每条告警一个新群。
方式二 · 监听现有告警群(Dashboard「消息监听」页,详见 群消息监听)
如果告警已经由第三方飞书机器人发到某个群,就不用配 Webhook:把机器人拉进那个群,开启消息监听,每条告警都会在它下方自动开话题排查。
- 发送者用黑名单模式,并勾选「机器人」类型,最稳妥地盯住第三方告警机器人。
- 没 @ 机器人的消息、其它机器人发的消息,靠大约每 30 秒一次的历史轮询补上,所以最多约 30 秒延迟。
再往上加一点:
- 进群就开工:在 Bot 配置里打开
autoStartOnGroupJoin,机器人被拉进新群(群里至少有一名管理员)就自动开工,不用手动 @。需要在飞书开放平台给应用订阅「机器人进群」事件,见bots.json· 主动开工。 - 一个项目一个报警机器人:每个机器人配上带项目背景的角色,再
/oncall bind到对应仓库,告警进来直接在那个仓库里排查。 - 定时巡检:配合定时任务,比如
/schedule 每天9:00 检查昨天的报警趋势并总结,有异常才 @ 人。

场景三 · 个人研发
一个人,用多个机器人协作开发。
- 不同机器人绑不同 CLI:比如一个 Claude Code、一个 Codex,按任务挑顺手的。支持的 CLI 见 CLI 适配器。
- 互相 review:让不同模型的机器人互审,或同一个 CLI 的多个机器人互审,多一双眼睛更稳。
- 用
/g一句话拉群:/g(即/group)能建一个新群并把多个机器人一起拉进来,围着同一个需求开发,见 一键建会话群。也可以用话题群,一个话题一个需求,上下文天然隔离。 - 给每个机器人分工:有的写代码、有的做 review。用
/role写人设,用/role cap set <描述>设「能力标签」(别的机器人挑协作对象时会看到它)。详见 角色与团队。 - 让多个机器人共用记忆(可选,默认关):想让不同 CLI 的机器人共用同一份用户和项目记忆,可以接 OpenViking 共享记忆示例。Agent 自己决定何时搜索、读取和保存结论。它默认关闭,常规安装和启动都不会启用,要显式绑定选中的单用户 Bot 或本地 Agent;目前适合同一系统用户的个人开发环境。部署和绑定步骤见 OpenViking 共享记忆。

场景四 · 多人协作
团队里每人有自己的机器人,一起干活。
- 先记住飞书的限制:机器人不会被另一个机器人的普通消息触发。要接力,必须在
botmux send里用--mention <对方 openId>显式 @ 对方。 - 看看群里有谁:
botmux bots list列出当前群里能协作的机器人、能力标签和能否被 @(mentionable)。模型也会在上下文的<available_bots>里看到可接力的对象。 - 让后加入的机器人也知道前情:管理员在群里发
@机器人 /context-sharing on,同一部署的机器人会在后台旁听;之后某个机器人被 @ 时,会自动收到它错过的群消息。详见 多机器人协作。 - 跨机器找同团队的机器人(需接入中心平台):
botmux bots list --scope team列出同团队、别人机器上的机器人;botmux create-group --team <团队> --agent <appId>把它们和各自的 owner 拉进新群。详见 多机器人协作。
通用建议(各场景都适用)
- 会话常驻:装好 tmux(botmux 的默认后端),CLI 跑在 tmux 里,daemon 重启也不丢上下文,见 Tmux 会话常驻。
- 电脑和手机无缝切换:电脑上已经开着的 CLI,用
/adopt接进飞书,路上用手机接着聊;需要亲自动手时,点卡片上的「🔑 获取操作链接」打开可写的 Web 终端。 - 常开 + 开机自启:部署在常开的开发机或服务器上,执行
botmux autostart enable,机器重启后自动恢复。 - 及时清理:会话用完顺手
/close。想省心,在 Dashboard「群组管理」里给群打开「无交互的会话自动关闭」;已经积压的,用botmux delete stopped清掉进程已退出的僵尸会话。
