Crabbox 是 OpenClaw 项目中的远程验证包装与编排工具，用于把需要在远程环境完成的验证任务从本地转移到可复用的远程机器上执行。它本身不直接提供计算资源，而是充当传输与调度层，实际后端可以是托管 AWS Crabbox（provider=aws，租约 ID 形如 cbx_...，syncDelegated=false），也可以是通过 Crabbox 调用的 Blacksmith Testbox（provider=blacksmith-testbox，租约 ID 形如 tbx_...，syncDelegated=true）。两类后端的同步与执行职责不同，官方要求如实报告实际 provider 与 ID，不得把 Testbox 运行描述为 AWS Crabbox。
用途方面，Crabbox 适用于需要远程 Linux 验证的广泛测试、CI 一致性检查、密钥与托管服务验证、Docker/E2E/打包测试通道、预热可复用机器、同步耗时观察、日志与结果收集、缓存检查以及租约清理。OpenClaw 维护者的广泛 pnpm 门禁在满足 Testbox 规则时，可通过 Crabbox 调用 Blacksmith Testbox 完成，并报告 tbx_ 前缀 ID 与 Actions 运行信息。当任务需要直接的 AWS Crabbox 行为、持久直连 provider 租约、--fresh-pr、--full-resync、环境变量转发、捕获/下载支持或 provider 对比时，则使用仓库 .crabbox.yaml 配置的托管 AWS 路径。
主要能力包括：从仓库根目录运行并镜像当前检出；检查包装器版本与 provider 帮助；通过 --preflight 打印运行上下文、工作区模式、SSH 目标、远程用户与工作目录以及目标工具探测结果（覆盖 git、tar、node、npm、corepack、pnpm、yarn、bun、docker，以及 POSIX 的 sudo/apt/bubblewrap 和原生 Windows 的 powershell/execution_policy/longpaths/temp/pwsh 等）；通过 CRABBOX_ENV_ALLOW 仅转发列出的本地环境变量；通过 --env-from-profile 与 --allow-env 从本地 profile 加载变量并仅转发白名单项；通过 --env-helper 在 POSIX SSH 目标上持久化环境以便后续命令复用；通过 --script 或 --script-stdin 上传并执行远程脚本；通过 --fresh-pr 跳过本地脏同步并为 GitHub PR 创建全新远程检出，配合 --apply-local-patch 叠加本地 diff；通过 --full-resync 或 --fresh-sync 重置过期的直连 provider 工作目录；通过 --capture-stdout、--capture-stderr、--capture-on-fail 将远程输出写入本地文件或失败时下载测试结果、playwright 报告、覆盖率、JUnit XML 等；通过 --keep-on-failure 保留失败的 one-shot 租约以便调试；通过 --timing-json 输出机器可读计时，并支持在命令中插入 CRABBOX_PHASE 标记以生成 commandPhases。
使用方式上，需从仓库根目录运行，优先使用 ../crabbox/bin/crabbox（用户 PATH 中的 shim 可能过期），并先检查 .crabbox.yaml 中的直连 provider 默认值。省略 --provider 时默认走托管 AWS，其默认镜像是 eu-west-1 的 Linux 开发者镜像，仓库配置固定 eu-west-1a/b/c 放置以启用 Fast Snapshot Restore。广泛 OpenClaw 维护者 pnpm 门禁在适用 Testbox 政策时，优先使用 --provider blacksmith-testbox 或仓库 Testbox 辅助脚本。出现直连 provider 租约疑似过期时，先用 --full-resync 重试再替换租约。实时 provider 调试需使用配置好的密钥工作流，只把所需密钥注入单条命令的远程进程环境，不得打印、作为仓库文件同步或留在远程 shell 历史与日志中；若无安全的密钥注入路径，应说明实时 provider 认证被阻塞，而不是静默使用假密钥。
适用场景包括：广泛测试与 CI 一致性检查、Docker/安装/打包类问题的端到端验证、provider/模型/认证类问题的真实 E2E、渠道投递类问题、Gateway/会话/工具类问题、纯解析器/配置类问题的补充验证，以及 Windows 专项验证和静态 SSH 目标上的 macOS/Windows 验证。对于用户可见缺陷，官方建议在评论、关闭或提交 PR 前至少完成一次修复后的 E2E 证明，并从真实用户入口复现问题，而不是简单把测试复制到远程机器。
限制方面：crabbox actions hydrate/register 目前仅支持 Linux；静态 macOS 与 Windows 主机需使用普通 crabbox run 循环；托管 AWS 原生 Windows 使用 us-west-2 的按需开发者镜像；托管 macOS 需要确认协调器支持 EC2 Mac 主机生命周期/镜像路由，且操作者具备 AWS EC2 Mac 专用主机配额与 IAM，优先使用 CRABBOX_HOST_ID 或先运行不产生费用的预检；委托 provider 不支持 --capture-、--download、--checksum、--force-sync-large、--sync-only、--script、--fresh-pr、--full-resync、--env-helper，--keep-on-failure 对委托 one-shot 可用；--full-resync 与 --fresh-pr 冗余、与 --no-sync 不兼容；实时证明需要可达且由操作者管理的 SSH 主机，否则只能通过帮助输出、配置/参数测试和 Go 测试套件验证。此外，不得把本地 shell 继承的 OPENCLAW_LOCAL_CHECK_MODE=throttled 视为把广泛检查移到本地的许可，仅在用户明确要求本地证明时才使用该模式。