BotBus

BOTBUS / DOCS

BotBus Linux 版

一个命令行程序，装在 Linux 服务器或开发机上，让你在手机和手表上查看、审批这台机器上的 Codex、Claude Code 等 agent 任务。内容和 Mac 版一样端到端加密。

安装
curl -fsSL https://botbus.io/install.sh | sh

版本 1.0.5 · 发布于 2026-10-06 · x86_64 与 aarch64

01安装与配对

一行命令装好，终端里扫码配对

在要被手机查看的那台 Linux 机器上，用你平时登录的用户运行安装命令，不需要 sudo。

安装

终端
curl -fsSL https://botbus.io/install.sh | sh

没有 curl 时用 wget：

终端
wget -qO- https://botbus.io/install.sh | sh

安装脚本做了什么

  1. 按 uname -m 选 x86_64 或 aarch64 的包，下载本页列出的版本。
  2. 用发布清单里的 SHA-256 核对下载的包，对不上就停下，什么都不装。
  3. 把 botbus 放到 ~/.local/bin/botbus，不改系统目录。~/.local/bin 不在 PATH 里时会提示怎么加。
  4. 运行 botbus up：有 systemd 用户会话时装成用户服务 botbus.service，没有时用 nohup 在后台启动。
  5. 这台机器上有 Claude Code（~/.claude 存在）时，装好 BotBus 的 Claude Code hooks，电脑上开的 Claude 会话也能在手机上看到；卸载时会移除。
  6. 在终端里显示配对二维码，等你用手机扫码。

不在终端里运行时（CI、cloud-init、ssh host 'curl … | sh'），脚本只启动服务、不显示配对码，免得带密钥的配对链接进了日志。之后登录这台机器，在终端里运行 botbus pair。

退出 SSH 后保持运行

systemd 的用户服务默认在你最后一个登录会话结束时跟着停。在服务器上给这个用户开启 linger，服务就会一直运行，开机后也会自动启动：

终端
loginctl enable-linger $USER

有的系统要管理员权限才能开启，这时运行 sudo loginctl enable-linger $USER。botbus up 发现没有开启 linger 时会提示。

没有 systemd 的机器（容器、一些精简系统）用 nohup 在后台运行，退出 SSH 一般不受影响，但机器重启后要再运行一次 botbus up。有 systemd 时也想用这种方式，运行前设置 BOTBUS_NO_SYSTEMD=1。

配对手机

  • 用手机上的 BotBus 扫终端里的二维码。二维码是用字符画的，终端窗口太小显示不全时拉大一些。
  • 扫不了（比如就在手机上用 SSH 客户端）时，在手机上打开二维码下面的配对链接。链接里带着加密密钥，只在自己的设备之间传，不要贴进聊天或工单。
  • 配对码有有效期，终端里会写明；过期了就重新运行 botbus pair。
  • 已经配对过、想再加一台手机，也运行 botbus pair，它会生成邀请码。
  • 配对好之后，botbus status 显示连接状态和已配对的手机数。

02日常使用

用 botbus 命令管理

所有命令都以当前用户身份运行，经本机的管理通道和后台通信，只有你自己能用。

命令一览

命令作用
botbus up [--no-pair]安装并启动后台服务；还没配对时显示配对二维码。换了新版本的程序后再运行，会把后台换成新版本
botbus pair配对手机；已配对时生成邀请码，再加一台手机
botbus status [--json]连接状态、已配对的手机、检测到的 agent，以及有没有新版本
botbus agents列出检测到的 agent；botbus agents enable|disable <kind> 开关其中一个（如 claude、codex，ACP agent 写 acp:<id>）
botbus phones列出已配对的手机；botbus phones remove <id> 移除一台
botbus unpair解散整个配对组，所有手机都要重新扫码
botbus logs [-f]查看后台日志：systemd 下读 journal，nohup 方式读 ~/.local/share/botbus/daemon.log
botbus down停止后台服务，凭据保留
botbus update更新到最新版本
botbus uninstall [--purge]卸载后台服务与程序；--purge 同时删除凭据与数据
botbus --version显示版本

手机任务里 agent 用的 botbus share、link、list、mcp 与 Mac 版相同。Linux 版暂不支持开发预览（botbus preview）。

更新

终端
botbus update
  • 按 botbus.io 的发布清单下载本机架构的新版本，核对 SHA-256 和 Ed25519 签名，替换程序后重启后台，并确认跑起来的是新版本。
  • botbus status 会提示有没有新版本（每天检查一次）。
  • 也可以重新运行安装命令：装好新程序后，它运行的 botbus up 会把后台换成新版本。

卸载

终端
botbus uninstall

停止并移除后台服务，删掉 ~/.local/bin/botbus，并从 Claude Code 的设置里移除 BotBus 的 hooks。凭据留在 ~/.config/botbus，重新安装后不用再配对。

终端
botbus uninstall --purge

同时删除凭据与数据（~/.config/botbus、~/.local/share/botbus）。之后手机上这台电脑会显示离线，可以在手机上把它删掉。

03排障与参考

遇到问题

常见情况

  • 提示找不到 botbus 命令~/.local/bin 不在 PATH 里。运行 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile && . ~/.profile，或者直接用 ~/.local/bin/botbus。
  • 手机上看不到 Claude Code 或 Codexsystemd 服务用的是运行 botbus up 那一刻的 PATH。先装好 agent，确认终端里 which claude（或 which codex）找得到，再运行一次 botbus up，服务就会带上新的 PATH。botbus agents 列出检测到的 agent。
  • 电脑上开的 Claude Code 会话手机上看不到hooks 由 botbus up 在 ~/.claude 存在时装好，并用 curl 把事件报给 BotBus。装了 Claude Code 之后再运行一次 botbus up；没有 curl 时先装上。手机上新建的会话不靠 hooks。
  • 连不上，日志里有证书或 TLS 错误系统缺根证书。装上 ca-certificates（Debian / Ubuntu：sudo apt install ca-certificates，Alpine：apk add ca-certificates），再运行 botbus down && botbus up。最小化的容器镜像常常没有它。
  • 这台机器没有 systemd自动改用 nohup 在后台运行，容器里也能用；机器重启后运行 botbus up。
  • 退出 SSH 后服务就停了给这个用户开启 linger，见退出 SSH 后保持运行。
  • 后台起不来或状态不对看 botbus logs（加 -f 持续跟踪）。botbus status 也会报出凭据读取失败之类的原因。
  • 日志里的内容显示成 <private>日志默认把任务内容、路径这类字符串脱敏。排查时先 botbus down，再在前台临时运行 BOTBUS_LOG_PRIVATE=1 botbus daemon，按 Ctrl-C 结束后运行 botbus up。这样得到的日志含有任务内容，分享前先检查。

手动安装

不想用管道运行脚本时，可以自己下载、核对、解压。本版本的文件：

架构文件大小SHA-256
x86_64botbus-1.0.5-linux-x86_64.tar.gz
.sha256		30.5 MBfb75f3bc4bcaa62651653ce293514d6060ed422518e62c52f4649b3a7c128063
aarch64botbus-1.0.5-linux-aarch64.tar.gz
.sha256		29.1 MB5de0fa259dc4625674917381a8dfc7cc275228ae7b39a498c8535b7255373103
终端
VERSION=1.0.5
ARCH=$(uname -m)    # x86_64 或 aarch64
FILE=botbus-$VERSION-linux-$ARCH.tar.gz
curl -fLO https://botbus.io/downloads/linux/$FILE
curl -fLO https://botbus.io/downloads/linux/$FILE.sha256
sha256sum -c $FILE.sha256
mkdir -p ~/.local/bin
tar -xzf $FILE -C ~/.local/bin botbus
~/.local/bin/botbus up

sha256sum -c 应输出 OK，也可以和上表的 SHA-256 对照。发布包另有 Ed25519 签名，由 botbus update 校验。

文件放在哪里

位置内容
~/.local/bin/botbus程序本身：一个完全静态链接的文件
~/.config/botbus/配对凭据（文件权限 0600）与设置
~/.local/share/botbus/数据；nohup 方式运行时的日志 daemon.log
~/.config/systemd/user/botbus.servicesystemd 用户服务
$XDG_RUNTIME_DIR/botbus/管理 socket：botbus 命令经它和后台通信，只接受同一用户的连接

设置了 XDG_CONFIG_HOME、XDG_DATA_HOME 时按它们放。

安全

  • 内容端到端加密：任务、对话和命令在这台机器上加密后才发出，服务器只转发看不懂的密文。详见端到端加密。
  • 配对凭据只存在 ~/.config/botbus，文件权限 0600；同一台机器上的其他用户读不到，也连不上你的管理 socket。
  • 配对链接带着密钥，只打印在你的终端里，不写进日志。
  • 安装脚本按发布清单核对 SHA-256；botbus update 另外校验 Ed25519 签名。

更新于 2026-09-29