botmux

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

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

演示

演示视频

为什么选择 botmux

设计理念

不做 SDK wrapper，直接桥接 CLI。

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

核心优势

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

功能特性

实时流式卡片

每轮对话一张实时更新的飞书卡片，是你在手机/飞书上感知并操控 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              # 扫描 tmux，弹出选择卡片
/adopt 0:2.0        # 直接接入指定 tmux pane

• 共享模式 — 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 — 向当前话题发消息（支持文本、图片、文件、@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 终端 / 多选批量关闭会话
• 拉新群、自动转让群主、@ 提醒
• 解散群聊、bot 退群（关联会话自动清理）
• 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 >= 20
• AI 编程 CLI / 本地 Agent 应用 已安装并完成认证（claude、codex、coco、cursor-agent、gemini、opencode、hermes、seed（Seed CLI，Claude Code 衍生）、pi、omp（oh-my-pi，Pi 衍生）、copilot（GitHub Copilot CLI）、traex（TRAE CLI）或 agy（Antigravity）在 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。第 1 次扫码建应用、拿到 AppID/AppSecret（事件订阅 + bot 能力默认已配好）；第 2 次扫码让 botmux 内置的飞书 Web 登录自动导入权限、配置重定向 URL、创建并提交发布版本。整个开放平台配置（建应用 / 权限 / 重定向 / 发版）都已由 setup 默认完成；加 --no-open-platform-auto 可跳过第二次自动配置、改走文末折叠的手动步骤。

1. 安装 botmux

npm install -g botmux

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

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

跑 botmux setup，按交互菜单一步步选：

1. 新建配置：输入 1 回车（已有配置时输入 2 添加机器人）。
2. 创建机器人：输入 1 → 扫码创建（推荐），飞书扫码完成后自动建出 PersonalAgent 应用并落盘 AppID/AppSecret，事件订阅 + bot 能力默认已配好，无需手动浏览器创建。底层走 @larksuiteoapi/node-sdk 官方 device flow。（也可输入 2 手动粘贴 AppID/Secret，见文末折叠的「手动创建应用」。）
3. 选择 CLI：选本次要接入的 CLI（如接 Claude Code 就选 1）。
4. 默认工作目录：通常填 git 项目的父级目录（如 ~/projects），新话题会从该目录向下查找 git 仓库（最多 3 层）；尽量别填 ~（要遍历太多文件夹）。

接着进入第 2 次扫码：botmux 内置的飞书 Web 登录会自动导入权限、配置 http://127.0.0.1:9768/callback 重定向 URL、创建并提交发布版本。失败会自动回退并打印手动步骤（见文末折叠），不影响已写入的配置；权限只导入了一部分也算成功，缺的可事后到开放平台补。

✅ 飞书 (feishu.cn) 与 Lark 国际版 (larksuite.com) 均支持。扫码创建时自动识别租户类型（国内 / 国际）并记住，无需手动选择；手动粘 AppID/Secret 时会让你选一次。每个机器人按所属版本独立连对应域名，同一台机器可同时跑飞书 + Lark 机器人，登录凭证按应用隔离、互不干扰。

setup 末尾会用 tenant_access_token 校验凭证（通过才落盘 bots.json），并把完整权限 JSON 写到 ~/.botmux/lark-scopes.json 备查。

3. 启动

botmux start

start 前再校验一次凭证；权限未配齐不会阻塞 daemon，只 WARN。如果之后需要确认事件订阅，飞书后台会要求 daemon 已在跑才能识别长连接。

4. 建群开聊

1. 飞书中创建一个话题群
2. 进入群设置 → 群机器人 → 添加刚创建的机器人
3. 在群里发消息，机器人自动响应

5. 开机自启（推荐）

确认机器人能正常收发消息之后，跑一次：

botmux autostart enable

手动创建应用：去 [飞书开放平台](https://open.larko