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

快速开始

API v1

API v1

基础地址：https://clawhub.ai

OpenAPI：/api/v1/openapi.json

公共目录复用

你可以基于 ClawHub 的公共只读 API 构建第三方目录、索引或搜索界面。公共 Skills 元数据和 Skills 文件依照 ClawHub 的 Skills 许可规则发布，而 API 本身有速率限制，应负责任地使用。

指南：

  • 使用公共只读端点（例如 GET /api/v1/skills、GET /api/v1/search 和 GET /api/v1/skills/{slug}）获取目录列表。
  • 缓存响应并遵循 429、Retry-After 和速率限制标头，而不是频繁轮询。
  • 显示列表时链接回 ClawHub Skills 的规范 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=
    • 托管的 Skills 返回确定性的 ZIP 字节。
    • 当前由 GitHub 支持且扫描结果为 clean 或 suspicious 的 Skills 将返回 JSON public-github 移交描述符，而不是 ClawHub 字节。
  • GET /api/v1/skills/export?startDate=&endDate=&limit=&cursor=
    • 托管的 Skills 会按存储的文件导出。
    • 当前由 GitHub 支持且扫描结果为 clean 或 suspicious 的 Skills 会导出为 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