CLI

CLI 패키지: clawhub, bin: clawhub.

npm 또는 pnpm으로 전역 설치합니다.

npm i -g clawhub# orpnpm add -g clawhub

그런 다음 확인합니다.

clawhub --helpclawhub loginclawhub whoami

전역 플래그

• --workdir <dir>: 작업 디렉터리(기본값: cwd; 구성된 경우 Clawdbot 워크스페이스로 폴백)
• --dir <dir>: workdir 아래의 설치 디렉터리(기본값: skills)
• --site <url>: 브라우저 로그인을 위한 기본 URL(기본값: https://clawhub.ai)
• --registry <url>: API 기본 URL(기본값: 검색된 값, 없으면 https://clawhub.ai)
• --no-input: 프롬프트 비활성화

동등한 Env:

• CLAWHUB_SITE(레거시 CLAWDHUB_SITE)
• CLAWHUB_REGISTRY(레거시 CLAWDHUB_REGISTRY)
• CLAWHUB_WORKDIR(레거시 CLAWDHUB_WORKDIR)

HTTP 프록시

CLI는 회사 프록시나 제한된 네트워크 뒤에 있는 시스템을 위해 표준 HTTP 프록시 환경 변수를 따릅니다.

• HTTPS_PROXY / https_proxy
• HTTP_PROXY / http_proxy
• NO_PROXY / no_proxy

이 변수 중 하나라도 설정되어 있으면 CLI는 지정된 프록시를 통해 아웃바운드 요청을 라우팅합니다. HTTPS 요청에는 HTTPS_PROXY가 사용되고, 일반 HTTP에는 HTTP_PROXY가 사용됩니다. 특정 호스트나 도메인에 대해 프록시를 우회하도록 NO_PROXY / no_proxy가 적용됩니다.

직접 아웃바운드 연결이 차단된 시스템(예: Docker 컨테이너, 프록시 전용 인터넷이 있는 Hetzner VPS, 회사 방화벽)에서는 이것이 필요합니다.

예:

export HTTPS_PROXY=http://proxy.example.com:3128export NO_PROXY=localhost,127.0.0.1clawhub search "my query"

프록시 변수가 설정되어 있지 않으면 동작은 변경되지 않습니다(직접 연결).

구성 파일

API 토큰과 캐시된 레지스트리 URL을 저장합니다.

• macOS: ~/Library/Application Support/clawhub/config.json
• Linux/XDG: $XDG_CONFIG_HOME/clawhub/config.json 또는 ~/.config/clawhub/config.json
• Windows: %APPDATA%\\clawhub\\config.json
• 레거시 폴백: clawhub/config.json이 아직 없지만 clawdhub/config.json이 있으면 CLI가 레거시 경로를 재사용합니다
• 재정의: CLAWHUB_CONFIG_PATH(레거시 CLAWDHUB_CONFIG_PATH)

명령

login / auth login

• 기본값: 브라우저를 <site>/cli/auth로 열고 loopback 콜백을 통해 완료합니다.
• 헤드리스: clawhub login --token clh_...
• 원격/헤드리스 대화형: clawhub login --device는 코드를 출력하고 사용자가 <site>/cli/device에서 승인하는 동안 기다립니다.

whoami

• /api/v1/whoami를 통해 저장된 토큰을 확인합니다.

token

• 저장된 API 토큰을 stdout에 출력합니다.
• 로컬 로그인 토큰을 CI 시크릿 설정 명령으로 파이핑할 때 유용합니다.

star <skill> / unstar <skill>

• 하이라이트에 skill을 추가하거나 제거합니다.
• POST /api/v1/stars/<slug> 및 DELETE /api/v1/stars/<slug>를 호출합니다.
• --yes는 확인을 건너뜁니다.

search <query...>

• /api/v1/search?q=...를 호출합니다.
• 출력에는 skill slug, 소유자 handle, 표시 이름, 관련성 점수가 포함됩니다.
• 검색은 다운로드 인기도보다 정확한 slug/이름 토큰 일치를 우선합니다. map 같은 독립 slug 토큰은 amap 내부의 부분 문자열보다 personal-map과 더 강하게 일치합니다.
• 인기도는 작은 순위 사전값일 뿐이며, 최상위 배치를 보장하지 않습니다.
• skill이 표시되어야 하는데 표시되지 않으면, 메타데이터 이름을 바꾸기 전에 로그인한 상태에서 clawhub inspect @owner/slug를 실행해 소유자에게 표시되는 모더레이션 진단을 확인하세요.

explore

• /api/v1/skills?limit=...&sort=createdAt를 통해 최신 skills를 나열합니다(createdAt 내림차순 정렬).
• 플래그:
  • --limit <n>(1-200, 기본값: 25)
  • --sort newest|updated|rating|downloads|trending(기본값: newest). 레거시 설치 정렬 별칭도 호환성을 위해 계속 동작합니다.
  • --json(기계가 읽을 수 있는 출력)
• 출력: <slug> v<version> <age> <summary>(summary는 50자로 잘림).

inspect @owner/slug

• 설치하지 않고 skill 메타데이터와 버전 파일을 가져옵니다.
• --version <version>: 특정 버전을 검사합니다(기본값: latest).
• --tag <tag>: 태그된 버전을 검사합니다(예: latest).
• --versions: 버전 기록을 나열합니다(첫 페이지).
• --limit <n>: 나열할 최대 버전 수(1-200).
• --files: 선택한 버전의 파일을 나열합니다.
• --file <path>: 원시 파일 내용을 가져옵니다(텍스트 파일만, 200KB 제한).
• --json: 기계가 읽을 수 있는 출력.

install @owner/slug

• 지정된 소유자와 skill의 최신 버전을 해석합니다.
• /api/v1/download를 통해 zip을 다운로드합니다.
• <workdir>/<dir>/<slug>에 추출합니다.
• 고정된 skills 덮어쓰기를 거부합니다. 먼저 clawhub unpin <skill>을 실행하세요.
• 다음을 작성합니다.
  • <workdir>/.clawhub/lock.json(레거시 .clawdhub)
  • <skill>/.clawhub/origin.json(레거시 .clawdhub)

uninstall <skill>

• <workdir>/<dir>/<slug>를 제거하고 lockfile 항목을 삭제합니다.
• 로그인한 상태에서는 현재 설치 수를 비활성화할 수 있도록 최선의 telemetry를 보냅니다.
• 대화형: 확인을 요청합니다.
• 비대화형(--no-input): --yes가 필요합니다.

list

• <workdir>/.clawhub/lock.json(레거시 .clawdhub)을 읽습니다.
• 선택적 이유를 포함해 clawhub pin으로 동결된 skills 옆에 pinned를 표시합니다.

pin <skill>

• 설치된 skill을 lockfile에서 고정된 상태로 표시합니다.
• --reason <text>는 skill이 동결된 이유를 기록합니다.
• 고정된 skills는 update --all에서 건너뛰며 직접 update <skill>에서도 거부됩니다.
• 고정된 skills는 로컬 바이트가 실수로 교체되지 않도록 install --force도 거부합니다.

unpin <skill>

• 설치된 skill에서 lockfile pin을 제거해 향후 업데이트가 수정할 수 있게 합니다.

update [@owner/slug] / update --all

• 로컬 파일에서 fingerprint를 계산합니다.
• fingerprint가 알려진 버전과 일치하면 프롬프트가 없습니다.
• fingerprint가 일치하지 않으면:
  • 기본적으로 거부합니다
  • --force로 덮어씁니다(또는 대화형이면 프롬프트)
• 고정된 skills는 --force로도 절대 업데이트되지 않습니다.
• update <skill>은 고정된 skills에 대해 빠르게 실패하고 먼저 clawhub unpin <skill>을 실행하라고 안내합니다.
• update --all은 고정된 slugs를 건너뛰고 동결 상태로 남은 항목의 요약을 출력합니다.

skill publish <path>

• 로컬 번들 fingerprint를 ClawHub와 비교하고 콘텐츠가 이미 게시된 경우 성공적으로 종료합니다.
• 새 skills의 기본값은 1.0.0입니다. 변경된 skills는 기본적으로 다음 patch 버전이 됩니다.
• --version <version>은 버전을 명시적으로 선택하며 콘텐츠가 기존 버전과 일치하더라도 게시합니다.
• --dry-run은 업로드 없이 게시를 해석합니다. --json은 기계가 읽을 수 있는 결과를 출력합니다.
• --owner <handle>은 actor가 게시자 접근 권한을 가진 경우 org/user 게시자 handle 아래에 게시합니다.
• --migrate-owner는 새 버전을 게시하면서 기존 skill을 --owner로 이동합니다. 두 게시자 모두에 대한 admin/owner 접근 권한이 필요합니다.
• 소유자 및 리뷰 동작은 docs/publishing.md에 설명되어 있습니다.
• skill을 게시한다는 것은 ClawHub에서 MIT-0 하에 릴리스된다는 뜻입니다.
• 게시된 skills는 저작자 표시 없이 자유롭게 사용, 수정, 재배포할 수 있습니다.
• ClawHub는 유료 skills 또는 skill별 가격 책정을 지원하지 않습니다.
• 레거시 별칭: publish <path>.

clawhub skill publish ./my-skill --dry-runclawhub skill publish ./my-skillclawhub skill publish ./my-skill --version 2.0.0

GitHub Actions

ClawHub의 재사용 가능한 skill-publish.yml 워크플로는 하나의 skill_path에 대해, 또는 root(기본값: skills) 바로 아래의 각 skill 폴더에 대해 skill publish를 호출합니다. 변경되지 않은 skills는 건너뛰며 동일한 자동 patch 버전 동작을 사용합니다.

토큰 없이 미리 보려면 dry_run: true를 설정합니다. 실제 게시에는 clawhub_token 시크릿이 필요합니다.

sync

• 현재 workdir, 구성된 skills 디렉터리, 그리고 SKILL.md 또는 skill.md를 포함하는 로컬 skill 폴더를 찾기 위한 모든 --root <dir> 폴더를 스캔합니다.
• 각 로컬 skill fingerprint를 ClawHub와 비교하고 새 skill 또는 변경된 skill만 게시합니다.
• 새 skills는 1.0.0으로 게시됩니다. 변경된 skills는 기본적으로 다음 patch 버전을 게시합니다. 더 큰 semver 단계로 이동해야 하는 업데이트 배치에는 --bump minor|major를 사용하세요.
• --dry-run은 업로드 없이 게시 계획을 보여줍니다. --json은 기계가 읽을 수 있는 계획을 출력합니다.
• --all은 모든 새 skill 또는 변경된 skill을 프롬프트 없이 게시합니다. --all이 없으면 대화형 터미널에서 게시할 skills를 선택할 수 있습니다.
• --owner <handle>은 actor가 게시자 접근 권한을 가진 경우 org/user 게시자 handle 아래에 게시합니다.
• sync는 단방향 게시 전용입니다. 설치, 업데이트, 다운로드, 설치/다운로드 telemetry 보고를 수행하지 않습니다.

clawhub sync --all --dry-runclawhub sync --allclawhub sync --root ./skills --owner openclaw --bump minor

scan --slug <slug>

• clawhub login이 필요합니다.
• POST /api/v1/skills/-/scan을 통해 ClawHub ClawScan을 실행한 다음 scan이 terminal 상태가 될 때까지 폴링합니다.
• scans는 비동기이며 완료까지 시간이 걸릴 수 있습니다. 대기열에 있는 동안 terminal spinner는 현재 우선순위 scan 위치와 앞에 있는 scans 수를 표시합니다.
• 게시된 scans에는 소유권 또는 게시자 관리 접근 권한이 필요합니다. moderators/admins는 clawhub-admin을 통해 동일한 backend를 사용할 수 있습니다.
• --update는 --slug와 함께 사용할 때만 유효합니다. 성공한 게시 scan 결과를 선택한 버전에 다시 기록합니다.
• --output <file.zip>은 manifest.json, clawscan.json, skillspector.json, static-analysis.json, virustotal.json, README.md가 포함된 전체 report archive를 다운로드합니다.
• --json은 automation을 위해 전체 poll response를 출력합니다.
• 로컬 경로 scans는 더 이상 지원되지 않습니다. 새 버전을 업로드한 다음 scan download를 사용해 해당 제출 버전에 저장된 scan 결과를 가져오세요.

clawhub scan --slug gifgrepclawhub scan --slug gifgrep --version 1.2.3clawhub scan --slug gifgrep --update --output report.zip

scan download <name>

• clawhub login이 필요합니다.
• ClawHub 보안 검사에 의해 차단되거나 숨겨진 버전을 포함해 제출된 skill 또는 Plugin 버전에 대해 저장된 scan report ZIP을 다운로드합니다.
• Skill 다운로드는 skill slug를 사용하며 기본값은 --kind skill입니다.
• Plugin 다운로드는 패키지 이름을 사용하며 --kind plugin이 필요합니다.
• 작성자가 ClawHub가 차단한 정확한 제출 버전을 검사할 수 있도록 --version이 필요합니다.
• --output <file.zip>은 대상 경로를 선택합니다.

clawhub scan download gifgrep --version 1.2.3clawhub scan download @scope/demo --version 2.0.0 --kind plugin --output report.zip

GitHub Actions

ClawHub는 skill repos 및 catalog repos를 위한 공식 재사용 가능 워크플로를 다음 위치에 제공합니다. /.github/workflows/skill-publish.yml

일반적인 catalog 설정:

name: Skill Publish on:  pull_request:  workflow_dispatch: jobs:  dry-run:    if: github.event_name == 'pull_request'    uses: openclaw/clawhub/.github/workflows/skill-publish.yml@v1    with:      owner: nvidia      dry_run: true   publish:    if: github.event_name == 'workflow_dispatch'    uses: openclaw/clawhub/.github/workflows/skill-publish.yml@v1    with:      owner: nvidia      dry_run: false    secrets:      clawhub_token: ${{ secrets.CLAWHUB_TOKEN }}

참고:

• catalog repos의 root 기본값은 skills입니다.
• 하나의 skill 폴더를 처리하려면 skill_path: skills/review-helper를 전달하세요.
• owner는 CLI --owner 플래그에 매핑됩니다. 인증된 사용자로 게시하려면 생략하세요.
• V1 skill publishing은 clawhub_token을 사용합니다. GitHub OIDC trusted publishing은 현재 package 전용입니다.

delete <skill>

• --version이 없으면 스킬을 소프트 삭제합니다(소유자, 모더레이터 또는 관리자).
• DELETE /api/v1/skills/{slug}를 호출합니다.
• 소유자가 시작한 소프트 삭제는 30일 동안 slug를 예약하며, 명령은 만료 시간을 출력합니다.
• --version <version>은 fail-closed 방식의 버전별 라우트를 통해 소유한 최신이 아닌 버전 하나를 영구 삭제합니다. 삭제된 버전은 복원하거나 다시 게시할 수 없습니다. 현재 최신 버전을 삭제하기 전에 대체 버전을 게시하세요. 플랫폼 스태프는 이 버전 전용 흐름에서 소유권을 우회하지 않습니다.
• --reason <text>는 전체 스킬 소프트 삭제와 감사 로그에 모더레이션 메모를 기록합니다.
• --note <text>는 --reason의 별칭입니다.
• --yes는 확인을 건너뜁니다.

undelete <skill>

• 숨겨진 스킬을 복원합니다(소유자, 모더레이터 또는 관리자).
• 버전 undelete는 없습니다. 영구 삭제된 버전은 복원할 수 없습니다.
• POST /api/v1/skills/{slug}/undelete를 호출합니다.
• --reason <text>는 스킬과 감사 로그에 모더레이션 메모를 기록합니다.
• --note <text>는 --reason의 별칭입니다.
• --yes는 확인을 건너뜁니다.

hide <skill>

• 스킬을 숨깁니다(소유자, 모더레이터 또는 관리자).
• delete의 별칭입니다.

unhide <skill>

• 스킬 숨김을 해제합니다(소유자, 모더레이터 또는 관리자).
• undelete의 별칭입니다.

skill rename <skill> <new-name>

• 소유한 스킬의 이름을 변경하고 이전 slug를 리디렉션 별칭으로 유지합니다.
• POST /api/v1/skills/{slug}/rename을 호출합니다.
• --yes는 확인을 건너뜁니다.

skill merge <source> <target>

• 소유한 스킬 하나를 다른 소유한 스킬로 병합합니다.
• 소스 slug는 공개 목록 표시를 중지하고 대상에 대한 리디렉션 별칭이 됩니다.
• POST /api/v1/skills/{sourceSlug}/merge를 호출합니다.
• --yes는 확인을 건너뜁니다.

transfer

• 소유권 이전 워크플로.
• 사용자 핸들로 이전하면 수신자가 수락하는 대기 중 요청이 생성됩니다.
• org/publisher 핸들로 이전하는 경우 행위자가 현재 소유자와 대상 publisher 모두에 대한 관리자 접근 권한을 가진 경우에만 즉시 적용됩니다.
• 하위 명령:
  • transfer request <skill> <handle> [--message "..."] [--yes]
  • transfer list [--outgoing]
  • transfer accept <skill> [--yes]
  • transfer reject <skill> [--yes]
  • transfer cancel <skill> [--yes]
• 엔드포인트:
  • POST /api/v1/skills/{slug}/transfer
  • POST /api/v1/skills/{slug}/transfer/accept
  • POST /api/v1/skills/{slug}/transfer/reject
  • POST /api/v1/skills/{slug}/transfer/cancel
  • GET /api/v1/transfers/incoming
  • GET /api/v1/transfers/outgoing

package explore [query...]

• GET /api/v1/packages 및 GET /api/v1/packages/search를 통해 통합 패키지 카탈로그를 탐색하거나 검색합니다.
• Plugin 및 다른 패키지 계열 항목에는 이것을 사용하세요. 최상위 search는 계속 스킬 검색 표면입니다.
• 플래그:
  • --family skill|code-plugin|bundle-plugin
  • --official
  • --executes-code
  • --target <target>, --os <os>, --arch <arch>, --libc <libc>
  • --requires-browser, --requires-desktop, --requires-native-deps
  • --requires-external-service, --external-service <name>
  • --binary <name>, --os-permission <name>
  • --artifact-kind legacy-zip|npm-pack
  • --npm-mirror
  • --limit <n>(1-100, 기본값: 25)
  • --json

예:

clawhub package explore --family code-pluginclawhub package explore --family code-plugin --os darwin --requires-desktopclawhub package explore --family code-plugin --artifact-kind npm-packclawhub package explore --npm-mirrorclawhub package explore episodic-claw --family code-plugin

package inspect <name>

• 설치하지 않고 패키지 메타데이터를 가져옵니다.
• Plugin 메타데이터, 호환성, 검증, 소스, 버전/파일 검사에 이것을 사용하세요.
• --version <version>: 특정 버전을 검사합니다(기본값: latest).
• --tag <tag>: 태그된 버전을 검사합니다(예: latest).
• --versions: 버전 기록을 나열합니다(첫 페이지).
• --limit <n>: 나열할 최대 버전 수(1-100).
• --files: 선택한 버전의 파일을 나열합니다.
• --file <path>: 원시 파일 콘텐츠를 가져옵니다(텍스트 파일만, 200KB 제한).
• --json: 기계가 읽을 수 있는 출력.

package download <name>

• GET /api/v1/packages/{name}/versions/{version}/artifact를 통해 패키지 버전을 확인합니다.
• resolver의 downloadUrl에서 아티팩트를 다운로드합니다.
• 모든 아티팩트에 대해 ClawHub SHA-256을 검증합니다.
• ClawPack npm-pack 아티팩트의 경우 npm sha512 무결성, npm shasum, tarball의 package.json 이름/버전도 검증합니다.
• 레거시 ZIP 버전은 레거시 ZIP 라우트를 통해 다운로드합니다.
• 플래그:
  • --version <version>: 특정 버전을 다운로드합니다.
  • --tag <tag>: 태그된 버전을 다운로드합니다(기본값: latest).
  • -o, --output <path>: 출력 파일 또는 디렉터리.
  • --force: 기존 출력 파일을 덮어씁니다.
  • --json: 기계가 읽을 수 있는 출력.

예:

clawhub package download @openclaw/example-plugin --tag latestclawhub package download @openclaw/example-plugin --version 1.2.3 -o artifacts/

package verify <file>

• 로컬 아티팩트에 대해 ClawHub SHA-256, npm sha512 무결성, npm shasum을 계산합니다.
• --package와 함께 사용하면 ClawHub에서 예상 메타데이터를 확인하고 로컬 파일을 게시된 아티팩트 메타데이터와 비교합니다.
• 직접 digest 플래그를 사용하면 네트워크 조회 없이 검증합니다.
• 플래그:
  • --package <name>: 예상 아티팩트 메타데이터를 확인할 패키지 이름.
  • --version <version> 또는 --tag <tag>: 예상 패키지 버전.
  • --sha256 <hex>: 예상 ClawHub SHA-256.
  • --npm-integrity <sri>: 예상 npm 무결성.
  • --npm-shasum <sha1>: 예상 npm shasum.
  • --json: 기계가 읽을 수 있는 출력.

예:

clawhub package verify ./example-plugin-1.2.3.tgz --package @openclaw/example-plugin --version 1.2.3clawhub package verify ./example-plugin-1.2.3.tgz --sha256 <hex>

package validate <source>

• ClawHub CLI에 번들된 Plugin Inspector를 로컬 Plugin 패키지 폴더에 대해 실행합니다.
• 로컬 OpenClaw 체크아웃을 찾거나 가져오지 않고 오프라인/정적 검증을 기본값으로 사용합니다.
• 하드 호환성 오류는 0이 아닌 코드로 종료합니다. 경고만 있는 발견 사항은 출력하지만 0으로 종료합니다.
• 플래그:
  • --out <dir>: Plugin Inspector 보고서를 이 디렉터리에 씁니다.
  • --openclaw <path>: 명시적인 로컬 OpenClaw 체크아웃을 기준으로 검사합니다.
  • --runtime: 런타임 캡처를 활성화합니다. Plugin 코드를 가져옵니다.
  • --allow-execute: 격리된 워크스페이스에서 런타임 캡처를 허용합니다.
  • --no-mock-sdk: 런타임 캡처 중 모의 OpenClaw SDK를 비활성화합니다.
  • --json: 기계가 읽을 수 있는 출력.

예:

clawhub package validate ./example-plugin

검증에서 패키지, manifest, SDK import 또는 아티팩트 발견 사항이 보고되면 Plugin 검증 수정을 참조한 다음 명령을 다시 실행하세요.

package delete <name>

• --version이 없으면 패키지와 모든 릴리스를 소프트 삭제합니다.
• --version <version>은 fail-closed 방식의 버전별 라우트를 통해 소유한 최신이 아닌 릴리스 하나를 영구 삭제합니다. 삭제된 버전은 복원하거나 다시 게시할 수 없습니다. 현재 최신 버전을 삭제하기 전에 대체 버전을 게시하세요. 이 버전 전용 흐름에는 패키지 소유자 또는 org publisher 관리자가 필요합니다. 플랫폼 스태프는 패키지 소유권을 우회하지 않습니다.
• 전체 패키지 소프트 삭제에는 패키지 소유자, org publisher 소유자/관리자, 플랫폼 모더레이터 또는 플랫폼 관리자가 필요합니다.
• 플래그:
  • --version <version>: 최신이 아닌 버전 하나를 영구 삭제합니다.
  • --yes: 확인을 건너뜁니다.
  • --json: 기계가 읽을 수 있는 출력.

예:

clawhub package delete @openclaw/example-plugin --yesclawhub package delete @openclaw/example-plugin --version 1.2.3 --yes

package undelete <name>

• 소프트 삭제된 패키지와 릴리스를 복원합니다.
• 버전 undelete는 없습니다. 영구 삭제된 버전은 복원할 수 없습니다.
• 패키지 소유자, org publisher 소유자/관리자, 플랫폼 모더레이터 또는 플랫폼 관리자가 필요합니다.
• POST /api/v1/packages/{name}/undelete를 호출합니다.
• 플래그:
  • --yes: 확인을 건너뜁니다.
  • --json: 기계가 읽을 수 있는 출력.

예:

clawhub package undelete @openclaw/example-plugin --yes

package transfer <name>

• 패키지를 다른 publisher로 이전합니다.
• 플랫폼 관리자가 수행하지 않는 한, 현재 패키지 소유자와 대상 publisher 모두에 대한 관리자 접근 권한이 필요합니다.
• 범위가 지정된 패키지 이름은 일치하는 범위 소유자에게 이전되어야 합니다.
• POST /api/v1/packages/{name}/transfer를 호출합니다.
• 플래그:
  • --to <owner>: 대상 publisher 핸들.
  • --reason <text>: 선택적 감사 사유.
  • --json: 기계가 읽을 수 있는 출력.

예:

clawhub package transfer @openclaw/example-plugin --to openclaw

package report

• 패키지를 모더레이터에게 신고하기 위한 인증된 명령.
• POST /api/v1/packages/{name}/report를 호출합니다.
• 신고는 패키지 수준이며, 선택적으로 버전에 연결될 수 있고 검토를 위해 모더레이터에게 표시됩니다.
• 신고만으로 패키지를 자동으로 숨기거나 다운로드를 차단하지 않습니다.
• 플래그:
  • --version <version>: 신고에 첨부할 선택적 패키지 버전.
  • --reason <text>: 필수 신고 사유.
  • --json: 기계가 읽을 수 있는 출력.

예:

clawhub package report @openclaw/example-plugin --version 1.2.3 --reason "suspicious native payload"

package moderation-status

• 패키지 모더레이션 표시 상태를 확인하기 위한 소유자 명령.
• GET /api/v1/packages/{name}/moderation을 호출합니다.
• 현재 패키지 스캔 상태, 열린 신고 수, 최신 릴리스 수동 모더레이션 상태, 다운로드 차단 상태, 모더레이션 사유를 표시합니다.
• 플래그:
  • --json: 기계가 읽을 수 있는 출력.

예:

clawhub package moderation-status @openclaw/example-plugin

package readiness <name>

• 패키지가 향후 OpenClaw 소비에 준비되었는지 확인합니다.
• GET /api/v1/packages/{name}/readiness를 호출합니다.
• 공식 상태, ClawPack 사용 가능 여부, 아티팩트 digest, 소스 출처, OpenClaw 호환성, 호스트 대상, 환경 메타데이터, 스캔 상태에 대한 차단 요소를 보고합니다.
• 플래그:
  • --json: 기계가 읽을 수 있는 출력.

예:

clawhub package readiness @openclaw/example-plugin

package migration-status <name>

• 번들 OpenClaw Plugin을 대체할 수 있는 패키지의 운영자 지향 마이그레이션 상태를 표시합니다.
• package readiness와 동일하게 계산된 readiness 엔드포인트를 호출하지만, 마이그레이션 중심 상태, 최신 버전, 공식 패키지 상태, 검사, 차단 요소를 출력합니다.
• 플래그:
  • --json: 기계가 읽을 수 있는 출력.

예:

clawhub package migration-status @openclaw/example-plugin

publisher create <handle>

• 인증된 사용자가 소유한 org publisher를 생성합니다.
• 핸들은 소문자로 정규화되며 @가 있거나 없어도 전달할 수 있습니다.
• 새로 생성된 org publisher는 기본적으로 신뢰/공식 상태가 아닙니다.
• 핸들이 기존 publisher, 사용자 또는 예약된 라우트에서 이미 사용 중이면 실패합니다.

clawhub publisher create opik --display-name "Opik"

package publish <source>

• POST /api/v1/packages를 통해 코드 Plugin 또는 번들 Plugin을 게시합니다.
• <source>는 다음을 허용합니다.
  • 로컬 폴더 경로: ./my-plugin
  • 로컬 ClawPack npm-pack tarball: ./my-plugin-1.2.3.tgz
  • GitHub 저장소: owner/repo 또는 owner/repo@ref
  • GitHub URL: https://github.com/owner/repo
• 메타데이터는 package.json, openclaw.plugin.json 및 .codex-plugin/plugin.json, .claude-plugin/plugin.json, .cursor-plugin/plugin.json 같은 실제 OpenClaw 번들 마커에서 자동 감지됩니다.
• .tgz 소스는 ClawPack으로 처리됩니다. CLI는 정확한 npm-pack 바이트를 업로드하고, 추출된 package/ 내용은 유효성 검사와 메타데이터 사전 채우기에만 사용합니다.
• 코드 Plugin 폴더는 업로드 전에 ClawPack npm tarball로 패키징되므로 OpenClaw 설치에서 정확한 아티팩트를 검증할 수 있습니다. 번들 Plugin 폴더는 계속 추출된 파일 게시 경로를 사용합니다.
• GitHub 소스의 경우 저장소, 확인된 커밋, ref, 하위 경로에서 소스 귀속 정보가 자동으로 채워집니다.
• 로컬 폴더의 경우 origin remote가 GitHub를 가리키면 로컬 git에서 소스 귀속 정보가 자동 감지됩니다.
• 외부 코드 Plugin은 openclaw.compat.pluginApi와 openclaw.build.openclawVersion을 명시적으로 선언해야 합니다. 최상위 package.json.version은 게시 유효성 검사의 폴백으로 사용되지 않습니다.
• --dry-run은 업로드하지 않고 확인된 게시 페이로드를 미리 보여줍니다.
• --json은 CI용 기계 판독 가능 출력을 내보냅니다.
• --owner <handle>은 행위자에게 게시자 접근 권한이 있을 때 사용자 또는 조직 게시자 핸들 아래에 게시합니다.
• 범위 지정 패키지 이름은 선택한 소유자와 일치해야 합니다. docs/publishing.md를 참고하세요.
• 기존 플래그(--family, --name, --version, --source-repo, --source-commit, --source-ref, --source-path)는 여전히 재정의로 작동합니다.
• 비공개 GitHub 저장소에는 GITHUB_TOKEN이 필요합니다.

clawhub package publish ./plugin.tgz --owner openclaw

권장 로컬 흐름

라이브 릴리스를 만들기 전에 확인된 패키지 메타데이터와 소스 귀속 정보를 확인할 수 있도록 먼저 --dry-run을 사용하세요.

npm packclawhub package publish ./my-plugin-1.2.3.tgz --family code-plugin --dry-runclawhub package publish ./my-plugin-1.2.3.tgz --family code-plugin

로컬 폴더 흐름

코드 Plugin의 경우 폴더 게시는 패키지 폴더에서 ClawPack 아티팩트를 빌드하고 업로드합니다.

clawhub package publish ./my-plugin --family code-plugin --dry-runclawhub package publish ./my-plugin --family code-plugin

--family code-plugin을 위한 최소 package.json

외부 코드 Plugin에는 package.json에 소량의 OpenClaw 메타데이터가 필요합니다. 이 최소 매니페스트만으로도 성공적으로 게시할 수 있습니다.

{  "name": "@myorg/openclaw-my-plugin",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "compat": {      "pluginApi": ">=2026.3.24-beta.2"    },    "build": {      "openclawVersion": "2026.3.24-beta.2"    }  }}

필수 필드:

• openclaw.compat.pluginApi
• openclaw.build.openclawVersion

참고:

• package.json.version은 패키지 릴리스 버전이지만, OpenClaw 호환성/빌드 유효성 검사의 폴백으로 사용되지 않습니다.
• openclaw.hostTargets와 openclaw.environment는 선택적 메타데이터입니다. ClawHub는 존재하는 경우 이를 표시할 수 있지만 게시에 필수는 아닙니다.
• 더 자세한 호환성 메타데이터를 게시하려면 openclaw.compat.minGatewayVersion과 openclaw.build.pluginSdkVersion을 선택적 추가 항목으로 사용할 수 있습니다.
• 이전 clawhub CLI 릴리스를 사용 중이라면, 업로드 전에 로컬 사전 검사가 실행되도록 게시 전에 업그레이드하세요.
• 유효성 검사가 해결 코드를 보고하면 Plugin 유효성 검사 수정을 참고하세요.

GitHub Actions

ClawHub는 Plugin 저장소용 공식 재사용 가능 워크플로도 /.github/workflows/package-publish.yml에 제공합니다.

일반적인 호출자 설정:

name: Package Publish on:  pull_request:  workflow_dispatch:  push:    tags:      - "v*" jobs:  dry-run:    if: github.event_name == 'pull_request'    uses: openclaw/clawhub/.github/workflows/package-publish.yml@v0.12.0    with:      dry_run: true   publish:    if: github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/')    permissions:      contents: read      id-token: write    uses: openclaw/clawhub/.github/workflows/package-publish.yml@v0.12.0    with:      dry_run: false    secrets:      clawhub_token: ${{ secrets.CLAWHUB_TOKEN }}

참고:

• 재사용 가능 워크플로는 기본적으로 source를 호출자 저장소로 설정합니다.
• 모노레포의 경우 워크플로가 Plugin 패키지 폴더를 게시하도록 source_path를 전달하세요. 예: source_path: extensions/codex.
• 재사용 가능 워크플로를 안정 태그 또는 전체 커밋 SHA에 고정하세요. @main에서 릴리스 게시를 실행하지 마세요.
• pull_request는 CI가 오염되지 않도록 dry_run: true를 사용해야 합니다.
• 실제 게시는 workflow_dispatch 또는 태그 푸시 같은 신뢰할 수 있는 이벤트로 제한해야 합니다.
• 시크릿 없는 신뢰할 수 있는 게시는 workflow_dispatch에서만 작동합니다. 태그 푸시에는 여전히 clawhub_token이 필요합니다.
• 첫 게시, 신뢰할 수 없는 패키지 또는 비상 게시를 위해 clawhub_token을 사용할 수 있게 유지하세요.
• 워크플로는 JSON 결과를 아티팩트로 업로드하고 워크플로 출력으로 노출합니다.

package trusted-publisher get <name>

• 패키지의 GitHub Actions 신뢰할 수 있는 게시자 구성을 표시합니다.
• 구성을 설정한 뒤 저장소, 워크플로 파일 이름, 선택적 환경 고정을 확인하는 데 사용하세요.
• 플래그:
  • --json: 기계 판독 가능 출력.

예:

clawhub package trusted-publisher get @openclaw/example-plugin

package trusted-publisher set <name>

• 기존 패키지에 GitHub Actions 신뢰할 수 있는 게시자 구성을 연결하거나 교체합니다.
• 패키지는 먼저 일반 수동 또는 토큰 인증 clawhub package publish를 통해 생성되어야 합니다.
• 구성이 설정되면 이후 지원되는 GitHub Actions 게시는 장기 보관 ClawHub 토큰 없이 OIDC/신뢰할 수 있는 게시를 사용할 수 있습니다.
• --repository <repo>는 owner/repo여야 합니다.
• --workflow-filename <file>은 .github/workflows/ 안의 워크플로 파일 이름과 일치해야 합니다.
• --environment <name>은 선택 사항입니다. 구성된 경우 OIDC 클레임의 GitHub Actions 환경이 정확히 일치해야 합니다.
• ClawHub는 이 명령이 실행될 때 구성된 GitHub 저장소를 검증합니다. 공개 저장소는 공개 GitHub 메타데이터를 통해 검증할 수 있습니다. 비공개 저장소는 예를 들어 향후 ClawHub GitHub App 설치 또는 다른 승인된 GitHub 통합을 통해 ClawHub가 해당 저장소에 대한 GitHub 접근 권한을 가져야 합니다.
• 플래그:
  • --repository <repo>: GitHub 저장소, 예: openclaw/example-plugin.
  • --workflow-filename <file>: 워크플로 파일 이름, 예: package-publish.yml.
  • --environment <name>: 선택적 정확 일치 GitHub Actions 환경.
  • --json: 기계 판독 가능 출력.

예:

clawhub package trusted-publisher set @openclaw/example-plugin \  --repository openclaw/example-plugin \  --workflow-filename package-publish.yml \  --environment release

package trusted-publisher delete <name>

• 패키지에서 신뢰할 수 있는 게시자 구성을 제거합니다.
• 워크플로, 저장소 또는 환경 고정을 비활성화하거나 다시 만들어야 하는 경우 롤백으로 사용하세요.
• 이후 실제 게시는 구성이 다시 설정될 때까지 일반 인증 게시를 사용해야 합니다.
• 플래그:
  • --json: 기계 판독 가능 출력.

예:

clawhub package trusted-publisher delete @openclaw/example-plugin

설치 텔레메트리

• 로그인한 상태에서 CLAWHUB_DISABLE_TELEMETRY=1이 설정되어 있지 않으면 clawhub install <slug> 이후 전송됩니다.
• 보고는 최선 노력 방식입니다. 텔레메트리를 사용할 수 없어도 설치 명령은 실패하지 않습니다.
• 자세한 내용: docs/telemetry.md.