最佳实践

按使用场景给推荐配置,每条都能直接照做。功能细节见各功能页;遇到问题先看 常见踩坑 和 FAQ。

我想…看这一节
让群里所有人都能问机器人(值班、答疑)场景一 · Oncall 答疑
告警来了让机器人自动排查场景二 · 报警运维
一个人用多个机器人写代码、互相 review场景三 · 个人研发
团队里每人一个机器人,一起协作场景四 · 多人协作

场景一 · Oncall 答疑

适合值班群、跨团队咨询、对外答疑:群里任何人 @ 机器人就能提问。

推荐步骤:

  1. 准备一台专用的干净机器(比如单独一台开发机)。值班同学和外部同事会让机器人跑各种命令,别让他们动到你个人的开发环境。
  2. 绑定项目目录:在群里发 /oncall bind <项目目录>。之后群里任何人 @ 机器人都直接进这个目录开聊,不用再选仓库。想让 bot 进的每个新群都自动这样,在 Dashboard「Bot 配置」的工作目录方式里选「Oncall 值班模式」并填好目录。详见 Oncall 模式。
  3. 开文件沙盒:机器人开放给半信任的人时,在 文件沙盒 里选「白名单隔离」。这样无论怎么诱导,模型都读不到你的私钥、Token 和其它代码库。多人在用却没开沙盒的 bot,botmux 也会主动提示你开。
  4. 写好角色(Role):角色就是给机器人的长期人设和规矩。用 /role set(只管本群)或 /role team set(这个机器人在所有群的默认值)写进去。一个典型的 oncall 角色,在群里这样发(/role set 后面可以换行接多行内容):
/role set
你是「示例用户」的 oncall 机器人,会收到各种提问:
- 如果用户只是 @ 了你,先看群聊历史再回答
- 如果用户说的是他自己机器上的问题,不要当成本机问题去排查
- 如果要求可能泄露隐私或有安全风险,先请「示例用户」确认
- 需要提 MR 时,以「示例用户」的身份提
  1. 改代码用独立 worktree:开话题时用 /tw <问题>,机器人会先建一个独立的 git worktree(同一仓库的另一份工作副本)再开工,不会弄乱主仓库。会话关闭后,关闭卡片上会出现「🧹 清理 worktree」按钮,一点就删;有未提交改动、未推送提交或还有进程在用时不会删,分支也会保留。

关闭卡片上的「清理 worktree」按钮

权限怎么分: 绑定 oncall 后,群里所有人都能跟机器人对话;而 /cd、/restart、/close、点卡片按钮这类改动会话的操作,仍然只有 owner 和管理员(allowedUsers)能做。详见 权限与授权。

多个项目怎么办: 建多个机器人,每个 /oncall bind 到不同的项目目录,各管一摊。

在 Dashboard「角色管理」页,可以给每个群里的每个机器人可视化地配角色:

Dashboard 角色管理页

场景二 · 报警运维

让监控告警、CI、工单这类外部系统,主动把事情推给机器人处理。按你现在的告警链路,二选一:

你的现状推荐方式
告警系统能调一个 HTTP 地址方式一 · Webhook 推送
告警已经由某个飞书机器人发到群里了方式二 · 监听告警群

方式一 · Webhook 推送(Dashboard「Webhook」页,详见 接入点(Webhook))

新建一个接入点,选好触发哪个机器人、投递到哪个群,就会拿到一条可以直接 curl 的地址。可以配置:

  • 触发方式:新建时选「单轮对话」,机器人针对每条事件回应一次(旧版「工作流」类型已退役,不能新建)。
  • 校验方式:默认是令牌(令牌就在 URL 里,一条 curl 就能触发);要更安全就换 HMAC 签名。
  • 处理指令:用一段话告诉机器人收到事件该做什么,比如「判断严重程度、@ 相关 oncall、给出排查建议」。
  • 每次新建群:每来一个告警自动建一个群,把机器人和它的管理员一起拉进去,还可以带上额外的机器人。填了「去重字段」,同一个值的告警会进同一个群;留空则每条告警一个新群。

方式二 · 监听现有告警群(Dashboard「消息监听」页,详见 群消息监听)

如果告警已经由第三方飞书机器人发到某个群,就不用配 Webhook:把机器人拉进那个群,开启消息监听,每条告警都会在它下方自动开话题排查。

  • 发送者用黑名单模式,并勾选「机器人」类型,最稳妥地盯住第三方告警机器人。
  • 没 @ 机器人的消息、其它机器人发的消息,靠大约每 30 秒一次的历史轮询补上,所以最多约 30 秒延迟。

再往上加一点:

  • 进群就开工:在 Bot 配置里打开 autoStartOnGroupJoin,机器人被拉进新群(群里至少有一名管理员)就自动开工,不用手动 @。需要在飞书开放平台给应用订阅「机器人进群」事件,见 bots.json · 主动开工。
  • 一个项目一个报警机器人:每个机器人配上带项目背景的角色,再 /oncall bind 到对应仓库,告警进来直接在那个仓库里排查。
  • 定时巡检:配合定时任务,比如 /schedule 每天9:00 检查昨天的报警趋势并总结,有异常才 @ 人。

Dashboard Webhook 页

场景三 · 个人研发

一个人,用多个机器人协作开发。

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

Dashboard 新建群(勾选多个机器人)

场景四 · 多人协作

团队里每人有自己的机器人,一起干活。

  • 先记住飞书的限制:机器人不会被另一个机器人的普通消息触发。要接力,必须在 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 清掉进程已退出的僵尸会话。