# Windows 版

> 在 Windows 上用一行 PowerShell 命令安装 BotBus：不需要管理员权限，登录后在后台运行、带托盘图标，扫码配对后在手机上查看、审批 Codex、Claude Code 等任务。

Canonical: https://botbus.io/docs/install-windows  
Updated: 2026-09-30

装在 Windows 电脑上，登录后在后台运行，通知区域里有 BotBus 图标。让你在手机和手表上查看、审批这台电脑上的 Codex、Claude Code 等 agent 任务，内容和 Mac 版一样端到端加密。

```powershell
irm https://botbus.io/install.ps1 | iex
```

版本 **1.0.7** · 发布于 **2026-10-09** · Windows 10 / 11（ARM 电脑需要 Windows 11）

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

在要被手机查看的那台电脑上，用你平时登录的 Windows 账户打开 PowerShell 运行安装命令，不需要管理员权限。

### 安装

```powershell
irm https://botbus.io/install.ps1 | iex
```

#### 安装脚本做了什么

1. 下载本页列出的版本。它是一个 x64 程序，ARM 电脑上的 Windows 11 会自动模拟运行它；Windows 10 的 ARM 电脑装不了。
2. 用发布清单里的 SHA-256 核对下载的包，对不上就停下，什么都不装。
3. 解压到 `%LOCALAPPDATA%\Programs\BotBus`，并把这个目录加进你的用户 PATH（之后新开的终端里就能直接用 `botbus`），不改系统目录。
4. 运行 `botbus up`：在任务计划程序里建一个「BotBus」任务，每次登录 Windows 时在后台启动；再打开通知区域里的 BotBus 图标，它也会随登录启动。
5. 这台电脑上有 Claude Code（`%USERPROFILE%\.claude` 存在）时，装好 BotBus 的 Claude Code hooks，电脑上开的 Claude 会话也能在手机上看到；卸载时会移除。
6. 在 PowerShell 窗口里显示配对二维码，等你用手机扫码。

不在交互式终端里运行时（远程脚本、自动化部署），脚本只启动后台、不显示配对码，免得带密钥的配对链接进了日志。之后在这台电脑上右键托盘图标选「配对手机…」，或者在终端里运行 `botbus pair`。

### 配对手机

- 用手机上的 BotBus 扫 PowerShell 窗口里的二维码。二维码是用字符画的，窗口太小显示不全时拉大一些。
- 也可以右键通知区域里的 BotBus 图标，选「配对手机…」，在弹出的窗口里扫码。
- 扫不了时，把窗口里的配对链接发到手机上打开。链接里带着加密密钥，只在自己的设备之间传，不要贴进聊天或工单。
- 配对码有有效期，过期了就重新运行 `botbus pair`（或在托盘菜单里重新打开）。
- 已经配对过、想再加一台手机，也运行 `botbus pair`，它会生成邀请码。

## 托盘图标与 botbus 命令

托盘图标和 `botbus` 命令都以当前用户身份运行，经本机只给你自己用的管理通道和后台通信。

### 托盘图标

通知区域里的 BotBus 图标按连接状态变色。左键点它（或开始菜单里的 BotBus）打开主窗口：列出这台电脑上的 agent，每个下面有「打开桌面应用」「在终端中打开」，没装的给安装入口；从这里打开的 Claude Code、Codex 用的是 BotBus 后台同一个程序和登录（Claude Code 还会先装上 hooks），电脑上开的会话会出现在手机上。右上角的齿轮是设置窗口。

右键菜单里有：

- 打开 BotBus（主窗口）；
- 当前版本、连接状态、正在跑和等你处理的任务数，有新版本时点一下就更新；
- 本机 agent 列表：每个 agent 一个子菜单，列出手机上发起的会话（点一条在终端里接着聊）、打开或关掉它、在终端中打开它（用来登录）、它的设置；
- 添加 Agent…：BotBus 支持的全部 agent，没装的给官网和一行安装命令，装好后点「重新检测」；还没检测到任何 agent 时托盘会提示一次；
- 已配对的手机（点一台打开它的设置页，在那里移除）、配对手机；
- 设置…：和 Mac 版一样的设置窗口（连接状态、已配对设备、各个 agent、添加 Agent、新建项目的存放目录、登录时启动、检查更新）；
- 打开日志（后台由托盘图标照看：没在运行时，托盘启动或点开菜单就会把它启动起来）；
- 退出托盘图标（后台照常运行，运行 `botbus tray` 可以再打开）。

Windows 可能把新图标收在「显示隐藏的图标」的箭头里，可以把它拖到任务栏上常驻。

### 命令一览

| 命令 | 作用 |
| --- | --- |
| `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]` | 查看后台日志 `%LOCALAPPDATA%\BotBus\daemon.log` |
| `botbus tray` | 打开通知区域里的 BotBus 图标 |
| `botbus open` | 打开主窗口（本机的 agent 与打开它们的按钮） |
| `botbus settings` | 打开设置窗口 |
| `botbus down` | 停止后台，凭据保留；下次登录 Windows 时仍会自动启动 |
| `botbus update` | 更新到最新版本 |
| `botbus uninstall [--purge]` | 卸载后台、托盘图标与程序；`--purge` 同时删除凭据与数据 |
| `botbus --version` | 显示版本 |

手机任务里 agent 用的 `botbus share`、`link`、`list`、`mcp` 与 Mac 版相同。Windows 版暂不支持开发预览（`botbus preview`）和操控电脑屏幕。

### 更新

```powershell
botbus update
```

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

### 卸载

```powershell
botbus uninstall
```

也可以在 Windows 的「设置 → 应用 → 已安装的应用」里找到 BotBus 点「卸载」，效果相同。

停止后台，删掉「BotBus」计划任务、托盘图标的自启动、开始菜单与「已安装的应用」里的 BotBus，从 Claude Code 的设置里移除 BotBus 的 hooks，把程序目录从用户 PATH 里去掉并删除。凭据留在 `%LOCALAPPDATA%\BotBus`，重新安装后不用再配对。

```powershell
botbus uninstall --purge
```

同时删除凭据与数据（`%LOCALAPPDATA%\BotBus`）。之后手机上这台电脑会显示离线，可以在手机上把它删掉。

## 遇到问题

### 常见情况

- **提示找不到 botbus 命令** — PATH 的改动只对之后新开的终端生效。关掉重开 PowerShell，或者直接用 `& "$env:LOCALAPPDATA\Programs\BotBus\botbus.exe"`。
- **手机上看不到 Claude Code 或 Codex** — 后台用的是运行 `botbus up` 那一刻的 PATH。先装好 agent，确认新开的终端里 `Get-Command claude`（或 `codex`）找得到，再运行一次 `botbus up`。`botbus agents` 列出检测到的 agent。
- **电脑上开的 Claude Code 会话手机上看不到** — hooks 由 `botbus up` 在 `%USERPROFILE%\.claude` 存在时装好。装了 Claude Code 之后再运行一次 `botbus up`。手机上新建的会话不靠 hooks。
- **找不到托盘图标** — 先看通知区域「显示隐藏的图标」的箭头里。退出过托盘图标就运行 `botbus tray`。
- **电脑不允许建计划任务** — 有的公司电脑禁止普通用户建计划任务。这时 `botbus up` 直接在后台启动，但重新登录后要再运行一次 `botbus up`。
- **后台起不来或状态不对** — 看 `botbus logs`（加 `-f` 持续跟踪）。`botbus status` 也会报出凭据读取失败之类的原因。
- **日志里的内容显示成 <private>** — 日志默认把任务内容、路径这类字符串脱敏。排查时先 `botbus down`，再在前台临时运行 `$env:BOTBUS_LOG_PRIVATE = '1'; botbus daemon`，按 Ctrl-C 结束后运行 `botbus up`。这样得到的日志含有任务内容，分享前先检查。

### 手动安装

不想用管道运行脚本时，可以自己下载、核对、解压。本版本的文件（x64 与 ARM 电脑通用）：

| 架构 | 文件 | 大小 | SHA-256 |
| --- | --- | --- | --- |
| x64 | [`botbus-1.0.7-windows-x86_64.zip`](https://botbus.io/downloads/windows/botbus-1.0.7-windows-x86_64.zip)  
[.sha256](https://botbus.io/downloads/windows/botbus-1.0.7-windows-x86_64.zip.sha256) | 52.8 MB | `9bfca38cd7678e5d920169c3121fcbfb2fbc13a31e98e6eda8359c6073be4e99` |

```powershell
$Version = '1.0.7'
$File = "botbus-$Version-windows-x86_64.zip"
Invoke-WebRequest -UseBasicParsing "https://botbus.io/downloads/windows/$File" -OutFile $File
(Get-FileHash $File -Algorithm SHA256).Hash.ToLower()
Expand-Archive $File "$env:LOCALAPPDATA\Programs\BotBus" -Force
& "$env:LOCALAPPDATA\Programs\BotBus\botbus.exe" up
```

第四行打印的 SHA-256 应当和上表一致。手动安装不改 PATH：要在任意终端里直接用 `botbus`，把 `%LOCALAPPDATA%\Programs\BotBus` 加进用户 PATH。发布包另有 Ed25519 签名，由 `botbus update` 校验。

### 文件放在哪里

| 位置 | 内容 |
| --- | --- |
| `%LOCALAPPDATA%\Programs\BotBus\` | 程序：`botbus.exe`（命令行）、`botbusw.exe`（后台与托盘图标，不弹窗口）和它们用的运行库 |
| `%LOCALAPPDATA%\BotBus\` | 配对凭据 `credentials.dat`（用 Windows 的 DPAPI 加密）、设置与日志 `daemon.log` |
| 任务计划程序里的「BotBus」 | 登录 Windows 时启动后台 |
| `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` 的 `BotBus` | 登录时打开托盘图标 |
| 开始菜单里的「BotBus」 | 打开主窗口（托盘图标没在运行时一并打开） |
| 「设置 → 应用 → 已安装的应用」里的 BotBus | 版本、占用空间与卸载入口（`HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\BotBus`） |
| `\\.\pipe\botbus-admin-…` | 管理通道：`botbus` 命令和托盘图标经它和后台通信，只接受你自己的连接 |

### 安全

- 内容端到端加密：任务、对话和命令在这台电脑上加密后才发出，服务器只转发看不懂的密文。详见[端到端加密](https://botbus.io/docs/security)。
- 配对凭据用 Windows 的 DPAPI 加密，只有你的 Windows 账户在这台电脑上解得开；文件和管理通道都只允许你自己访问，同一台电脑上的其他用户读不到、也连不上。
- 配对链接带着密钥，只显示在你的终端和托盘的配对窗口里，不写进日志。
- 安装脚本按发布清单核对 SHA-256；`botbus update` 另外校验 Ed25519 签名。

更新于 2026-09-30
