Crabbox 是一个远程验证与编排工具，主要服务于 OpenClaw 的远程测试需求，覆盖 Linux、macOS、Windows 和 WSL2 平台，并支持委托 Blacksmith Testbox 进行验证。
用途 Crabbox 用于在 OpenClaw 需要远程 Linux 验证时执行广泛测试、CI 一致性检查、密钥与托管服务测试、Docker/E2E/打包通道、预热可复用机器、同步计时、日志与结果收集、缓存检查以及租约清理。它本身是传输与编排层，实际后端可以是直接代理的 AWS Crabbox，也可以是通过 Crabbox 委托的 Blacksmith Testbox。
主要能力 Crabbox 支持两种后端：直接代理的 AWS Crabbox（provider=aws，租约 ID 形如 cbx_...，syncDelegated=false）和通过 Crabbox 委托的 Blacksmith Testbox（provider=blacksmith-testbox，ID 形如 tbx_...，syncDelegated=true）。对于 OpenClaw 维护者的广泛 pnpm 门禁，通过 Crabbox 包装器使用 Blacksmith Testbox 是可接受且通常更优的选择，但不应将其描述为“AWS Crabbox”，而应报告为 Testbox-through-Crabbox，并附上 tbx_... ID 和 Actions 运行信息。
Crabbox 提供多种可观测性参数，包括 --preflight（打印运行上下文、工作区模式、SSH 目标、远程用户/目录及目标特定工具探测）、--timing-json（机器可读的最终计时）、--capture-stdout/--capture-stderr（将远程流写入本地文件）、--capture-on-fail（非零退出时下载捕获文件）、--keep-on-failure（保留失败的一次性租约以供调试）、--script/--script-stdin（上传本地脚本到远程执行）、--fresh-pr（跳过本地脏同步，创建 GitHub PR 的全新远程检出）、--full-resync/--fresh-sync（重置过期的直接代理工作目录）、--env-from-profile 与 --allow-env（从本地配置文件加载并转发允许的环境变量）、--env-helper（在 POSIX SSH 目标上持久化环境配置）等。
使用方式 使用前需从仓库根目录运行，并检查包装器与 provider：command -v crabbox、../crabbox/bin/crabbox --version、pnpm crabbox:run -- --help 等。OpenClaw 脚本优先使用 ../crabbox/bin/crabbox。检查 .crabbox.yaml 以了解直接代理默认值；省略 --provider 意味着当前使用代理 AWS。代理 AWS 默认是 eu-west-1 的 Linux 开发者镜像，仓库配置固定热 eu-west-1a/b/c 放置以应用 Fast Snapshot Restore。
对于直接代理 AWS 后端，可使用 pnpm crabbox:run 执行变更门禁、完整套件或聚焦重跑，并读取 JSON 摘要中的 provider、leaseId、syncDelegated、commandPhases、commandMs/totalMs、exitCode 等字段。Crabbox 应在运行后自动停止一次性 AWS 租约，运行失败、中断或输出不明确时需验证清理。
对于 Blacksmith Testbox，使用 node scripts/crabbox-wrapper.mjs run 并指定 --provider blacksmith-testbox 及相关参数。blacksmith testbox list 可能隐藏正在水合或就绪的机器，应使用 blacksmith testbox list --all 和 blacksmith testbox status <tbx_id>。
macOS 和 Windows 目标仅在任务需要现有非 Linux 主机时使用。原生代理 Windows 可用于 Windows 特定验证，使用 us-west-2 的 AWS 开发者镜像。Crabbox 支持静态 SSH 目标，例如 --provider ssh --target macos --static-host mac-studio.local 或 --target windows --windows-mode wsl2。
适用场景 Crabbox 适用于 OpenClaw 的远程广泛测试、CI 一致性检查、Docker/E2E/打包通道验证、密钥与托管服务测试、提供商/模型/认证缺陷的真实 E2E 验证、渠道交付缺陷验证、网关/会话/工具缺陷验证，以及需要 macOS 或 Windows 特定证明的场景。对于用户可见缺陷，建议在修复后运行一次 E2E 证明，从用户面向的入口点开始，而非仅复制测试到远程运行。
限制 Crabbox 的 actions hydrate/register 目前仅限 Linux；静态 macOS 和 Windows 主机需使用普通 crabbox run 循环。委托 provider 不支持 --capture-、--download、--checksum、--force-sync-large、--sync-only、--script、--fresh-pr、--full-resync、--env-helper 等参数，因为 provider 拥有同步或命令传输。--keep-on-failure 对委托一次性任务可用。在 blacksmith-testbox 上，环境转发不受支持，密钥应放在 Testbox 工作流中。实时验证需要可访问的、由操作员管理的 SSH 主机；没有时只能通过帮助、配置/标志测试和 Crabbox Go 测试套件验证。macOS 代理运行需要确认协调器支持 EC2 Mac 主机生命周期/镜像路由，且操作员拥有 AWS EC2 Mac 专用主机配额和 IAM。