OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Get started

API v1

API v1

基礎位址：https://clawhub.ai

OpenAPI：/api/v1/openapi.json

公開目錄重用

你可以在 ClawHub 的公開唯讀 API 上建置第三方目錄、索引或搜尋介面。公開的 Skill 中繼資料與 Skill 檔案依 ClawHub 的 Skill 授權規則發布，而 API 本身有速率限制，應以負責任的方式使用。

準則：

  • 使用公開唯讀端點（例如 GET /api/v1/skills、GET /api/v1/search 和 GET /api/v1/skills/{slug}）取得目錄清單。
  • 快取回應，並遵循 429、Retry-After 和速率限制標頭，而非頻繁輪詢。
  • 顯示清單時連結回 ClawHub Skill 的標準 URL，讓使用者可以查看來源登錄記錄。
  • 使用格式為 https://clawhub.ai/<owner>/skills/<slug> 的標準頁面 URL。
  • 不得暗示 ClawHub 認可、驗證或營運該第三方網站。
  • 不得透過繞過公開 API 篩選條件或驗證邊界，鏡像隱藏、私人或遭內容管理封鎖的內容。

驗證

  • 公開唯讀：不需要權杖。
  • 寫入與帳戶：Authorization: Bearer clh_...。

速率限制

依驗證狀態執行限制：

  • 匿名要求：依 IP。

  • 已驗證要求（有效的 Bearer 權杖）：依使用者配額。

  • 缺少或無效的權杖會改用 IP 限制。

  • 讀取：每個 IP 每分鐘 3000 次，每個金鑰每分鐘 12000 次

  • 寫入：每個 IP 每分鐘 300 次，每個金鑰每分鐘 3000 次

  • 下載：每個 IP 每分鐘 1200 次，每個金鑰每分鐘 6000 次

標頭：X-RateLimit-Limit、X-RateLimit-Reset、RateLimit-Limit、RateLimit-Reset； X-RateLimit-Remaining、RateLimit-Remaining 和 Retry-After 會包含在 429 中。

語意：

  • X-RateLimit-Reset：Unix 紀元秒數（絕對重設時間）
  • RateLimit-Reset：距離重設的延遲秒數
  • X-RateLimit-Remaining / RateLimit-Remaining：若存在，表示確切的剩餘配額；分片處理的成功要求會省略此值，而不會傳回近似的全域值
  • Retry-After：遇到 429 時應等待的延遲秒數

429 範例：

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

用戶端處理方式：

  • 若有 Retry-After，優先使用。
  • 否則使用 RateLimit-Reset，或根據 X-RateLimit-Reset 計算延遲時間。
  • 重試時加入隨機抖動。

錯誤

  • v1 錯誤為純文字（text/plain; charset=utf-8），包括 400、401、403、404、429 和遭封鎖的下載回應。
  • 為維持相容性，未知的查詢參數會被忽略。
  • 已知的查詢參數若包含無效值，會傳回 400。

端點

公開唯讀：

  • GET /api/v1/search?q=...
    • 選用篩選條件：highlightedOnly=true、nonSuspiciousOnly=true
    • 舊版別名：nonSuspicious=true
  • GET /api/v1/skills?limit=&cursor=&sort=
    • sort：updated（預設）、recommended（default）、createdAt（newest）、downloads、stars（rating），舊版安裝別名 installsCurrent/installs/installsAllTime 會對應至 downloads、trending
    • 無效的 sort 值會傳回 400
    • cursor 適用於非 trending 排序
    • 選用篩選條件：nonSuspiciousOnly=true
    • 舊版別名：nonSuspicious=true
    • 使用 nonSuspiciousOnly=true 時，游標分頁所含項目可能少於 limit 個；請使用 nextCursor 繼續。
    • recommended 使用互動度和近期性訊號。
  • 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=
    • 託管的 Skill 會傳回可重現的 ZIP 位元組。
    • 目前由 GitHub 支援且掃描結果為 clean 或 suspicious 的 Skill，會傳回 JSON public-github 轉交描述元，而非 ClawHub 位元組。
  • GET /api/v1/skills/export?startDate=&endDate=&limit=&cursor=
    • 託管的 Skill 會以儲存時的檔案形式匯出。
    • 目前由 GitHub 支援且掃描結果為 clean 或 suspicious 的 Skill，會匯出為 public-github 轉交描述元。
  • GET /api/v1/packages?limit=&cursor=&sort=
    • sort：updated（預設）、recommended、downloads，舊版別名 installs
    • 無效的 sort 值會傳回 400
  • GET /api/v1/plugins?limit=&cursor=&sort=
    • sort：recommended（預設）、downloads、updated，舊版別名 installs
  • GET /api/v1/plugins/search?q=...
  • GET /api/v1/packages/{name}/versions/{version}/artifact
  • GET /api/v1/packages/{name}/versions/{version}/security
  • GET /api/v1/packages/{name}/versions/{version}/artifact/download
  • GET /api/npm/{package}
  • GET /api/npm/{package}/-/{tarball}.tgz

需要驗證：

  • POST /api/v1/skills（發布，建議使用 multipart）
  • DELETE /api/v1/skills/{slug}
  • DELETE /api/v1/packages/{name}
  • POST /api/v1/skills/{slug}/undelete
  • POST /api/v1/packages/{name}/undelete
  • POST /api/v1/skills/{slug}/rename
  • POST /api/v1/skills/{slug}/merge
  • POST /api/v1/skills/{slug}/transfer
  • POST /api/v1/packages/{name}/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/skills/export?startDate=&endDate=&limit=&cursor=
  • GET /api/v1/plugins/export?startDate=&endDate=&limit=&cursor=&family=
  • GET /api/v1/transfers/incoming
  • GET /api/v1/transfers/outgoing
  • GET /api/v1/whoami

僅限管理員：

  • POST /api/v1/users/reserve 會為擁有者控制代碼保留根層級 slug 和沒有發行版本的私人套件預留位置。

舊版

舊版 /api/* 和 /api/cli/* 仍可使用。請參閱 DEPRECATIONS.md。

Was this useful?
On this page

On this page