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 里装。

🔁 升级：botmux upgrade（原地换二进制），或重跑一遍上面那条 curl 命令——同样原地升级，不会重复往启动文件追加 PATH。装指定版本：BOTMUX_VERSION=v3.18.8 curl … | sh。

📦 也可以走 npm（npm install -g botmux，需 Node ≥ 22 才能执行安装本身）：npm 包内带的是同一个自包含二进制（实测与 GitHub Release 资产 SHA-256 逐字节相同，按 os/arch 只装匹配的那一个），postinstall 把 ~/.botmux/bin/botmux 指向它并同样写 PATH。区别只在谁来装、以后谁来升：npm 路径需要 Node，升级交回 npm i -g botmux@latest；curl 路径全程不碰 Node。跑起来之后两者完全一致。

跑 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 回车。（已有配置时输入 2 添加机器人）
创建机器人：
- 输入 1 → 扫码创建（推荐）：飞书扫码，自动建出 PersonalAgent 应用并落盘 AppID/AppSecret，事件订阅 + bot 能力默认已配好。
- 输入 2 → 手动创建：去飞书开放平台建企业自建应用，粘 AppID/AppSecret。
选择 CLI：选本次要接入的 CLI（如接 Claude Code 就选 1）。
默认工作目录：通常填 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 · 建群开聊

飞书里创建一个话题群（普通群也支持）。
群设置 → 群机器人 → 添加你刚建的机器人。
群里直接发消息，机器人自动响应——它会弹一张仓库选择卡片，选项目后 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 / 排错。

#5 分钟快速接入

#Step 1 · 安装

#Step 2 · 配置（botmux setup）

#Step 3 · 启动