botmux

飞书 + AI 编程 CLI——私聊 / 群聊 / 话题，每个会话一个独立 CLI 进程，实时流式回传。 Daemon 监听飞书消息，为每个新会话自动启动独立 CLI 进程（Claude Code / Codex / Cursor / Gemini / OpenCode / Antigravity / GitHub Copilot / Kimi Code / Grok Build / Kiro），提供实时流式卡片和可交互 Web 终端。

✨ 先看效果：《5 分钟创建一个真正好用的飞书助理》 —— 飞书图文 + 视频演示：AI 消息提醒 / 多端同步跨端操作 / 多 Bot 协作 / 多话题并行编排 / 语音总结 + 飞书会议 / Oncall 与个人替身。

📖 完整文档（命令 / 配置 / 最佳实践 / 排错）：https://deepcoldy.github.io/botmux/ ——本 README 只讲为什么用它和怎么快速上手。

演示

演示视频

为什么选择 botmux

设计理念

不做 SDK wrapper，直接桥接 CLI。

botmux 不重新实现 Agent 能力，而是直接桥接已有的 AI 编程 CLI（Claude Code、Codex、Cursor、Gemini、OpenCode、Antigravity、GitHub Copilot、Kimi Code、Kiro）。记忆、上下文管理、工具调用、权限体系——这些能力 CLI 本身都在快速迭代，botmux 选择站在这个进化之上，而不是平行重造一套。CLI 的每次升级，botmux 零适配自动受益。

核心优势

与 OpenClaw 等基于 Agent SDK 构建的方案相比：

功能特性

Skill 管理

botmux 可以管理 CLI 无关的自定义 Skill Registry，并按 bot 配置在会话启动时优先披露指定 skill；未配置时完全保持 Claude / Codex 等 CLI 自己的默认 skill 行为。安装、bot 级策略、Claude scoped plugin 和 Codex prompt delivery 说明见 Skill 管理。

实时流式卡片

每轮对话一张实时更新的飞书卡片，是你在手机/飞书上感知并操控 CLI 的主窗口：

• 终端画面实时截图刷新到卡片（xterm 无头渲染成图，原样还原 CLI 的 TUI）；可一键「显示 / 隐藏输出」「导出文字」「上下翻屏」
• 状态实时指示：启动中 → 正在分析 → 工作中 / 执行中 → 等待输入；额度用满会标「限额已达 · 可重试」
• 卡片上直接操作：打开（可写）终端、🔑 取操作链接、重启 / 关闭 / 接管会话、重发上一条任务
• 每轮一张新卡片，上一轮冻结存档；会话用 /relay 搬到别的群后，原卡片自动冻结为存档
• 关闭给「可恢复」卡片（附 CLI 原生 resume 命令），随时点回来继续

Web 终端（可交互）

每个会话提供一个 Web 终端，地址为 http://<WEB_EXTERNAL_HOST>:<端口>。

• 只读链接 — 展示在群话题的流式卡片上，随时查看进度
• 可操作链接 — 按需获取（点击卡片上的「🔑 获取操作链接」通过私聊发送），可直接在浏览器中操作 CLI
• 移动端/平板提供悬浮快捷键工具栏（Esc、Ctrl+C、Tab、方向键等），手机上也能流畅操作

多机器人协作

同一台机器上可运行多个飞书机器人，每个机器人可对应不同的 CLI。同一群聊中通过 @mention 路由消息，仅有一个机器人时无需 @ 自动响应；多机器人时 @<bot1> @<bot2> /t xxx 可让每个被 @ 的机器人在同一条消息上各自独立开新话题。先发一次 @<bot1> @<bot2> /introduce 让它们互相登记 open_id，之后各 bot 就能在自己的会话里显式 @mention 对方协作（命令详见 📖 文档 · 斜杠命令）。

多话题协作模式

「多机器人协作」的升级版：主 bot（编排者）把一个大任务拆成多个子项目，在群里自动开多条话题，每条话题派一组 bot 并行推进（常见「一个写代码 + 一个 review」），用一张飞书任务清单当所有人共享的进度板，最后由主 bot 收齐汇总。一个普通群就是一个并行工作台，你在飞书任务面板一眼看完成度。

怎么跑 —— botmux-orchestrate skill 教编排者走完整流程：

拆子项目 → 提一版「子项目 ↔ bot」分配 → 发给你一次审批（可用卡片确认） → 建飞书任务清单 → 逐个开话题派活 → 收齐回报 → 汇总

底层派活靠 botmux dispatch：在群里种一条话题、把指定 bot @ 进去各起独立会话。

botmux dispatch --title "实现登录模块" \
  --bot "ou_xxx:Alice:coder" --bot "ou_yyy:Bob:reviewer" \
  --repo /path/to/repo --brief-file /tmp/brief.md

• --repo <目录> —— 预设子 bot 的工作目录（绝对路径，需在子 bot 所在机器上存在），起会话直接进去、免手点「选仓库」卡。
• --standby —— 必须配 --repo（且不能与 --into 同用）：只发一次 /repo 把 bot 拉起到指定目录待命、不派简报，之后用 --into ... --brief(-file) 激活派活。
• --into <话题root> —— 回到已有话题追加一条（激活待命的 bot / 追加协调）；仍需 --bot，且非 standby 时必须带 --brief 或 --brief-file。

协作边界：

• 同部署的「自家」bot 之间互信 —— 编排者能直接对它们跑 /repo 等 operate 级命令（与自家 bot 的对话权限一致）。外部 bot 的授权分两层：/grant @bot 只给「对话 / 被 chat-scope 拉起」的权限（talk-only，不碰 allowedUsers、跑不了 operate 级命令）；要让外部 bot 跑 /repo 等 operate 级命令，需把它列进 allowedUsers（或后续 operate 级授权）。/introduce 只负责发现 / 登记 open_id，不授予任何权限。
• 子 bot 须已在群里、可被 @（具备 im:message.group_at_msg.include_bot 权限）。
• 一条话题可放多个 bot，它们在话题内互相 @ 协作（如 coder 写完 @ reviewer 审）。

Tmux 会话常驻

安装 tmux 后自动启用。CLI 进程常驻在 tmux session 内，所有功能不受影响。

核心收益：Daemon 重启不中断 CLI。 botmux restart 时 worker 进程退出，但 tmux session（及其中的 CLI 进程）保持运行。下次收到消息时 worker 自动 re-attach，无需 --resume 重载上下文。

# 交互式会话列表 — 选择后直接 attach 到 tmux（见 § CLI 命令）
botmux list

# 也可以手动 attach（会话名 = bmx-<sessionId 前 8 位>）
tmux attach -t bmx-<session-id-前8位>
# Ctrl+B, D 退出 attach，不影响 CLI 继续运行

# 强制降级到纯 pty 模式（不使用 tmux）
BACKEND_TYPE=pty botmux start

会话接入（Adopt）

将已在 tmux 中运行的 CLI 进程无缝接入 Botmux，在手机上通过飞书查看进度和交互。

/adopt              # 弹出选择卡片：① 接管运行中的会话 ② 从磁盘 resume 导入历史会话
/adopt 0:2.0        # 直接接入指定 tmux pane（或传历史会话 id 直接 resume 导入）

• 历史会话导入 — 卡片第二栏列出本机该 CLI 的历史会话（claude-code / seed / codex / traex / antigravity / genius），选中即以 --resume 在原工作目录重建为标准 Botmux 会话，无需进程仍在运行、也不用先迁进 tmux
• 共享模式 — Botmux 接入后，iTerm2 和飞书双向同步：流式卡片实时显示终端输出，飞书聊天框输入直接透传到终端
• 一键接管 — 点击流式卡片上的「🔄 接管」按钮，Botmux 以 --resume 重建会话，转为标准 Botmux 会话
• 安全断开 — 点击「⏏ 断开」，Botmux 退出观察，原 CLI 不受影响

定时任务

支持三种调度类型 + 中文自然语言，支持原话题延续（到点在同一话题内继续，不另开 thread）。

两种创建方式：

• 斜杠命令（快捷）：/schedule 每日17:50 帮我看看AI圈有什么新闻
• 对话触发（灵活）：直接跟 agent 说「帮我加个每天 18:00 检查部署的定时任务」，自动触发 botmux-schedule Skill

支持的调度格式：

• 中文自然语言：每日17:50 / 每周一10:00 / 30分钟后 / 明天9:00
• 英文 duration/interval：30m / 2h / every 30m / every 2h
• Cron 表达式：0 9 * * *
• ISO 时间戳：2026-05-01T10:00

与飞书话题的交互（Skill + CLI）

CLI 进入 botmux 会话时自动获得 ~/.botmux/bin 在 PATH 中，以及一组开箱即用的 Skill：

• botmux send — 向当前话题发消息（支持文本、图片、文件、interactive 卡片 JSON、@mention）
• botmux history — 读取当前会话历史消息（话题/thread 会话拉话题内，普通群 chat-scope 会话拉整群）
• botmux quoted <message_id> — 用户用引用 UI @ 机器人时，按需读取被引用的那条消息
• botmux bots list — 查询当前群聊的机器人及 open_id
• botmux schedule — 增删改查定时任务

这些能力通过 --append-system-prompt 注入和 Skill 描述自动引导 agent 使用。Skill + CLI 的组合相比 Anthropic 官方 Telegram channel 那套 MCP 方案：CLI 启动不用做 MCP 握手、不占用工具列表 token，且对 Claude Code / Codex / Cursor / Gemini / OpenCode / Antigravity / GitHub Copilot 通用 —— 只要 CLI 能读 system prompt 跑 shell 命令就行，不依赖任何 MCP 协议支持。

Dashboard 管控面

命令行 botmux dashboard 出一次性 token URL，浏览器里跨所有 daemon/机器人管控

• 一键定位回飞书话题 / 跳 Web 终端 / 多选批量关闭会话
• 添加机器人对齐 Feishu 单次扫码主路径：名称可选且全程冻结，支持 AI CLI / 工作目录选择、管理员 fail-closed 补填与显式兼容模式
• 拉新群、自动转让群主、@ 提醒
• 解散群聊、bot 退群（关联会话自动清理）
• 会话洞察（owner-only，只读）：解析各会话 transcript，看动作 span / 工作时序 / 上下文曲线 / 失败聚合 + 诊断建议；聊天里发 /insight 可取当前会话摘要卡
• Workflows 管控面：
  • Run List 5s 轮询；Run Detail 看 summary / dangling 红区 / node-activity 表 / event timeline / 并发执行 timeline（attempt 级时序），到 terminal 自动停轮询
  • Dashboard 内可直接 cancel run、批准/拒绝 humanGate（approve/reject + 评论）
  • Workflow Catalog：列所有 ~/.botmux/workflows/ 下的 workflow，点进去看 schema / 依赖图，直接在 UI 触发 run（带 params 输入）
  • IM 卡片（cancel / approve / reject）仍可用；CLI 子命令也保留

前置要求

• Node.js >= 22
• AI 编程 CLI / 本地 Agent 应用 已安装并完成认证（claude、codex、coco、cursor-agent、gemini、genius、opencode、hermes、seed（Seed CLI，Claude Code 衍生）、relay（Relay CLI，Seed 新版）、pi、omp（oh-my-pi，Pi 衍生）、copilot（GitHub Copilot CLI）、traex（TRAE CLI）、mircli（Mir CLI）、agy（Antigravity）、kimi（Kimi Code）、grok（Grok Build）或 kiro-cli（Kiro）在 PATH 中）
  • CoCo 最低版本 0.120.32：type-ahead（会话忙时即可发新消息，由 CoCo 自己的消息队列接住）依赖 0.120.32+ 的行为；更早版本忙时输入可能丢失或串行，请升级后再用
• tmux >= 3.x（可选，安装后自动启用会话常驻）
• CJK 字体（用于截图渲染中文/emoji）：
  • macOS 自带 PingFang/Hiragino，无需配置
  • Debian/Ubuntu：daemon 启动时若检测到缺字体会后台 apt-get install fonts-noto-cjk fonts-noto-color-emoji（需免密 sudo 或以 root 运行；装完重启 daemon 生效）
  • 其他 Linux 发行版请手动安装 Noto CJK + Noto Color Emoji（包名视发行版而定）

5 分钟快速接入

💡 TL;DR：npm i -g botmux → botmux setup，飞书租户扫一次码就能建好一个可用机器人 → botmux start。这次扫码拿到的 Web 登录态会连续完成：按 botmux-N（可自定义）命名并创建应用、读取 AppID/AppSecret、导入权限、配置重定向 URL、创建并提交发布版本。整个开放平台配置都由 setup 默认完成；加 --no-open-platform-auto 可跳过应用创建后的权限/发版自动配置。

1. 安装 botmux

npm install -g botmux
# 或：pnpm add -g botmux

botmux 的手动/定时更新会识别当前全局安装归属，并继续使用同一个 npm 或 pnpm 安装位置；无法安全识别的安装方式不会自动回退到 npm。

要求 Node.js ≥ 22，且本地已装好并登录至少一种 AI 编程 CLI（claude / codex / cursor-agent / gemini / opencode / coco / agy / grok / kiro-cli 等在 PATH 中）。推荐顺手装 tmux（装了自动启用会话常驻）。

2. 创建应用并配置（botmux setup）

跑 botmux setup，全程交互式选择（↑/↓ 选择、输入即搜索、⏎ 确认、Esc 取消；非交互终端自动回退为序号输入）：

1. 操作：首次安装直接进入创建流程；已有配置时先选「添加新机器人 / 重新配置 / 编辑现有机器人 / 删除机器人」。
2. 飞书应用来源：三选一——
   • 一次扫码创建新应用（推荐）：可填写机器人名称；留空自动使用 botmux-0、botmux-1……。首