# 首次安装自动配置

0.4.4 内测版提供完整安装器。旧的 0.4.1/0.4.2 没有 `onboard`，可先运行自动安装器或更新 CLI。

## 已装 CLI

在已经登录 Grok Bot 的 Mac 或 Windows 上运行

```bash
boxbridge onboard
```

Windows PowerShell 使用 `boxbridge.cmd onboard`，或安装手册里的完整命令路径。`boxbridge onboard --check` 只检查本机，不读取登录 token、不请求云机、不操作桌面。

引导依次完成登录检查、本机 Orca、登录后台服务、云端 Orca、配对、项目选择、守护维护及最终验证。缺少本机 Orca 时下载固定官方版本并校验大小和 SHA-256，安装到当前用户目录。已有授权、服务、启动脚本、数据和可用配对均优先复用。

唯一已有云端项目会自动选择，多个项目才询问一次；没有项目时使用云机工作目录。HTTP、配对后的项目 RPC、守护程序及本机后台服务全部验证通过后才报告成功。完成后自行打开 Orca，选择保存好的云机环境和项目，不需要复制配对链接。

## 用户处理的步骤

- Grok Bot 尚未登录时，在自己的客户端登录。
- 首次钥匙串或系统安全提示，由用户在系统窗口处理，不把密码、验证码交给 Agent。授权过的助手继续复用。
- 缺少配对或可信执行通道时，首次部署需要一次云机终端操作。引导会明确询问，允许后在云机新终端安装本账号公钥验证的执行器，再部署 Orca。全程不调用模型、不激活本机窗口。
- 多个项目时选择一次，或预先指定 `--project /absolute/cloud/project`。

已有配对正常时不安装执行器，也不操作云机桌面。已有执行器会校验本账号签名身份；端口上的服务不受信任时停止，不覆盖它。

只想先安装程序时，Mac 安装器可加 `--install-only`，PowerShell 安装器可加 `-InstallOnly`。此模式安装运行环境、CLI 和命令路径，并执行本机预检，不读取账号或操作云机；后续由 `onboard` 完成配置。

## Agent 和非交互调用

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

标准输出是最终 JSON，进度写标准错误。`--json` 将进度也改为 JSON 行，错误检查退出码及 `error.code`。

- 用户明确授权本次读取登录信息后，非交互调用可加 `--authorize`，系统窗口仍由用户操作。
- 用户明确允许本次云端终端输入后，可加 `--desktop`。此参数不改变后台守护的桌面操作限制。
- 两项权限都已授予时，可用 `onboard --desktop --authorize --project /workspace/project --json`，不要作为默认重试命令。
- `desktop-bootstrap-unverified` 表示输入已发出但结果未确认。先核对终端或执行器状态，不自动重发、不调用模型兜底。
- `onboarding-busy` 表示同一配置已有安装过程，等待其结束。一个配置同时只允许一个引导进程。
- 账号变化、未知安装、端口冲突、旧图形端或前台进程占用均保留现场并提示处理。

还支持 `--environment NAME`、`--orca /absolute/native/cli`、`--cloud-root /absolute/cloud/install`。重复执行会核对真实状态并复用完成的配置，阶段记录只保存时间和安全错误码。

配对能力通过无窗口子进程的标准输入交给 Orca，仅进入 Orca 自身配对资料目录。不放入命令参数、环境变量、临时文件、历史或诊断；不自动清空或重新生成原配对。

## 完整首次安装

Mac/Windows 安装器，自动准备独立 Node 运行时、校验 CLI 包、添加命令路径，然后调用 `onboard`。无需先装 Node/npm，无管理员安装步骤。安装器检查官方清单，拒绝不兼容版本或未校验内容。

Mac 下载脚本后运行

```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
```

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
```

上述 PowerShell 策略参数只作用于这次安装进程，不修改全局配置；组织策略有要求时由用户处理。Orca 使用 [官方 1.4.243 发行包](https://github.com/stablyai/orca/releases/tag/v1.4.243)，Node 使用 [官方 22.23.4 校验表](https://nodejs.org/dist/v22.23.4/SHASUMS256.txt)中的固定包。下载不符时停止，不执行未校验内容。

## 验收范围

隔离合成账号覆盖全新配置、旧配置复用、授权不足、阶段中断、并发阻止和私密导入。真实 Mac 上的无窗口 Orca 导入使用独立资料目录及合成配对。Windows 使用原生 runner 验证官方 Orca 静默安装、私密配对导入、Node/CLI 安装器、后台服务和更新回滚。真实 Grok Windows 账号仍由内测用户在自己的设备授权。不会为首次安装验收重建用户云机或操作其真实云端桌面。
