前言¶

要做技能目录、自动化安装流水线，或对接 ClawHub 的搜索与下载接口，往往要反复翻官方文档：哪些端点可以匿名访问、Bearer Token 怎么带、429 时该看哪些响应头。把说明写进对话上下文既占 token，也容易漏掉限流与写操作的风险。

下面介绍 SkillHub 上的 clh-api-guidance（坐标 @user_15292d5a/yjkj-clh-api-guidance）。它把 ClawHub API 的快速上手、认证、端点索引、典型场景示例和错误/限流处理整理成 Agent 可读的 SKILL 文档，让模型在写集成代码或排查 HTTP 问题时按同一套材料作答，而不是每次从零检索。

这是什么¶

clh-api-guidance 是一份面向开发者的 ClawHub API 使用指南 Skill（包内标题为 ClawHub API Guidance）。内容由社区发布者 user_15292d5a 维护，在 SkillHub 上归类为 knowledge-management，当前版本 1.0.0，来源为 community。Skill 卡片标明许可为 MIT-0，适用地域为 Global。

它解决的是：在 IDE 或 CLI Agent 会话中，如何稳定引用 ClawHub 的 Base URL（https://clawhub.ai）、公开读与需认证写的边界、以及配套参考文档（接口列表、数据模型、枚举），而不是替代 ClawHub 服务本身。

SkillHub 页面标注标签 requires_api_key=true：涉及写入、账户或部分受保护资源时，需要你在 ClawHub 账户中生成 API Key（格式 clh_...），并通过环境变量等方式注入，不应硬编码进仓库。

核心功能¶

以下能力均来自 Skill 包内 SKILL.md 与 reference/ 目录，可与安装后的文件逐项核对。

1. 快速开始
   说明如何获取 API Key、用 curl 或 Python requests 发起第一个调用（例如 GET /api/v1/search）。公开读取类端点可不携带 Token。

2. 认证说明
   Bearer Token 写法、Key 管理建议，以及 401/403 的常见含义。

3. API 接口索引
   主文档指向 reference/api-reference.md，声称覆盖 41 个接口；SKILL.md 中提供搜索、技能列表/详情、包目录、下载、whoami 等快速对照表，并区分技能、统一包目录、插件等类别。

4. 使用场景示例
   包内给出三类场景的步骤与 Python 示例：构建第三方技能目录（列表 + 搜索 + 回链规范 URL）、技能安全检查（moderation / scan / security 相关端点）、下载技能 ZIP 与读取技能内文件。

5. 最佳实践与运维向说明
   含错误处理、429 重试（Retry-After 与抖动）、简单缓存示例、环境变量存放密钥；另附错误码表与读写/下载的速率限制表（如读取约 3000/分钟每 IP、12000/分钟每 Key 等，以 Skill 文档记载为准）。

6. 公共目录复用指南
   强调缓存、遵守限流、链接回源、不绕过审核与私有边界等使用约束。

7. 附属参考
   reference/data-models.md（数据结构示例）、reference/enums.md（枚举取值）。

Skill 文档标注最后更新日期为 2026-06-03。Skill 卡片亦提示：端点、限额或响应形状可能变化，上线前应对照当前 ClawHub API 行为做验证。

安装与启用¶

通过 SkillHub CLI 安装¶

先确认本机是否已有 CLI：

command -v skillhub && skillhub --version

未安装时，可按 SkillHub 安装说明执行完整安装（示例为官方文档中的推荐命令）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

安装 Skill 时，必须用 --dir 指向当前 Agent 实际使用的 skills 目录；默认装到 ./skills/ 往往不会被客户端加载。

skillhub install @user_15292d5a/yjkj-clh-api-guidance --dir <你的 skills 目录>

社区包在 CLI 中可能以内部 slug yjkj-clh-api-guidance 解析；若带命名空间的写法失败，可尝试让 Agent 按 SkillHub 安装说明 处理坐标与目录。

SkillHub 技能页亦提供「让 AI 安装」的提示词，大意是：请根据 https://skillhub.cn/install/skillhub.md 安装 @user_15292d5a/yjkj-clh-api-guidance。

各客户端 skills 目录（节选）¶

以下为 SkillHub 安装文档中列出的常见路径，请按你当前使用的客户端择一：

装好后按各自客户端要求刷新或重启，使 Skill 被索引。启用后，在对话中描述 ClawHub 集成、搜索、下载或鉴权问题时，Agent 应优先读取该 Skill 中的 SKILL.md 与 reference/。

典型用法¶

1. 匿名搜索（验证环境与网络）¶

Skill 建议的第一步是不带认证的搜索请求：

curl -X GET "https://clawhub.ai/api/v1/search?q=example&limit=10"

等价 Python 示例：

import requests

response = requests.get(
    "https://clawhub.ai/api/v1/search",
    params={"q": "example", "limit": 10},
)
print(response.json())

这一步用于确认 Base URL 与参数格式；公开读取无需 Bearer Token。

2. 需要写操作或账户信息时¶

在请求头中携带 Token（示例格式来自 Skill 文档）：

Authorization: Bearer clh_...

Skill 建议通过环境变量读取密钥，例如 CLAWHUB_API_KEY，避免写入代码库。

3. 在 Agent 会话里引用完整接口表¶

当任务涉及具体路径、查询参数或响应字段时，让 Agent 结合本 Skill 打开 reference/api-reference.md，并对照 data-models.md、enums.md。列表类接口通常支持 cursor 分页；遇到 429 时按 Skill 中的重试逻辑处理 Retry-After。

4. 按场景套用包内示例¶

• 目录/搜索聚合：GET /api/v1/skills + GET /api/v1/search，注意限流与回链 https://clawhub.ai/<owner>/<slug> 一类规范 URL。
• 安装前安全检查：moderation、scan、包版本 security 等只读端点（示例见 SKILL.md 场景 2）。
• 下载与读文件：GET /api/v1/download 或包下载相关端点，以及 GET /api/v1/skills/{slug}/file（示例见场景 3）。

执行任何会改变账户、技能、包或所有权的请求前，Skill 卡片要求人工审阅并明确批准，尤其是删除、转移、发布类操作。

适用场景与注意¶

适合谁

• 正在用 Agent 编写 ClawHub API 集成、内部目录或安装工具的开发者。
• 需要在对话中快速查认证、限流、错误码，而不是每次打开浏览器翻多页文档的团队。

限制与注意

• 这是文档型 Skill，输出为 Markdown、curl、Python 等指导内容，不代替你方生产环境的密钥管理与合规审查。
• requires_api_key=true：真实写操作依赖有效 API Key；示例中的状态变更调用可能造成不可逆后果。
• 文档日期为 2026-06-03，ClawHub 线上行为若有变更，应以官方 OpenAPI/文档为准做差异核对。
• SkillHub 统计（抓取时）：评分 100000，下载 867，安装 0；社区来源，与 ClawHub 上同名技能页面（发布者 jason7602）为同一指南的不同分发渠道，集成时 Base URL 仍以 Skill 正文中的 clawhub.ai 为准。

结尾¶

若你的工作流已经围绕 ClawHub 的 /api/v1 展开，把 clh-api-guidance 装进 Agent 的 skills 目录，可以在一次会话里对齐认证、端点、限流与场景示例，减少反复查文档的成本。安装与元数据以 SkillHub 为准：

• API 入口：https://api.skillhub.cn/user_15292d5a/yjkj-clh-api-guidance
• 技能页：https://www.skillhub.cn/skills/user_15292d5a/yjkj-clh-api-guidance
• 坐标：@user_15292d5a/yjkj-clh-api-guidance，版本 1.0.0