스킬

Crabbox: agent에게 테스트, 빌드, UI 점검을 맡길 수 있는 즉시 사용 가능한 박스 제공

agent나 본인이 테스트, 빌드, UI 점검을 필요할 때 즉시 쓸 수 있는 클라우드 박스, 로컬 VM/컨테이너 또는 기존 머신에서 실행하면서 코드 편집은 로컬에서 계속하는 데 가장 적합합니다. 첫 사용 전 가장 중요한 전제 조건은 로컬에 Docker 또는 Podman을 먼저 설치해야 하고, CLI도 별도로 설치해야 한다는 점입니다.

Official source · openclaw/crabbox

Install

npx skills add openclaw/crabbox --skill crabbox

Crabbox는 coding agent가 로컬 코드를 편집하는 동시에 테스트, 빌드 또는 UI 점검을 필요할 때 즉시 쓸 수 있는 원격 머신에 맡겨 실행하는 데 가장 적합합니다. 시작 전 가장 중요한 전제 조건은: 머신에 CLI를 설치할 수 있어야 하고, 로컬 컨테이너 퀵 패스를 사용하려면 Docker 또는 Podman을 미리 설치하고 실행 중이어야 한다는 점입니다.

누구에게 적합한가

  • agent나 본인이 클라우드 박스, 로컬 VM/컨테이너 또는 기존에 보유한 머신에서 테스트, 빌드, UI 점검을 실행하면서 코드 편집은 로컬에서 계속하고 싶은 사람에게 적합합니다.
  • Crabbox는 CLI로서 세 가지 형태의 박스를 제공합니다: 클라우드 박스, 로컬 VM 또는 컨테이너, 그리고 이미 보유한 자신의 머신.
  • 로컬 컨테이너 퀵 패스는 로컬 머신에 Docker 또는 Podman이 설치되어 실행 중이어야 합니다. SSH 워크플로를 사용하려면 로컬에 git, ssh, ssh-keygen, rsync, curl이 필요합니다. 이 전제 조건을 충족하지 못할 경우 다른 사용 가능한 방법이 있는지 공식 자료에는 설명되어 있지 않습니다.
  • 클라우드 박스에 계정이 필요한지, 과금 방식, 지원하는 클라우드 플랫폼이 무엇인지는 자료에 설명되어 있지 않으므로, 사용 전에 공식 문서에서 직접 확인해야 합니다.

3분 만에 첫 시도하기

권장되는 공식 메인 경로는 로컬 컨테이너 퀵 스타트이며, 전 과정에서 클라우드 계정이 필요하지 않습니다:

  1. 전제 조건: 로컬 머신에 Docker 또는 Podman을 설치하고 실행합니다. CLI는 별도로 설치합니다(공식 설명은 "Install the CLI separately"이며, 구체적인 설치 명령은 공식 README를 기준으로 합니다).

  2. agent 스킬 설치: 지원되는 agent에서 공식 명령을 실행합니다:

    npx skills add openclaw/crabbox --skill crabbox

    공식은 crabbox-quickstart 스킬도 배포하고 있으며, 이를 대안으로 사용할 수 있습니다.

  3. 신뢰할 수 있는 Git 저장소로 이동합니다(공식은 신뢰할 수 있는 저장소에서 작업할 것을 요구합니다).

  4. agent에게(또는 터미널에서) 공식 자가 점검 명령을 실행하게 합니다:

    crabbox doctor --provider local-container

    성공 신호: doctor가 로컬 컨테이너 환경 점검을 통과합니다.

  5. 이어서 저위험·읽기 전용인 첫 작업을 실행해 전체 체인을 검증합니다:

    crabbox run --provider local-container -- uname -a

    성공 신호: Crabbox가 일회성 컨테이너 박스를 임대하고, 명령 출력을 터미널로 스트리밍한 뒤 박스를 해제합니다. 이 예제는 uname -a만 실행하며 파일을 변경하지 않습니다.

  6. 이후의 핵심 워크플로는 crabbox run -- <cmd>입니다: 박스를 임대하고, 작업 트리(커밋되지 않은 변경 사항 포함)를 동기화하고, 명령을 실행해 출력을 터미널로 스트리밍하고, 종료 코드를 반환한 뒤 일회성 박스를 해제합니다. 주의: 동기화되는 것은 커밋되지 않은 변경 사항을 포함한 작업 트리 전체이므로, 실제 테스트 명령을 처음 실행하기 전에 박스에서 실행될 내용이 무엇인지 파악하고 있는지 확인하세요.

사용 사례

사례 1: 커밋 전에 깨끗한 박스에서 테스트 스위트 실행. 상황: 본인(또는 agent)이 코드를 수정했지만 로컬 환경을 오염시키고 싶지 않은 경우. agent에게 crabbox run -- pnpm test를 실행하게 합니다(pnpm test는 프로젝트의 테스트 명령으로 교체). 기대할 수 있는 결과: 일회성 박스가 임대되고, 커밋되지 않은 변경 사항을 포함한 작업 트리가 동기화되며, 테스트 출력이 실시간으로 터미널에 스트리밍되고, 종료 후 실제 종료 코드를 받고, 박스가 해제됩니다.

사례 2: 컨테이너 박스 환경 검증. 상황: 처음 설정하거나 환경에 문제가 있다고 의심되는 경우. agent에게 먼저 crabbox doctor --provider local-container로 진단하게 하고, 이어서 crabbox run --provider local-container -- uname -a를 실행해 박스가 명령을 실행할 수 있는지 확인합니다. 기대할 수 있는 결과: doctor가 로컬 컨테이너 환경이 준비되었는지 보고하고, run이 박스의 시스템 정보를 반환해 임대—동기화—실행—회수의 전체 체인이 작동함을 증명합니다. 이 두 작업은 점검과 시스템 정보 읽기만 수행하는, 전형적인 저위험 첫 사용 행동입니다.

사용 경계

  • 부작용과 확인 지점: crabbox run을 실행할 때마다 박스가 임대되고 작업 트리(커밋되지 않은 변경 사항 포함)가 해당 박스에 동기화된 뒤, 지정한 명령이 그 안에서 실행됩니다. 명령은 박스에서 실제로 실행되므로, 실행 전에 명령 내용을 확인하세요. 로컬 컨테이너 경로는 또한 여러분의 머신에서 컨테이너를 시작합니다. 클라우드 박스와 관련된 외부 서비스 경계는 자료에 설명되어 있지 않습니다.
  • 실행 환경 전제 조건: 로컬 컨테이너 퀵 패스에는 Docker 또는 Podman이 필요하고, SSH 워크플로에는 로컬에 git, ssh, ssh-keygen, rsync, curl이 필요합니다.
  • 클라이언트 전제 조건: 스킬은 npx skills add로 설치되며, agent skills를 지원하는 agent에 적용됩니다. 구체적으로 어떤 클라이언트가 지원되는지는 자료에 개별적으로 명시되어 있지 않습니다.
  • 아직 확인되지 않은 핵심 정보: 클라우드 박스의 개설 및 계정 요구 사항, crabbox doctor 또는 run이 네트워크에 접근하는지 또는 어떤 로컬 파일을 읽고 쓰는지, 그리고 문서에 표시된 명령 외에 어떤 하위 명령이 있는지는 공식 자료에 모두 설명되어 있지 않으므로, 사용 전에 공식 README를 확인하세요.