5 分钟快速接入

TL;DR：npm i -g botmux → botmux setup（一次飞书扫码连续建应用 + 配全权限 + 发版）→ botmux start → botmux autostart enable → 拉机器人进群开聊。

适用对象：任何要跑 botmux daemon 的机器（开发机 / devbox / 服务器）。如果只是在别人已部署好的群里 @ 机器人，本机不需要装任何东西。产品背景见 overview。

前置条件

「装完连不上 / 会话起不来」很多都是这里缺件：

Node.js ≥ 22：node -v 确认，低于 22 会有原生模块 / 语法报错。
至少一种 AI 编程 CLI 已安装并完成认证，可执行文件在 PATH 中：claude（Claude Code）、codex、cursor-agent（Cursor）、gemini、opencode、coco（Trae / CoCo）、agy（Antigravity）、hermes 等，完整 cliId 见 adapters。botmux 只是桥接层，不代管登录——先在终端里手动跑一次该 CLI 确认能对话，再接 botmux。
tmux ≥ 3.x：默认配置下会话后端就是 tmux，装了才能起会话。tmux 不可用时 botmux 不再静默降级 pty，而是硬拦截并弹卡提示装 tmux（见 tmux）。要跑无 tmux 环境，需显式选别的后端：BACKEND_TYPE=pty 或 per-bot backendType（pty / herdr / zellij）——pty 不跨 daemon 重启存活；herdr / zellij 需各自二进制。riff 是云 Agent，不占本地后端。

推荐部署形态：部署在常开的开发机 / devbox 上（而非笔记本），daemon 长期在线、tmux 会话常驻、随时手机遥控，配合 botmux autostart enable 重启自恢复。

Step 1 · 安装

npm install -g botmux

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 并打印一键复制命令；发布版本可用性范围选「仅自己可见」自动通过。

setup 的源码流程见 setup-flow；机器人配置文件字段见 bots-json。

Step 3 · 启动

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

Step 4 · 建群开聊与验证

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

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

收不到消息？自查

绝大多数「收不到消息」是本地配置或网络问题，不是 botmux 的 bug。推荐做法：用自己装的 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
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。

Wiki AI

目录