Crabbox 是 OpenClaw 的远程验证封装与编排层，用于在本地无法覆盖的环境里运行测试和端到端证明。它本身不提供计算资源，而是把当前代码检出同步到远端，执行命令，并返回机器可读的计时与结果摘要。
用途
Crabbox 用于在 OpenClaw 需要远程 Linux 证明时运行范围较大的测试、CI 一致性检查、真实密钥与服务联调、Docker/E2E/打包通道、预热可复用盒子、同步计时、日志与结果收集、缓存检查以及租约清理。它支持代理式 AWS Crabbox（provider=aws，租约 ID 形如 cbx_...）和经 Crabbox 委托的 Blacksmith Testbox（provider=blacksmith-testbox，ID 形如 tbx_...）两种后端，也支持静态 SSH 目标连接已有的 macOS 和 Windows 主机。
主要能力
Crabbox 会从仓库根目录运行并镜像当前检出。主要能力包括：命令执行与 shell 模式；JSON 计时摘要，包含 provider、leaseId、syncDelegated、commandPhases、commandMs/totalMs 和 exitCode；预热与租约管理（warmup、list）；全量重新同步（--full-resync 或 --fresh-sync）；GitHub PR 全新检出（--fresh-pr）；本地脚本上传执行（--script、--script-stdin）；环境变量白名单转发（CRABBOX_ENV_ALLOW、--env-from-profile、--allow-env）；输出捕获（--capture-stdout、--capture-stderr、--capture-on-fail）；失败保留租约（--keep-on-failure）；预检诊断（--preflight）等。黑盒 Testbox 委托运行还支持指定组织、工作流、作业和引用。
使用方式
先在仓库根目录检查封装与 provider。OpenClaw 脚本优先使用 ../crabbox/bin/crabbox。省略 --provider 时默认为代理式 AWS。代理式 AWS 默认使用 eu-west-1 的 Linux 开发者镜像。对于 OpenClaw 维护者的大范围 pnpm 门禁，建议使用仓库封装配合 --provider blacksmith-testbox 或仓库 Testbox 辅助脚本。所有运行都应报告实际 provider 和 ID：cbx_... 表示 AWS Crabbox，tbx_... 表示经 Crabbox 的 Blacksmith Testbox。
直接代理式 AWS 的典型调用形式为 pnpm crabbox:run -- --idle-timeout 90m --ttl 240m --timing-json --shell -- "命令"，可运行 pnpm test:changed、完整 pnpm test 或聚焦重跑。经 Crabbox 的 Blacksmith Testbox 使用 node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox 并指定 blacksmith-org、blacksmith-workflow、blacksmith-job、blacksmith-ref。黑盒 Testbox 不支持捕获、下载、脚本、fresh-pr、full-resync 和 env-helper 等由 provider 掌控同步或命令传输的选项。
适用场景
适合范围较大的 pnpm 测试门禁、CI 环境一致性验证、Docker 与 E2E 测试、打包验证、真实服务与密钥的端到端联调、渠道投递验证、网关/会话/工具问题复现，以及 Windows 或 macOS 特定问题证明。对于紧凑的本地编辑循环，建议优先使用本地针对性测试。当需要 Windows 特定证明时，可使用按需的 us-west-2 AWS 开发者镜像；macOS 代理运行需要确认协调器支持 EC2 Mac 主机生命周期与镜像路由，并具备 AWS EC2 Mac 专用主机配额和 IAM 权限。
限制
Crabbox 的静态 SSH 目标需要可访问且由操作者管理的 SSH 主机；没有这样的主机时，只能通过 --help、配置/标志测试和 Go 测试套件验证。crabbox actions hydrate/register 目前仅支持 Linux。经 Crabbox 的 Blacksmith Testbox 由工作流负责检出与同步，因此不支持环境转发和多项同步相关标志。预检仅用于诊断，不负责安装工具链。真实 provider 鉴权应使用配置好的密钥工作流，只注入所需密钥，不得打印、同步为仓库文件或留在远端历史与日志中；没有安全的注入路径时应报告真实 provider 鉴权被阻塞，而不是静默使用假密钥。