botmux 文档
  • 简体中文

      • 5 分钟快速接入

      💡 TL;DR：curl -fsSL .../install.sh | sh → botmux setup（一次飞书扫码连续建应用 + 配全权限 + 发版）→ botmux start → botmux autostart enable → 拉机器人进群开聊。

      开始前：先确认 前置要求（目标 CLI 已装并登录、tmux）——这里缺件是「装完连不上」最常见的原因。

      Step 1 · 安装

      curl -fsSL https://raw.githubusercontent.com/deepcoldy/botmux/master/install.sh | sh

      botmux 是自包含单文件二进制，运行时已嵌在里面——装它和跑它都不需要机器上有 Node。装到 ~/.botmux/bin/botmux（BOTMUX_INSTALL_DIR 可改），按 OS/arch 自动选二进制、校验 SHA-256，并把 ~/.botmux/bin 写进你当前 shell 的启动文件（zsh / bash / fish 各写对的那个），开个新终端就能用。支持 linux / macOS × x64 / arm64（Alpine 等 musl 环境自动选 musl 版）；Windows 请在 WSL2 里装。

      🔁 升级统一用 curl（与当初的安装方式无关，npm / pnpm 装的也一样）：重跑一遍上面那条命令即原地替换二进制，不会重复往启动文件追加 PATH，装完开个新终端跑 botmux restart。装指定版本：curl -fsSL https://raw.githubusercontent.com/deepcoldy/botmux/master/install.sh | BOTMUX_VERSION=v3.18.8 sh（变量必须写在管道右侧的 sh 前面才生效）。⚠️ v3.18.0 之前的老版本不要用 npm 升级——跨「Node 源码 → 二进制」形态边界会让 daemon 重启失败，详见 FAQ · 怎么升级？。

      📦 也可以走 npm（npm install -g botmux，需 Node ≥ 22 才能执行安装本身）：npm 包内带的是同一个自包含二进制（实测与 GitHub Release 资产 SHA-256 逐字节相同，按 os/arch 只装匹配的那一个），postinstall 把 ~/.botmux/bin/botmux 指向它并同样写 PATH。区别只在谁来装：npm 路径需要 Node，curl 路径全程不碰 Node；无论当初怎么装，升级都重跑 curl（v3.18.0 之前的老版本用 npm 跨形态升级会让 daemon 起不回来，见 FAQ · 怎么升级？）。跑起来之后两者完全一致。

      跑 botmux 本身不需要 Node，但本地要装好并登录至少一种 AI 编程 CLI（claude / codex / cursor-agent / gemini / opencode / coco / agy 等，它们各自的运行时要求另算）。默认会话后端是 tmux（≥3.x），需装好——不可用时会硬拦截弹卡、不再自动降级 pty；确需无 tmux 环境才用 BACKEND_TYPE=pty 或 per-bot backendType（pty/herdr/zellij）等显式后端（riff 是云 Agent，不占本地后端）。

      Step 2 · 配置（botmux setup）

      botmux setup

      交互式向导，跟着选即可：

      1. 新建配置：输入 1 回车。（已有配置时输入 2 添加机器人）
      2. 创建机器人：
        • 输入 1 → 扫码创建（推荐）：飞书扫码，自动建出 PersonalAgent 应用并落盘 AppID/AppSecret，事件订阅 + bot 能力默认已配好。
        • 输入 2 → 手动创建：去 飞书开放平台 建企业自建应用，粘 AppID/AppSecret。
      3. 选择 CLI：选本次要接入的 CLI（如接 Claude Code 就选 1）。
      4. 默认工作目录：通常填 git 项目的父级目录（如 ~/projects），最多向下查找 3 层。尽量别填 ~（要遍历太多文件夹）。

      ✅ 飞书 (feishu.cn) 与 Lark 国际版 (larksuite.com) 均支持：扫码建应用时自动识别租户类型，手动粘贴时可选。同机可混跑两种。

      🔧 扫码创建会自动配好全部权限并发版，无需手动操作。只有加 botmux setup --no-open-platform-auto（跳过自动配置）或手动建应用时，才需自己去开放平台导入权限 JSON（setup 会把完整权限写到 ~/.botmux/lark-scopes.json 并打印一键复制命令）并创建发布版本，可用性范围选「仅自己可见」自动通过。

      Step 3 · 启动

      botmux start            # 启动 daemon
botmux autostart enable # 开机自启（推荐，重启机器不丢，无需 sudo）

      Step 4 · 建群开聊

      1. 飞书里创建一个话题群（普通群也支持）。
      2. 群设置 → 群机器人 → 添加你刚建的机器人。
      3. 群里直接发消息，机器人自动响应——它会弹一张仓库选择卡片，选项目后 CLI 就在该目录启动。

      也可以私聊机器人直接开聊，或用 botmux dashboard 切到 Group Tab 一键拉群。

      收不到消息？自查

      绝大多数"收不到消息"是本地配置或网络问题，不是 botmux 的 bug。botmux 本就接了 AI agent——用你的 CLI 跑一条 headless 自查命令，让它读日志、查配置、直接给结论。

      先把排查任务存成变量（单行，省得重复粘）：

      DIAG='botmux 在飞书群收不到消息，请只读排查（别改任何东西），依次执行并给出最可能原因+修复步骤：botmux status（daemon 在跑吗）；botmux logs --lines 150（找 WebSocket 连接失败、token 鉴权、权限报错 401/403/411/400、CLI spawn 失败）；cat ~/.botmux/bots.json（确认 AppID/Secret/CLI 配置）；判断长连接是否被公司网/代理/防火墙挡住。最后给结论。'

      按你装的 CLI 选一条（都是非交互模式，跑完直接打印结论）：

      claude -p "$DIAG" --allowedTools "Bash"   # Claude Code
codex exec "$DIAG"                         # Codex
gemini -p "$DIAG" --yolo                   # Gemini
coco  -p "$DIAG" --yolo                    # Trae / CoCo（别名 trae-agent / ta）
cursor-agent -p "$DIAG"                    # Cursor

      末尾那些 flag（--allowedTools / --yolo 等）是让 agent 能真正执行命令读日志——纯只读排查。botmux logs 几乎能定位所有问题，是排查金标准。

      仍没头绪时手动核对（多为本地侧）：

      • daemon 没跑 / 改了配置没重启 → botmux status 看状态，botmux restart 重启。
      • 机器人权限不全 / 复用了旧应用创建的机器人（最常见）→ 见 常见踩坑，用最新 botmux setup 扫码重建。
      • 事件订阅 / 机器人能力（仅手动建应用需查）：开放平台订阅 im.message.receive_v1 + card.action.trigger（长连接 WebSocket）、应用功能 → 机器人 已开通。
      • 网络：长连接 WebSocket 出不去（公司网络 / 代理 / 防火墙）→ agent 在 logs 里能看到连接错误。

      确认后 botmux restart。更多见 FAQ / 排错。

      编辑消息补 @ 没有触发？

      编辑一条尚未触发机器人的消息并补上 @，需要额外订阅 im.message.updated_v1，且事件接收方式为长连接。缺少此事件不会影响普通新消息。

      群聊上下文共享（/context-sharing）要把撤回的消息从记录里标记掉，需要额外订阅 im.message.recalled_v1。缺少此事件时撤回不会同步到记录，机器人启动日志会提示未覆盖；不影响普通新消息。

      启动时，botmux 只会借助已有的飞书开放平台登录态，在现有长连接配置中补齐这个事件；不会切换接收方式、修改权限或自动发布版本。日志中的「更新请求成功」「配置回读包含事件」都不能证明已发布版本生效或已收到真实推送。正式应用新增订阅后，请在开放平台检查待发布改动并发布版本，再用一条尚未触发过的消息编辑补 @ 验证。

      如果发送者依赖团队成员身份获得发言权限，编辑消息还需要通过通讯录查询补齐 union_id。应用需要相应通讯录读取权限（默认权限清单含 contact:user.id:readonly），且发送者在应用可见范围内。权限不足或查询失败时，botmux 只使用消息原作者的 open_id 按原有规则鉴权，无法仅凭团队成员身份放行；不会借用编辑操作者的身份。