LANSHUTOOLS & IDEAS
内测分发 CLI V0.4.4
BOXBRIDGE CLIEARLY ACCESS · CLI ONLY

一套 CLI,
接入你的云机。

把本页发给能操作你电脑的 Agent,自动安装 CLI 和 Skill。
按提示完成登录授权,即可配置 Orca、配对、保活和自动守护。

YOUR DESKTOP本地 OrcaMac / Windows
THE BRIDGEBoxBridge 自连复用 Grok 原生受鉴权通道
GROK COMPUTER云端 Orca项目 / 终端 / Claude Code
无需额外 VPN 组网保活零模型调用后台静默运行
01 / CAPABILITIES

连上云机,也能和 Bot 对话。

所有功能均从 CLI 调用。
保活自动运行,模型和云端输入保持手动授权。

01 / BOTCLI · 指定 Bot

和指定 Bot 聊天

列出 Bot,按名称或 ID 发送消息,再读取回复。也可以由自己的 Agent 调用,发送前须明确允许使用模型额度。

agents · chat · tail查看聊天用法
02 / COMMANDCLI · 手动触发

执行云端命令

配置执行器后,用 run 获取输出和退出码、用 sh 按行操作。也可授权指定 Bot 接手任务。

run · sh · exec查看执行用法
03 / DESKTOPCLI · 手动触发

截图、鼠标和键盘

保存云端截图,发送点击、按键与文本输入。操作发送到云端,本机不弹出控制窗口。

screen · click · key · type查看全部桌面命令
04 / WORKSPACECLI + Orca

接回 Orca 与 Claude Code

CLI 维持连接,在独立的 Orca 客户端打开云端项目和终端。代码与 Claude Code 继续在云机运行。

pair · start · service install查看连接与配对
05 / CONNECTIONCLI · 常驻服务

静默保活,断线重连

后台刷新连接、自动重试,登录后静默启动。保活不调用模型,也不操作云端桌面。

pause · resume · wake查看日常使用
06 / AGENTCLI + SKILL

让 Agent 装好、配好

从本页安装 CLI 与 Skill,统一引导配置 Orca、项目、自启和守护。需要登录、系统权限或首次云端操作时明确提示你。

onboard --check · onboard --json查看 Agent 说明
关于模型额度

后台保活、状态查询和读取回复不调用模型。chat / exec 必须显式加 --allow-model;Agent 不应自行添加授权参数。云端截图与输入只在用户明确要求时执行。

02 / DOWNLOAD

选好系统,自动安装。

安装器准备运行环境、CLI 和首次配置。
连接云机前,请先登录 Grok Bot。

MACOS / UNIVERSALApple / Intel

Mac 安装器

macOS 14+ · 无需先安装 Node/npm

下载 Mac 安装器
0.4.4 · 自动准备 Node + CLI安装步骤 ↗

手动 CLI 包 · 0.8 MB · .tgz ↓

查看 CLI 包 SHA-256ce8c160d2bfc7b61821cd05838cfaa9b85f63013ee7463b03f333585c362995a

自动安装 CLI 并进入首次配置。已有钥匙串授权继续复用,系统提示由你在本机处理。

WINDOWS / X64Windows 10 / 11

Windows 安装器

Windows x64 · 无需先安装 Node/npm

下载 Windows 安装器
0.4.4 · 自动准备 Node + CLI安装步骤 ↗

手动 CLI 包 · 0.8 MB · .tgz ↓

查看 CLI 包 SHA-256c987356d703e48981de2bbc1b6557c357b289470778e70a2a0645535ac135251

用 PowerShell 运行,自动配置命令路径和首次引导。附 Windows 原生安装、配对与后台服务验收。

推荐自动安装器。已有 Node 或使用自定义环境时,也可下载手动 .tgz 包。

SHA-256 校验文件
云端 Orca 部署 · 按需使用GROK LINUX ONLY +
Linux 云端控制程序 0.4.0 ↓

仅在 Grok 云机运行 · Linux x64 / glibc 2.35+ · 6.3 MB
只使用 Bot 聊天时可跳过。部署步骤见云端 Orca 手册。

03 / UPDATES

已有安装,直接升级。

官网最新 CLI v0.4.4
升级沿用原授权、配对和配置。

01 / CHECK

检查更新

查看已安装版本与官网最新版本。

boxbridge update --check
02 / UPDATE

升级 CLI

校验安装包后升级,默认保留当前连接。

boxbridge update
03 / ROLLBACK

需要时回滚

有升级备份时,恢复上一次程序并保留配置。

boxbridge update --rollback

boxbridge --version 查看已安装 CLI;boxbridge status 中的 runtimeVersion 查看实际后台版本。若更新结果显示 restartRequired: true,按升级手册切换后台,Orca 会短暂重连。

版本记录与编号规则 当前 v0.4.4 +

0.x 为内测阶段。问题修复递增补丁号,例如 0.4.4 → 0.4.5;新功能递增次版本,例如 0.5.0。完成稳定性验收后再进入 1.0.0。

程序包按版本发布,同一版本保留同一份文件与校验值。网页和手册可单独更新;下一次修改程序包时使用新版本号。

以下包含本地试跑与已发布版本的历史说明,可下载版本以发布清单为准。下载版本记录(Markdown) ↗

0.4.4 — Guided installation for the CLI beta

  • Publish checksum-pinned Mac and Windows installers that prepare a private Node runtime and CLI before guided setup. Agents can use --install-only / -InstallOnly for installation without account access, then request any required user authorization.
  • Include guided Orca deployment, original pairing reuse, project selection, background service and bounded watchdog recovery in the downloadable CLI.
  • Handle Windows Unicode paths, NSIS install paths with spaces, PowerShell 5.1 script encoding and built-in module discovery when launched from PowerShell 7.
  • Add native Windows acceptance for official Orca installation, private stdin pairing, a fresh private Node runtime, repeat installation, preserved configuration, startup ownership and unchanged window focus. Tests use synthetic identities and never call a model.
  • Synchronize the download page, installation manual and three-file Agent Skill around the same guided setup flow. Keep source private and desktop downloads withdrawn.

0.4.3 — Guided first installation (local trial)

  • Add onboard and local-only onboard --check for login, verified per-user Orca installation, background service, cloud deployment, saved pairing, project selection and watchdog verification.
  • Reuse existing installations and require explicit one-time desktop permission when no execution channel exists. No model fallback or background desktop control.
  • Import pairing through stdin in a headless process without secret arguments, environment variables, temporary files or logs.
  • Keep safe resumable stages, prevent overlapping setup and verify actual readiness on reruns.
  • Prepare checksum-pinned Mac/Windows host installers with a private Node runtime. Public rollout and new Windows native acceptance remain pending.

0.4.2 — Event-driven Orca watchdog maintenance (local trial)

  • Add opt-in watchdog enable, status, check, and disable through an existing Orca pairing and a dedicated background maintenance terminal.
  • Ensure the recognized tmux watchdog or reuse the checksum-verified cloud supervisor, preserving data, pairing, launcher and user terminals.
  • Reuse gateway health events with a six-hour success cache, ten-minute recovery cooldown, coalesced requests and a persisted three-failure budget. No additional local polling timer, model request or desktop fallback.
  • Observe tmux process exit with Linux pidfds when available, with a five-minute local HTTP audit and timed fallback on older kernels.
  • Embed maintenance payloads in standalone bundles to preserve the existing updater archive format. Public downloads retain the previously published version pending trial acceptance.

0.4.1 — CLI updates and preserved authorization

  • Make the CLI a standalone JavaScript bundle with no npm dependency installation during self-update.
  • Add update, update --check and update --rollback, using the official HTTPS catalog, exact download paths, bounded archives, SHA-256 validation, standalone startup checks and failure rollback.
  • Preserve active gateway processes, profile settings, Orca pairing and native helper identity during updates; restarting a background service remains explicit.
  • Preserve an already-authorized Mac helper in the private profile, pin its binary digest and share it across future CLI/desktop versions. Never cache a password or plaintext login token.
  • Make repeated init reuse the current account authorization and report running gateway version and owner kind.
  • Keep the published desktop 0.4.0 packages available while prioritizing CLI 0.4.1.

0.4.0 — Desktop Bot chat

  • Add a Mac/Windows Bot chat page with Bot selection, message submission, recent replies, per-Bot drafts and read-only auto-update while visible.
  • Require explicit model-usage confirmation for every message. Block duplicate submissions; uncertain sends remain manual and are never resent automatically.
  • Keep login/route credentials in the main process; pass only display fields to the renderer, render replies as plain text, and exclude conversations from logs and diagnostics.
  • Cancel stale reads across account/settings changes and stop reply polling when leaving or hiding the chat view.
  • Validate the backend with synthetic clients and the renderer with hidden native Mac/Windows fixtures; automated checks never submit a real Grok prompt.

0.3.1 — Binary beta distribution

  • Point desktop help and cloud setup at the hosted beta download/manual page, so users do not need private repository access.
  • Link directly to the pinned official Orca release for desktop installation.
  • Provide private-source Mac/Windows binaries and a verified Linux cloud executable with a checksum-pinned installer.

0.3.0 — Windows x64 private preview

  • Add current-user DPAPI and Chromium AES-GCM login adapters, protected executor identities and private NTFS metadata.
  • Add Windows proxy discovery, a colored tray, native window controls and platform-specific onboarding.
  • Add silent per-user CLI startup with an owned Windows Job Object; never kill an unrelated PID.
  • Add per-user NSIS/ZIP packaging and native Windows credential, installer, startup, no-focus and uninstall checks.
  • Keep Windows CI artifacts private. Real Grok Windows-account validation remains a separate acceptance step.

0.2.0 — Private cloud CLI preview

  • Add all 17 missing command names from the local reference CLI, plus status --cloud.
  • Add direct run, line-oriented sh, signed executor install/check/autostart, read-only agents/transcripts, PNG screenshots and explicit remote input.
  • Keep model prompts behind --allow-model; desktop bootstrap requires --desktop. Never use a model or remote desktop as a background reconnect fallback.
  • Derive an account-bound Ed25519 executor identity in memory, install only its public key, reject replay/expired/modified requests, and bound execution/output.
  • Preserve the existing local gateway/control protocol and separate CLI/cloud setup.
  • Add isolated HTTP/RFB/shell regression coverage and include the executor in the private CLI payload audit. No public release or live model/UI testing.

0.1.1 — Private preview preparation

  • Fully ad-hoc sign both architectures of the native Keychain helper and include a designated code requirement. Packaged smoke checks now validate the helper separately from the app bundle.
  • Explain persistent Keychain permission, the complete CLI login-service setup, keepawake timing and checkout-based installation while the repository is private.
  • Scan the staged CLI payload before distribution and keep checksums scoped to the current version.

0.1.0 — Preview

  • Mac menu bar app with English/Chinese setup, account authorization, pairing conversion, connection controls, proxy settings, login startup and diagnostics.
  • CLI sharing a single private profile owner with the desktop app.
  • Loopback-only opaque WebSocket relay, authenticated provider route validation, server-first frame preservation, bounded retries and transient-failure recovery.
  • Memory-only provider credentials and a noninteractive native Keychain helper.
  • Checksum-pinned official Linux Orca installer with persistent pairing data, bounded process supervision and optional cloud desktop autostart.
  • Core, real local WebSocket, hidden desktop and simulated cloud lifecycle tests; release privacy checks, CI builds and third party notices.

This preview uses a private provider API and is not Apple notarized. Platform uptime and authenticated live Orca sessions require validation in the user's own account; automated tests do not use personal Grok credentials.

04 / AGENT SKILL

让 Agent 帮你安装。

把本页链接发给有本机终端权限的 Agent。它会按手册安装 CLI 与 Skill,再完成首次引导;登录和必要的授权会提示你处理。

请按官网说明在这台电脑安装 BoxBridge CLI 和 Skill,并完成 Orca、配对、项目、自启和守护配置。需要我登录或授权时告诉我;保持零模型调用,不抢窗口焦点。
https://lanshuagent.com/boxbridge/

手动安装时,解压后把整个 boxbridge 目录放进 Agent 的 Skills 目录。说明中有 Codex 和 Claude Code 的路径及使用示例。

05 / GET STARTED

从安装,到用起来。

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

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

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

开始前

想让 Agent 代装时,把官网链接和安装请求发给能操作本机终端的 Agent。它可以按Agent 安装说明下载、校验和安装 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。

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 运行

$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 时使用

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

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

Agent 可以先用 Mac 安装器的 --install-only 或 PowerShell 的 -InstallOnly 安装程序并做本机预检,再按用户授权运行 onboard --json。完整机制见首次配置说明。手动 .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 终端执行:

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 会停止连接;已有后台服务时不要再启动第二个长期进程。

boxbridge status
boxbridge pair

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

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

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

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

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

常驻保活与日常使用

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 代理端口:

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

Windows 使用:

'{"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. 读取发布清单并复用已有程序

读取发布清单和校验表。核对用户系统,支持 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,核对 bytes 和 sha256。ZIP 只应包含下面三个普通文件,拒绝额外条目、符号链接、绝对路径或跳出目录的路径。

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. 调用统一引导

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

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 选择已保存的云机环境,不自动激活本机窗口。

详细机制及手动兼容路径见安装手册和首次配置说明。

推荐检查顺序

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 入口;首次安装器的进程级策略参数按前文执行。

默认使用的读取命令

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。名称重名或含糊时报告歧义,不替用户猜测。

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

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 守护自动维护。运行 boxbridge watchdog enable --environment "用户环境名" --worktree /absolute/cloud/project,再执行 boxbridge watchdog check。运行中的服务也需为新版。watchdog status 只读带时间的缓存。自动维护保留原数据和配对,执行通道失效时等待恢复,不自动转用桌面、模型或新执行器。

  • 登录或授权错误:请用户本人处理;不要自动重置凭据或切换账号。
  • executor-offline / executor-untrusted:报告缺少执行器;安装按手册由用户明确发起。
  • 命令或消息提交超时:先检查任务或回复是否已经产生,不自动重发可能有副作用的请求。
  • 网络临时失败:读取操作可有限重试并退避;不要创建无限轮询或多个保活进程。
  • restartRequired: true:新版程序已安装,旧后台进程仍在运行。报告给用户,获得重启指示后按手册重启 CLI 服务。
  • BoxBridge 报 remote-unavailable 或 502 时,按安装手册检查云机的 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 会使用模型额度,只有明确需要发送时才执行:

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 控制程序分开安装。先在本地生成安装脚本:

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

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

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 模型请求。截图存到本机,鼠标键盘输入发送到云端,不弹本地控制窗口。

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,中文会拒绝有损转换。不要把截图或剪贴板里的私有内容写入公开反馈。

连接断开时

先运行:

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。

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

官网的升级入口提供检查、升级和回滚命令,也可查看版本记录。CLI 文件更新完成后,后台可能仍使用原版本,以 runtimeVersion 和 restartRequired 为准。

boxbridge update --check
boxbridge update
boxbridge update --rollback

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

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

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 手动安装的用户,通过安装时的前缀卸载,配置默认保留:

npm uninstall --global --prefix "$HOME/.local" boxbridge
& $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。

FEEDBACK

一起把这条路走稳。

内测反馈请附系统、版本、时间和错误码。
配对链接、账号 token 和项目机密,请留在你自己的设备上。

回到下载