# Orca 自动守护维护

CLI 0.4.2 起提供此功能，0.4.4 的首次引导会自动启用。已有配置可按下文单独管理。

BoxBridge 通过本机 Orca 已保存的配对，在后台检查云机的 Orca 守护程序。缺少时补装，停止时拉起，保留原启动脚本、数据目录和配对。它只维护识别出的安装，不会自动安装第二套 Orca、启动远程桌面或调用 Grok 模型。

## 一次启用

先确认 `boxbridge status` 正常，Orca 已通过 `ws://127.0.0.1:16768` 配对，且本机 Orca CLI 可用。以下环境名和项目路径换成自己的值。

```bash
boxbridge watchdog enable --environment "My cloud" --worktree /workspace/project
boxbridge watchdog check
boxbridge watchdog status
```

Mac 和 Windows 参数相同。Windows 在 PowerShell 使用已安装的 `boxbridge.cmd`，Orca 使用原生 `orca.exe`。未自动找到 Orca CLI 时，增加 `--orca` 指定完整的本机可执行文件路径。自定义云端监督进程目录使用 `--cloud-root /absolute/cloud/install`。启用会校验所选 Orca 环境的首选地址是否指向当前 BoxBridge 本机端口，不匹配时不发送云端命令。

运行中的 BoxBridge 也需为 0.4.2 或更新版本。仅更新文件还未重启服务时，用 `status.runtimeVersion` 判断，按 [CLI 使用手册](CLI-QUICKSTART.md) 重启现有登录服务。旧配置默认关闭；启用后会沿用到后续更新。

## 检查频率

- 本地没有新增轮询定时器，复用已有连接健康事件。首次健康连接、云机路由变化、断线恢复和缓存到期时触发检查。
- 按账号、云机路由和所选环境缓存。成功缓存 6 小时，断线恢复检查最短间隔 10 分钟，网络 token 轮换不会触发重装。
- 并发检查合并为一次维护。失败后至少等待 1 分钟、5 分钟，连续 3 次失败就停止自动尝试。重启本机程序不会清空失败次数。修复后手动 `watchdog check` 再试，新的云机路由也会开始新的检查。
- 每次使用新建的后台 Orca 终端，不带 `--focus`，完成后关闭自己的终端，不输入现有工作终端。
- `watchdog status` 只读带时间的本机缓存，不证明实时在线。`check` 会实际维护云端守护程序。

## 云端维护范围

| 已有安装 | 行为 |
| --- | --- |
| `~/.orca/start-orca-tmux.sh` 启动的 `orca` 会话 | 幂等安装 `~/.orca/watch-orca.py`，验证单实例锁和桌面自动启动项，复用原启动脚本 |
| 官方 `/workspace/.boxbridge` 安装 | 校验已有控制程序摘要，复用监督进程和自动启动项，不叠加 watchdog |
| 自定义或未知文件、版本、启动方式 | 保留文件，返回 `conflict` 或 `unsupported-installation`，需人工核对 |

tmux watchdog 在 Linux 支持时使用 pidfd 监听会话进程退出，退出后尝试恢复；每 5 分钟在云机本地复核一次 HTTP。旧内核回退为低频本机检查。启动失败会退避，成功必须以 `6768` 返回 HTTP `200` 为准。已有且未就绪的 Orca 会话保留，不强杀；卡死仍需排查。新版监督进程沿用原来的子进程退出检测。

启动项在云机桌面会话启动后生效，依赖原用户文件保留。尚未在真实用户云机上强制重启验收，避免中断 Claude。平台回收整个实例或清空文件时，需要重新部署和恢复数据。

## 检查和停止

```bash
boxbridge watchdog status
boxbridge watchdog check
boxbridge watchdog disable
```

关闭只停止本机自动维护，保留云端守护程序。`boxbridge pause` 同时暂停保活与自动维护，`resume` 恢复。维护不读取或回传配对密钥，诊断只记录状态、布尔值和失败次数。

Orca 离线时无法使用它的加密执行通道。此时 BoxBridge 保留重连，等待原有云端自动启动恢复，不自动使用桌面键鼠、模型消息或新执行器。首次部署或所有执行通道失效时需要一次人工恢复，恢复 HTTP 和原配对后继续自动维护。
