botmux 文档
  • 简体中文

      • macOS 桌面版

      Botmux Desktop 是 botmux 的 Mac App。它把运行环境打包在 App 里，不用装 Node，也不用装全局 botmux 命令，双击就能启动后台服务、看 Dashboard、看日志。

      适合这些情况：

      • 你在 Mac 上用 botmux，想要一个点一下就能启动 / 停止的窗口，而不是记命令。
      • 你不想在电脑上折腾 Node 版本。
      • 你希望登录 Mac 后 botmux 自动在后台跑起来。

      在 Linux 服务器或开发机上部署，还是用 快速接入 里的命令行安装。桌面版只有 macOS。

      和命令行版是什么关系

      桌面版命令行版（curl / npm 安装）
      运行环境App 自带，和 App 版本一致你装的那个 botmux 程序
      配置、会话、日志都在 ~/.botmux都在 ~/.botmux（同一份）
      机器人进程由 App 里的运行时启动由 botmux start 启动

      两边读写的是同一个 ~/.botmux：机器人配置（bots.json）、会话、日志、后台进程记录都共用。所以从命令行版换到桌面版，不用重新配置机器人。

      但同一时间只能有一方在管这批机器人。桌面版打开时会自动把它们接过来，详见下面的 打开 App 时会发生什么。

      安装

      1. 打开 GitHub Releases，找到最新的正式版。
      2. 在附件里下载 Botmux-<版本号>-mac-universal.dmg（或同名的 .zip）。
        • 这是 Universal 包，Intel 和 Apple 芯片（M 系列）的 Mac 都能用。
        • 安装包经过 Apple 签名和公证，双击打开时不会被系统拦下。
      3. 打开 DMG，把 Botmux 拖进「应用程序」文件夹。
      4. 从「应用程序」或启动台打开 Botmux。

      只有正式版带桌面安装包。-canary、-beta 这类预览版只有命令行版。另外，安装包是在正式版发布后才挂上去的，刚发版的几分钟里可能还看不到。

      开始前：你要用的 AI CLI（如 claude、codex）仍然要先在终端里装好、登录好，默认还需要 tmux，见 前置要求。App 会读取你 shell 配置（zsh / bash / fish 的 profile 和 rc 文件）里的 PATH，所以终端里能找到的命令，App 启动的机器人也能找到。

      第一次使用

      以前用过命令行版：直接打开 App 就行。它会读到 ~/.botmux 里已有的机器人，自动接管并启动。

      完全没配过机器人：App 左下角会显示「需要配置」，控制台也加载不出来。这时要先添加第一个机器人：

      • 用命令行跑一次 botmux setup，飞书扫码就能自动建好应用。这一步要先装好命令行版，安装和 setup 的步骤见 快速接入 第 1、2 步。配好后回到 App 点「启动」。
      • 或者按 bots.json 配置 手写 ~/.botmux/bots.json（App 顶栏「打开目录」可以直接打开这个文件夹）。

      有了第一个机器人、服务跑起来之后，后面再加机器人就可以直接点 App 顶栏的「添加机器人」。

      日常使用

      App 分三块：

      位置能做什么
      左侧栏Dashboard 的各个页面（总览、会话、群组、定时、Bot 配置等）；底部是运行状态和「启动 / 停止 / 重启」按钮，以及「开机启动 App」开关
      顶栏在线 Daemon 数、需要处理的数量、已配置的 Bot 数；「创建会话」「添加机器人」「文档」「日志」「打开目录」；中 / EN 切换
      中间内嵌的 Dashboard，用法和浏览器里一样，见 Dashboard 管控面

      常见操作：

      想做什么怎么做
      启动 / 停止 / 重启所有机器人左下角的按钮，或菜单栏图标的 Start / Stop / Restart Botmux
      看日志顶栏「日志」，在抽屉里选要看的进程，可以一键复制；「打开文件夹」直接打开 ~/.botmux/logs
      登录 Mac 后自动运行打开左下角「开机启动 App」。App 会在后台静默启动，并自动把机器人拉起来
      关掉窗口点红色关闭按钮只是隐藏窗口，机器人继续在后台跑。点菜单栏图标可以再打开

      菜单栏图标的菜单：

      Show Console        打开窗口
Start Botmux        启动
Stop Botmux         停止
Restart Botmux      重启
Open Logs           打开日志文件夹
Open Botmux Home    打开 ~/.botmux
Quit App            退出 App

      「Quit App」只退出 App 窗口程序，不会停止机器人。想让机器人也停下来，先点「停止」再退出。

      打开 App 时会发生什么

      App 启动时会看一下现在的机器人是谁在跑：

      当前情况App 的动作
      没有在跑用 App 自带的运行时启动
      已经是 App 自己在跑什么都不做，直接显示
      是命令行版 botmux start 起的（或版本和 App 不一致）先正常停掉这批进程，再用 App 自带的运行时重新拉起来

      最后一种情况左下角会短暂显示「检测到由外置 botmux 启动的运行时，Desktop 正在切换到内置运行时」。这是正常的交接，不是命令行版被破坏了：

      • 不会删除或改动 ~/.botmux 里的配置。
      • 和平时 botmux restart 一样，进行中的会话会在重启后自动恢复。
      • 只替换 botmux 自己的核心进程，插件服务不受影响。

      另外，App 开着的时候，如果你又在终端里跑了 botmux restart / botmux start，App 几秒内会发现并再接管回来。这样可以避免两个版本同时连着同一批机器人。

      切回命令行版

      想改回用终端里的 botmux 管理：

      1. 在 App 里点「停止」（可选，但能少一次重启）。
      2. 关掉左下角的「开机启动 App」，以免下次登录又被 App 接管。
      3. 从菜单栏图标选「Quit App」退出 App（或按 ⌘Q）。
      4. 在终端执行 botmux start（之前点过停止）或 botmux restart（没停止）。

      只要 App 没开，命令行版就会一直管着机器人。哪天再打开 App，它会按上面的规则再接管过去。

      两边都设了开机自启时（App 的「开机启动 App」和命令行的 botmux autostart enable），登录后会先由命令行版拉起、再被 App 接管一次。能用但多一次重启，建议只留一个：用桌面版就执行 botmux autostart disable；用命令行版就关掉 App 的开关。

      升级

      下载新版 DMG，把新的 Botmux 拖进「应用程序」覆盖旧版，再打开 App。

      App 发现正在跑的进程版本和自己不一致，会自动用新版本重启一次。桌面版的升级只跟着 App 走：命令行的 botmux update 或重跑 curl 安装脚本，升级的是命令行版，不会改动 App。

      常见问题

      App 一直显示「需要处理」，控制台不出来？ 先点顶栏「日志」看报错。常见原因：~/.botmux/bots.json 格式写错（左下角会直接显示哪一项有问题），或者 App 正在从命令行版接管、稍等几秒。

      机器人提示找不到 claude / codex？ App 用的是你 shell 配置里的 PATH。先确认在新开的终端里 which claude 能找到。如果是 App 打开之后才装的或才改的 shell 配置：退出 App（菜单栏「Quit App」）再重新打开，然后点「重启」，让机器人用上新的 PATH。只重开 App 不够，因为退出 App 不会停掉正在跑的机器人。

      App 一打开就退出？ 通常是 App 包不完整（比如拷贝中断）。重新下载 DMG，覆盖安装一次。

      退出 App 后机器人还在回消息？ 正常。退出 App 不会停服务，要停先点「停止」。

      我能同时用桌面版和命令行版吗？ 可以都装着，配置也共用，但同一时间只有一方在跑机器人。App 开着时由 App 管；App 退出后可以用命令行版管。命令行里只查看、不改动的命令（比如 botmux status、botmux logs）随时都能用。