# 端到端加密

> BotBus 怎么做端到端加密：钥匙经电脑屏幕上的二维码交给手机，服务器只转发密文。加密了什么、服务器还看得到什么、加密保护不了什么，都在这里。

Canonical: https://botbus.io/docs/security  
Updated: 2026-09-27

在手机上看电脑里的 agent，数据要经过我们的中转服务器。我们把它做成一个看不懂信的邮差：对话、代码路径、命令和截图在你的设备上加密后才发出；解密用的钥匙在配对时经电脑屏幕上的二维码交给手机，从来不经过服务器。下面讲清楚我们是怎么做的、服务器还能看到什么，以及加密保护不了什么。

- **服务器只见密文** — 任务、对话、命令、图片、通知正文和远程操作画面，全部用 AES-256-GCM 加密后才离开设备。
- **钥匙不上网** — 组密钥只经电脑屏幕上的二维码交接，只存在你各台设备的系统钥匙串里。
- **可以自己核对** — 电脑和手机各显示一串 8 位密钥指纹，两边一致，就是同一把钥匙。

*示意：一条消息从手机经服务器到电脑*

## 服务器只转发，不读信

加密和解密只发生在你的电脑、手机和手表上。服务器从头到尾拿不到钥匙，也就读不到内容——不是“我们承诺不看”，而是“我们看不了”。

### 为什么要经过服务器

电脑和手机通常不在同一个网络：你出门了，电脑还在家里或公司。两边都连得上的，只有互联网上的一台服务器，我们叫它 Relay，运行在 Cloudflare 上。

Relay 做三件事：把电脑上的变化转给手机，把手机的命令排队交给电脑，电脑离线时暂存最近的状态。这三件事只需要知道“这段数据属于哪台电脑、哪个任务、什么时候更新的”，不需要知道里面写了什么。所以我们只让它知道这些。

### 钥匙怎么交到手机上

你的一组设备（电脑、手机、手表）共用一把 256 位的随机钥匙，叫**组密钥**。难点在于：怎么把它交给新设备，又不让中间的服务器拿到。答案是电脑屏幕——你拿手机对着它扫一下，这条通道服务器碰不到。

#### 第一次配对

1. **电脑生成一对临时钥匙** — 在电脑上点「配对手机」时，BotBus 生成一对一次性的 X25519 钥匙。私钥留在电脑的钥匙串里，公钥印进屏幕上的二维码。
2. **手机扫码，生成组密钥** — 手机在本机随机生成组密钥，再用二维码里的公钥把它封进一个「密钥信封」。只有电脑手里那把临时私钥拆得开。
3. **信封经服务器送到电脑** — 服务器负责转交，但它从没见过二维码里的公钥，算不出拆信封所需的共享秘密。
4. **电脑拆开信封，删掉临时钥匙** — 电脑取出组密钥存进钥匙串，临时私钥随即删除。此后双方往来的一切都用组密钥加密。

- **服务器没法冒充你的电脑。**冒充要换掉那把公钥，而公钥只出现在电脑屏幕上。手机认领成功后还会核对：服务器说配上的是哪台电脑，必须和二维码里写的一致，不一致立即作废。
- **再配一台手机：**已配对的电脑出的邀请二维码里直接带着组密钥。
- **再加一台电脑：**已配对的手机扫新电脑的二维码，用已有的组密钥做信封，过程同上。
- **Apple Watch：**从配对的 iPhone 经系统加密的 WatchConnectivity 通道同步，不经过服务器。
- **不能手动输 6 位码配对。**6 位数字装不下一把钥匙，所以只能扫码，或把电脑上「复制配对链接」得到的链接粘贴进手机。这是有意的：配对必须在电脑跟前完成。

配对二维码和配对链接等于钥匙本身：只给自己的手机扫、只粘贴到自己的手机里，不要截图或发到聊天里。配对码 5 分钟后过期，只能用一次。

### 加密了什么，服务器看得见什么

加密，服务器看不懂

- 任务标题、状态、最近一条输出
- 项目名称与路径、git 未提交的改动
- 完整的对话记录
- 你发的消息、图片和文件
- agent 分享回来的截图、文件和视频
- 审批内容（要跑的命令、要改的文件）和你的回答
- 手机发出的每条命令：新建、续聊、审批、中断——连是哪种命令也在密文里
- 电脑名和手机名
- 通知的标题和正文
- 远程操作的画面、点击和键盘输入

服务器看得见（转发必需）

- 配对编号、每台设备的编号
- 电脑是否在线、最后在线时间
- 任务的编号和更新时间；编号带来源前缀（如 `codex:`），能看出任务来自哪一家 agent
- 命令的编号和发出时间
- 通知的类别：待审批、待回复、完成、失败
- 每段密文的大小
- 设备连接时的 IP 地址（任何联网服务都会看到）

这些信息够服务器把数据送对地方、按时间留下最近的任务，但拼不出你在做什么。下面是一条续聊命令在两边的样子：

*你在手机上发的 · 加密前*

```
{
  "id": "6b1c2d3e-…",
  "createdAt": "2026-09-17T08:06:00Z",
  "kind": "followUp",
  "followUp": {
    "taskId": "codex:01a0ab79-…",
    "prompt": "顺便把按钮颜色改成主题色"
  }
}
```

*服务器收到并转发的 · 密文已截断*

```
{
  "id": "6b1c2d3e-…",
  "agentId": "hV3nQ7pLxK2mR8sTfW4bZQ",
  "createdAt": "2026-09-17T08:06:00Z",
  "sealed": "AQQ021RNmIp90_5yD0EsY4kuQD9…"
}
```

### 用的是什么加密

| 用途 | 算法 |
| --- | --- |
| 加密内容 | AES-256-GCM，每段密文一个新的随机 nonce |
| 配对时交换钥匙 | X25519，每次配对一对新的临时钥匙 |
| 派生子钥匙 | HKDF-SHA256 |

- **只用公开、久经审查的标准算法**，用各平台系统自带的实现（Apple 设备上是 CryptoKit），不自己发明加密。
- **同样的内容，每次加密结果都不同。**服务器没法靠比对密文猜出你发了什么，也看不出两条消息是否相同。
- **改不了，也挪不了。**GCM 自带完整性校验，改动一个字节就解不开。每段密文还绑定了它的位置——哪台电脑、哪个任务、哪条命令：服务器把 A 任务的密文放到 B 任务下，或把发给一台电脑的命令转给另一台，解密都会失败。解开后，设备还会核对里面的编号和时间与外面是否一致。
- **不同用途用不同的钥匙。**从组密钥派生出内容、通知、远程操作各自的子钥匙。iPhone 上负责显示通知的系统扩展只拿得到通知那一把。
- **文件也是密文。**图片、文件、视频以加密后的字节上传，服务器那边一律是“未知的二进制数据”，连文件类型都看不到。附件的编号用只存在电脑上的钥匙计算，服务器没法拿一张已知的图片算出同样的编号，来比对你是否传过它。

### 通知

推送通知要经过 Apple 的推送服务（APNs）。服务器交给 Apple 的只有一句固定文案，比如“有任务在等你审批”，外加一段密文。

iPhone 收到后，在本机用通知钥匙解开密文，换上真正的电脑名、任务标题和内容再显示给你。所以 Apple 和我们的服务器看到的都只是那句固定文案。Apple Watch 上的通知停在固定文案；打开 app 后，内容照常在手表上解密显示。

### 远程操作

远程操作让你在手机上看电脑屏幕、点击和打字——可能包括输入密码。这是最敏感的一条链路，保护也最多：

- 画面的每一帧、每次点击、每个按键都加密，用单独的远程操作钥匙。
- 显示画面的页面装在 app 里，不从服务器加载。服务器没有机会塞进一段代码把钥匙带走。
- 每条输入都带着它的目标和时间：服务器重放一条旧输入，或者把“输入文字”挪成“点击”，电脑都会拒绝。
- 没有组密钥的电脑，远程操作服务整个不开。

### 服务器存了什么、存多久

| 数据 | 以什么形式 | 保留多久 |
| --- | --- | --- |
| 任务、电脑和项目的最新状态 | 密文 | 配对期间；连续 30 天没有设备连接就清空 |
| 等电脑执行的命令 | 密文 | 10 分钟 |
| 你打开的对话记录 | 密文 | 只向手机提供 5 分钟 |
| 图片、文件和视频 | 密文 | 7 天 |
| 设备凭据 | 只存摘要，不存原文 | 配对期间 |

即使服务器的存储整个泄露，拿到的也只是这张表里的密文和上一节列出的元数据。你电脑上的原始任务记录由各个 agent 自己保存，不在服务器上。iPhone 版另用 Firebase Analytics 记录固定的配对和操作事件，不含任务内容、项目路径或配对码，详见[隐私协议](https://botbus.io/privacy)。

## 自己核对，心里有数

加密不需要你做任何设置，配对完就开着。下面是你可以亲手确认的地方，以及我们想让你事先知道的边界。

### 核对密钥指纹

指纹是组密钥的一个短摘要，8 位十六进制。两台设备的指纹一致，说明它们拿的是同一把钥匙，中间没有人换过。

- **电脑上** — BotBus 菜单 →「再配一台手机…」，配对窗口里写着「端到端加密 · 密钥指纹」和一串 8 位字符。
- **手机上** — 设置 →「连接」→「端到端加密」，右边是同一串字符。

指纹由钥匙算出，不能反推出钥匙，给别人看也没关系。

### 加密保护不了的

- **拿到你已解锁设备的人** — 钥匙存在系统钥匙串里，受设备锁屏保护。但有人拿到你解锁的电脑或手机，就能看到 BotBus 显示的一切，和看你的聊天软件一样。
- **agent 自己的模型服务** — 我们加密的是电脑到手机这一段。Codex、Claude Code 这些 agent 本来就会把对话发给各自的模型服务商（例如 OpenAI、Anthropic），模型请求由电脑上的 agent 发起，Relay 看不到其明文，但 BotBus 的加密不覆盖这一段。从手机或手表发起任务前，app 会要求你核对实际服务商并明确同意；详见[AI 服务与授权](https://botbus.io/privacy#ai-services)。
- **开发预览** — 用 `botbus` 把电脑上的本地网页分享到手机时，浏览器要直接请求网页里的各种资源，只能由服务器代理，所以不在端到端加密范围内，只在你分享期间可访问。远程操作不属于这一类，它是加密的。
- **元数据** — 服务器能看到上文列出的编号、时间、在线状态和数据大小。这是任何中转服务都绕不开的，我们把它压到了转发所需的最少。
- **被移除的手机手里的旧钥匙** — 在电脑的设置里移除一台手机，它的凭据立即作废，服务器不再给它任何数据；但它之前拿到的组密钥不会自动更换。想彻底换一把新钥匙，在手机的设置里「解除配对」，然后重新扫码——新配对会生成一把全新的组密钥。
- **服务器能做的最坏的事** — 是不转发、延迟转发，或者退回你之前见过的某个旧状态。它伪造不了内容，也读不到内容。

端到端加密让你不必信任服务器；你信任的是装在自己设备上的 BotBus app。Mac 版经 Apple 公证后在官网发布，手机 app 经 Apple 的渠道分发。

### 常见问题

#### 你们能看到我的代码或对话吗？

不能。服务器上只有密文，钥匙只在你的设备上。我们的工程师、Cloudflare，或者任何拿到服务器数据的人，看到的都是上面那样的一串乱码。

#### 如果有人要求你们交出数据呢？

我们能交出的只有密文和上面列出的元数据。我们没有钥匙，也就没法解密后再交出。

#### 手机丢了怎么办？

在电脑的 BotBus 设置 →「已配对设备」里移除那台手机，它和它的手表会立刻断开。如果它是组里唯一的手机，那里给的是「解散配对」：整组重新开始，钥匙也一起换新。任务记录都在电脑上，不受影响。

#### 钥匙丢了能找回吗？

我们没有你的钥匙，所以没法帮你找回。好在也不需要：重新扫码配对就会生成新钥匙，任务本身都在电脑上，重新配对后会重新同步过来。

#### 会让 app 变慢吗？

几乎感觉不到。AES-GCM 由芯片直接加速，加解密的开销远小于网络传输。唯一的区别是对话里的视频要整段下载、解密后才能播放，不能边下边播。

更新于 2026-09-27 · 更多条款见[隐私协议](https://botbus.io/privacy)
