# BoxBridge CLI 安装与使用手册

CLI 0.4.4 · 内测分发 · 更新于 2026 年 11 月 12 日

本页只提供 Mac、Windows 的 BoxBridge CLI。它可以为 Grok 云机保活、连接本地 Orca、与指定 Bot 聊天，也可供脚本和 Agent 调用。后台保活不提交模型请求，不自动操作云端桌面。

安装包和手册免登录，知道链接即可访问；源码仓库保持私有。推荐使用自动安装器，它会准备独立 Node 运行环境和 CLI，再由 `onboard` 自动配置 Orca、配对、项目及守护。已有配置优先复用。

## 开始前

想让 Agent 代装时，把[官网链接](https://lanshuagent.com/boxbridge/)和安装请求发给能操作本机终端的 Agent。它可以按[Agent 安装说明](https://lanshuagent.com/boxbridge/agent.md)下载、校验和安装 CLI 与 Skill。

- 本地电脑：macOS 14+，或 Windows 10/11 x64。Windows ARM、32 位系统和 WSL 版本暂未验收。
- 推荐自动安装器准备独立运行环境；手动安装 `.tgz` 时才需要 Node.js 22.16+。
- 在同一操作系统用户下安装并登录自己的 Grok Bot 客户端，确认可以手动打开云机。BoxBridge 不提供 Grok 或 Claude 账号。
- `onboard` 会准备本机和云端 Orca。只与 Bot 聊天可跳过完整引导，使用 `init` 后运行 Bot 命令。
- 若之前使用过 BoxBridge 图形程序，先退出并关闭它的登录自启，再安装 CLI 常驻服务。原配置和 Orca 配对保留，不要删除私有数据目录。

## Mac 安装

推荐运行自动安装器，无需预先安装 Node/npm。

```bash
curl --proto '=https' --tlsv1.2 -fsSLo /tmp/boxbridge-install-cli.sh \
  https://lanshuagent.com/boxbridge/install-cli.sh && \
  bash /tmp/boxbridge-install-cli.sh
```

安装器配置命令路径并进入 `boxbridge onboard`。首次钥匙串授权只在系统弹窗中完成，已授权的助手继续复用。安装后若当前终端找不到命令，使用 `"$HOME/.local/bin/boxbridge"`，或新开终端。已有 CLI 可直接运行 `boxbridge onboard`。

## Windows 安装

在 PowerShell 运行

```powershell
$installer = Join-Path $env:TEMP 'boxbridge-install-cli.ps1'
Invoke-WebRequest https://lanshuagent.com/boxbridge/install-cli.ps1 -OutFile $installer
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $installer
```

策略参数仅用于这次安装进程，不修改全局配置，组织策略由用户处理。安装器准备独立 Node、CLI 和命令路径，再进入首次引导。当前会话尚未刷新 PATH 时使用

```powershell
$bridgeCommand = Join-Path $env:LOCALAPPDATA 'BoxBridgeCLI\boxbridge.cmd'
& $bridgeCommand onboard --check
& $bridgeCommand onboard
```

默认引导会检查本机和云端 Orca、保存配对、选择项目、启用登录自启及自动守护。用户只需处理 Grok 登录、系统提示和必要的一次云端终端授权。已有可用配对时不触发桌面引导。后台保活不调用模型、不操作桌面。

Agent 可以先用 Mac 安装器的 `--install-only` 或 PowerShell 的 `-InstallOnly` 安装程序并做本机预检，再按用户授权运行 `onboard --json`。完整机制见[首次配置说明](/boxbridge/ONBOARDING.md)。手动 `.tgz` 包仍供已有 Node 的用户和自定义环境使用，下载后按官方清单校验。

## 准备云端 Orca

只与 Bot 聊天可以跳过本节。已经通过 BoxBridge 连过的云机，服务恢复后直接连接本地 Orca 的原条目。保留云端 Orca 的数据目录，其中保存了主机身份和配对授权。

| 默认端口 | 在哪里使用 |
| --- | --- |
| `6768` | Orca 在 Grok 云机上的监听端口。在云机终端检查 `http://127.0.0.1:6768/web-index.html`。 |
| `16768` | BoxBridge 在本地电脑上的监听端口。本地 Orca 的连接地址为 `ws://127.0.0.1:16768`。 |

完整引导会自动处理本节。需要手动部署或排障时，可在 Grok 云机的 Linux 终端执行：

```bash
curl --proto '=https' --tlsv1.2 -fsSLo /tmp/boxbridge-install.sh \
  https://lanshuagent.com/boxbridge/install.sh && \
  bash /tmp/boxbridge-install.sh --local-port 16768 --port 6768
```

安装器下载经过校验的官方 Orca 1.4.243 和本次云端控制程序，默认放到 `/workspace/.boxbridge`。云端包适用于 Linux x64、glibc 2.35+。它只管理自己创建的 Orca 进程，不会结束现有 Claude 或无关 Node 进程。

等云机的 HTTP 健康检查返回 `200`，再回到本地 Orca 连接。首次配对时使用安装器打印的私密链接，只在自己的设备间传递。已有 Orca 占用 `6768` 时，沿用它的启动方式和数据目录。

## 首次连接与配对

完整引导自动处理首次配对，无需复制私密链接。以下是手动兼容路径。`service install` 会启动后台连接；也可以先用 `boxbridge start` 在当前终端试运行。前台运行时 Ctrl-C 会停止连接；已有后台服务时不要再启动第二个长期进程。

```bash
boxbridge status
boxbridge pair
```

在 Mac 的 `pair` 命令中粘贴完整云端配对链接，然后按 Ctrl-D 结束输入。CLI 只将 endpoint 转为 `ws://127.0.0.1:16768`，保留设备授权和主机身份，输出一条可在本地 Orca 打开的链接。

Windows 可在 PowerShell 中手动粘贴，通过标准输入传递：

```powershell
$pairLink = Read-Host '粘贴私密的云端 Orca 配对链接'
$pairLink | & $bridgeCommand pair
Remove-Variable pairLink
```

把输出的链接交给本地 Orca 打开，接受配对，再选择云端项目目录。输入和输出的链接都包含设备权限，不要作为命令参数写进历史或公开日志。

已有配对可以直接重连。HTTP `200` 或 CLI 的 `ready` 表示服务可达。确认 Orca 显示 `Connected`，再打开原项目或终端验证配对会话。

## 常驻保活与日常使用

```bash
boxbridge status
boxbridge doctor
boxbridge pause
boxbridge resume
boxbridge wake
```

- `status` 读取本机状态，`doctor` 检查安装、账号绑定和服务自启。
- `pause` / `resume` 暂停或恢复定时保活；`wake` 刷新当前网关路由。尚未启动网关时，可用 `up` 明确请求云机唤醒。
- 默认每 5 分钟刷新路由、每 1 分钟检查云端 Orca，申请 1 小时空闲保留期；平台是否采用由 Grok 决定。
- `service install` 启用登录后的静默自启，安装后可关闭终端。本地电脑需保持唤醒和联网，合盖睡眠时无法持续保活。
- `stop` 停止本地网关，后台服务本身可保留，再用 `start` 恢复。`service uninstall` 移除 CLI 自启，不删除配置、项目或配对。

后台保活不提交 Grok 模型请求、不向 Bot 发消息、不操作桌面。手动运行 `chat/exec --allow-model`，或远程命令自行调用 Claude 等服务时，仍按各服务规则使用额度。

## 代理与网络

自动代理优先读取 HTTP(S) 环境变量，再读取系统 HTTP(S) 代理。PAC 或只有 SOCKS 的配置不能直接作为 HTTP 代理地址。无需额外配置 Tailscale 或 Cloudflare Tunnel。

若需显式指定代理，在本机终端执行，把 8080 换成自己的 HTTP 代理端口：

```bash
printf '%s\n' '{"proxy":{"mode":"custom","url":"http://127.0.0.1:8080"}}' | boxbridge configure
boxbridge stop
boxbridge start
```

Windows 使用：

```powershell
'{"proxy":{"mode":"custom","url":"http://127.0.0.1:8080"}}' | & $bridgeCommand configure
& $bridgeCommand stop
& $bridgeCommand start
```

保存配置后重新启动网关会让 Orca 短暂重连。`configure` 也支持 `listenPort` 等设置，端口变更后配对地址须使用新端口。不要把密码写进代理 URL。下载网站使用 Cloudflare，运行时连接复用 Grok 原生受鉴权通道。

## Agent 调用说明


适用于 CLI 0.4.4 内测版。入口 https://lanshuagent.com/boxbridge/ ，安装包、安装器、手册和 Skill 均免登录；源码仓库保持私有。

用户把官网链接发来并要求安装配置时，先确认你能在用户本机运行终端、写入用户目录。只能浏览网页或操作远程沙盒时，应说明缺少本机执行权限，不把沙盒里的安装当作用户电脑已安装。不要索要密码、登录 token 或配对链接。

### 从网页完成安装与配置

#### 1. 读取发布清单并复用已有程序

读取[发布清单](https://lanshuagent.com/boxbridge/releases.json)和[校验表](https://lanshuagent.com/boxbridge/SHA256SUMS)。核对用户系统，支持 macOS 14+ 和 Windows 10/11 x64。检查已有 `boxbridge --version`；Mac 也检查 `"$HOME/.local/bin/boxbridge"`，Windows 检查 `& (Join-Path $env:LOCALAPPDATA 'BoxBridgeCLI\boxbridge.cmd') --version`。

已有支持 `onboard` 的兼容版本可复用，用户要求更新时运行 `update`。需要安装时，优先选下列自动安装器，它会准备独立 Node 运行时和 CLI，不要求用户先装 Node/npm。

| 系统 | 安装器 | 先安装程序并预检 |
| --- | --- | --- |
| Mac | https://lanshuagent.com/boxbridge/install-cli.sh | `bash /absolute/download/install-cli.sh --install-only` |
| Windows x64 | https://lanshuagent.com/boxbridge/install-cli.ps1 | `powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\absolute\install-cli.ps1 -InstallOnly` |

将安装器下载到临时目录，执行前比对 `SHA256SUMS` 中对应文件的唯一 SHA-256。下载 URL 必须仍属于 `https://lanshuagent.com/boxbridge/`。不符时重新读取清单并重试下载一次，仍不符就停止。PowerShell 策略参数只用于这次安装进程，不更改全局策略，组织策略由用户处理。

需要手动 `.tgz` 时，按 `cliVersion` 选择 `macos-cli` 或 `windows-cli` 文件，核对清单的 `bytes` 和 `sha256`，以 `npm install --global --prefix 用户目录 --ignore-scripts ./verified-package.tgz` 安装；Node 需达到 22.16+。不要访问私有源码仓库或编译源码。

#### 2. 安装 Skill

读取清单中的 `skill` 条目，下载 [BoxBridge Skill ZIP](https://lanshuagent.com/boxbridge/boxbridge-skill.zip)，核对 `bytes` 和 `sha256`。ZIP 只应包含下面三个普通文件，拒绝额外条目、符号链接、绝对路径或跳出目录的路径。

```text
boxbridge/SKILL.md
boxbridge/references/install.md
boxbridge/references/recovery.md
```

先解压到临时目录，再安装到当前 Agent 的 Skills 目录。

| Agent | 个人目录 | 项目目录 |
| --- | --- | --- |
| Codex | `~/.agents/skills/boxbridge/`，或已配置的 `~/.codex/skills/boxbridge/` | `.agents/skills/boxbridge/` |
| Claude Code | `~/.claude/skills/boxbridge/` | `.claude/skills/boxbridge/` |

`~` 代表当前系统用户主目录。已有相同 Skill 就复用；用户要求更新且内容有差异时，先保留本地备份再替换。确认入口及两份参考文档可读。Codex 可选择 `$boxbridge`，Claude Code 可输入 `/boxbridge`；当前会话还没发现时，重新打开会话。

#### 3. 调用统一引导

使用已经确认的绝对命令路径，先预检，再运行引导。

```bash
boxbridge onboard --check
boxbridge onboard --json
```

预检只检查本机，不读登录 token、不请求云机、不操作桌面。完整引导配置本地/云端 Orca、后台登录服务、私密配对、项目和守护，优先复用已有设置。正常完成会返回 `ready: true`、`watchdogReady: true` 和 `modelRequests: 0`。进度为 stderr 的 JSON 行，最终结果在 stdout。

- 用户未登录 Grok Bot时，请其在同一系统账号的客户端登录。
- `authorization-required` 时，说明需要读取加密登录状态，得到本次许可后加 `--authorize`，或让用户在自己的终端交互运行引导。系统密码只填在系统弹窗。
- `desktop-opt-in-required` 时，说明本次将通过云机新终端安装本账号签名执行器及 Orca。用户明确允许后才加 `--desktop`。已有可用配对时不需要这一步。
- `project-selection-required` 时，询问用户要使用的绝对云端目录，再加 `--project /absolute/cloud/project`。不要猜选多个项目中的任意一个。
- `desktop-bootstrap-unverified` 表示输入已经发送，先核对执行器或云机终端，不自动重发，不用模型兜底。

`--desktop`、`--authorize` 不作为默认重试参数，不改变后台守护的权限。`onboarding-busy` 时等待已有过程结束，不并行启动多个安装器。配对能力由程序通过 stdin 自动交给 Orca，不打印、复制到聊天或另存。

#### 4. 交付安装结果

报告 CLI 版本、Skill 位置、引导结果、后台服务与守护状态。HTTP `200` 和网关 `ready` 只代表传输可达，完整引导还会验证原配对下的项目 RPC。用户可自行打开 Orca 选择已保存的云机环境，不自动激活本机窗口。

详细机制及手动兼容路径见[安装手册](https://lanshuagent.com/boxbridge/guide.md)和[首次配置说明](https://lanshuagent.com/boxbridge/ONBOARDING.md)。

### 推荐检查顺序

```bash
boxbridge --version
boxbridge status
boxbridge doctor
boxbridge update --check
```

这些命令不会向 Bot 发送消息。`status`、`doctor` 检查本机；`update --check` 访问公开更新目录。不要给所有命令默认追加 `--json`：常规控制命令本来就输出 JSON，更新命令不接受该参数。

- `doctor.accountBound` 为 false 时，请用户在自己的终端运行 `boxbridge init`。不要索要密码、登录 token 或钥匙串内容。
- 已授权时，重复 `init` 可返回 `{"authorized":true,"reused":true}`。不要为了更新版本重置账号、配对或私有数据目录。
- `status.state` 为 `ready` 代表网关就绪，Orca 的加密会话还需在 Orca 中确认。
- `boxbridge --version` 是已安装 CLI 的版本；`status.runtimeVersion` 是当前后台进程的版本，两者在更新后可能暂时不同。
- 已有后台服务时复用它。先看 `doctor.serviceInstalled`，不要反复安装自启，也不要再启动第二个长期前台进程。

Windows 在 PowerShell 使用安装手册配置的 `& $bridgeCommand` 代替 `boxbridge`。日常调用直接使用 `.cmd` 入口；首次安装器的进程级策略参数按前文执行。

### 默认使用的读取命令

```bash
boxbridge status --cloud
boxbridge agents --no-wake --json
boxbridge tail BOT_ID 8 --no-wake --json
boxbridge daemon --no-wake --json
```

| 命令 | 行为 | 需要注意 |
| --- | --- | --- |
| `status --cloud` | 读取云机状态和执行器可用性 | 不请求唤醒，不提交模型消息 |
| `agents --no-wake` | 读取 Bot 名称和 ID | 云机未运行时报告状态，不自行唤醒 |
| `tail BOT_ID 8 --no-wake` | 读取指定 Bot 最近回复 | 使用明确 ID；最多读取 100 条 |
| `daemon --no-wake` | 检查签名执行器 | 未就绪时报告，不自动安装或恢复 |

`agents`、`tail` 等云端命令在未加 `--no-wake` 时可能请求唤醒云机。读取回复不调用模型，但回复可能含用户的私有项目内容，不要直接写入公开日志。

### 会改变状态的命令

| 命令 | 用途 | 执行条件 |
| --- | --- | --- |
| `up` / `wake` | 请求云机唤醒或刷新连接 | 用户要求建立或恢复连接时 |
| `service install` / `uninstall` | 配置或移除本机 CLI 登录自启 | 用户要求安装、迁移或重启服务时 |
| `update` / `update --rollback` | 替换或回滚 CLI 程序 | 用户授权升级或回滚时 |
| `run` / `sh` | 在云机执行命令 | 执行器已就绪，命令在用户任务范围内 |
| `chat` / `exec` | 向 Grok Bot 提交模型请求 | 用户明确授权本次发送，并显式加 `--allow-model` |
| `screen`、鼠标、键盘、剪贴板命令 | 读取截图或操作云端桌面 | 用户明确要求这次云端桌面操作 |

后台保活永远不调用模型、不操作桌面。执行器离线或命令失败时，禁止自动改用 `exec`、`chat`、`install --desktop` 或 `daemon --desktop` 兜底。

`run/sh` 自身不提交 Grok 模型消息；执行的命令可能调用其他模型、修改文件或访问网络，仍须遵守用户对该任务的授权范围。

### 指定 Bot、传参和输出

先读取 `agents`，再使用返回的唯一 Bot ID。名称重名或含糊时报告歧义，不替用户猜测。

只有获得本次模型调用授权后，才执行下面的示例：

```bash
boxbridge chat BOT_ID "请汇报当前任务进度" --allow-model
boxbridge tail BOT_ID 8 --no-wake --json
```

`chat` 返回代表消息已提交，回复需要稍后用 `tail` 读取。`exec` 的 Bot 回复可能只是进度，不代表云端命令已经成功，也不代表取得真实退出码。

脚本与 Agent 应将用户文本作为独立参数传递，避免拼接到 shell 命令中。`chat BOT_ID -`、`run -` 支持从标准输入读取正文；`pair` 从标准输入读取配对链接，`configure` 从标准输入读取 JSON。

| 输出类型 | 对应入口 |
| --- | --- |
| JSON | `status`、`doctor`、`init`、`update` 等控制命令；Bot 列表与回复 |
| 云端执行结果 JSON | `run ... --json`，字段含 `stdout`、`stderr`、`code`、`cwd`、`truncated` |
| 原始文本或交互流 | `--version`、`help`、`pair`、`install --print`、普通 `run/sh` |

本机 CLI 错误通常输出 `{"error":{"code":"...","message":"...","retryable":false}}` 并以非零状态退出。读取稳定的 `error.code`，不要只匹配错误文案。`run` 的进程退出码跟随云端结果的 `code`。

### 失败处理与重试

首次引导会启用守护维护，已有 CLI 也可按用户要求单独启用 [Orca 守护自动维护](ORCA-WATCHDOG.md)。运行 `boxbridge watchdog enable --environment "用户环境名" --worktree /absolute/cloud/project`，再执行 `boxbridge watchdog check`。运行中的服务也需为新版。`watchdog status` 只读带时间的缓存。自动维护保留原数据和配对，执行通道失效时等待恢复，不自动转用桌面、模型或新执行器。

- 登录或授权错误：请用户本人处理；不要自动重置凭据或切换账号。
- `executor-offline` / `executor-untrusted`：报告缺少执行器；安装按手册由用户明确发起。
- 命令或消息提交超时：先检查任务或回复是否已经产生，不自动重发可能有副作用的请求。
- 网络临时失败：读取操作可有限重试并退避；不要创建无限轮询或多个保活进程。
- `restartRequired: true`：新版程序已安装，旧后台进程仍在运行。报告给用户，获得重启指示后按手册重启 CLI 服务。
- BoxBridge 报 `remote-unavailable` 或 `502` 时，按[安装手册](https://lanshuagent.com/boxbridge/#guide-11)检查云机的 `6768` 端口。`000` 表示探测未收到 HTTP 响应。云端返回 `200` 后，在本地 Orca 用原配对确认会话；默认连接地址为 `ws://127.0.0.1:16768`。

### 隐私与权限边界

不要收集或外发 Grok/Claude 登录 token、Mac 密码、钥匙串内容、签名私钥、Orca 配对 URI 或原始私有诊断。配对链接及其转换结果都包含设备权限，只交给用户自己的 Orca。

不要自动运行 `pkill node`、清空配置、重新配对或结束云端 Claude 进程。后台保活和前台 Agent 任务应分开管理。

`status.modelRequests: 0` 只描述常驻网关，不包含用户手动触发的 `chat/exec` 调用。不要用它声称整个账号未使用模型。


## 和指定 Bot 聊天

先列出 Bot，使用准确名称或唯一 ID。以下 `chat` 会使用模型额度，只有明确需要发送时才执行：

```bash
boxbridge agents --no-wake --json
boxbridge chat BOT_ID "请汇报当前任务进度" --allow-model
boxbridge tail BOT_ID 8 --no-wake --json
```

`agents` 和 `tail` 不提交模型消息；`--no-wake` 避免为读取操作请求唤醒云机。云机未运行时，由用户明确运行 `boxbridge up`。名称含糊时使用 ID，不自动选相似 Bot。

`chat` 提交后返回，稍后用 `tail` 读回复。`tail` 默认 8 条，最多 100 条。超时或发送状态未知时，先看云端是否已收到，避免重复发送。`status.modelRequests: 0` 只描述常驻网关，不含这些手动调用。

## 执行云端命令

`run/sh` 需要独立的签名执行器，与前面的 Orca 控制程序分开安装。先在本地生成安装脚本：

```bash
boxbridge install --output ./executor-install.sh
```

将脚本传到自己的云机，在云机终端执行 `bash /path/to/executor-install.sh`。脚本包含执行器程序和账号绑定公钥，不包含登录 token 或签名私钥。再回到本地检查和使用：

```bash
boxbridge daemon --no-wake --json
boxbridge run "pwd" --cwd /workspace --timeout 30 --json
boxbridge sh --cwd /workspace
```

`run --json` 返回 `stdout`、`stderr`、`code`、`cwd` 和 `truncated`，CLI 退出码跟随云端 `code`。普通 `run` 直接输出 stdout/stderr。`sh` 按行执行并保留当前目录，每行使用新 shell；持续环境变量、完整交互终端或 TUI 请用 Orca。

请求 Bot 执行使用 `exec ... --agent BOT_ID --allow-model`，会调用模型。Bot 回复可能只是进度，不能代替真实退出码。执行器离线时不要自动改用 Bot 或云端桌面恢复。`install --desktop` / `daemon --desktop` 只能在用户明确要求这次远程终端操作时运行。

## 查看与操作云端桌面

这些命令仅在手动执行时触发，不提交 Grok 模型请求。截图存到本机，鼠标键盘输入发送到云端，不弹本地控制窗口。

```bash
boxbridge screen ./cloud.png
boxbridge move 100 200
boxbridge click 100 200 --double
boxbridge key Enter
boxbridge type "pwd" --enter
boxbridge combo ctrl+alt t
boxbridge paste ./clipboard.txt --do-paste
```

`screen` 默认不覆盖文件，坐标以云端像素为准。`type` 支持 ASCII，`key` 可输入单个 Unicode 字符；`paste` 只支持 Latin-1，中文会拒绝有损转换。不要把截图或剪贴板里的私有内容写入公开反馈。

## 连接断开时

先运行：

```bash
boxbridge status
boxbridge doctor
boxbridge status --cloud
```

- **需要登录或授权**：本人检查同一系统用户的 Grok Bot 登录，必要时手动 `boxbridge init`。不要清空配置或发送凭据给维护者。
- **临时网络失败**：确认联网和 HTTP 代理可用；已配置网关可运行 `wake`，云机未运行时由用户明确运行 `up`。
- **CLI `ready`、Orca 未连上**：检查本地 Orca 的地址和原配对身份，再查看 Orca 自己的连接状态。
- **端口被占用**：确认是否已有 BoxBridge，不结束未知 Node 进程。必要时用 `configure` 改本机端口，再更新配对地址。
- **云机冻结或回收**：平台生命周期由 Grok 决定。恢复后确认原文件和 Orca 身份是否保留，重要代码自行提交或备份。

如果 BoxBridge 显示 `remote-unavailable` 或收到 `502`，先在 **Grok 云机的 Linux 终端**检查 Orca 的默认监听端口。改过云端端口时，用实际端口替换 `6768`。

```bash
curl --noproxy '*' --silent --show-error --max-time 5 --output /dev/null \
  --write-out 'Orca HTTP %{http_code}\n' http://127.0.0.1:6768/web-index.html
```

- **云机内返回 `200`**：云端 Orca 已就绪。若 BoxBridge 仍收到 `502`，检查 Grok 云机的入口和路由，再用原配对连接。
- **云机内显示 `000`**：这次探测没有收到 HTTP 响应。首次解包或刚启动时，等待服务就绪再复查。持续无响应时，查看现有 Orca 的启动状态和本机日志。

用本手册安装的云端服务可运行 `/workspace/.boxbridge/boxbridge-cloud status`，以 `localHTTPStatus: 200` 判断 Orca 就绪。如果状态为 `stopped`，运行 `/workspace/.boxbridge/boxbridge-cloud start`，再查看状态。使用 AppImage 和 tmux 的已有安装，请用原启动脚本。tmux 会话出现后，仍需等待端口返回 `200`。

如果旧脚本显示了两个端口，检查脚本的打印行和启动参数。配对地址应为 `--pairing-address ws://127.0.0.1:16768`，云端监听端口单独用 `--port 6768` 传入。恢复已有服务时，继续使用原数据目录和本地已配对的条目。启动日志和 `pairing` 的输出可能含私密配对链接，请在自己的设备上查看。

## 更新、回滚与卸载

先分清已安装 CLI、运行中的后台和官网最新版本：

| 查看什么 | 命令或字段 |
| --- | --- |
| 已安装 CLI 版本 | `boxbridge --version` |
| 后台实际版本 | `boxbridge status` 中的 `runtimeVersion` |
| 官网可升级版本 | `boxbridge update --check` 中的 `availableVersion` |

官网的[升级入口](https://lanshuagent.com/boxbridge/#upgrade)提供检查、升级和回滚命令，也可查看[版本记录](https://lanshuagent.com/boxbridge/CHANGELOG.md)。CLI 文件更新完成后，后台可能仍使用原版本，以 `runtimeVersion` 和 `restartRequired` 为准。

```bash
boxbridge update --check
boxbridge update
boxbridge update --rollback
```

`--check` 只读公开版本目录；`update` 校验 HTTPS 下载、长度、SHA-256、解包路径和独立启动后再替换 CLI。失败恢复旧版，`--rollback` 可恢复上一次安装。更新默认保留当前连接、配置和已授权助手。

`restartRequired: true` 表示新程序已安装、旧后台仍在运行。可以等下次登录；需要立即接管时，手动执行下面两条命令，Orca 会短暂重连：

```bash
boxbridge service uninstall
boxbridge service install
```

0.4.0 及更早 CLI 首次需用新 tgz 覆盖安装，迁移时可能需要一次系统授权。从 0.4.1 起，私有助手目录保留已授权程序身份；更换系统用户、账号、登录状态或撤销系统权限时仍可能需要处理授权。

卸载时先 `boxbridge service uninstall`。自动安装器的程序位于 Mac 的 `~/Library/Application Support/BoxBridge/runtime/` 或 Windows 的 `%LOCALAPPDATA%\BoxBridgeCLI\`，停止服务后可移除该程序目录与命令入口，保留独立的 BoxBridge 账号配置目录。不要删除私有配置和原 Orca 数据。

使用 npm 手动安装的用户，通过安装时的前缀卸载，配置默认保留：

```bash
npm uninstall --global --prefix "$HOME/.local" boxbridge
```

```powershell
& $bridgeCommand service uninstall
npm.cmd uninstall --global --prefix (Join-Path $env:LOCALAPPDATA 'BoxBridgeCLI') boxbridge
```

反馈提供系统、CLI 版本、时间和脱敏错误码。`boxbridge diagnostics` 输出脱敏状态，发送前仍自行检查，不提交私有项目、配对 URI 或完整原始日志。

## 内测范围与隐私

目前分发 0.4.4 CLI、自动安装器、使用手册和 Skill，不公开源码仓库。安装包可被获得链接的人转发，发布清单记录对应文件大小和 SHA-256。Windows 原生验收使用隔离合成账号，真实账号由用户在自己的设备登录和授权。

本机网关只监听回环地址。Grok 登录和路由凭据在运行时使用，不写入设置、自启项和诊断。Mac 私有助手目录保存程序及校验身份；Windows 执行器身份保存为当前用户的加密数据。

Orca 负责加密配对和会话验证。BoxBridge 转发传输数据；同一系统用户下的恶意程序不在隔离边界内。Grok 非公开接口、账号状态与云机生命周期变化仍可能影响可用性。

BoxBridge 与 xAI、Cursor、Orca、Anthropic 无隶属关系。不索要 Grok/Claude token、Mac 密码、钥匙串内容或签名私钥。任何含设备授权的 URI 只交给用户自己的 Orca。
