openclaw/crabbox

crabbox 是做什么的？

当项目需要远程证明、更大的云端容量、干净的 PR 检出、可重用的预热盒子、GitHub Actions 风格的环境设置、持久的运行日志/结果、UI 证明产物，或从脏的本地检出同步时，请使用 Crabbox。

检测 Crabbox

• 将仓库根目录下的 crabbox.yaml 或 .crabbox.yaml 视为使用此技能进行验证工作的有意信号。.crabbox.yml 不是受支持的配置文件名称。
• 如果这两个配置文件都不存在，command -v crabbox 仍然可以识别已安装的 CLI。在依赖于它进行远程工作之前，请运行 crabbox doctor。
• 在执行前检查配置。检测并不意味着允许暴露秘钥、绕过命令批准或启动付费基础设施。

事实来源

• 从仓库根目录运行 Crabbox；同步会镜像当前检出。
• 将仓库本地的 crabbox.yaml 或 .crabbox.yaml 视为可执行的项目自动化脚本。在远程运行前检查它，特别是 provider、actions、jobs、profiles、env.allow、产物和清理策略。
• 在依赖示例之前验证已安装的二进制文件：command -v crabbox && crabbox --version && crabbox --help | sed -n '1,120p'。
• 使用 crabbox providers 或 crabbox providers --json 获取当前的提供商/能力矩阵；提供商文档可能滞后于编译的二进制文件。
• 使用 crabbox doctor 进行实时就绪检查，使用 crabbox config show 检查合并的配置而不打印秘钥。
• 对于紧密的编辑循环，首选本地定向测试。对于大型套件、包繁多的检查、Docker/E2E/实时提供商证明、跨操作系统证明、UI 证明或会使本地机器负担过重的命令，请改用 Crabbox。

认证与配置

代理操作需要一个协调器 URL 和令牌。首次登录通常需要显式的代理 URL：

crabbox login --url <broker-url>
crabbox whoami
crabbox doctor

配置 broker.url 后，crabbox login 可以重用它。受信任的操作者自动化可以将共享令牌存储在 argv 之外：

printf '%s' "$CRABBOX_COORDINATOR_TOKEN" |
  crabbox login --url <broker-url> --provider aws --token-stdin

配置优先级为 flags > env > 仓库配置 > 用户配置 > 默认值。 默认用户配置在 macOS 上为 ~/Library/Application Support/crabbox/config.yaml，在 Linux 上为 ~/.config/crabbox/config.yaml，或当设置 $XDG_CONFIG_HOME 时为 $XDG_CONFIG_HOME/crabbox/config.yaml。crabbox config path 打印当前用户配置路径。

将提供商和代理令牌保存在仓库配置和命令参数之外。使用环境变量、凭据存储、协调器管理的秘钥或短期令牌命令。

选择远程表面

• crabbox run -- <command>：在新鲜或重用的盒子上运行一条命令。
• crabbox warmup：创建一个可重用的租赁，稍后使用 --id 运行命令。
• crabbox prewarm：预热一个可重用租赁，并从配置的 GitHub Actions 进行填充。
• crabbox job run <name>：使用仓库本地的命名流程，它会扩展为 warmup、可选填充、run 和 stop。
• crabbox run --pool <key>：借用一个已填充的协调器准备池租赁，运行，然后根据 --pool-return 归还/排空/释放它。
• crabbox run --fresh-pr ...：忽略本地同步，在远程检出 GitHub PR；添加 --apply-local-patch 在该 PR 之上测试本地未提交的更改。
• crabbox run --provider ssh：使用现有的 macOS、Linux 或 Windows 主机。
• crabbox warmup --desktop --browser：为 UI 测试、WebVNC、截图和产物配置一个可见的桌面/浏览器。

如果远程证明被阻止，请精确说明缺失的能力：认证、协调器、容量、提供商支持、目标操作系统、填充、秘钥访问、产物存储、桌面支持或委托提供商的限制。

通用的远程证明

一次性命令：

crabbox run --preflight --timing-json -- pnpm test

预热并重用租赁：

crabbox warmup --class beast --idle-timeout 90m
crabbox status --id <cbx_id-or-slug> --wait
crabbox run --id <cbx_id-or-slug> -- pnpm test:changed
crabbox run --id <cbx_id-or-slug> --full-resync -- pnpm test:changed
crabbox stop <cbx_id-or-slug>

配置后使用仓库本地任务：

crabbox job list
crabbox job run --dry-run <job-name>
crabbox job run <job-name>
crabbox job run --id <cbx_id-or-slug> <job-name>

当协调器具有已填充的池容量时使用准备池租赁：

crabbox pool ready
crabbox run --pool <pool-key> -- pnpm test
crabbox run --pool <pool-key> --pool-return drain -- pnpm test:flaky

当仓库已在 CI 中拥有设置时使用 GitHub Actions 填充：

crabbox warmup --idle-timeout 90m
crabbox actions hydrate --id <cbx_id-or-slug>
crabbox run --id <cbx_id-or-slug> -- pnpm test

仅当工作流需要完整的 GitHub Actions 语义（如仓库秘钥、OIDC、服务容器、作业容器或不支持的 uses: 步骤）时使用 --github-runner：

crabbox actions hydrate --github-runner --id <cbx_id-or-slug>

同步与新鲜检出

正常同步传输已跟踪的文件加上未忽略的未跟踪文件，排除被忽略的依赖/构建/缓存输出，尊重 .crabboxignore 和 sync.exclude，尽可能从 origin 播种远程检出，并在同步指纹匹配时跳过 rsync。

在大型运行前使用 crabbox sync-plan。意外的计数通常意味着本地生成了变动；更新 .crabboxignore 或 sync.exclude 而不是强制大量上传。

crabbox sync-plan
crabbox run --debug --timing-json -- pnpm test
crabbox run --full-resync -- pnpm test

当本地依赖变动或脏同步可能混淆结果时，使用新鲜的 PR 检出：

crabbox run --fresh-pr example-org/my-app#123 --script ./scripts/e2e-smoke.sh
crabbox run --fresh-pr 123 --apply-local-patch -- pnpm test

--fresh-pr 接受 owner/repo#number、GitHub PR URL 或来自当前 GitHub origin 的数字 PR。非 GitHub 主机被拒绝。新鲜 PR 检出一个 SSH 运行同步功能；委托提供商拒绝它。支持原生 Windows SSH 目标。

当预热租赁感觉陈旧时，优先使用 --full-resync（别名 --fresh-sync）来重置远程工作目录，跳过同步指纹快速路径，尽可能重新播种 Git，并从零开始上传检出。

脚本、Shell 和 Windows 目标

在 -- 后使用纯 argv 来运行一个可执行文件。使用 --shell 运行多语句 shell 片段、管道或 shell 扩展：

crabbox run --id <lease> -- go test ./...
crabbox run --id <lease> --shell 'corepack enable && pnpm install --frozen-lockfile && pnpm test'

对于多行命令，首选上传的脚本。脚本包含在失败包中，并避免脆弱的带引号 shell 字符串：

crabbox run --script ./scripts/e2e-smoke.sh --timing-json
printf '%s\n' 'echo CRABBOX_PHASE:test' 'pnpm test' | crabbox run --script-stdin

原生 Windows 目标使用 PowerShell 和基于 tar 的清单同步。首选纯 argv 运行一个可执行文件，如 dotnet test；使用 --shell 运行多语句 PowerShell，使用 --script <file.ps1> 运行更长的脚本。

Hyper-V Windows 租赁

hyperv 需要 Gen2 VHDX、DHCP 以及受信任配置或 CRABBOX_HYPERV_GUEST_PASSWORD 中的已知本地管理员密码。它在缺失时通过 PowerShell Direct 安装固定的、已验证的 OpenSSH 和 MinGit 包。有关模板和生命周期详细信息，请参阅 docs/providers/hyperv.md。

对于提供商测试，首选提升权限的无头运行器；早期的 PowerShell Direct 失败可能显示凭据 UI。将密码保留在参数和日志之外，并验证租赁变得就绪、通过 SSH 运行并释放。

秘钥和环境变量转发

Crabbox 不会转发整个本地环境。转发基于名称：只有实际在本地设置或在允许的配置文件中设置了白名单名称的变量才会跨越边界。避免白名单秘钥形状的名称，除非运行是一个明确的实时秘钥冒烟测试。

crabbox run --allow-env CI,NODE_OPTIONS -- pnpm test
crabbox run \
  --env-from-profile ~/.project-live.profile \
  --allow-env API_TOKEN \
  --preflight \
  --script ./scripts/live-smoke.sh

--env-from-profile 解析简单的 export NAME=value 和 NAME=value 行，而不执行配置文件。Crabbox 打印经过编辑的存在/长度元数据，而非值。POSIX SSH 租赁可以在您控制的租赁上为后续命令持久化一个辅助脚本：

crabbox run \
  --id <lease> \
  --env-from-profile ~/.project-live.profile \
  --allow-env API_TOKEN \
  --env-helper live \
  -- true
crabbox run --id <lease> -- ./.crabbox/env/live ./scripts/live-smoke.sh

生成的辅助脚本和匹配的秘钥配置文件保留在远程工作目录中，直到清理、租赁重置或 --full-resync；不要在共享或不受信任的租赁上持久化辅助脚本。

配置文件、预设、证明和结果

仓库配置可以定义配置文件、预设、doctor 要求、产物 glob、必需的产物和证明模板。使用它们来建立稳定的验证通道，而不是将项目知识编码到代理提示中。

crabbox run \
  --profile live-qa \
  --preset qa-live \
  --scenario login-regression \
  --emit-proof /tmp/proof.md \
  --stop-after success

使用 --preflight 在命令之前获取目标能力快照，而不是作为安装程序。使用 --preflight-tools 调整探测：

crabbox run --preflight --preflight-tools node,bun,docker -- bun test
crabbox run --preflight --preflight-tools default,uv -- node --test

当命令发出结构化结果和证明产物时，附加它们：

crabbox run --junit reports/junit.xml -- ./scripts/test-with-junit.sh
crabbox run --artifact-glob 'reports/**' --require-artifact reports/summary.json -- pnpm test:e2e
crabbox run --download reports/summary.json=.crabbox/logs/summary.json -- pnpm test:e2e

如果远程命令以退出码 0 结束但证明文件缺失，--require-artifact 会失败运行。保持必需的产物有界且经过清洗；不要收集原始数据集、秘钥、凭据、签名的 URL 或未编辑的客户行。

运行句柄和可观测性

协调器支持的后台运行会在租赁开始前打印一个持久的 run_... 句柄。在状态更新和 PR 备注中保留该运行 ID。

crabbox history --limit 20
crabbox history --lease <cbx_id-or-slug> --limit 20
crabbox attach <run_id>
crabbox attach <run_id> --after <seq>
crabbox events <run_id> --after <seq> --limit 100
crabbox events <run_id> --json
crabbox logs <run_id>
crabbox results <run_id>

当需要稳定的机器可读计时记录时，在 run、warmup 和 actions hydrate 上使用 --timing-json。命令可以通过在 stdout 或 stderr 上打印标记来标记子阶段：

echo CRABBOX_PHASE:install
pnpm install --frozen-lockfile
echo CRABBOX_PHASE:test
pnpm test

输出事件是有限制的预览。使用 logs 获取保留的输出尾部，使用 results 获取解析的测试摘要。

桌面、WebVNC 和 UI 证明

创建桌面/浏览器租赁，用于视觉 QA、有头浏览器自动化或 UI 证明：

crabbox warmup --desktop --browser
crabbox warmup --provider aws --os ubuntu:26.04 --desktop --browser --desktop-env wayland
crabbox warmup --provider aws --os ubuntu:26.04 --desktop --browser --desktop-env gnome

ubuntu:26.04 是默认的可移植 Linux 操作系统选择器，在提供商目录支持的情况下使用。仅当测试必须保持在之前的 LTS 版本上时，才使用 --os ubuntu:24.04。显式的提供商标识标志仍然优先于 --os。

对于人工演示，首选 WebVNC 而非原生 VNC，因为 crabbox webvnc --open 会在浏览器片段中预加载租赁密码：

crabbox webvnc --id <lease> --open --take-control
crabbox webvnc status --id <lease>
crabbox webvnc reset --id <lease> --open --take-control
crabbox vnc --id <lease> --open

对于输入自动化，使用一等辅助脚本，而不是手写的 xdotool：

crabbox desktop doctor --id <lease>
crabbox desktop launch --id <lease> --browser --url https://example.com --webvnc --open --take-control
crabbox desktop click --id <lease> --x 640 --y 420
crabbox desktop paste --id <lease> --text "[email protected]"
printf '[email protected]' | crabbox desktop paste --id <lease>
crabbox desktop type --id <lease> --text "[email protected]"
crabbox desktop key --id <lease> ctrl+l
crabbox screenshot --id <lease> --output desktop.png

当桌面/WebVNC 挂起时，首先信任内联的救援输出：problem: 和 rescue: 行通常会命名确切的下一个命令，例如 webvnc status/reset、desktop doctor 或原生 vnc --open。

使用产物进行 UI QA 证明，而不是将截图或视频提交到产品仓库分支：

crabbox artifacts collect --id <lease> --all --output artifacts/<slug>
crabbox artifacts publish --dir artifacts/<slug> --pr <number>
crabbox artifacts list <artifact-manifest-url-or-dir>
crabbox artifacts pull <artifact-manifest-url-or-dir> --output /tmp/<slug>-proof

artifacts publish 在配置后使用代理存储，或使用显式的 S3/R2 / Cloudflare/本地托管标志。在审查生成的 Markdown 或存储命令时，在公开 PR 评论前使用 --dry-run。

提供商边界

SSH 租赁提供商在所有支持的同步/运行表面上运行：脚本、新鲜 PR 检出、捕获、下载、Actions 填充、SSH、端口、WebVNC、code-server、桌面、浏览器、缓存卷和清理。

委托运行提供商拥有命令传输。期望它们拒绝 SSH 运行的功能，例如 --capture-stdout、--capture-stderr、--capture-on-fail、--script、--script-stdin、--fresh-pr、本地捕获、--download、--full-resync 和 --env-helper，除非 crabbox providers --json 和提供商文档声明了匹配的能力。--keep-on-failure 对于一次性委托提供商仍然有用，这些提供商在命令失败后 Crabbox 通常会自动停止。

模块运行时委托提供商，su

…

[为翻译截断]