botmux

https://github.com/user-attachments/assets/2cd97623-6b92-42ea-a9e9-75c6f5434db6

Daemon 监听飞书消息，为每个新会话自动 spawn 一个独立的会话进程，把 AI 编程 CLI / Agent 的输出实时流式回传成飞书卡片，并提供可交互的 Web 终端。它不重造 Agent 能力，而是直接桥接你已经在用的工具（20+ CLI / Agent 适配器，见 支持的 CLI / Agent）。

它解决什么

• Agent 收不到通知、手机控不了 — CLI 跑在开发机上，人在手机上。botmux 把每轮输出推成飞书卡片，随时随地查看 / 追问 / 打断，还能开可写 Web 终端直接操作。
• CLI 不感知飞书上下文 — 把机器人拉进话题群 / oncall 群，@ 一句就在你本机的代码库里开跑；会话可以用 /relay 原样搬到另一个群，上下文一点不丢。
• 单个 Agent 不够用 — 同一个群里放多个不同 CLI 的机器人，@ 谁谁干活，让 Claude Code 和 Codex 一起 review 同一个 MR、各自独立分析、观点不同自动互怼。

5 分钟接入

约 5 分钟：botmux setup 一次飞书扫码就连续建好应用、配全权限、发版（加 --no-open-platform-auto 则只建应用、跳过权限与发版的自动配置，之后需手动完成；手动创建 / 粘贴凭证是 setup 里的另一个选项）。

curl -fsSL https://raw.githubusercontent.com/deepcoldy/botmux/master/install.sh | sh
botmux setup                 # 一次扫码建应用 → 选 CLI → 选工作目录（自动配权限 + 发版）
botmux start                 # 启动 daemon（botmux autostart enable 设开机自启）

botmux 本体是一个自包含单文件二进制，运行时已嵌在里面——装它和跑它都不需要机器上有 Node（你要接的 AI 编程 CLI 自己需要什么另算）。装到 ~/.botmux/bin/botmux（BOTMUX_INSTALL_DIR 可改），按 OS/arch 自动选对应二进制、校验 SHA-256，并把 ~/.botmux/bin 写进你当前 shell 的启动文件（zsh / bash / fish 各写对的那个），开个新终端就能用。

安装过程不编译任何原生模块（不需要 Python / node-gyp / 编译器）：PTY 已经嵌在二进制里。支持 linux / macOS × x64 / arm64（Alpine 等 musl 环境自动选 musl 版）；Windows 请在 WSL2 里安装（daemon 依赖 PTY / tmux / Unix 信号，原生 Windows 跑不了；WSL2 报告为 linux，是完整支持的一等环境）。平台不在列表里、或下下来的二进制在本机跑不起来，安装会明确报错并保留原有版本，而不是装上一个起不来的命令。

正式版 macOS CLI 使用稳定的 Apple Developer ID 签名。升级替换二进制后，macOS 的文件与 App 数据访问授权仍绑定同一代码身份，不会因为版本哈希变化而把 botmux 当成一个新程序；canary / beta / rc 等预览版仍使用 ad-hoc 签名。

升级：一律重跑上面那条 curl 命令（npm / pnpm 全局安装也用它，原地替换、不会重复往启动文件里追加 PATH），装完开个新终端跑 botmux restart；≥3.18 的二进制安装上 botmux upgrade 与其等价。装指定版本（含回滚）：curl -fsSL https://raw.githubusercontent.com/deepcoldy/botmux/master/install.sh | BOTMUX_VERSION=v3.18.8 sh（变量必须在管道右侧的 sh 前面）。⚠️ v3.18.0 之前的老版本不要用 npm 升级——跨「Node 源码 → 二进制」形态边界会让 daemon 重启失败。

npm install -g botmux        # 需要 Node >= 22 装包本身

npm 包内带的是同一个自包含二进制（按 os/arch 只装匹配的那一个）。包的 bin 指向随包发布的 sh 启动器，由包管理器自己链到 PATH——npm / pnpm / bun 三种装法都不依赖生命周期脚本（pnpm 10/11 与 bun 默认不跑依赖的 postinstall，早期版本因此装完没有任何 botmux 命令）。postinstall 仍会把 ~/.botmux/bin/botmux 指向同一个二进制并写 PATH。所以装完始终只有一个 botmux 版本（两个入口都 exec 同一个二进制），不再出现「装了两个 Node 版本、各自带一份全局 botmux 互相打架 / 不知道更新了哪个」。

区别只在谁来装：npm 路径需要 Node ≥ 22 才能执行安装本身，curl 路径全程不碰 Node；无论哪种装法，升级都重跑 curl（v3.18.0 之前的老版本用 npm 跨形态升级会让 daemon 起不回来）。跑起来之后两者完全一致——同样的二进制、同样的命令。

然后私聊机器人、或 botmux dashboard 拉个群，直接开聊。完整步骤（含 Lark 国际版、--no-open-platform-auto 后手动配置权限 / 发版、排查）见 5 分钟快速接入。

核心场景

• 实时流式卡片 — 每轮对话一张实时刷新的卡片，终端画面原样截图回传；一键显示/隐藏输出、翻屏、重启/关闭/接管会话。
• 多机器人协作 — 同群多 bot @mention 路由，不同 CLI 背后不同模型，天然多样性；方案评审 / 代码 review / 技术选型让它们互相挑刺。
• 群内真人独立 lane — 可复用 Dashboard 的「跨身份打断隔离（XPI）」开关，让同一群里的真人各用独立 CLI 上下文和 git worktree；消息仍公开可见，引用别人的任务仍可走建议/确认协作。
• 多话题并行编排 — 给编排者一个大任务，它自动在群里种话题、拉各 bot 起独立会话跑流水线，飞书任务面板一眼看完所有子任务进度。
• 可交互 Web 终端 — 不只是看输出，浏览器 / 手机直接操作 CLI，移动端带悬浮快捷键栏（Esc、Ctrl+C、方向键）。
• 会话接入 & 接力 — tmux / Zellij / Herdr / Orca（实验性）里跑到一半，手机 /adopt 接入；/relay 把整个会话（原进程、原记忆）搬进团队群继续。
• 定时任务 & 外部触发 — 自然语言配周期任务（报警分析 / 群总结）；从外部系统编程式触发用 Webhook 或 API 任务触发。
• Oncall 模式 & 语音总结 — 拉进 oncall 群，任何成员 @ 即在项目目录排查；配好 TTS 后每张卡片页脚会多一个 🔊 语音总结按钮，让模型「说人话」。

更多：角色与团队 · 文件沙盒 · Dashboard 管控面 · tmux 会话常驻 · 飞书会议智能体（效果展示）。

按 Bot 设置零注入

在 Dashboard →「Bot 配置」→ 选中 Bot →「高级」→「零注入」打开开关；需要统一管理多个 Bot 时，在「Agent 配置」里开启「零注入」分组，关联的 Bot 会随同步一起切换（此时 Bot 配置页的开关锁定）。也可在对应 bots.json 条目设置 "promptInjection": "none"。适合 lead-bot 派活、sub-bot 专注执行的场景。default / 删除字段恢复原行为，既有 prompt、角色和技能配置不会被清空。当前 CLI、终端后端或沙盒组合不支持时开关置灰并说明原因。

此模式只传任务正文与附件信息，跳过 botmux 的系统提示、逐轮提醒、身份信封、角色、白板、记忆与技能目录；自动从 CLI 转写回传最终回答。使用新会话验证：已经进入历史的提示无法撤回，CLI 原生系统提示、项目 AGENTS.md 及用户自行安装的技能仍由 CLI 管理。

支持范围复用 CLI 的最终回复兜底采集能力：目前包括 Claude Code、Codex、TraeX、CoCo、Hermes、MTR、Pi、Oh My Pi、ebsd、Grok、Cursor（普通 spawn 与零注入均始终启用，模型忘调 botmux send 时自动补发；可在 Bot 配置里显式开启 replyDelivery: transcript 后连逐轮信封也改为转写模式），以及仅在零注入下启用转写采集的 Antigravity（常规模式仍通过 botmux send 回复，故默认不采集；均限 PTY、tmux 等本地后端，Codex / TraeX 可走 RPC 输入）。暂不支持远端后端和 v3 workflow；Cursor、Antigravity 的转写目录（~/.cursor、~/.gemini）在 oncall 沙箱（sandbox: true/oncall、读隔离、BOTMUX_SANDBOX）中以目录级 bind 直挂宿主真实路径，零注入可与其同时使用；全根 COW 的 sandbox: "scratch" 暂不支持这两者（结构化桥读不到 merged 视图，零注入直接报错；Cursor 的 replyDelivery: transcript 在该模式下也不允许写入，避免模型被要求不调 send 而采集静默无回复）。Antigravity 的静默终态需经视口确认，故暂不支持 zmx 后端（Cursor 的终态即时采集，不受此限）。CLI 的共享技能目录若存在全局安装的 botmux-* 技能，会拒绝启动以免假称零注入；请使用按会话的技能注入方式或独立 home，不会删除其它 bot 共用的文件。

普通协作可直接在群内 @ 执行 bot，最终回答自动回复当前会话，并默认 @ 本轮任务的发起人（真人或 bot）。收件人取自宿主记录的本轮身份，排队和重试不借用后续轮次的发送者；缺少可用身份时不猜测会话 owner，也不注入额外 prompt。已经 @ 发起 bot 的回复本身就是回报，不再额外通过 HTTP 重复追加一轮任务。回答正文用完整显示名点名群内其它 bot（如 @Reviewer 请合并）时，与 botmux send 一样就地换成真正的 @，被点名的 bot 才会被唤醒；这时不再 @ 真人发起人，点名的 bot 解析不出身份时宁可不 @ 任何人，发起 bot 仍照常被 @。代码里的名字、私聊和失败通知不受影响。

零注入会话也默认回传 Web 终端中的最终回答：/rewind 重跑和随后直接输入的多轮对话，都沿用最新飞书发起人的回复位置和 @，以普通回复卡发送，不附加终端来源或复述输入。每个终端回合开始时固定回复对象，新飞书消息只影响之后开始的回合；/model 等设置命令、菜单输出和已有历史不回传。该行为复用原生转写监听，不增加开关或 prompt；普通模式和 /adopt 保持原行为。

没有通过 @ 发起 bot 回报时，已建立签名回报绑定的 botmux dispatch --bot-app <稳定 App ID> 派单仍可自动回报原 lead：sub 的 daemon 根据绑定去掉自动附加的 report/send 指令，每轮最终回答回报一次，不自动判定任务完成。回报使用独立重试和持久化去重回执，失败不影响子会话回复；lead 正常在原会话回复，不进入 HTTP 结果轮询。提交结果不明时拒绝自动重放。dispatch --into 向此前没有派单记录的普通消息追加任务不会创建该绑定，仍会保留完成指令，不能据此验证零注入。

支持的 CLI / Agent

可选的 OpenViking 共享记忆示例让所有具备 shell 的 coding agent 共用用户与项目记忆，自主搜索、读取和保存重要结论。默认关闭，通过公共 Skill/CLI 显式绑定本地 Agent 或单用户 Bot；Codex 自动会话采集作为独立可选适配。（该示例仅存在于源码仓库的 examples/，npm 包不打包 examples/，此链接在 npm 页面不可达。）

bots.json 里用 cliId 一键切换。20+ 适配器，覆盖本地 CLI（进程隔离，tmux attach 可直连）和 API / 云 Agent（如 Mira、riff——通过 API / 远端接入，非本地进程；mojo 为 API 驱动、默认在宿主机执行工具，可配 cloud: true 走云沙箱）。代表项：

claude-code · codex · gemini · cursor · opencode · opencode2 · mimocode · antigravity · copilot · grok · kimi · codem (CodeM) · kiro-cli · reasonix · dsh · aiden · coco(TRAE) · hermes · ebsd · mira · riff(云 Agent) … · mojo(API 驱动,默认宿主机执行) · remote-runner(通用远端 Runner 协议) · minimax(MiniMax Code / mcode，支持文件与 Shell 工具、原生 Skills 和精确会话恢复；mcode login / mcode login --region global 登录，多账号用 MINIMAX_DATA_DIR 隔离) …

ebsd 使用独立的外部服务身份和原生 OMP 会话目录；部署方必须通过受限权限文件配置 Diag Gateway token 与 ByteCloud service account，不能把密钥写入 bots.json。

bots.json 里只放非敏感元数据和密钥文件路径，例如：

{
  "cliId": "ebsd",
  "workingDir": "/var/lib/botmux/ebsd-work",
  "sandbox": true,
  "env": {
    "EBSD_BOTMUX_DIAG_ENDPOINT": "https://ebsbot.example",
    "EBSD_BOTMUX_DIAG_TOKEN_FILE": "/run/secrets/ebsd-botmux/diag-token",
    "EBSD_BOTMUX_BYTECLOUD_ACCESS_KEY_FILE": "/run/secrets/ebsd-botmux/bytecloud-ak",
    "EBSD_BOTMUX_BYTECLOUD_SECRET_KEY_FILE": "/run/secrets/ebsd-botmux/bytecloud-sk",
    "EBSD_BOTMUX_SUBJECT": "botmux-ebsd@prod",
    "EBSD_BOTMUX_REPOSITORY_ROOT": "/srv/repos"
  }
}

三个密钥文件必须是运行 BotMux 的账号持有的 0600 普通文件，不能是符号链接；文件内容、AK/SK 和 Gateway token 都不得写进 bots.json。workingDir 应是专用空目录，仓库通过只读的 EBSD_BOTMUX_REPOSITORY_ROOT 暴露。Linux 开启 sandbox 前需安装 bubblewrap，隔离建立失败时会拒绝启动。当前/上一把 Gateway key 可以在服务端并存完成轮换，subject 保持不变。

当前完整 cliId 以 src/adapters/cli/registry.ts 为准；各 CLI 的配置与套 wrapper / 网关方法见 多 CLI 适配器。

托管的本地 Codex（tmux，含 aiden x codex）会话卡片提供「思考强度」下拉框。仅修改当前会话；空闲时选择后仅保存配置，卡片显示「待生效」；当前 CLI、预览和后台服务保持运行。设置在下一次正常冷恢复、重新创建 Worker/CLI 时生效，下一条消息或连接重附不会强制重启。执行中、等待输入、接管的外部 CLI 和未验证的后端会拒绝切换。下拉框优先显示上一轮实际强度，已保存但尚未应用的配置沿用「待生效」提示；独立 Codex 实例按已绑定的 home 检查历史，Aiden wrapper 继续遵守上游不支持实例池的限制。机器人默认值仍由各机器人配置管理，不修改本机 Codex 默认值。

会话级 CLI 选择

在会话尚未启动前，可以用 /cli <cliId> 为当前会话选择已注册的 CLI，例如：

/cli codex

这个选择只切换裸 CLI 适配器，不继承当前 bot 配置中的 wrapperCli、model 或 startupCommands。因此依赖 ttadk、aiden 等 wrapper / 网关才能启动的 CLI，不适合用会话级选择切换；应直接把 bot 默认配置设为对应的 wrapper 组合。会话启动后 CLI 选择冻结，后续消息和恢复都会继续使用该 CLI。

会话级 Codex 实例

同一 Bot 的 Codex 多登录目录可使用 [会话级 Codex 实例](do