Crabbox：让 Coding Agent 在远端盒子里跑命令

项目地址

GitHub：openclaw/crabbox

• 官网：crabbox.sh，文档站与仓库 docs/ 同源（docs/.i18n 下有 zh-CN 等译本）
• 作者：Peter Steinberger（steipete，OpenClaw 作者）与 OpenClaw 团队

项目介绍

一句话定位

一条 crabbox run -- pnpm test 完成：租机 → 同步工作区（含未提交改动和未跟踪文件）→ 远端执行 → 流式回传输出与退出码 → 释放。对 Agent 来说语义和本地跑命令一样（stdout / stderr + exit code），机器在哪、怎么开、怎么删由 Crabbox 负责。

为什么需要它

• 并发 Agent 抢本机：几个 Codex / Claude Code 同时跑测试、构建、e2e，CPU、内存、端口、Docker 互相踩。git worktree 只隔离代码，不隔离运行时；Crabbox 把「运行」整体挪到远端，每个 Agent 一台盒子
• 跨 OS 真机验证：同一份工作区在 Linux / macOS / 原生 Windows / WSL2 上跑，不用为每个系统维护一套 CI
• 可视化 QA：desktop + WebVNC + code-server，Agent 用 computer use 操作远端桌面。steipete 的实际用法是让 Codex 当 QA，在 Crabbox 桌面里测 OpenClaw；Crabbox 本身也是 Codex 在 Crabbox 里构建的
• 团队治理：云凭据、预算上限、过期回收集中到可选的 Coordinator，不散落在每个开发者和 Agent 手里

能做什么

• 一次性 run：crabbox run，用完即删
• 热盒复用：warmup --slug 起盒保留，run --id 每轮只同步 diff 再执行，connect 进 SSH，stop 释放
• 证据：阶段事件、日志分块、JUnit 解析、--require-artifact 产物门禁、失败 bundle、--attest 签名回执 + crabbox verify
• 并行与复用：shard 分片、checkpoint fork、ready pool 预热池
• 交互：远端桌面、WebVNC、code-server、portal
• 衔接 CI：Actions hydration 复现 CI 工作区；capsule 把失败的 Actions run 变成可重复的调试用例

边界：它明确不做什么

VISION.md 列出的非目标：

• 被 Agent 使用，而不是编排 Agent：不托管 agent runtime、模型凭据、prompt、记忆
• 不做 workflow 引擎、Agent 框架、插件市场
• 不提供 MCP：入口就是 CLI + 生成的 Skill

技术架构

分层

架构图：控制面（蓝虚线）只发租约；数据面（绿实线）由 CLI 经 SSH + rsync 直连 runner；委托沙箱不走 SSH 数据面，同步和执行由平台自己负责。

Mermaid 源码

flowchart LR
  subgraph CALL["调用方"]
    A1["Coding Agent<br/>Codex / Claude Code"]
    A2["Harness / 脚本"]
    A3["开发者 / CI"]
  end
  CLI["crabbox CLI（Go，本地）<br/>配置合并 · 租约 SSH key · provider 路由<br/>同步引擎 · 执行回传 · 心跳 · 证据"]
  subgraph CO["Coordinator（可选，TypeScript）"]
    C1["CF Worker + Durable Object<br/>或 Node + PostgreSQL + pg-boss"]
    C2["托管凭据 · 串行化 fleet 变更 · spend cap<br/>过期回收 · run 记录 · WebVNC / code bridge"]
  end
  subgraph PV["Provider adapters：81 内置 + external"]
    P1["SSH lease<br/>aws · azure · gcp · hetzner · tart · ssh"]
    P2["Delegated run<br/>e2b · modal · cloudflare · vercel-sandbox"]
    P3["Service control<br/>railway · fastapi-cloud · unikraft-cloud"]
  end
  R["Runners<br/>Linux · macOS · Windows · WSL2<br/>/work/crabbox/{lease}/{repo}"]
  CALL --> CLI
  CLI -.->|"控制面：HTTPS + /v1/control WS"| CO
  CO -.->|"provision / release"| PV
  CLI -.->|"direct：本地凭据"| PV
  PV -->|"创建 / 删除 / 快照"| R
  CLI ==>|"数据面：SSH + rsync"| R

一次 run 发生了什么

1. 规划：配置按 flags > env > 仓库 .crabbox.yaml > 用户配置 > 默认值合并；按 ProviderSpec 声明的 Kind / Features 选路，无法兑现的参数直接拒绝
2. 租约：brokered 模式向 Coordinator 申请（凭据在服务端、预算 admission、fleet 变更串行化）；direct 模式用本地凭据直接创建。每个租约生成独立的 ed25519 key；runner bootstrap 只装 SSH、Git、rsync、curl、jq，完成后写 crabbox-ready
3. 同步：取 workspace owner 锁 → 生成清单和指纹 → 无变化就跳过，否则 Git seed + delta rsync，空盒走流式 tar
4. 执行：经 SSH 执行，stdout / stderr 实时回流，返回远端退出码；执行期心跳按需续期；产出阶段事件、日志分块、JUnit 和产物
5. 释放：一次性租约随 run 删除；--keep 的交给空闲时钟；兜底 cleanup 只删能证明归属的资源

委托沙箱（e2b、modal 等）的第 3、4 步交给平台：backend 实现 Warmup / Run / List / Status / Stop，负责预热、执行、流式输出和停止，声明 FeatureArchiveSync 的可以上传 checkout 归档；core 仍负责 provider 选择、配置、本地 claim、slug、计时和 list / status 渲染。

机制演示（可交互）

六个值得记住的设计决定

1. 控制面与数据面分离

Coordinator 只处理租约、凭据、预算、回收和 run 记录；同步与执行始终是 CLI → runner 直连（SSH 默认 2222 端口，回落 22），runner 不回调 Coordinator。所以 Coordinator 可以是单副本的 Cloudflare Worker + Durable Object，不扛任何大流量；它不在数据路径上，短暂不可用也不会打断已建立的同步和执行。两套实现（CF Worker + DO / Node + PostgreSQL + pg-boss）状态不互通，选定后不要来回切。

2. Providers configure backends. Core commands own workflows.

provider 只声明能力，run / warmup / sync / list / stop 这些工作流只在 core 实现一份。81 个 provider 被压成三种 ProviderSpec Kind：

• external provider：子进程 + JSON over stdio，不 fork 仓库就能接私有云或内部平台
• 部署模式与形态正交：brokered（经 Coordinator）/ direct（本地凭据）/ registered（direct 创建，但把元数据登记到 Coordinator，换来 portal、WebVNC 和库存可见性）/ static SSH（provider: ssh）
• 国内云：内置只有 tencentcloud 和 sealos-devbox，其他都要走 external 或 static SSH
• 账单盲区：direct 与 delegated 的花费不经过 Coordinator，crabbox usage 统计不到

3. 同步引擎：清单 + 指纹 + Git seed + delta

• 清单：git ls-files --cached --others --exclude-standard -z，天然包含未提交改动和未跟踪文件，尊重 .gitignore；同时生成删除列表
• 指纹：清单指纹一致就直接跳过（“No changes detected, skipping sync”），Agent 反复 run 时同步几乎零成本
• Git seed：远端先从 origin 取到本地 HEAD，再只传本地 delta 和远端被改动的跟踪文件；seed 验证不过就回退到完整清单 rsync（--files-from=- --from0）
• 冷启动：新的空 POSIX 工作区且不用 Git seed 时，走单条 SSH 通道的流式 tar（gzip fast，不落地）
• Windows：同一份清单打 tar，经 OpenSSH 上传后解包，不走 rsync
• 护栏：workspace owner 锁、large-sync 预检（warnFiles / failFiles）、prune 只删同步过的文件、大规模删除守卫（需要 CRABBOX_ALLOW_MASS_DELETIONS=1 才放行）；sync.timeout 15m 是 I/O 不活跃时长，不是总时长

4. 租约是成本与清理的最小单位

expiresAt = min(createdAt + min(ttl, maxTTL), lastTouchedAt + idleTimeout)，默认 TTL 30m、idle 30m，direct provider 的 maxTTL 默认 4h（上限 24h），brokered 请求由 Coordinator 钳制。

• 心跳不等于续期：心跳走 /v1/control WebSocket，失败回落 HTTPS；到期后的心跳一律被拒
• 只在真实工作时续期：只有用户命令执行期间，剩余不足 10 分钟时才 +30 分钟，直到 maxTTL（需策略与 provider 能力允许）；setup、sync-only、SSH、desktop 都不续期
• 预算先占：admission 时按「最坏寿命 × 单价」预留，超限返回 429 cost_limit_exceeded；续期同样过预算，预留按新 TTL 原子替换、只补差额；显式 extend 超预算返回 403，心跳触发的续期超预算则跳过并带回 policyNotice
• 价格源：CRABBOX_COST_RATES_JSON > 实时价格 > 内置兜底 > 通用兜底

5. 生命周期 fail-closed

删除前必须有所有权证明：provider、资源、claim 三者一致。名字、标签、ID 都不算证据，任何一环校验失败就不删。付费 provider 合并进主干前，要提交 create → use → destroy 零残留的实测证明。

6. 证据是一等公民

每次 run 产出结构化阶段事件、日志分块、JUnit 结果、产物门禁（--require-artifact）和失败 bundle（stdout / stderr、计时、脱敏后的 env / config）。失败时给出 blockedStage / retryLikely，Agent 据此判断该重试还是该改代码；--attest 生成签名回执，crabbox verify 在本地校验。

进阶原语速查

文档

仓库 docs/ 共 292 篇，和 crabbox.sh 同源。按价值排序：

文档有漂移：architecture.md 表格里的 TTL 默认值（5400s / 86400s）和 lifecycle-cleanup.md（1800s / 14400s）不一致，以后者和 crabbox --help 为准。

Quick Start

最快路径：本机容器，零凭据

brew install openclaw/tap/crabbox
crabbox --version && crabbox doctor

# 在一个可信仓库里，用本机 Docker / Podman 跑通完整链路
crabbox run --provider local-container -- pnpm test

上云：一次性 run

crabbox providers recommend     # 按场景比较 provider
crabbox init --detect           # 识别项目，生成 .crabbox.yaml
crabbox run --provider hetzner --class small -- pnpm test

热盒复用：Agent 多轮迭代

crabbox warmup --provider hetzner --slug fix-auth   # 起盒并保留
crabbox run --id fix-auth -- pnpm test:changed      # 每轮只同步 diff
crabbox run --id fix-auth --sync-only               # 只同步不执行
crabbox connect fix-auth                            # 进 SSH 排查
crabbox extend fix-auth --by 30m                    # 手动续期
crabbox stop fix-auth                               # 释放

仓库配置

# .crabbox.yaml（仓库根目录；优先级 flags > env > 仓库 > 用户 > 默认）
provider: hetzner
target: linux
class: small          # 默认是 beast，先调小
lease:
  ttl: 30m
  idleTimeout: 30m
sync:
  gitSeed: true
  exclude:
    - node_modules
    - .turbo
env:
  allow:
    - CI
    - NODE_OPTIONS
    - PROJECT_*

团队与 Agent 接入

crabbox login --url https://broker.example.com   # 之后租约由 Coordinator 托管凭据与预算
crabbox usage                                    # 花费统计（direct / delegated 不计入）

# 给 Codex / Claude Code 装 Skill
npx skills add https://github.com/openclaw/crabbox --skill crabbox
npx skills add https://github.com/openclaw/crabbox --skill crabbox-quickstart

失败时怎么办

踩坑清单

• 只对可信仓库用：远端会执行仓库里的 setup 和命令
• 环境变量默认只转发 CI、NODE_OPTIONS，其他要写进 env.allow（支持尾部通配）
• 默认 class 是 beast（大机型），试用先用 --class tiny / small
• --provider 不是全局 flag，要写在子命令后面
• go install 只装 CLI，缺 crabbox-runtime pack；用 brew 或 Release 归档，runtime 目录要和 CLI 放在一起
• Hostinger：crabbox stop 只停 VPS，不退订阅，账单继续；machine0：保留的算力和快照持续计费；boxd：用 org 隔离的 key 时要配 CRABBOX_BOXD_ORG，否则 list / cleanup 会拒绝处理 org 计费的机器；Morph：要先备好含 bash / git / rsync / tar 的快照
• warmup 默认保留盒子；direct provider 如果没有自动空闲回收，要设 warmup.keep: false 并定期跑 crabbox cleanup（cleanup 会跳过 kept 的盒子），或显式 stop
• 文档滞后时，以 crabbox --help 和 crabbox providers --json 为准

生态位

Crabbox 在栈里的位置：编排层之下、沙箱平台之上的执行适配层。

典型用法

1. 多 Agent 并发跑测试：每个 Agent 一台热盒，run --id 每轮只同步 diff，本机只负责编辑
2. 跨 OS 验证：同一工作区切 --target linux / macos / windows，或 Windows 的 WSL2 模式
3. 可视化 QA：Codex 通过 WebVNC + computer use 在远端桌面上测 OpenClaw（steipete 的日常用法）
4. 自举：Codex 在 Crabbox 盒子里构建 Crabbox 自己
5. CI 红了交给 Agent：capsule 把失败的 Actions run 变成可复现用例，Agent 在同样环境里修

对我做 Agent 项目的启示

值得直接抄的

1. 控制面只发租约，数据不过控制面。 调度服务只管「谁、在哪、多久、花多少」，素材上传和产物下载由 worker 直连对象存储。对 Hyperframes 云渲染、视频生成这类大流量任务，这是调度服务能做成单副本、近乎无状态的前提。
2. 租约 = 成本单位 + 清理单位。 每个 GPU / 渲染任务带 TTL、idle、maxTTL，admission 时按「最坏寿命 × 单价」预留预算，续期只补差额，超限直接拒绝。比事后对账可靠。
3. 心跳不等于续期。 只有真实命令执行期才续，SSH 挂着、桌面开着都不续，直接掐掉「Agent 忘了关机」的长尾账单。
4. 所有权证明 + fail-closed 回收。 后台回收孤儿资源时，只删 provider、资源、claim 三方一致的；名字、标签、ID 都不算证据，校验失败宁可不删。
5. 清单指纹 + delta 同步。 Agent 多轮修改工程目录或产物时，先比指纹再决定是否同步，只传 diff；再加大规模删除守卫，防止 Agent 一次误删整个目录。
6. 阶段事件 + 可重试判定。 每个 run 按 sync / setup / command 等阶段打事件，带 blockedStage / retryLikely，直接映射成 Langfuse 的 span 和 tag，让上层 Agent 自动决定重试还是改代码。
7. CLI + --json + Skill，不做 MCP。 对能跑 shell 的 coding agent，CLI 是最便宜的接口：零常驻进程、天然可组合，Skill 负责教模型怎么用。

现在就能用的方式

• 先用 --provider local-container 在本机零凭据跑通链路，确认仓库能同步、能执行
• 字节内部 devbox 或自有机器：provider: ssh（static SSH，不创建不删除），把现成机器直接纳入 crabbox run
• 火山引擎：没有内置 provider，用 external（JSON over stdio）写适配器，先只实现 SSH lease 形态最省事
• 给 Codex / Claude Code 装 crabbox Skill，让 Agent 自己决定什么时候把测试挪到远端

不建议照搬的

参考资料

• GitHub：openclaw/crabbox
• crabbox.sh 文档站
• VISION.md：定位与非目标
• steipete 在 X 上关于 Crabbox 的帖子（1）
• steipete 在 X 上关于 Crabbox 的帖子（2）
• steipete 在 X 上关于 Crabbox 的帖子（3）
• AI Builder Club：Crabbox parallel agent sandboxes