crabbox

用途

Crabbox 是 OpenClaw 用于远程验证的传输与编排封装层，主要服务于需要在远端真实环境中证明代码路径的场景，例如大范围测试、CI 一致性校验、密钥与托管服务联调、Docker/E2E/打包通道、预热可复用实例、同步计时、日志与结果收集、缓存检查以及租约清理。

远端执行的后端有两种：

经纪式 AWS Crabbox：直连提供方，provider=aws，租约 id 形如 cbx_...，syncDelegated=false。
通过 Crabbox 的 Blacksmith Testbox：委派提供方，provider=blacksmith-testbox，id 形如 tbx_...，syncDelegated=true。

报告中必须写明实际使用的提供方和 id：cbx_... 表示 AWS Crabbox，tbx_... 表示通过 Crabbox 的 Blacksmith Testbox。

主要能力

两种后端选择：当任务需要直接 AWS Crabbox 行为、持久直连租约、--fresh-pr、--full-resync、环境转发或捕获下载时，使用仓库 .crabbox.yaml 的经纪式 AWS 路径；当任务需要 OpenClaw 维护者 Testbox 证明、准备好的 CI 环境或大范围 pnpm 门禁时，使用 --provider blacksmith-testbox。
预热与复用：存在预热实例、同步计时、缓存检查与租约清理相关能力。经纪式 AWS 默认使用 eu-west-1 的 Linux 开发镜像，仓库配置固定 eu-west-1a/b/c 的放置，以便应用 Fast Snapshot Restore。
同步控制：Crabbox 同步会镜像当前检出目录。若预热直连租约疑似过期，可先重试 --full-resync（别名 --fresh-sync）再替换租约，该操作会重置远端工作目录、跳过指纹快速路径、在可能时重新播种 Git 并从头上传检出目录。--fresh-pr owner/repo#123|URL|number 可跳过本地脏同步并在远端创建全新的 GitHub PR 检出。
脚本与环境：--script <file> / --script-stdin 可将本地脚本上传到 .crabbox/scripts/ 并在远端执行；CRABBOX_ENV_ALLOW=NAME,... 仅转发列出的本地环境变量；--env-from-profile <file> 配合 --allow-env NAME 从本地 profile 加载简单的 export NAME=value 行而不执行它，只转发白名单名称。
观测与调试：--preflight 打印运行上下文、工作区模式、SSH 目标、远端用户/目录及目标相关的工具探测；--timing-json 输出机器可读的最终计时；--capture-stdout / --capture-stderr 将远端输出写入本地文件；--capture-on-fail 在非零退出时下载包含测试结果、playwright 报告、覆盖率、JUnit XML 和日志的打包；--keep-on-failure 保留失败的一次性租约以便现场调试。

使用方式

从仓库根目录运行。先检查封装层与提供方：

command -v crabbox
../crabbox/bin/crabbox --version
pnpm crabbox:run -- --help | sed -n '1,120p'
../crabbox/bin/crabbox desktop launch --help
../crabbox/bin/crabbox webvnc --help

OpenClaw 脚本优先使用 ../crabbox/bin/crabbox，用户 PATH 中的 shim 可能已过期。省略 --provider 时当前默认是经纪式 AWS。

直连经纪式 AWS 的改变门禁示例：

pnpm crabbox:run -- \
  --idle-timeout 90m \
  --ttl 240m \
  --timing-json \
  --shell -- \
  "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed"

通过 Crabbox 使用 Blacksmith Testbox：

node scripts/crabbox-wrapper.mjs run \
  --provider blacksmith-testbox \
  --blacksmith-org openclaw \
  --blacksmith-workflow .github/workflows/ci-check-testbox.yml \
  --blacksmith-job check \
  --blacksmith-ref main \
  --idle-timeout 90m \
  --ttl 240m \
  --timing-json \
  -- \
  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 OPENCLAW_TESTBOX=1 OPENCLAW_TESTBOX_REMOTE_RUN=1 pnpm check:changed

静态 SSH 目标示例：

../crabbox/bin/crabbox run --provider ssh --target macos --static-host mac-studio.local -- xcodebuild test
../crabbox/bin/crabbox run --provider ssh --target windows --windows-mode normal --static-host win-dev.local -- pwsh -NoProfile -Command "dotnet test"
../crabbox/bin/crabbox run --provider ssh --target windows --windows-mode wsl2 --static-host win-dev.local -- pnpm test

适用场景

大范围或重型 pnpm 门禁与 CI 一致性校验。
Docker、安装/打包、E2E 路径的实际用户视角验证。
需要真实密钥的提供方/模型/认证联调（须走配置好的 secret 注入流程）。
渠道投递、Gateway/会话/工具相关缺陷的端到端验证。
Windows 专有问题验证（按需使用 us-west-2 的 AWS 开发镜像）。
需要时使用静态 SSH 主机上的 macOS 或 Windows 原生/WSL2 目标。

限制与注意事项

委派提供方（blacksmith-testbox）拥有同步与命令传输，不支持 --capture-*、--download、--checksum、--force-sync-large、--sync-only、--script*、--fresh-pr、--full-resync、--env-helper 等参数；--keep-on-failure 可用于委派一次性任务。
crabbox actions hydrate/register 目前仅限 Linux；静态 macOS 与 Windows 主机请使用普通 crabbox run 循环。
经纪式 macOS 需先确认部署的协调器支持 EC2 Mac 主机生命周期/镜像路由，且操作者具备 AWS EC2 Mac Dedicated Host 配额与 IAM；可用 crabbox admin hosts quota 和 --dry-run 预检。
不要将继承的 shell 环境变量（如 OPENCLAW_LOCAL_CHECK_MODE=throttled）视为操作者意图；仅在用户明确要求本地证明时使用。
真实密钥只注入到单条命令的远端进程环境，不得打印、作为仓库文件同步或留在远端历史与日志中；若没有安全的注入路径，应说明真实联调被阻塞，而不是静默使用假密钥。
预热镜像假设 Docker 已内置，仅在镜像探测显示缺失时才安装。
blacksmith testbox list 可能隐藏 hydrating 或 ready 实例，使用 blacksmith testbox list --all 与 blacksmith testbox status <tbx_id> 确认。

暂未提供

资料未提供该工具的授权协议、收费方式、社区支持渠道等信息。