api

기준일: 2026-07-26
공식 기준: api

api 문서는 OpenClaw 공식 문서(clawhub/api)를 한국어로 정리한 가이드입니다. Public REST API (v1) overview and conventions. 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Public REST API (v1) overview and conventions.

한국어 가이드 범위: clawhub/api 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• API v1
• Public catalog reuse
• Auth
• Rate limits
• Errors
• Endpoints
• Legacy

상세 내용

API v1

Base: https://clawhub.ai

OpenAPI: /api/v1/openapi.json

Public catalog reuse

You can build a third-party catalog, directory, or search surface on top of ClawHub's public read APIs. Public skill metadata and skill files are published under ClawHub's skill license rules, while the API itself is rate-limited and should be consumed responsibly.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Use public read endpoints such as GET /api/v1/skills, GET /api/v1/search, and GET /api/v1/skills/{slug} for catalog listings.
• Cache responses and respect 429, Retry-After, and rate-limit headers instead of polling aggressively.
• Link back to the canonical ClawHub skill URL when displaying listings so users can inspect the source registry record.
• Use canonical page URLs in the form https://clawhub.ai/<owner>/skills/<slug>.
• Do not imply that ClawHub endorses, verifies, or operates the third-party site.
• Do not mirror hidden, private, or moderation-blocked content by bypassing public API filters or auth boundaries.

Auth

주요 항목:

• Public read: no token required.
• Write + account: Authorization: Bearer clh_....

Rate limits

Headers: X-RateLimit-Limit, X-RateLimit-Reset, RateLimit-Limit, RateLimit-Reset; X-RateLimit-Remaining, RateLimit-Remaining, and Retry-After are included on 429.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Anonymous requests: per IP.
• Authenticated requests (valid Bearer token): per user bucket.
• Missing/invalid token falls back to IP enforcement.
• Read: 3000/min per IP, 12000/min per key
• Write: 300/min per IP, 3000/min per key
• Download: 1200/min per IP, 6000/min per key
• X-RateLimit-Reset: Unix epoch seconds (absolute reset time)
• RateLimit-Reset: delay seconds until reset
• X-RateLimit-Remaining / RateLimit-Remaining: exact remaining budget when
• Retry-After: delay seconds to wait on 429
• Prefer Retry-After when present.
• Otherwise use RateLimit-Reset or derive delay from X-RateLimit-Reset.
• Add jitter to retries.

HTTP/2 429
x-ratelimit-limit: 20
x-ratelimit-remaining: 0
x-ratelimit-reset: 1771404540
ratelimit-limit: 20
ratelimit-remaining: 0
ratelimit-reset: 34
retry-after: 34

Errors

401, 403, 404, 429, and blocked-download responses.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• v1 errors are plain text (text/plain; charset=utf-8), including 400,
• Unknown query parameters are ignored for compatibility.
• Known query parameters with invalid values return 400.

Endpoints

JSON public-github handoff descriptor instead of ClawHub bytes.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• GET /api/v1/search?q=...
• Optional filters: highlightedOnly=true, nonSuspiciousOnly=true
• Legacy alias: nonSuspicious=true
• GET /api/v1/skills?limit=&cursor=&sort=
• sort: updated (default), recommended (default), createdAt (newest), downloads, stars (rating), legacy install aliases installsCurrent/installs/installsAllTime map to downloads, trending
• Invalid sort values return 400
• cursor applies to non-trending sorts
• Optional filter: nonSuspiciousOnly=true
• Legacy alias: nonSuspicious=true
• With nonSuspiciousOnly=true, cursor-based pages may contain fewer than limit items; use nextCursor to continue.
• recommended uses engagement and recency signals.
• GET /api/v1/skills/{slug}
• GET /api/v1/skills/{slug}/moderation
• GET /api/v1/skills/{slug}/versions?limit=&cursor=
• GET /api/v1/skills/{slug}/versions/{version}
• GET /api/v1/skills/{slug}/scan?version=&tag=
• GET /api/v1/skills/{slug}/file?path=&version=&tag=
• GET /api/v1/resolve?slug=&hash=
• GET /api/v1/download?slug=&version=&tag=
• Hosted skills return deterministic ZIP bytes.
• Current GitHub-backed skills with a clean or suspicious scan return a
• GET /api/v1/skills/export?startDate=&endDate=&limit=&cursor=
• Hosted skills are exported as stored files.
• Current GitHub-backed skills with a clean or suspicious scan are exported
• GET /api/v1/packages?limit=&cursor=&sort=

Legacy

Legacy /api/* and /api/cli/* still available. See DEPRECATIONS.md.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/clawhub/api
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

HTTP/2 429
x-ratelimit-limit: 20
x-ratelimit-remaining: 0
x-ratelimit-reset: 1771404540
ratelimit-limit: 20
ratelimit-remaining: 0
ratelimit-reset: 34
retry-after: 34

관련 링크

• 공식 원문: clawhub/api
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.