# BoxBridge 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` 调用。不要用它声称整个账号未使用模型。
