快速开始

HTTP API

基础 URL：https://clawhub.ai（默认）。

所有 v1 路径均位于 /api/v1/... 下。为保持兼容性，旧版 /api/... 和 /api/cli/... 仍然保留（参见 DEPRECATIONS.md）。 OpenAPI：/api/v1/openapi.json。

公共目录复用

第三方目录可以使用公共读取端点列出或搜索 ClawHub Skills。请缓存结果、遵守 429/Retry-After、将用户链接回规范的 ClawHub 列表（https://clawhub.ai/<owner>/skills/<slug>），并避免暗示 ClawHub 为第三方网站背书。请勿尝试在公共 API 范围之外镜像隐藏、私有或被审核拦截的内容。

Web slug 快捷方式可跨注册表族解析，但 API 客户端应使用读取端点返回的规范 URL，而不是自行重建路由优先级。

速率限制

执行模型：

匿名请求：按 IP 执行限制。
已验证身份的请求（有效的 Bearer 令牌）：按用户存储桶执行限制。
如果令牌缺失或无效，则回退到按 IP 执行限制。
当服务器知道原因时，需要身份验证的写入端点不应仅返回 Unauthorized。对于令牌缺失、令牌无效或已撤销，以及账户已删除、被封禁或已停用等情况，应分别提供可操作的文本，以便 CLI 客户端告知用户具体的受阻原因。
读取：每个 IP 每分钟 3000 次，每个密钥每分钟 12000 次
写入：每个 IP 每分钟 300 次，每个密钥每分钟 3000 次
下载：每个 IP 每分钟 1200 次，每个密钥每分钟 6000 次（下载端点）

响应头：

旧版兼容：X-RateLimit-Limit、X-RateLimit-Reset
标准化：RateLimit-Limit、RateLimit-Reset
在 429 上：X-RateLimit-Remaining: 0 和 RateLimit-Remaining: 0
在 429 上：Retry-After

响应头语义：

X-RateLimit-Reset：绝对 Unix 纪元秒数
RateLimit-Reset：距离重置的秒数（延迟）
X-RateLimit-Remaining / RateLimit-Remaining：存在时表示准确的剩余配额。分片请求成功时会省略此响应头，而不会返回近似的全局值。
Retry-After：在 429 上重试前需要等待的秒数（延迟）

429 响应示例：

http

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

客户端指南：

如果存在 Retry-After，请等待指定秒数后再重试。
使用带抖动的退避策略，避免同步重试。
如果缺少 Retry-After，则回退到 RateLimit-Reset（或根据 X-RateLimit-Reset 计算）。

IP 来源：

仅当部署明确启用可信转发请求头时，才会使用可信客户端 IP 请求头，包括 cf-connecting-ip。
ClawHub 使用可信转发请求头在边缘识别客户端 IP。
如果没有可用的可信客户端 IP，匿名请求将使用仅按速率限制类型划分的回退存储桶。这些回退存储桶不包含调用方提供的路径、slug、软件包名称、版本、查询字符串或其他工件参数。

错误响应

公共 v1 错误响应是包含 content-type: text/plain; charset=utf-8 的纯文本。这包括验证失败（400）、公共资源缺失（404）、身份验证和权限失败（401/403）、速率限制（429）以及下载被拦截。客户端应将响应正文读取为人类可读的字符串。为保持兼容性，未知查询参数会被忽略，但值无效的已识别查询参数会返回 400。

公共端点（无需身份验证）

`GET /api/v1/search`

查询参数：

q（必填）：查询字符串
limit（可选）：整数
highlightedOnly（可选）：使用 true 筛选精选 Skills
nonSuspiciousOnly（可选）：使用 true 隐藏可疑（flagged.suspicious）Skills
nonSuspicious（可选）：nonSuspiciousOnly 的旧版别名

响应：

json

{  "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"      }    }  ]}

说明：

结果按相关性顺序返回（嵌入相似度 + 完全匹配 slug/名称词元的加权 + 较小的热度先验）。
相关性的权重高于热度。精确匹配 slug 或显示名称词元的结果，排名可以高于互动量高得多但匹配较宽泛的结果。
ASCII 文本按单词和标点边界进行词元化。例如，personal-map 包含独立的 map 词元，而 amap-jsapi-skill 包含 amap、jsapi 和 skill；因此，搜索 map 时，personal-map 的词法匹配强于 amap-jsapi-skill。
热度采用对数缩放并设有上限。当查询文本的匹配较弱时，高互动量的 Skills 也可能排名较低。
根据调用方筛选条件和当前审核状态，可疑或隐藏的审核状态可能会使 Skills 从公共搜索中移除。

发布者可发现性指南：

将用户实际会搜索的术语放入显示名称、摘要和标签中。仅当独立的 slug 词元也是你希望保留的稳定标识时才使用它。
不要仅为迎合某个查询而重命名 slug，除非新 slug 是更适合作为长期规范名称的选择。旧 slug 会成为重定向别名，但规范 URL、显示的 slug 和未来的搜索摘要将使用新 slug。
重命名别名会保留旧 URL 以及通过注册表进行解析的安装流程，但在重命名完成索引后，搜索排名将基于规范的 Skills 元数据。现有统计数据仍归属于该 Skills。
如果某个 Skills 意外不可见，请先在登录状态下使用 clawhub inspect @owner/slug 检查审核状态，然后再更改与排名相关的元数据。

`GET /api/v1/skills`

查询参数：

limit（可选）：整数（1–200）
cursor（可选）：用于任何非 trending 排序方式的分页游标
sort（可选）：updated（默认）、recommended（别名：default）、createdAt（别名：newest）、downloads、stars（别名：rating）；旧版安装别名 installsCurrent/installs/installsAllTime 映射到 downloads、trending
nonSuspiciousOnly（可选）：使用 true 隐藏可疑（flagged.suspicious）Skills
nonSuspicious（可选）：nonSuspiciousOnly 的旧版别名

无效的 sort 值会返回 400。

说明：

recommended 使用互动量和新近度信号。
trending 按最近 7 天内的安装次数排名（基于遥测数据）。
createdAt 对新 Skills 抓取保持稳定；现有 Skills 重新发布时，updated 会发生变化。
当 nonSuspiciousOnly=true 时，基于游标的排序在一页中返回的条目数可能少于 limit，因为可疑 Skills 会在获取页面后被筛除。
如果存在 nextCursor，请使用它继续分页。页面较短本身并不表示结果已结束。

响应：

json

{  "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}`

响应：

json

{  "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  }}

说明：

由所有者重命名/合并流程创建的旧 slug 会解析到规范 Skills。
metadata.os：Skills frontmatter 中声明的操作系统限制（例如 ["macos"]、["linux"]）。未声明时为 null。
metadata.systems：Nix 系统目标（例如 ["aarch64-darwin", "x86_64-linux"]）。未声明时为 null。
如果 Skills 没有平台元数据，metadata 为 null。
仅当 Skills 被标记或所有者正在查看时，才会包含 moderation。

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

返回结构化审核状态。

响应：

json

{  "moderation": {    "isSuspicious": true,    "isMalwareBlocked": false,    "verdict": "suspicious",    "reasonCodes": ["suspicious.dynamic_code_execution"],    "summary": "检测到：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": "检测到动态代码执行。",        "evidence": ""      }    ]  }}

说明：

所有者和审核员可以访问隐藏 Skills 的审核详情。
公共调用方仅能为已标记且可见的 Skills 获取 200。
面向公共调用方的证据会经过删减，仅向所有者/审核员提供原始代码片段。

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

举报 Skills 以供审核员审查。举报以 Skills 为单位，可以选择关联到某个版本，并进入 Skills 举报队列。

身份验证：

需要 API 令牌。

请求：

json

{ "reason": "安装步骤可疑", "version": "1.2.3" }

响应：

json

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

`GET /api/v1/skills/-/reports`

用于接收 Skills 举报的审核员/管理员端点。

查询参数：

status（可选）：open（默认）、confirmed、dismissed 或 all
limit（可选）：整数（1-200）
cursor（可选）：分页游标

响应：

json

{  "items": [    {      "reportId": "skillReports:...",      "skillId": "skills:...",      "skillVersionId": "skillVersions:...",      "slug": "gifgrep",      "displayName": "GifGrep",      "version": "1.2.3",      "reason": "可疑的安装步骤",      "status": "open",      "createdAt": 1730000000000,      "reporter": {        "userId": "users:...",        "handle": "reporter",        "displayName": "报告者"      },      "triagedAt": null,      "triagedBy": null,      "triageNote": null    }  ],  "nextCursor": null,  "done": true}

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

用于解决或重新打开技能报告的版主/管理员端点。

请求：

json

{ "status": "confirmed", "note": "已审查并隐藏受影响的版本。", "finalAction": "hide" }

note 是 confirmed 和 dismissed 的必填项；将 status 重新设置为 open 时可以省略。对已分流的报告传入 finalAction: "hide"，即可在同一可审计工作流中隐藏该技能。

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

查询参数：

limit（可选）：整数
cursor（可选）：分页游标

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

返回版本元数据和文件列表。

version.security 包含规范化的扫描验证状态和扫描器详细信息（VirusTotal + LLM，如可用）。

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

返回技能版本的安全扫描验证详细信息。

查询参数：

version（可选）：特定版本字符串。
tag（可选）：解析带标签的版本（例如 latest）。

注意：

如果既未提供 version，也未提供 tag，则使用最新版本。
包含规范化的验证状态以及各扫描器的详细信息。
仅当扫描器给出明确结论（clean、suspicious 或 malicious）时，security.hasScanResult 才为 true。
moderation 是根据最新版本得出的当前技能级审核快照。
查询历史版本时，在将 moderation 和 security 视为同一版本上下文之前，请检查 moderation.matchesRequestedVersion 和 moderation.sourceVersion。

`POST /api/v1/skills/-/scan`

用于提交新 ClawScan 任务的已验证身份端点。

不再支持本地上传扫描。使用 multipart/form-data 或 { "source": { "kind": "upload" } } 的请求将返回 410。

已发布扫描使用 JSON：

json

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

注意：

超过保留期限后，扫描请求负载和可下载报告将从扫描请求存储中失效。
已发布扫描要求拥有者/发布者管理访问权限，或平台版主/管理员权限。
仅当 update: true 且扫描成功完成时，已发布扫描才会回写。
响应为包含 { "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." } } 的 202。
扫描任务以异步方式运行。手动扫描请求的优先级高于普通发布/回填工作，但完成时间仍取决于工作进程的可用性。

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

用于轮询已提交扫描的已验证身份端点。

返回已排队/运行中/成功/失败状态。
排队期间返回 queue.queuedAhead 和 queue.position，以便客户端显示该请求之前有多少个优先手动扫描。超大队列会受到限制，并通过 queuedAheadIsEstimate: true 报告。
如可用，report 包含 clawscan、skillspector、staticAnalysis 和 virustotal 部分。
失败的扫描任务返回包含 lastError 的 status: "failed"。

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

已验证身份的报告归档端点。

要求扫描已成功；非终止状态的扫描返回 409。
返回一个 ZIP，其中包含 manifest.json、clawscan.json、skillspector.json、static-analysis.json、virustotal.json 和 README.md。

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

用于已提交版本的已验证身份存储报告归档端点。

要求拥有对技能或插件的拥有者/发布者管理访问权限，或平台版主/管理员权限。
返回所提交确切版本的已存储扫描结果，包括被阻止或隐藏的版本。
kind 默认为 skill；插件/软件包扫描请使用 kind=plugin。
返回与扫描请求下载相同结构的 ZIP。

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

仅限管理员使用的规范批量重新扫描路由。它接受与旧版 POST /api/v1/skills/-/rescan-batch 相同结构的负载。

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

仅限管理员使用的规范批量状态路由。它接受 { "jobIds": ["..."] }，并返回与旧版 POST /api/v1/skills/-/rescan-batch/status 相同的汇总计数器。

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

返回 clawhub skill verify 使用的技能卡验证信封。

查询参数：

version（可选）：特定版本字符串。
tag（可选）：解析带标签的版本（例如 latest）。

注意：

仅当所选版本已生成技能卡、未被审核机制因恶意软件而阻止且 ClawScan 验证结果为干净时，ok 才为 true。
技能身份、发布者身份和所选版本元数据是信封的顶层字段（slug、displayName、publisherHandle、version、resolvedFrom、tag、createdAt），因此 shell 自动化无需解包嵌套包装器即可读取它们。
security 是顶层 ClawScan/安全结论。自动化应以 ok、decision、reasons 和 security.status 为判断依据。
security.signals 包含支持性扫描器证据，例如 staticScan、virusTotal 和 skillSpector。
security.signals.dependencyRegistry 为兼容 v1 响应而保留，但依赖项注册表存在性扫描器已停用，此键始终为 null。
仅当 ClawHub 在发布或导入期间解析并存储了 GitHub 仓库/ref/提交/路径时，provenance 才为 server-resolved-github-import；否则为 unavailable。

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

返回确切技能版本的当前精简安全结论。此集合端点适用于已经知道需要显示哪些已安装 ClawHub 技能版本的客户端，例如 OpenClaw Control UI。

请求：

json

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

注意：

items 必须包含 1-100 个唯一的 { slug, version } 对。
结果按项目返回；某个技能或版本缺失不会导致整个响应失败。
响应仅包含安全信息。它不包含技能卡数据、已生成卡片状态、工件文件列表或详细扫描器负载。
security.signals 仅包含状态级支持证据；完整扫描器详细信息请使用 /scan 或 ClawHub 安全审计页面。
security.signals.dependencyRegistry 为兼容 v1 响应而保留，但依赖项注册表存在性扫描器已停用，此键始终为 null。
缺少技能卡不会影响此端点的 ok、decision 或 reasons；客户端需要卡片内容时，应在本地读取已安装的 skill-card.md。
需要单个技能的技能卡验证信封时使用 /verify，需要生成的卡片 Markdown 时使用 /card，需要详细扫描器数据时使用 /scan。

响应：

json

{  "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": "未找到版本" },      "security": null    }  ]}

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

将确切存储的文件字节作为下载返回。添加 preview=1 可请求有界的转义文本预览；只要文件字节是有效的 UTF-8，无论其扩展名或 MIME 元数据如何，都可以预览。

查询参数：

path（必填）
version（可选）
tag（可选）
preview=1（可选；字节不是有效 UTF-8 时返回 text/plain 或 415）

注意：

默认为最新版本。
原始下载限制：10MB。
文本预览限制：200KB。

`GET /api/v1/packages`

以下内容的统一目录端点：

技能
代码插件
捆绑插件

查询参数：

limit（可选）：整数（1–100）
cursor（可选）：分页游标
family（可选）：skill、code-plugin 或 bundle-plugin
channel（可选）：official、community 或 private
isOfficial（可选）：true 或 false
sort（可选）：updated（默认）、recommended、trending、downloads、旧版别名 installs
category（可选）：插件类别筛选器。仅当请求限定为插件软件包（/api/v1/plugins、 /api/v1/code-plugins、/api/v1/bundle-plugins，或包含 family=code-plugin/family=bundle-plugin 的软件包端点）时才受支持。受控类别和旧版 v1 筛选器别名记录在 GET /api/v1/plugins 下。

注意：

family、channel、isOfficial、featured、 highlightedOnly 或 sort 的无效值将返回 400。未知查询参数会被忽略。
GET /api/v1/code-plugins 和 GET /api/v1/bundle-plugins 保持为固定系列别名。
技能条目仍由技能注册表支持，并且仍只能通过 POST /api/v1/skills 发布。
POST /api/v1/packages 仍仅用于代码插件和捆绑插件版本。
匿名调用方只能看到公开软件包渠道。
已验证身份的调用方可以在列表/搜索结果中看到其所属发布者的私有软件包。
channel=private 仅返回已验证身份的调用方有权读取的软件包。

`GET /api/v1/packages/search`

跨技能和插件软件包的统一目录搜索。

查询参数：

q（必填）：查询字符串
limit（可选）：整数（1–100）
family（可选）：skill、code-plugin 或 bundle-plugin
channel（可选）：official、community 或 private
isOfficial（可选）：true 或 false
category（可选）：插件类别筛选器。仅当请求范围限定为插件包时才受支持。受控类别和旧版 v1 筛选器别名记录在 GET /api/v1/plugins 下。

注意：

family、channel、isOfficial、featured 或 highlightedOnly 的无效值会返回 400。未知的查询参数将被忽略。
匿名调用方只能看到公开包渠道。
经过身份验证的调用方可以搜索其所属发布者的私有包。
channel=private 仅返回经过身份验证的调用方可读取的包。

`GET /api/v1/plugins`

仅浏览代码插件包和插件包集合的插件目录。

查询参数：

limit（可选）：整数（1-100）
cursor（可选）：分页游标
isOfficial（可选）：true 或 false
sort（可选）：recommended（默认）、trending、downloads、updated、旧版别名 installs
category（可选）：插件类别筛选器。当前值： channels、models、memory、context、voice、media、web、 tools、runtime、gateway、security、other。

读取端点仍接受旧版 v1 筛选器别名：

mcp-tooling、data 和 automation 解析为 tools。
observability 和 deployment 解析为 gateway。
dev-tools 解析为 runtime。

trending 是按七天统计的安装/下载排行榜，不使用累计总数。在统一的 /api/v1/packages 端点上，它仅适用于插件；技能目录请使用 /api/v1/skills?sort=trending。

旧版别名不能用作存储的或作者声明的类别值。

`GET /api/v1/skills/export`

批量导出最新的公开技能，以供离线分析。

身份验证：

需要 API 令牌。

查询参数：

startDate（必填）：技能 updatedAt 的 Unix 毫秒时间下限。
endDate（必填）：技能 updatedAt 的 Unix 毫秒时间上限。
limit（可选）：整数（1-250），默认为 250。
cursor（可选）：来自上一次响应的分页游标。

响应：

正文：ZIP 归档。
每个导出的技能均以 {publisher}/{slug}/ 为根目录。
托管技能包含最新存储版本的文件，并在 _manifest.json 中以 sourceRef: "public-clawhub" 列出。
当前由 GitHub 支持且具有 clean 或 suspicious 扫描结果的技能包含 _source_handoff.json，其中含有 sourceRef: "public-github"、仓库、提交、路径、内容哈希和归档 URL。它们不包含由 ClawHub 托管的源文件。
每个技能都包含 _export_skill_meta.json。
_manifest.json 始终包含在 ZIP 根目录中。
当个别技能或文件无法导出时，将包含 _errors.json。

响应头：

X-Next-Cursor
X-Has-More
X-Total-Returned
X-Date-Range
X-Export-Errors

`GET /api/v1/plugins/export`

批量导出最新的公开插件版本，以供离线分析。

身份验证：

需要 API 令牌。

查询参数：

startDate（必填）：插件 updatedAt 的 Unix 毫秒时间下限。
endDate（必填）：插件 updatedAt 的 Unix 毫秒时间上限。
limit（可选）：整数（1-250），默认为 250。
cursor（可选）：来自上一次响应的分页游标。
family（可选）：code-plugin 或 bundle-plugin。省略表示同时包含两种插件系列。

响应：

正文：ZIP 归档。
每个导出的插件均以 {family}/{packageName}/ 为根目录。
每个导出的插件都包含最新版本所存储的文件。
每个插件的导出元数据存储在 __clawhub_export/{family}/{packageName}/plugin_meta.json。
_manifest.json 始终包含在 ZIP 根目录中。
当个别插件或文件无法导出时，将包含 _errors.json。

响应头：

X-Next-Cursor
X-Has-More
X-Total-Returned
X-Date-Range
X-Export-Errors

`GET /api/v1/plugins/search`

仅搜索代码插件包和插件包集合。

查询参数：

q（必填）：查询字符串
limit（可选）：整数（1-100）
isOfficial（可选）：true 或 false
category（可选）：插件类别筛选器。当前值： channels、models、memory、context、voice、media、web、 tools、runtime、gateway、security、other。

注意：

也接受记录在 GET /api/v1/plugins 下的旧版 v1 筛选器别名。
类别筛选是由插件类别摘要行支持的真实 API 筛选器，而不是对搜索查询的改写。
结果按相关性顺序返回，目前不支持分页。
浏览器 UI 中的插件搜索排序控件会对已加载的相关性结果重新排序，与当前 /skills 的浏览行为一致。

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

返回包的详细元数据。

注意：

在统一目录中，技能也可以通过此路由解析。
除非调用方可以读取所属发布者，否则私有包返回 404。

`DELETE /api/v1/packages/{name}`

软删除包及其所有版本。

注意：

需要包所有者、组织发布者的所有者/管理员、平台版主或平台管理员的 API 令牌。

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

返回版本历史记录。

查询参数：

limit（可选）：整数（1–100）
cursor（可选）：分页游标

注意：

除非调用方可以读取所属发布者，否则私有包返回 404。

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

返回单个包版本，包括文件元数据、兼容性、验证、工件元数据和扫描数据。

注意：

对于旧式包归档，version.artifact.kind 为 legacy-zip；对于由 ClawPack 支持的版本，则为 npm-pack。
ClawPack 版本包含与 npm 兼容的 npmIntegrity、npmShasum 和 npmTarballName 字段。
version.sha256hash 是面向旧客户端的已弃用兼容性元数据。它对 /api/v1/packages/{name}/download 返回的精确 ZIP 字节进行哈希计算。现代客户端应使用 version.artifact.sha256，它用于标识规范版本工件。
存在扫描数据时，会包含 version.vtAnalysis、version.llmAnalysis 和 version.staticScan。
除非调用方可以读取所属发布者，否则私有包返回 404。

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

向安装客户端返回确切的包版本安全与信任摘要。这是公开的 OpenClaw 使用界面，用于决定已解析的版本是否可以安装。

身份验证：

公开读取端点。不需要所有者、发布者、版主或管理员令牌。

响应：

json

{  "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  }}

响应字段：

package.name、package.displayName 和 package.family 标识已解析的注册表包。
release.releaseId、release.version 和 release.createdAt 标识经过评估的确切版本。
已知版本工件的相关信息时，会包含 release.artifactKind、release.artifactSha256、release.npmIntegrity、 release.npmShasum 和 release.npmTarballName。
trust.scanStatus 是根据扫描器输入和手动版本审核得出的有效信任状态。
trust.moderationState 可为空。不存在手动版本审核时，其值为 null。
trust.blockedFromDownload 是安装阻止信号。当此值为 true 时，OpenClaw 和其他安装客户端应阻止安装，而不是根据扫描器或审核字段重新推导阻止规则。
trust.reasons 是面向用户和审计的说明列表。原因代码是稳定且紧凑的字符串，例如 manual:quarantined、scan:malicious 和 package:malicious。
trust.pending 表示一个或多个信任输入仍在等待完成。
trust.stale 表示信任摘要是根据过时的输入计算得出的，在作出高置信度允许决定之前，应将其视为需要刷新。

注意：

此端点精确对应版本。客户端应在解析出准备安装的包版本后调用它，而不应仅在读取最新的包元数据后调用。
除非调用方可以读取所属发布者，否则私有包返回 404。
此端点有意比所有者/版主审核端点的范围更窄。它公开的是安装决定和公开说明，而不是举报者身份、举报正文、私有证据或内部审核时间线。

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

返回包版本的显式工件解析器元数据。

注意：

旧版包版本返回 legacy-zip 工件和旧版 ZIP downloadUrl。
ClawPack 版本返回 npm-pack 工件、npm 完整性字段、 tarballUrl 和旧版 ZIP 兼容性 URL。
这是 OpenClaw 解析器界面；它无需通过共享 URL 猜测归档格式。

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

通过显式解析器路径下载版本工件。

注意：

ClawPack 版本会流式传输已上传的 npm-pack .tgz 的精确字节。
旧版 ZIP 版本会重定向到 /api/v1/packages/{name}/download?version=。
使用下载速率桶。

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

返回为 OpenClaw 未来使用而计算的就绪状态。

就绪检查包括：

官方渠道状态
最新版本可用性
ClawPack npm-pack 工件可用性
工件摘要
源代码仓库和提交来源
OpenClaw 兼容性元数据
主机目标
扫描状态

响应：

json

{  "package": {    "name": "@openclaw/example-plugin",    "displayName": "示例插件",    "family": "code-plugin",    "isOfficial": true,    "latestVersion": "1.2.3"  },  "ready": false,  "checks": [    {      "id": "clawpack",      "label": "ClawPack 工件",      "status": "fail",      "message": "最新版本仅提供旧版 ZIP。"    }  ],  "blockers": ["clawpack"]}

`GET /api/v1/packages/migrations`

用于列出官方 OpenClaw 插件迁移记录的审核员端点。

身份验证：

需要审核员或管理员用户的 API 令牌。

查询参数：

phase（可选）：planned、published、clawpack-ready、 legacy-zip-only、metadata-ready、blocked、ready-for-openclaw 或 all（默认）。
limit（可选）：整数（1-100）
cursor（可选）：分页游标

响应：

json

{  "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": ["缺少 ClawPack"],      "hostTargetsComplete": true,      "scanClean": false,      "moderationApproved": false,      "runtimeBundlesReady": false,      "notes": null,      "createdAt": 1760000000000,      "updatedAt": 1760000000000    }  ],  "nextCursor": null,  "done": true}

`POST /api/v1/packages/migrations`

用于创建或更新官方插件迁移记录的管理员端点。

身份验证：

需要管理员用户的 API 令牌。

请求正文：

json

{  "bundledPluginId": "core.search",  "packageName": "@openclaw/search-plugin",  "owner": "platform",  "sourceRepo": "openclaw/openclaw",  "sourcePath": "plugins/search",  "sourceCommit": "abc123",  "phase": "blocked",  "blockers": ["缺少 ClawPack"],  "hostTargetsComplete": true,  "scanClean": false,  "moderationApproved": false,  "runtimeBundlesReady": false,  "notes": "正在等待发布者上传"}

注意：

bundledPluginId 会标准化为小写，并作为稳定的 upsert 键。
packageName 会按 npm 名称规则标准化；对于计划中的迁移，软件包可以不存在。
这仅跟踪迁移就绪状态，不会修改 OpenClaw 或生成 ClawPack。

`GET /api/v1/packages/moderation/queue`

用于软件包版本审核队列的审核员/管理员端点。

身份验证：

需要审核员或管理员用户的 API 令牌。

查询参数：

status（可选）：open（默认）、blocked、manual 或 all
limit（可选）：整数（1-100）
cursor（可选）：分页游标

状态含义：

open：可疑、恶意、待处理、已隔离、已撤销或已举报的版本。
blocked：已隔离、已撤销或恶意版本。
manual：任何具有手动审核覆盖设置的版本。
all：任何具有手动覆盖设置、非干净扫描状态或软件包举报的版本。

响应：

json

{  "items": [    {      "packageId": "packages:...",      "releaseId": "packageReleases:...",      "name": "@openclaw/example-plugin",      "displayName": "示例插件",      "family": "code-plugin",      "channel": "community",      "isOfficial": false,      "version": "1.2.3",      "createdAt": 1730000000000,      "artifactKind": "npm-pack",      "scanStatus": "malicious",      "moderationState": "quarantined",      "moderationReason": "人工审核",      "sourceRepo": "openclaw/example-plugin",      "sourceCommit": "abc123",      "reportCount": 2,      "lastReportedAt": 1730000001000,      "reasons": ["manual:quarantined", "scan:malicious", "reports:2"]    }  ],  "nextCursor": null,  "done": true}

`POST /api/v1/packages/{name}/report`

举报软件包以供审核员审查。举报以软件包为单位，可选择关联到某个版本。举报会进入审核队列，但本身不会自动隐藏软件包或阻止下载；审核员应使用版本审核来批准、隔离或撤销工件。

身份验证：

需要 API 令牌。

请求：

json

{ "reason": "可疑的原生二进制文件", "version": "1.2.3" }

响应：

json

{  "ok": true,  "reported": true,  "alreadyReported": false,  "packageId": "packages:...",  "releaseId": "packageReleases:...",  "reportCount": 1}

`GET /api/v1/packages/reports`

用于接收软件包举报的审核员/管理员端点。

身份验证：

需要审核员或管理员用户的 API 令牌。

查询参数：

status（可选）：open（默认）、confirmed、dismissed 或 all
limit（可选）：整数（1-100）
cursor（可选）：分页游标

响应：

json

{  "items": [    {      "reportId": "packageReports:...",      "packageId": "packages:...",      "releaseId": "packageReleases:...",      "name": "@openclaw/example-plugin",      "displayName": "示例插件",      "family": "code-plugin",      "version": "1.2.3",      "reason": "可疑的原生二进制文件",      "status": "open",      "createdAt": 1730000000000,      "reporter": {        "userId": "users:...",        "handle": "reporter",        "displayName": "举报者"      },      "triagedAt": null,      "triagedBy": null,      "triageNote": null    }  ],  "nextCursor": null,  "done": true}

`GET /api/v1/packages/{name}/moderation`

用于查看软件包审核可见性的所有者/审核员端点。

身份验证：

需要软件包所有者、发布者成员、审核员或管理员用户的 API 令牌。

响应：

json

{  "package": {    "packageId": "packages:...",    "name": "@openclaw/example-plugin",    "displayName": "示例插件",    "family": "code-plugin",    "channel": "community",    "isOfficial": false,    "reportCount": 2,    "lastReportedAt": 1730000001000,    "scanStatus": "malicious"  },  "latestRelease": {    "releaseId": "packageReleases:...",    "version": "1.2.3",    "artifactKind": "npm-pack",    "scanStatus": "malicious",    "moderationState": "quarantined",    "moderationReason": "人工审核",    "blockedFromDownload": true,    "reasons": ["manual:quarantined", "scan:malicious", "reports:2"],    "createdAt": 1730000000000  }}

`POST /api/v1/packages/reports/{reportId}/triage`

用于解决或重新打开软件包举报的审核员/管理员端点。

请求：

json

{  "status": "confirmed",  "note": "已审查并隔离受影响的版本。",  "finalAction": "quarantine"}

note 对于 confirmed 和 dismissed 是必需的；将 status 重新设置为 open 时可以省略。对已确认的举报传递 finalAction: "quarantine" 或 finalAction: "revoke"，即可在同一个可审计工作流中应用版本审核。

响应：

json

{  "ok": true,  "reportId": "packageReports:...",  "packageId": "packages:...",  "status": "confirmed",  "reportCount": 0}

`POST /api/v1/packages/{name}/versions/{version}/moderation`

用于软件包版本审核的审核员/管理员端点。

请求：

json

{ "state": "quarantined", "reason": "可疑的原生载荷。" }

支持的状态：

approved：已人工审核并允许。
quarantined：在后续处理前阻止。
revoked：先前受信任的版本之后被阻止。

已隔离和已撤销的版本会从工件下载路由返回 403。每次更改都会写入审计日志条目。

`GET /api/v1/packages/{name}/file`

以下载形式返回存储的软件包文件的精确字节。添加 preview=1 可请求用于技能文件的同一种有界 UTF-8 文本预览。

查询参数：

path（必需）
version（可选）
tag（可选）
preview=1（可选；字节不是有效 UTF-8 时返回 text/plain 或 415）

注意：

默认为最新版本。
使用读取速率桶，而不是下载速率桶。
原始下载限制：10MB。
文本预览限制：200KB；不透明文件仅在预览请求中返回 415。
待处理的 VirusTotal 扫描不会阻止读取；恶意版本在其他位置仍可能被阻止提供。
除非调用方可以读取所属发布者，否则私有软件包返回 404。

`GET /api/v1/packages/{name}/download`

下载软件包版本的旧版确定性 ZIP 归档。

查询参数：

version（可选）
tag（可选）

注意：

默认为最新版本。
Skills 会重定向到 GET /api/v1/download。
插件/软件包归档是以 package/ 为根目录的 zip 文件，以便旧版 OpenClaw 客户端继续工作。
此路由仅保留 ZIP，不会流式传输 ClawPack .tgz 文件。
响应包含 ETag、Digest、X-ClawHub-Artifact-Type 和 X-ClawHub-Artifact-Sha256 标头，用于解析器完整性检查。
仅注册表使用的元数据不会注入下载的归档。
待处理的 VirusTotal 扫描不会阻止下载；恶意版本返回 403。
除非调用方是所有者，否则私有软件包返回 404。

`GET /api/npm/{package}`

返回由 ClawPack 支持的软件包版本的 npm 兼容 packument。

注意：

仅列出已上传 ClawPack npm-pack tarball 的版本。
有意省略仅提供旧版 ZIP 的版本。
dist.tarball、dist.integrity 和 dist.shasum 使用 npm 兼容字段，因此用户可以选择将 npm 指向该镜像。
限定作用域软件包的 packument 同时支持 /api/npm/@scope/name 和 npm 的编码请求路径 /api/npm/@scope%2Fname。

`GET /api/npm/{package}/-/{tarball}.tgz`

为 npm 镜像客户端流式传输已上传 ClawPack tarball 的精确字节。

注意：

使用下载速率桶。
下载标头包含 ClawHub SHA-256，以及 npm integrity/shasum 元数据。
审核和私有软件包访问检查仍然适用。

`GET /api/v1/resolve`

由 CLI 用于将本地指纹映射到已知版本。

查询参数：

slug（必需）
hash（必需）：包指纹的 64 字符十六进制 sha256

响应：

json

{ "slug": "gifgrep", "match": { "version": "1.2.2" }, "latestVersion": { "version": "1.2.3" } }

`GET /api/v1/download`

下载托管的技能版本 ZIP；对于当前由 GitHub 支持、具有 clean 或 suspicious 扫描且没有托管版本的技能，则返回 GitHub 源代码移交信息。

查询参数：

slug（必填）
version（可选）：semver 字符串
tag（可选）：标签名称（例如 latest）

注意事项：

如果既未提供 version，也未提供 tag，则使用最新版本。
软删除的版本返回 410。
由 GitHub 支持的技能移交不会代理或镜像字节。JSON 响应包含 sourceRef: "public-github"、repo、commit、path、contentHash 和 archiveUrl；扫描/当前状态仅作为门控条件，不会作为成功载荷的元数据包含在内。
下载统计按 UTC 日内的唯一身份计数（API 令牌有效时使用 userId，否则使用 IP）。

身份验证端点（Bearer 令牌）

所有端点均要求：

Code

Authorization: Bearer clh_...

`GET /api/v1/whoami`

验证令牌并返回用户 handle。

`POST /api/v1/skills`

发布新版本。

首选：使用包含 payload JSON 和 files[] blob 的 multipart/form-data。
也接受包含 files（基于 storageId）的 JSON 正文。
可选载荷字段：ownerHandle。提供该字段时，API 会在服务器端解析该发布者，并要求执行者拥有该发布者的访问权限。
可选载荷字段：migrateOwner。当 true 与 ownerHandle 一同使用时，如果执行者同时是当前和目标发布者的管理员/所有者，则可将现有技能移交给该所有者。若未明确选择此选项，则拒绝更改所有者。

`POST /api/v1/packages`

发布代码插件或捆绑插件版本。

需要 Bearer 令牌身份验证。
需要 multipart/form-data。
允许的表单字段包括 payload、重复的 files blob，或一个 clawpack tarball 引用。clawpack 可以是 .tgz blob，也可以是上传 URL 流程返回的存储 ID。使用暂存存储 ID 发布时，还必须包含该上传 URL 返回的 clawpackUploadTicket。
使用 files 或 clawpack 中的任意一个，切勿在同一请求中同时使用二者。
拒绝 JSON 正文和调用方提供的 payload.files / payload.artifact 元数据。
直接 multipart 发布请求上限为 18MB。ClawPack tarball 可使用上传 URL 流程，最高达到 120MB 的 tarball 上限。
可选载荷字段：ownerHandle。提供该字段时，只有管理员可以代表该所有者发布。

验证要点：

family 必须为 code-plugin 或 bundle-plugin。
插件包需要 openclaw.plugin.json。ClawPack .tgz 上传必须在 package/openclaw.plugin.json 中包含该字段。
代码插件需要 package.json、源代码仓库元数据、源代码提交元数据、配置架构元数据、openclaw.compat.pluginApi 和 openclaw.build.openclawVersion。
openclaw.hostTargets 和 openclaw.environment 是可选元数据。
只有 openclaw 组织发布者和当前 openclaw 组织成员的个人发布者可以发布到 official 渠道。
代表他人发布时，仍会根据目标所有者账户验证官方渠道资格。

`DELETE /api/v1/skills/{slug}` / `POST /api/v1/skills/{slug}/undelete`

软删除/恢复技能（所有者、版主或管理员）。

可选 JSON 正文：

json

{ "reason": "因等待法律审查而暂缓，供版主管理。" }

提供 reason 时，它将存储为技能的版主管理备注，并复制到审计日志中。所有者发起的软删除会保留 slug 30 天，之后其他发布者可认领该 slug。当此过期规则适用时，删除响应会包含 slugReservedUntil。版主/管理员隐藏和安全移除不会以这种方式过期。

删除响应：

json

{ "ok": true, "slugReservedUntil": 1730000000000 }

状态码：

200：成功
401：未授权
403：禁止访问
404：未找到技能/用户
500：内部服务器错误

`POST /api/v1/users/publisher`

仅限管理员。确保指定 handle 存在组织发布者。如果该 handle 仍指向旧版共享用户/个人发布者，该端点会先将其迁移为组织发布者。对于新创建的组织，请提供 memberHandle；不会将执行操作的管理员添加为成员。 memberRole 默认为 owner。

正文：{ "handle": "openclaw", "displayName": "OpenClaw", "memberHandle": "alice", "memberRole": "owner", "trusted": true }
响应：{ "ok": true, "publisherId": "...", "handle": "openclaw", "created": true, "migrated": false, "trusted": true, "member": { "userId": "...", "handle": "alice", "role": "owner" } }

`POST /api/v1/publishers`

经过身份验证的自助式组织发布者创建。创建新的组织发布者，并将调用方添加为所有者。此端点不会迁移现有的用户/个人 handle，也不会将发布者标记为受信任/官方发布者。

正文：{ "handle": "opik", "displayName": "Opik" }
响应：{ "ok": true, "publisherId": "...", "handle": "opik", "created": true, "trusted": false }
当该 handle 已被发布者、用户或个人发布者使用时，返回 409。

`POST /api/v1/users/reserve`

仅限管理员。为合法所有者保留根 slug 和包名称，而不发布版本。包名称会成为没有版本行的私有占位包，因此同一所有者之后可以将真正的代码插件或捆绑插件版本发布到该名称下。

正文：{ "handle": "openclaw", "slugs": ["diffs"], "packageNames": ["@openclaw/diffs"], "reason": "reserved for official OpenClaw plugin" }
响应：{ "ok": true, "succeeded": 2, "failed": 0, "results": [{ "kind": "slug", "name": "diffs", "ok": true, "action": "reserved" }] }

`POST /api/v1/users/publisher-recovery`

仅限管理员。为经过验证的替代 GitHub OAuth 主体恢复个人发布者，无需编辑 Convex Auth 账户行。请求必须指定两个不可变的 GitHub 提供商账户 ID；可变 handle 仅用作面向操作员的防护条件。

该端点默认为试运行。应用恢复需要 dryRun: false 和 confirmIdentityVerified: true，且工作人员须独立验证两个 GitHub 主体之间的连续性。如果目标用户当前的个人发布者拥有技能、包或 GitHub 技能源，恢复将以失败关闭。恢复还会迁移已恢复发布者的技能、技能 slug 别名、包、包检查器警告和派生搜索摘要行中的旧版 ownerUserId 字段，使直接所有者路径与新的发布者权限保持一致。已恢复 handle 的有效受保护 handle 保留项也会重新分配给替代用户，以免后续个人资料同步恢复原用户相互冲突的权限。每个主表在每次应用事务中最多处理 100 行；规模更大的恢复必须先使用可恢复的所有者迁移。 GitHub 技能源以发布者为作用域，并报告为已检查，而不是重写。

正文：{ "handle": "gingiris", "nextUserHandle": "gingiris-1031", "previousGitHubProviderAccountId": "123", "nextGitHubProviderAccountId": "456", "reason": "Verified account continuity for issue #2555", "confirmIdentityVerified": true, "dryRun": false }
响应：{ "ok": true, "dryRun": false, "recovered": true, "publisherId": "...", "handle": "gingiris", "previousUser": { "userId": "...", "handle": "gingiris", "nextHandle": "gingiris-recovered", "githubProviderAccountId": "123", "authAccountCount": 1 }, "nextUser": { "userId": "...", "handle": "gingiris-1031", "nextHandle": "gingiris", "githubProviderAccountId": "456", "authAccountCount": 1 }, "retiredPersonalPublisher": null, "resourceOwnerMigration": { "limitPerTable": 100, "skills": 1, "skillSlugAliases": 1, "packages": 0, "packageInspectorWarnings": 0, "githubSourcesChecked": 1, "handleReservations": 1 }, "identityVerified": true, "reason": "Verified account continuity for issue #2555" }

所有者 slug 管理端点

POST /api/v1/skills/{slug}/rename
- 正文：{ "newSlug": "new-canonical-slug" }
- 响应：{ "ok": true, "slug": "new-canonical-slug", "previousSlug": "old-slug" }
POST /api/v1/skills/{slug}/merge
- 正文：{ "targetSlug": "canonical-target-slug" }
- 响应：{ "ok": true, "sourceSlug": "old-slug", "targetSlug": "canonical-target-slug" }

注意事项：

两个端点均需要 API 令牌身份验证，且仅适用于技能所有者。
rename 将以前的 slug 保留为重定向别名。
merge 会隐藏源列表，并将源 slug 重定向到目标列表。

所有权转移端点

POST /api/v1/skills/{slug}/transfer
- 正文：{ "toUserHandle": "target_handle", "message": "optional" }
- 响应：{ "ok": true, "transferId": "skillOwnershipTransfers:...", "toUserHandle": "target_handle", "expiresAt": 1730000000000 }
POST /api/v1/skills/{slug}/transfer/accept
POST /api/v1/skills/{slug}/transfer/reject
POST /api/v1/skills/{slug}/transfer/cancel
- 响应（接受/拒绝/取消）：{ "ok": true, "skillSlug": "demo-skill?" }
GET /api/v1/transfers/incoming
GET /api/v1/transfers/outgoing
- 响应结构：{ "transfers": [{ "_id": "...", "skill": { "slug": "demo", "displayName": "Demo" }, "fromUser"|"toUser": { "handle": "..." }, "message": "...", "requestedAt": 0, "expiresAt": 0 }] }

`POST /api/v1/users/ban`

封禁用户并硬删除其拥有的技能（仅限版主/管理员）。

正文：

json

{ "handle": "user_handle", "reason": "可选的封禁原因" }

或

json

{ "userId": "users_...", "reason": "可选的封禁原因" }

响应：

json

{ "ok": true, "alreadyBanned": false, "deletedSkills": 3 }

`POST /api/v1/users/unban`

解除用户封禁并恢复符合条件的技能（仅限管理员）。

正文：

json

{ "handle": "user_handle", "reason": "可选的解封原因" }

或

json

{ "userId": "users_...", "reason": "可选的解封原因" }

响应：

json

{ "ok": true, "alreadyUnbanned": false, "restoredSkills": 3 }

`POST /api/v1/users/reclassify-ban`

更改现有封禁所存储的原因，而不解除封禁或恢复内容（仅限管理员）。除非 dryRun 为 false，否则默认为试运行。

正文：

json

{ "handle": "user_handle", "reason": "批量发布垃圾内容", "dryRun": true }

或

json

{ "userId": "users_...", "reason": "批量发布垃圾内容", "dryRun": false }

响应：

json

{  "ok": true,  "dryRun": false,  "userId": "users_...",  "handle": "user_handle",  "previousReason": "恶意软件自动封禁",  "nextReason": "批量发布垃圾内容",  "changed": true}

`POST /api/v1/users/role`

更改用户角色（仅限管理员）。

正文：

json

{ "handle": "user_handle", "role": "moderator" }

或

json

{ "userId": "users_...", "role": "admin" }

响应：

json

{ "ok": true, "role": "moderator" }

`GET /api/v1/users`

列出或搜索用户（仅限管理员）。

查询参数：

q（可选）：搜索查询
query（可选）：q 的别名
limit（可选）：最大结果数（默认 20，最大 200）

响应：

json

{  "items": [    {      "userId": "users_...",      "handle": "user_handle",      "displayName": "用户",      "name": "用户",      "role": "moderator"    }  ],  "total": 1}

`POST /api/v1/stars/{slug}` / `DELETE /api/v1/stars/{slug}`

添加/移除书签。为保持兼容性，旧版 stars 路由和响应字段名称仍然保留。两个端点均具有幂等性。

响应：

json

{ "ok": true, "starred": true, "alreadyStarred": false }

json

{ "ok": true, "unstarred": true, "alreadyUnstarred": false }

旧版 CLI 端点（已弃用）

仍支持旧版 CLI：

GET /api/cli/whoami
POST /api/cli/upload-url
POST /api/cli/publish
POST /api/cli/telemetry/install
POST /api/cli/skill/delete
POST /api/cli/skill/undelete

移除计划请参阅 DEPRECATIONS.md。

POST /api/cli/upload-url 返回 uploadUrl 和 uploadTicket。暂存 ClawPack tarball 的包发布必须将生成的存储 ID 作为 clawpack 发送，并将返回的票据作为 clawpackUploadTicket 发送。

注册表发现（`/.well-known/clawhub.json`）

CLI 可以从站点发现注册表/身份验证设置：

/.well-known/clawhub.json（JSON，首选）
/.well-known/clawdhub.json（旧版）

架构：

json

{ "apiBase": "https://clawhub.ai", "authBase": "https://clawhub.ai", "minCliVersion": "0.0.5" }

如果自行托管，请提供此文件（或显式设置 CLAWHUB_REGISTRY；旧版为 CLAWDHUB_REGISTRY）。

Was this useful?

HTTP API

公共目录复用

速率限制

错误响应

公共端点（无需身份验证）

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=<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

GET /api/v1/packages/{name}

DELETE /api/v1/packages/{name}

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

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

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

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

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

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

GET /api/v1/packages/migrations

POST /api/v1/packages/migrations

GET /api/v1/packages/moderation/queue

POST /api/v1/packages/{name}/report

GET /api/v1/packages/reports

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

POST /api/v1/packages/reports/{reportId}/triage

POST /api/v1/packages/{name}/versions/{version}/moderation

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

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

GET /api/npm/{package}

GET /api/npm/{package}/-/{tarball}.tgz

GET /api/v1/resolve

GET /api/v1/download

身份验证端点（Bearer 令牌）

GET /api/v1/whoami

POST /api/v1/skills

POST /api/v1/packages

DELETE /api/v1/skills/{slug} / POST /api/v1/skills/{slug}/undelete

POST /api/v1/users/publisher

POST /api/v1/publishers

POST /api/v1/users/reserve

POST /api/v1/users/publisher-recovery

所有者 slug 管理端点

所有权转移端点

POST /api/v1/users/ban

POST /api/v1/users/unban

POST /api/v1/users/reclassify-ban

POST /api/v1/users/role

GET /api/v1/users

POST /api/v1/stars/{slug} / DELETE /api/v1/stars/{slug}

旧版 CLI 端点（已弃用）

注册表发现（/.well-known/clawhub.json）

On this page

`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=<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`

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

`DELETE /api/v1/packages/{name}`

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

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

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

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

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

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

`GET /api/v1/packages/migrations`

`POST /api/v1/packages/migrations`

`GET /api/v1/packages/moderation/queue`

`POST /api/v1/packages/{name}/report`

`GET /api/v1/packages/reports`

`GET /api/v1/packages/{name}/moderation`

`POST /api/v1/packages/reports/{reportId}/triage`

`POST /api/v1/packages/{name}/versions/{version}/moderation`

`GET /api/v1/packages/{name}/file`

`GET /api/v1/packages/{name}/download`

`GET /api/npm/{package}`

`GET /api/npm/{package}/-/{tarball}.tgz`

`GET /api/v1/resolve`

`GET /api/v1/download`

`GET /api/v1/whoami`

`POST /api/v1/skills`

`POST /api/v1/packages`

`DELETE /api/v1/skills/{slug}` / `POST /api/v1/skills/{slug}/undelete`

`POST /api/v1/users/publisher`

`POST /api/v1/publishers`

`POST /api/v1/users/reserve`

`POST /api/v1/users/publisher-recovery`

`POST /api/v1/users/ban`

`POST /api/v1/users/unban`

`POST /api/v1/users/reclassify-ban`

`POST /api/v1/users/role`

`GET /api/v1/users`

`POST /api/v1/stars/{slug}` / `DELETE /api/v1/stars/{slug}`

注册表发现（`/.well-known/clawhub.json`）