http-api

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

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

핵심 요약

HTTP API reference (public + CLI endpoints + auth).

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

문서 구성

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

• HTTP API
• Public catalog reuse
• Rate limits
• Error responses
• Public endpoints (no auth)
• GET /api/v1/search
• GET /api/v1/skills
• GET /api/v1/skills/{slug}
• GET /api/v1/skills/{slug}/moderation
• POST /api/v1/skills/{slug}/report
• GET /api/v1/skills/-/reports
• POST /api/v1/skills/-/reports/{reportId}/triage
• GET /api/v1/skills/{slug}/versions
• GET /api/v1/skills/{slug}/versions/{version}
• GET /api/v1/skills/{slug}/scan
• POST /api/v1/skills/-/scan
• GET /api/v1/skills/-/scan/{scanId}
• GET /api/v1/skills/-/scan/{scanId}/download
• GET /api/v1/skills/-/scan/download/{name}?version=&kind=skill|plugin
• POST /api/v1/skills/-/scan/batch
• POST /api/v1/skills/-/scan/batch/status
• GET /api/v1/skills/{slug}/verify
• POST /api/v1/skills/-/security-verdicts
• GET /api/v1/skills/{slug}/file
• GET /api/v1/packages
• GET /api/v1/packages/search
• GET /api/v1/plugins
• GET /api/v1/skills/export
• GET /api/v1/plugins/export
• GET /api/v1/plugins/search

상세 내용

HTTP API

Base URL: https://clawhub.ai (default).

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

Public catalog reuse

Third-party directories may use the public read endpoints to list or search ClawHub skills. Please cache results, honor 429/Retry-After, link users back to the canonical ClawHub listing (https://clawhub.ai//skills/), and avoid implying ClawHub endorsement of the third-party site. Do not attempt to mirror hidden, private, or moderation-blocked content outside the public API surface.

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

Rate limits

the server knows the reason. Missing tokens, invalid/revoked tokens, and deleted/banned/disabled accounts should each get actionable text so CLI clients can tell users what blocked them.

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

주요 항목:

• Anonymous requests: enforced per IP.
• Authenticated requests (valid Bearer token): enforced per user bucket.
• If token is missing/invalid, behavior falls back to IP enforcement.
• Authenticated write endpoints should not return a bare Unauthorized when
• 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 (download endpoints)
• Legacy compatibility: X-RateLimit-Limit, X-RateLimit-Reset
• Standardized: RateLimit-Limit, RateLimit-Reset
• On 429: X-RateLimit-Remaining: 0 and RateLimit-Remaining: 0
• On 429: Retry-After
• X-RateLimit-Reset: absolute Unix epoch seconds
• RateLimit-Reset: seconds until reset (delay)
• X-RateLimit-Remaining / RateLimit-Remaining: exact remaining budget when present.
• Retry-After: seconds to wait before retry (delay) on 429
• If Retry-After exists, wait that many seconds before retry.
• Use jittered backoff to avoid synchronized retries.
• If Retry-After is missing, fallback to RateLimit-Reset (or compute from X-RateLimit-Reset).
• Uses trusted client IP headers, including cf-connecting-ip, only when the
• ClawHub uses trusted forwarding headers to identify client IPs at the edge.
• If no trusted client IP is available, anonymous requests use fallback buckets

HTTP/2 429
content-type: text/plain; charset=utf-8
x-ratelimit-limit: 20
x-ratelimit-remaining: 0
x-ratelimit-reset: 1771404540
ratelimit-limit: 20
ratelimit-remaining: 0
ratelimit-reset: 34
retry-after: 34

Rate limit exceeded

Error responses

Public v1 error responses are plain text with content-type: text/plain; charset=utf-8. This includes validation failures (400), missing public resources (404), auth and permission failures (401/403), rate limits (429), and blocked downloads. Clients should read the response body as a human-readable string. Unknown query parameters are ignored for compatibility, but recognized query parameters with invalid values return 400.

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

Public endpoints (no auth)

이 섹션의 세부 항목은 공식 문서 Public endpoints (no auth)를 참고하세요.

GET /api/v1/search

주요 항목:

• q (required): query string
• limit (optional): integer
• highlightedOnly (optional): true to filter to highlighted skills
• nonSuspiciousOnly (optional): true to hide suspicious (flagged.suspicious) skills
• nonSuspicious (optional): legacy alias for nonSuspiciousOnly
• Results are returned in relevance order (embedding similarity + exact slug/name token boosts + a small popularity prior).
• Relevance is stronger than popularity. A precise slug or display-name token match can outrank a looser match with much stronger engagement.
• ASCII text is tokenized on word and punctuation boundaries. 예를 들어, personal-map contains a standalone map token, while amap-jsapi-skill contains amap, jsapi, and skill; searching for map therefore gives personal-map a stronger lexical match than amap-jsapi-skill.
• Popularity is log-scaled and capped. High-engagement skills can rank lower when the query text is a weaker match.
• Suspicious or hidden moderation state can remove a skill from public search depending on caller filters and current moderation status.
• Put the terms users will literally search for in the display name, summary, and tags. Use a standalone slug token only when it is also a stable identity you want to keep.
• Do not rename a slug just to chase one query unless the new slug is a better long-term canonical name. Old slugs become redirect aliases, but the canonical URL, displayed slug, and future search digests use the new slug.
• Rename aliases preserve resolution for old URLs and installs that resolve through the registry, but search ranking is based on the canonical skill metadata after the rename has indexed. Existing stats stay with the skill.
• If a skill is unexpectedly invisible, check moderation state first with clawhub inspect @owner/slug while logged in before changing ranking-related metadata.

{
  "results": [
    {
      "score": 0.123,
      "slug": "gifgrep",
      "displayName": "GifGrep",
      "summary": "…",
      "version": "1.2.3",
      "updatedAt": 1730000000000,
      "ownerHandle": "openclaw",
      "owner": {
        "handle": "openclaw",
        "displayName": "OpenClaw",
        "image": "https://example.com/avatar.png"
      }
    }
  ]
}

GET /api/v1/skills

주요 항목:

• limit (optional): integer (1–200)
• cursor (optional): pagination cursor for any non-trending sort
• sort (optional): updated (default), recommended (alias: default), createdAt (alias: newest), downloads, stars (alias: rating), legacy install aliases installsCurrent/installs/installsAllTime map to downloads, trending
• nonSuspiciousOnly (optional): true to hide suspicious (flagged.suspicious) skills
• nonSuspicious (optional): legacy alias for nonSuspiciousOnly
• recommended uses engagement and recency signals.
• trending ranks by installs in the last 7 days (telemetry-based).
• createdAt is stable for new-skill crawls; updated changes when existing skills are republished.
• When nonSuspiciousOnly=true, cursor-based sorts may return fewer than limit items on a page because suspicious skills are filtered after page retrieval.
• Use nextCursor to continue pagination when present. A short page does not by itself mean end-of-results.

{
  "items": [
    {
      "slug": "gifgrep",
      "displayName": "GifGrep",
      "summary": "…",
      "topics": ["Productivity"],
      "tags": { "latest": "1.2.3" },
      "stats": {},
      "createdAt": 0,
      "updatedAt": 0,
      "latestVersion": { "version": "1.2.3", "createdAt": 0, "changelog": "…" },
      "metadata": { "os": ["macos"], "systems": ["aarch64-darwin"] }
    }
  ],
  "nextCursor": null
}

GET /api/v1/skills/{slug}

주요 항목:

• Old slugs created by owner rename/merge flows resolve to the canonical skill.
• metadata.os: OS restrictions declared in skill frontmatter (e.g. ["macos"], ["linux"]). null if not declared.
• metadata.systems: Nix system targets (e.g. ["aarch64-darwin", "x86_64-linux"]). null if not declared.
• metadata is null if the skill has no platform metadata.
• moderation is included only when the skill is flagged or the owner is viewing it.

{
  "skill": {
    "slug": "gifgrep",
    "displayName": "GifGrep",
    "summary": "…",
    "topics": ["Productivity"],
    "tags": { "latest": "1.2.3" },
    "stats": {},
    "createdAt": 0,
    "updatedAt": 0
  },
  "latestVersion": { "version": "1.2.3", "createdAt": 0, "changelog": "…" },
  "metadata": { "os": ["macos"], "systems": ["aarch64-darwin"] },
  "owner": { "handle": "steipete", "displayName": "Peter", "image": null },
  "moderation": {
    "isSuspicious": false,
    "isMalwareBlocked": false,
    "verdict": "clean",
    "reasonCodes": [],
    "summary": null,
    "engineVersion": "v2.0.0",
    "updatedAt": 0
  }
}

GET /api/v1/skills/{slug}/moderation

주요 항목:

• Owners and moderators can access moderation details for hidden skills.
• Public callers only get 200 for already-flagged visible skills.
• Evidence is redacted for public callers and only includes raw snippets for owners/moderators.

{
  "moderation": {
    "isSuspicious": true,
    "isMalwareBlocked": false,
    "verdict": "suspicious",
    "reasonCodes": ["suspicious.dynamic_code_execution"],
    "summary": "Detected: suspicious.dynamic_code_execution",
    "engineVersion": "v2.0.0",
    "updatedAt": 0,
    "legacyReason": null,
    "evidence": [
      {
        "code": "suspicious.dynamic_code_execution",
        "severity": "critical",
        "file": "index.ts",
        "line": 3,
        "message": "Dynamic code execution detected.",
        "evidence": ""
      }
    ]
  }
}

POST /api/v1/skills/{slug}/report

Report a skill for moderator review. Reports are skill-level, optionally linked to a version, and feed the skill report queue.

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

주요 항목:

• Requires an API token.

{ "reason": "Suspicious install step", "version": "1.2.3" }

{
  "ok": true,
  "reported": true,
  "alreadyReported": false,
  "reportId": "skillReports:...",
  "skillId": "skills:...",
  "reportCount": 1
}

GET /api/v1/skills/-/reports

Moderator/admin endpoint for skill report intake.

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

주요 항목:

• status (optional): open (default), confirmed, dismissed, or all
• limit (optional): integer (1-200)
• cursor (optional): pagination cursor

{
  "items": [
    {
      "reportId": "skillReports:...",
      "skillId": "skills:...",
      "skillVersionId": "skillVersions:...",
      "slug": "gifgrep",
      "displayName": "GifGrep",
      "version": "1.2.3",
      "reason": "Suspicious install step",
      "status": "open",
      "createdAt": 1730000000000,
      "reporter": {
        "userId": "users:...",
        "handle": "reporter",
        "displayName": "Reporter"
      },
      "triagedAt": null,
      "triagedBy": null,
      "triageNote": null
    }
  ],
  "nextCursor": null,
  "done": true
}

POST /api/v1/skills/-/reports/{reportId}/triage

Moderator/admin endpoint for resolving or reopening skill reports.

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

{ "status": "confirmed", "note": "Reviewed and hid affected version.", "finalAction": "hide" }

GET /api/v1/skills/{slug}/versions

주요 항목:

• limit (optional): integer
• cursor (optional): pagination cursor

GET /api/v1/skills/{slug}/versions/{version}

주요 항목:

• version.security includes normalized scan verification status and scanner details

GET /api/v1/skills/{slug}/scan

Returns security scan verification details for a skill version.

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

주요 항목:

• version (optional): specific version string.
• tag (optional): resolve a tagged version (for example latest).
• If neither version nor tag is provided, uses the latest version.
• Includes normalized verification status plus scanner-specific details.
• security.hasScanResult is true only when a scanner produced a definitive verdict (clean, suspicious, or malicious).
• moderation is a current skill-level moderation snapshot derived from the latest version.
• When querying a historical version, check moderation.matchesRequestedVersion and moderation.sourceVersion before treating moderation and security as the same version context.

POST /api/v1/skills/-/scan

Authenticated submit endpoint for new ClawScan jobs.

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

주요 항목:

• Scan request payloads and downloadable reports expire from the scan-request store after the retention window.
• Published scans require owner/publisher management access, or platform moderator/admin authority.
• Published scans write back only when update: true and the scan completes successfully.
• Response is 202 with { "ok": true, "scanId": "...", "jobId": "...", "status": "queued", "sourceKind": "published", "update": false, "queue": { "queuedAhead": 0, "queuedAheadIsEstimate": false, "position": 1, "running": 0, "runningIsEstimate": false, "note": "Scans are asynchronous and may take time to complete." } }.
• Scan jobs are asynchronous. Manual scan requests are prioritized ahead of normal publish/backfill work, but completion still depends on worker availability.

{
  "source": { "kind": "published", "slug": "gifgrep", "version": "1.2.3" },
  "update": false
}

GET /api/v1/skills/-/scan/{scanId}

Authenticated poll endpoint for a submitted scan.

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

주요 항목:

• Returns queued/running/succeeded/failed status.
• Returns queue.queuedAhead and queue.position while queued so clients can show how many prioritized manual scans are ahead of the request. Very large queues are bounded and reported with queuedAheadIsEstimate: true.
• When available, report contains clawscan, skillspector, staticAnalysis, and virustotal sections.
• Failed scan jobs return status: "failed" with lastError.

GET /api/v1/skills/-/scan/{scanId}/download

주요 항목:

• Requires a succeeded scan; non-terminal scans return 409.
• Returns a ZIP with manifest.json, clawscan.json, skillspector.json, static-analysis.json, virustotal.json, and README.md.

GET /api/v1/skills/-/scan/download/{name}?version=&kind=skill|plugin

Authenticated stored report archive endpoint for submitted versions.

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

주요 항목:

• Requires owner/publisher management access to the skill or plugin, or platform moderator/admin authority.
• Returns stored scan results for the exact submitted version, including blocked or hidden versions.
• kind defaults to skill; use kind=plugin for plugin/package scans.
• Returns the same ZIP shape as scan-request downloads.

POST /api/v1/skills/-/scan/batch

Admin-only canonical batch rescan route. It accepts the same payload shape as legacy POST /api/v1/skills/-/rescan-batch.

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

POST /api/v1/skills/-/scan/batch/status

Admin-only canonical batch status route. It accepts { "jobIds": ["..."] } and returns the same aggregate counters as legacy POST /api/v1/skills/-/rescan-batch/status.

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

GET /api/v1/skills/{slug}/verify

Returns the Skill Card verification envelope used by clawhub skill verify.

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

주요 항목:

• version (optional): specific version string.
• tag (optional): resolve a tagged version (for example latest).
• ok is true only when the selected version has a generated Skill Card, is not malware-blocked by moderation, and ClawScan verification is clean.
• Skill identity, publisher identity, and selected version metadata are top-level envelope fields (slug, displayName, publisherHandle, version, resolvedFrom, tag, createdAt) so shell automation can read them without unpacking nested wrappers.
• security is the top-level ClawScan/security verdict. Automation should key off ok, decision, reasons, and security.status.
• security.signals contains supporting scanner evidence such as staticScan, virusTotal, and skillSpector.
• security.signals.dependencyRegistry is retained for v1 response compatibility, but the dependency registry existence scanner is retired and this key is always null.
• provenance is server-resolved-github-import only when ClawHub resolved and stored a GitHub repo/ref/commit/path during publish or import; otherwise it is unavailable.

POST /api/v1/skills/-/security-verdicts

Returns current compact security verdicts for exact skill versions. This collection endpoint is intended for clients that already know which installed ClawHub skill versions they need to display, such as OpenClaw Control UI.

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

주요 항목:

• items must contain 1-100 unique { slug, version } pairs.
• Results are per item; one missing skill or version does not fail the whole response.
• The response is security-only. It does not include Skill Card data, generated card status, artifact file lists, or detailed scanner payloads.
• security.signals contains status-level supporting evidence only; use /scan or the ClawHub security-audit page for full scanner details.
• security.signals.dependencyRegistry is retained for v1 response compatibility, but the dependency registry existence scanner is retired and this key is always null.
• Skill Card absence does not affect this endpoint's ok, decision, or reasons; clients should read installed skill-card.md locally when they need card content.
• Use /verify when you need the single-skill Skill Card verification envelope, /card when you need generated card markdown, and /scan when you need detailed scanner data.

{
  "items": [{ "slug": "gifgrep", "version": "1.2.3" }]
}

{
  "schema": "clawhub.skill.security-verdicts.v1",
  "items": [
    {
      "ok": true,
      "decision": "pass",
      "reasons": [],
      "requestedSlug": "gifgrep",
      "slug": "gifgrep",
      "displayName": "GifGrep",
      "publisherHandle": "steipete",
      "publisherDisplayName": "Peter",
      "requestedVersion": "1.2.3",
      "version": "1.2.3",
      "createdAt": 0,
      "checkedAt": 0,
      "skillUrl": "https://clawhub.ai/steipete/skills/gifgrep",
      "securityAuditUrl": "https://clawhub.ai/steipete/skills/gifgrep/security-audit?version=1.2.3",
      "security": {
        "status": "clean",
        "passed": true,
        "signals": {
          "staticScan": { "status": "clean", "reasonCodes": [] },
          "virusTotal": null,
          "skillSpector": null,
          "dependencyRegistry": null
        }
      }
    },
    {
      "ok": false,
      "decision": "fail",
      "reasons": ["version.not_found"],
      "requestedSlug": "missing-version",
      "requestedVersion": "1.0.0",
      "error": { "code": "version_not_found", "message": "Version not found" },
      "security": null
    }
  ]
}

GET /api/v1/skills/{slug}/file

Returns exact stored file bytes as a download. Add preview=1 to request a bounded escaped-text preview; any file with valid UTF-8 bytes can be previewed, regardless of its extension or MIME metadata.

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

주요 항목:

• path (required)
• version (optional)
• tag (optional)
• preview=1 (optional; returns text/plain or 415 when the bytes are not valid UTF-8)
• Defaults to latest version.
• Raw download limit: 10MB.
• Text preview limit: 200KB.

GET /api/v1/packages

request is scoped to plugin packages (/api/v1/plugins, /api/v1/code-plugins, /api/v1/bundle-plugins, or package endpoints with family=code-plugin/family=bundle-plugin). Controlled categories and legacy v1 filter aliases are documented under GET /api/v1/plugins.

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

주요 항목:

• skills
• code plugins
• bundle plugins
• limit (optional): integer (1–100)
• cursor (optional): pagination cursor
• family (optional): skill, code-plugin, or bundle-plugin
• channel (optional): official, community, or private
• isOfficial (optional): true or false
• sort (optional): updated (default), recommended, trending, downloads, legacy alias installs
• category (optional): plugin category filter. Supported only when the
• Invalid values for family, channel, isOfficial, featured,
• GET /api/v1/code-plugins and GET /api/v1/bundle-plugins remain fixed-family aliases.
• Skill entries stay backed by the skill registry and can still be published only through POST /api/v1/skills.
• POST /api/v1/packages is still only for code-plugin and bundle-plugin releases.
• Anonymous callers only see public package channels.
• Authenticated callers can see private packages for publishers they belong to in list/search results.
• channel=private only returns packages the authenticated caller can read.

GET /api/v1/packages/search

Unified catalog search across skills + plugin packages.

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

주요 항목:

• q (required): query string
• limit (optional): integer (1–100)
• family (optional): skill, code-plugin, or bundle-plugin
• channel (optional): official, community, or private
• isOfficial (optional): true or false
• category (optional): plugin category filter. Supported only when the
• Invalid values for family, channel, isOfficial, featured, or
• Anonymous callers only see public package channels.
• Authenticated callers can search private packages for publishers they belong to.
• channel=private only returns packages the authenticated caller can read.

GET /api/v1/plugins

Plugin-only catalog browse across code-plugin and bundle-plugin packages.

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

주요 항목:

• limit (optional): integer (1-100)
• cursor (optional): pagination cursor
• isOfficial (optional): true or false
• sort (optional): recommended (default), trending, downloads, updated, legacy alias installs
• category (optional): plugin category filter. Current values:
• mcp-tooling, data, and automation resolve to tools.
• observability and deployment resolve to gateway.
• dev-tools resolves to runtime.

GET /api/v1/skills/export

Bulk export of latest public skills for offline analysis.

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

주요 항목:

• API token required.
• startDate (required): Unix milliseconds lower bound for skill updatedAt.
• endDate (required): Unix milliseconds upper bound for skill updatedAt.
• limit (optional): integer (1-250), default 250.
• cursor (optional): pagination cursor from the previous response.
• Body: ZIP archive.
• Each exported skill is rooted at {publisher}/{slug}/.
• Hosted skills include the latest stored version files and are listed in
• Current GitHub-backed skills with a clean or suspicious scan include
• Each skill includes _export_skill_meta.json.
• _manifest.json is always included at the ZIP root.
• _errors.json is included when individual skills or files could not be
• X-Next-Cursor
• X-Has-More
• X-Total-Returned
• X-Date-Range
• X-Export-Errors

GET /api/v1/plugins/export

Bulk export of latest public plugin releases for offline analysis.

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

주요 항목:

• API token required.
• startDate (required): Unix milliseconds lower bound for plugin updatedAt.
• endDate (required): Unix milliseconds upper bound for plugin updatedAt.
• limit (optional): integer (1-250), default 250.
• cursor (optional): pagination cursor from the previous response.
• family (optional): code-plugin or bundle-plugin. Omitted means both
• Body: ZIP archive.
• Each exported plugin is rooted at {family}/{packageName}/.
• Each exported plugin includes the latest release's stored files.
• Per-plugin export metadata is stored at
• _manifest.json is always included at the ZIP root.
• _errors.json is included when individual plugins or files could not be
• X-Next-Cursor
• X-Has-More
• X-Total-Returned
• X-Date-Range
• X-Export-Errors

GET /api/v1/plugins/search

Plugin-only search across code-plugin and bundle-plugin packages.

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

주요 항목:

• q (required): query string
• limit (optional): integer (1-100)
• isOfficial (optional): true or false
• category (optional): plugin category filter. Current values:
• The legacy v1 filter aliases documented under GET /api/v1/plugins are also
• Category filtering is a real API filter backed by plugin category digest
• Results are returned in relevance order and do not currently paginate.
• Browser UI sort controls for plugin search reorder the loaded relevance results,

GET /api/v1/packages/{name}

주요 항목:

• Skills can also resolve through this route in the unified catalog.
• Private packages return 404 unless the caller can read the owning publisher.

DELETE /api/v1/packages/{name}

주요 항목:

• Requires an API token for the package owner, an org publisher owner/admin,

GET /api/v1/packages/{name}/versions

주요 항목:

• limit (optional): integer (1–100)
• cursor (optional): pagination cursor
• Private packages return 404 unless the caller can read the owning publisher.

GET /api/v1/packages/{name}/versions/{version}

Returns one package version, including file metadata, compatibility, verification, artifact metadata, and scan data.

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

주요 항목:

• version.artifact.kind is legacy-zip for old-world package archives or
• ClawPack releases include npm-compatible npmIntegrity, npmShasum, and
• version.sha256hash is deprecated compatibility metadata for old clients. It
• version.vtAnalysis, version.llmAnalysis, and version.staticScan are
• Private packages return 404 unless the caller can read the owning publisher.

GET /api/v1/packages/{name}/versions/{version}/security

Returns the exact package release security and trust summary for install clients. This is the public OpenClaw consumption surface for deciding whether a resolved release can be installed.

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

주요 항목:

• Public read endpoint. No owner, publisher, moderator, or admin token is
• package.name, package.displayName, and package.family identify the
• release.releaseId, release.version, and release.createdAt identify the
• release.artifactKind, release.artifactSha256, release.npmIntegrity,
• trust.scanStatus is the effective trust status derived from scanner inputs
• trust.moderationState is nullable. It is null when no manual release
• trust.blockedFromDownload is the install block signal. OpenClaw and other
• trust.reasons is the user-facing and audit explanation list. Reason codes
• trust.pending means one or more trust inputs are still awaiting completion.
• trust.stale means the trust summary was computed from outdated inputs and
• This endpoint is version-exact. Clients should call it after resolving the
• Private packages return 404 unless the caller can read the owning publisher.
• This endpoint is intentionally narrower than owner/moderator moderation

{
  "package": {
    "name": "@openclaw/example-plugin",
    "displayName": "Example Plugin",
    "family": "code-plugin"
  },
  "release": {
    "releaseId": "packageReleases:...",
    "version": "1.2.3",
    "artifactKind": "npm-pack",
    "artifactSha256": "0123456789abcdef...",
    "npmIntegrity": "sha512-...",
    "npmShasum": "0123456789abcdef0123456789abcdef01234567",
    "npmTarballName": "example-plugin-1.2.3.tgz",
    "createdAt": 1730000000000
  },
  "trust": {
    "scanStatus": "malicious",
    "moderationState": "quarantined",
    "blockedFromDownload": true,
    "reasons": ["manual:quarantined", "scan:malicious"],
    "pending": false,
    "stale": false
  }
}

GET /api/v1/packages/{name}/versions/{version}/artifact

Returns the explicit artifact resolver metadata for a package version.

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

주요 항목:

• Legacy package versions return a legacy-zip artifact and a legacy ZIP
• ClawPack versions return an npm-pack artifact, npm integrity fields, a
• This is the OpenClaw resolver surface; it avoids guessing archive format from

GET /api/v1/packages/{name}/versions/{version}/artifact/download

Downloads the version artifact through the explicit resolver path.

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

주요 항목:

• ClawPack versions stream the exact uploaded npm-pack .tgz bytes.
• Legacy ZIP versions redirect to /api/v1/packages/{name}/download?version=.
• Uses the download rate bucket.

GET /api/v1/packages/{name}/readiness

Returns computed readiness for future OpenClaw consumption.

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

주요 항목:

• official channel status
• latest version availability
• ClawPack npm-pack artifact availability
• artifact digest
• source repo and commit provenance
• OpenClaw compatibility metadata
• host targets
• scan state

{
  "package": {
    "name": "@openclaw/example-plugin",
    "displayName": "Example Plugin",
    "family": "code-plugin",
    "isOfficial": true,
    "latestVersion": "1.2.3"
  },
  "ready": false,
  "checks": [
    {
      "id": "clawpack",
      "label": "ClawPack artifact",
      "status": "fail",
      "message": "Latest version is legacy ZIP-only."
    }
  ],
  "blockers": ["clawpack"]
}

GET /api/v1/packages/migrations

Moderator endpoint for listing official OpenClaw plugin migration rows.

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

주요 항목:

• Requires an API token for a moderator or admin user.
• phase (optional): planned, published, clawpack-ready,
• limit (optional): integer (1-100)
• cursor (optional): pagination cursor

{
  "items": [
    {
      "migrationId": "officialPluginMigrations:...",
      "bundledPluginId": "core.search",
      "packageName": "@openclaw/search-plugin",
      "packageId": "packages:...",
      "owner": "platform",
      "sourceRepo": "openclaw/openclaw",
      "sourcePath": "plugins/search",
      "sourceCommit": "abc123",
      "phase": "blocked",
      "blockers": ["missing ClawPack"],
      "hostTargetsComplete": true,
      "scanClean": false,
      "moderationApproved": false,
      "runtimeBundlesReady": false,
      "notes": null,
      "createdAt": 1760000000000,
      "updatedAt": 1760000000000
    }
  ],
  "nextCursor": null,
  "done": true
}

POST /api/v1/packages/migrations

Admin endpoint for creating or updating an official plugin migration row.

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

주요 항목:

• Requires an API token for an admin user.
• bundledPluginId is normalized to lowercase and is the stable upsert key.
• packageName is npm-name normalized; the package can be missing for planned
• This tracks migration readiness only. It does not mutate OpenClaw or generate

{
  "bundledPluginId": "core.search",
  "packageName": "@openclaw/search-plugin",
  "owner": "platform",
  "sourceRepo": "openclaw/openclaw",
  "sourcePath": "plugins/search",
  "sourceCommit": "abc123",
  "phase": "blocked",
  "blockers": ["missing ClawPack"],
  "hostTargetsComplete": true,
  "scanClean": false,
  "moderationApproved": false,
  "runtimeBundlesReady": false,
  "notes": "waiting on publisher upload"
}

실습 체크리스트

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

자주 쓰는 명령·설정 예시

HTTP/2 429
content-type: text/plain; charset=utf-8
x-ratelimit-limit: 20
x-ratelimit-remaining: 0
x-ratelimit-reset: 1771404540
ratelimit-limit: 20
ratelimit-remaining: 0
ratelimit-reset: 34
retry-after: 34

Rate limit exceeded

{
  "results": [
    {
      "score": 0.123,
      "slug": "gifgrep",
      "displayName": "GifGrep",
      "summary": "…",
      "version": "1.2.3",
      "updatedAt": 1730000000000,
      "ownerHandle": "openclaw",
      "owner": {
        "handle": "openclaw",
        "displayName": "OpenClaw",
        "image": "https://example.com/avatar.png"
      }
    }
  ]
}

{
  "items": [
    {
      "slug": "gifgrep",
      "displayName": "GifGrep",
      "summary": "…",
      "topics": ["Productivity"],
      "tags": { "latest": "1.2.3" },
      "stats": {},
      "createdAt": 0,
      "updatedAt": 0,
      "latestVersion": { "version": "1.2.3", "createdAt": 0, "changelog": "…" },
      "metadata": { "os": ["macos"], "systems": ["aarch64-darwin"] }
    }
  ],
  "nextCursor": null
}

{
  "skill": {
    "slug": "gifgrep",
    "displayName": "GifGrep",
    "summary": "…",
    "topics": ["Productivity"],
    "tags": { "latest": "1.2.3" },
    "stats": {},
    "createdAt": 0,
    "updatedAt": 0
  },
  "latestVersion": { "version": "1.2.3", "createdAt": 0, "changelog": "…" },
  "metadata": { "os": ["macos"], "systems": ["aarch64-darwin"] },
  "owner": { "handle": "steipete", "displayName": "Peter", "image": null },
  "moderation": {
    "isSuspicious": false,
    "isMalwareBlocked": false,
    "verdict": "clean",
    "reasonCodes": [],
    "summary": null,
    "engineVersion": "v2.0.0",
    "updatedAt": 0
  }
}

{
  "moderation": {
    "isSuspicious": true,
    "isMalwareBlocked": false,
    "verdict": "suspicious",
    "reasonCodes": ["suspicious.dynamic_code_execution"],
    "summary": "Detected: suspicious.dynamic_code_execution",
    "engineVersion": "v2.0.0",
    "updatedAt": 0,
    "legacyReason": null,
    "evidence": [
      {
        "code": "suspicious.dynamic_code_execution",
        "severity": "critical",
        "file": "index.ts",
        "line": 3,
        "message": "Dynamic code execution detected.",
        "evidence": ""
      }
    ]
  }
}

{ "reason": "Suspicious install step", "version": "1.2.3" }

관련 링크

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

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