# Linux 版

> 在 Linux 上一行命令安装 BotBus：不需要 sudo，以 systemd 用户服务或后台进程运行，终端里扫码配对，在手机上查看、审批 Codex、Claude Code 等任务。

Canonical: https://botbus.io/docs/install-linux  
Updated: 2026-09-29

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

*安装*

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

版本 **1.0.7** · 发布于 **2026-10-09** · x86\_64 与 aarch64

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

在要被手机查看的那台 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` 显示连接状态和已配对的手机数。

## 用 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`）。之后手机上这台电脑会显示离线，可以在手机上把它删掉。

## 遇到问题

### 常见情况

- **提示找不到 botbus 命令** — `~/.local/bin` 不在 PATH 里。运行 `echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile && . ~/.profile`，或者直接用 `~/.local/bin/botbus`。
- **手机上看不到 Claude Code 或 Codex** — systemd 服务用的是运行 `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 后保持运行](https://botbus.io/docs/install-linux#linger)。
- **后台起不来或状态不对** — 看 `botbus logs`（加 `-f` 持续跟踪）。`botbus status` 也会报出凭据读取失败之类的原因。
- **日志里的内容显示成 <private>** — 日志默认把任务内容、路径这类字符串脱敏。排查时先 `botbus down`，再在前台临时运行 `BOTBUS_LOG_PRIVATE=1 botbus daemon`，按 Ctrl-C 结束后运行 `botbus up`。这样得到的日志含有任务内容，分享前先检查。

### 手动安装

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

| 架构 | 文件 | 大小 | SHA-256 |
| --- | --- | --- | --- |
| x86\_64 | [`botbus-1.0.7-linux-x86_64.tar.gz`](https://botbus.io/downloads/linux/botbus-1.0.7-linux-x86_64.tar.gz)  
[.sha256](https://botbus.io/downloads/linux/botbus-1.0.7-linux-x86_64.tar.gz.sha256) | 30.5 MB | `ff305b18c97631b4f3c442bad6631f1b17db87f96d13fa334fb45fbbc284e529` |
| aarch64 | [`botbus-1.0.7-linux-aarch64.tar.gz`](https://botbus.io/downloads/linux/botbus-1.0.7-linux-aarch64.tar.gz)  
[.sha256](https://botbus.io/downloads/linux/botbus-1.0.7-linux-aarch64.tar.gz.sha256) | 29.2 MB | `926f2d5728afb106f399fef8f517ec8d06d19d928d297f8e896570b49ee94561` |

*终端*

```
VERSION=1.0.7
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.service` | systemd 用户服务 |
| `$XDG_RUNTIME_DIR/botbus/` | 管理 socket：`botbus` 命令经它和后台通信，只接受同一用户的连接 |

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

### 安全

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

更新于 2026-09-29
