crabbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Crabbox

Use Crabbox when OpenClaw needs remote Linux proof on owned capacity, a large runner class, reusable warm state, or a Blacksmith alternative.

当OpenClaw需要在自有算力、大规格运行器类、可复用预热状态下进行远程Linux验证，或需要替代Blacksmith时，可使用Crabbox。

Before Running

运行前准备

Run from the repo root. Crabbox sync mirrors the current checkout.
Prefer local targeted tests for tight edit loops.
Prefer Blacksmith Testbox when the task explicitly asks for Blacksmith or a Blacksmith-specific CI comparison.
Use Crabbox for broad OpenClaw gates when owned AWS/Hetzner capacity is the right remote lane.
Check
```
.crabbox.yaml
```
for repo defaults before adding flags.
Sanity-check the selected binary before remote work. OpenClaw scripts prefer
```
../crabbox/bin/crabbox
```
when present; the user PATH shim can be stale:
```
command -v crabbox; ../crabbox/bin/crabbox --version; ../crabbox/bin/crabbox --help | sed -n '1,90p'
```
.

Install with

brew install openclaw/tap/crabbox

; auth is required before use:

printf '%s' "$CRABBOX_COORDINATOR_TOKEN" | crabbox login --url https://crabbox.openclaw.ai --provider aws --token-stdin

On macOS the user config is

~/Library/Application Support/crabbox/config.yaml

; it must include

broker.url

broker.token

, and usually

provider: aws

从仓库根目录运行。Crabbox同步会镜像当前的检出内容。
在频繁的编辑循环中，优先使用本地定向测试。
当任务明确要求使用Blacksmith或需要与Blacksmith特定CI进行对比时，优先选择Blacksmith Testbox。
当自有AWS/Hetzner算力是合适的远程渠道时，使用Crabbox进行全面的OpenClaw关卡测试。
在添加参数前，先查看
```
.crabbox.yaml
```
中的仓库默认配置。
在进行远程操作前，先检查所选二进制文件是否正常。OpenClaw脚本优先使用
```
../crabbox/bin/crabbox
```
（如果存在）；用户PATH中的shim可能已过期：
```
command -v crabbox; ../crabbox/bin/crabbox --version; ../crabbox/bin/crabbox --help | sed -n '1,90p'
```
。

使用

brew install openclaw/tap/crabbox

进行安装；使用前需完成认证：

printf '%s' "$CRABBOX_COORDINATOR_TOKEN" | crabbox login --url https://crabbox.openclaw.ai --provider aws --token-stdin

。

在macOS上，用户配置文件路径为
```
~/Library/Application Support/crabbox/config.yaml
```
；该文件必须包含
```
broker.url
```
、
```
broker.token
```
，通常还需设置
```
provider: aws
```
。

OpenClaw Flow

OpenClaw 流程

AWS/owned-capacity flow for

pnpm

tests:

pnpm crabbox:warmup -- --idle-timeout 90m
pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m
pnpm crabbox:hydrate -- --id <cbx_id-or-slug>
pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "env 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"

Blacksmith-backed Crabbox flow can delegate setup to the Testbox workflow:

pnpm crabbox:run -- --provider blacksmith-testbox --blacksmith-org openclaw --blacksmith-workflow .github/workflows/ci-check-testbox.yml --blacksmith-job check --blacksmith-ref main --idle-timeout 90m --timing-json --shell -- "env 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"

Stop boxes you created before handoff:

pnpm crabbox:stop -- <cbx_id-or-slug>

基于AWS/自有算力的pnpm测试流程：

pnpm crabbox:warmup -- --idle-timeout 90m
pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m
pnpm crabbox:hydrate -- --id <cbx_id-or-slug>
pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "env 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"

基于Blacksmith的Crabbox流程可将配置工作委托给Testbox工作流：

pnpm crabbox:run -- --provider blacksmith-testbox --blacksmith-org openclaw --blacksmith-workflow .github/workflows/ci-check-testbox.yml --blacksmith-job check --blacksmith-ref main --idle-timeout 90m --timing-json --shell -- "env 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"

在交接前停止你创建的实例：

pnpm crabbox:stop -- <cbx_id-or-slug>

Useful Commands

实用命令

crabbox status --id <id-or-slug> --wait
crabbox inspect --id <id-or-slug> --json
crabbox sync-plan
crabbox history --lease <id-or-slug>
crabbox logs <run_id>
crabbox results <run_id>
crabbox cache stats --id <id-or-slug>
crabbox ssh --id <id-or-slug>

Use

--debug

run

when measuring sync timing. Use

--timing-json

on warmup, hydrate, and run when comparing AWS and blacksmith-testbox timings. Use

--market spot|on-demand

on AWS warmup or one-shot run when testing quota or capacity behavior without changing

.crabbox.yaml

crabbox status --id <id-or-slug> --wait
crabbox inspect --id <id-or-slug> --json
crabbox sync-plan
crabbox history --lease <id-or-slug>
crabbox logs <run_id>
crabbox results <run_id>
crabbox cache stats --id <id-or-slug>
crabbox ssh --id <id-or-slug>

在

run

命令中添加

--debug

参数以测量同步计时。在warmup、hydrate和run命令中添加

--timing-json

参数，用于对比AWS和blacksmith-testbox的计时。在AWS的warmup或一次性run命令中使用

--market spot|on-demand

参数，可在不修改

.crabbox.yaml

的情况下测试配额或算力行为。

Hydration Boundary

初始化边界

.github/workflows/crabbox-hydrate.yml

is repo-specific on purpose. It owns OpenClaw checkout, setup-node, pnpm setup, provider env hydration, ready marker, and keepalive. Crabbox owns runner registration, workflow dispatch, SSH sync, command execution, logs/results, local lease claims, and idle cleanup.

Do not add OpenClaw-specific setup to Crabbox. Put repo setup in the hydration workflow and generic lease/sync behavior in Crabbox.

.github/workflows/crabbox-hydrate.yml

是特意为仓库定制的。它负责OpenClaw检出、setup-node、pnpm配置、提供商环境初始化、就绪标记以及保活。Crabbox负责运行器注册、工作流触发、SSH同步、命令执行、日志/结果处理、本地租约声明以及空闲清理。

不要在Crabbox中添加OpenClaw特定的配置。将仓库配置放在初始化工作流中，通用的租约/同步逻辑放在Crabbox中。

Cleanup

清理工作

Crabbox has coordinator-owned idle expiry and local lease claims, so OpenClaw does not need a custom ledger. Default idle timeout is 30 minutes unless config or flags set a different value. Still stop boxes you created when done. If

crabbox list

prints

orphan=no-active-lease

, treat it as an operator review hint; do not delete

keep=true

machines without checking provider and coordinator state.

Crabbox由协调器管理空闲过期时间和本地租约声明，因此OpenClaw不需要自定义账本。默认空闲超时为30分钟，除非配置或参数设置了其他值。使用完毕后仍需停止你创建的实例。如果

crabbox list

输出

orphan=no-active-lease

，可将其视为需要运维人员检查的提示；在未确认提供商和协调器状态前，不要删除标记为

keep=true

的机器。