杀了现在，也便杀了将来。——鲁迅

ClawHub：给 OpenClaw 找技能的“港口”，也是技能作者的“发布台”

openclaw/clawhub 的仓库描述只有一句话，却很像一句自我介绍时递出的名片：

Skill Directory for OpenClaw

ClawHub 就像一个很会收纳、也很讲秩序的管理员：它把 OpenClaw 世界里的“技能（skill）”集中安置在一个公共目录里，让使用者能搜索、安装、更新；也让作者能发布、打 tag、写 changelog、把版本管理得像一套正经软件一样有脾气、有记忆。

它还有一个自己的线上门牌号：

https://clawhub.ai

如果把它拟人化一点：ClawHub 像一个码头。
船（技能包）从各处驶来，带着版本号、说明书、文件清单、还有它的来历；码头把它们登记、分拣、贴标、公开展示；旅人（用户）则在这里挑选、下载、装进自己的工作目录里，然后继续上路。

它的基本气质：公开可读、写入需认证，节奏由限流守护

在 ClawHub 的 API v1 约定里，它把规则写得很清楚：

  • Public read：不需要 token
  • Write + account：需要 Authorization: Bearer clh_...

它还很认真地管理“人流”：

  • 匿名请求按 IP 限流
  • 带有效 Bearer token 的请求按用户桶限流
  • token 缺失/无效会退回按 IP 处理

并且把读写的节奏区分开来：

  • Read：120/min per IP，600/min per key
  • Write：30/min per IP，120/min per key

就像一个经验老到的门卫：看热闹欢迎，搬东西要出示通行证；人太多时会递上一张“稍后再来”的号码牌（429），并把你该等多久写在 Retry-After 里。

一眼能看懂的“公共目录”：API v1 的核心入口

ClawHub 的公共 API（v1）非常像一个规整的服务台，最常用的“窗口”都摆在明面上：

  • GET /api/v1/search?q=...：搜索
  • GET /api/v1/skills?limit=&cursor=&sort=：列表（支持排序）
    • sort 支持：updated（默认）、downloads、stars（别名 rating）、installsCurrent（别名 installs）、installsAllTime、trending
  • GET /api/v1/skills/{slug}：单个 skill
  • GET /api/v1/skills/{slug}/versions...：版本列表与详情
  • GET /api/v1/skills/{slug}/file?path=&version=&tag=：取文件
  • GET /api/v1/download?slug=&version=&tag=：下载
  • GET /api/v1/whoami：验证身份（需认证）

如果你把 ClawHub 当作一个角色，它会说：“我不神秘。你想怎么取数据、怎么把数据装走，路线我都给你画好了。”

CLI：ClawHub 的“随身工具箱”，把技能装进你的工作目录

ClawHub 不只给你网页和 API，它还有一个 CLI，而且它把 CLI 的脾气、旗帜、习惯写得相当细。

CLI 是什么、在哪里

  • CLI 包在 packages/clawdhub/
  • 发布名是 clawhub
  • 可执行文件（bin）也是 clawhub

在仓库里可以用 wrapper 方式运行：

1
bun clawhub --help

这就像 ClawHub 把一把瑞士军刀递给你：“不用开网页，你在终端里就能跟我说话。”

全局旗帜：工作目录、安装目录、站点与注册表

CLI 有一组全局 flags，控制它“走哪条路、把东西放哪儿”：

  • --workdir <dir>：工作目录（默认当前目录）
  • --dir <dir>：安装目录（默认 skills，位于 workdir 下）
  • --site <url>：浏览器登录用的站点（默认 https://clawhub.ai）
  • --registry <url>：API base（默认自动发现，否则 https://clawhub.ai）
  • --no-input：不交互

并且提供环境变量等价物：

  • CLAWHUB_SITE（兼容旧名 CLAWDHUB_SITE）
  • CLAWHUB_REGISTRY（兼容旧名 CLAWDHUB_REGISTRY）
  • CLAWHUB_WORKDIR（兼容旧名 CLAWDHUB_WORKDIR）

它像一个做事很有边界感的助手：你不说，它就用默认；你说了，它就照做，并且把“旧称呼”也照顾到，免得老用户迷路。

代理支持：在受限网络里也能把技能带回家

CLI 明确尊重标准代理变量：

  • HTTPS_PROXY / https_proxy
  • HTTP_PROXY / http_proxy
  • NO_PROXY / no_proxy

示例是这样写的：

1
2
3
export HTTPS_PROXY=http://proxy.example.com:3128
export NO_PROXY=localhost,127.0.0.1
clawhub search "my query"

这就像它在对你说：“你被公司网络拦住了？没关系，你告诉我从哪条隧道走，我照样把东西带回来。”

配置文件：把 token 收好，也把 registry 记住

CLI 的配置文件存储 API token + 缓存的 registry URL。

  • macOS 路径：~/Library/Application Support/clawhub/config.json
  • 可用 CLAWHUB_CONFIG_PATH 覆盖（兼容旧名 CLAWDHUB_CONFIG_PATH）

它很像一个谨慎的小账本：不把钥匙丢在桌面上，而是放进抽屉里。

CLI 命令群像：从“逛街”到“搬家”再到“开店”

ClawHub 的 CLI 命令列表读起来很像一个完整的生活系统：你可以先逛、再挑、再装、再更新；你也可以开店发布自己的技能；甚至还能做管理操作（转让、隐藏、恢复）。

下面是它在文档里明确写出的命令能力（按功能分组讲故事）：

1）登录与身份确认

  • login / auth login
    • 默认：打开浏览器到 <site>/cli/auth，并通过 loopback callback 完成
    • 无头（headless）：clawhub login --token clh_...
  • whoami
    • 通过 /api/v1/whoami 验证存储的 token

像是它先递给你一张通行证，再带你过闸机。

2）搜索与浏览：先看世界长什么样

  • search <query...>
    • 调用 /api/v1/search?q=...
  • explore
    • 列出最新更新的 skills（按 updatedAt 倒序）
    • 支持：
      • --limit <n>（1-200，默认 25）
      • --sort newest|downloads|rating|installs|installsAllTime|trending
      • --json
    • 输出形态：<slug> v<version> <age> <summary>（summary 截断到 50 字符）

它像一个会推荐“新上架”的书店店员：你不想搜？那我给你列最新的。

3）检查与安装：把技能带回本地

  • inspect <slug>
    • 不安装就能查看 metadata / 版本 / 文件
    • 支持 --version、--tag、--versions、--files、--file <path>、--json
    • 文档说明 text 文件有 200KB 限制
  • install <slug>
    • 解析最新版本：/api/v1/skills/<slug>
    • 下载 zip：/api/v1/download
    • 解压到：<workdir>/<dir>/<slug>
    • 写入：
      • <workdir>/.clawhub/lock.json（兼容 legacy .clawdhub）
      • <skill>/.clawhub/origin.json（兼容 legacy .clawdhub）

它做事很像一个管家：不仅把包裹拆好放到房间里，还把“我从哪儿拿的、拿的是哪个版本”记录在案。

4）卸载、列表与更新：让本地保持干净与可控

  • uninstall <slug>
    • 删除 <workdir>/<dir>/<slug> 并移除锁条目
    • 非交互时需要 --yes
  • list
    • 读取 <workdir>/.clawhub/lock.json
  • update [slug] / update --all
    • 计算本地文件指纹
    • 指纹匹配已知版本：不提示
    • 不匹配：默认拒绝，--force 可覆盖

这套规则很像一个严格但善意的管理员：你可以改本地文件，但我不会悄悄把你的改动冲掉；除非你明确告诉我“就覆盖吧”。

5）收藏与高亮：给喜欢的技能点星星

  • star <slug> / unstar <slug>
    • 调用 POST /api/v1/stars/<slug> 与 DELETE /api/v1/stars/<slug>
    • --yes 跳过确认

它像一个会记住你喜好的推荐系统：你点亮一颗星，它就知道你想把这项技能留在视线里。

6）发布与同步：当你想从用户变成作者

  • publish <path>
    • POST /api/v1/skills（multipart）
    • 需要 --version 1.2.3（semver）
    • 文档写明：发布到 ClawHub 的 skill 将以 MIT-0 释放，可自由使用、修改、再分发且无需署名
  • sync
    • 扫描本地 skill 目录并发布新增/变更
    • root 可以是 skills 目录，或包含 SKILL.md 的单个 skill 文件夹
    • 自动添加 Clawdbot 的 skill roots（当 ~/.clawdbot/clawdbot.json 存在时），并列出多种来源路径
    • flags：
      • --root <dir...>
      • --all、--dry-run
      • --bump patch|minor|major（默认 patch）
      • --changelog <text>（非交互）
      • --tags a,b,c（默认 latest）
      • --concurrency <n>（默认 4）
    • Telemetry：登录时在 sync 期间发送，可用 CLAWHUB_DISABLE_TELEMETRY=1 关闭

它像一个愿意��舞台让出来的主持人：你不只是观众，你也可以把自己的作品带上台，并且它会帮你管理版本与变更记录。

7）隐藏/恢复/转让：技能也有“生命周期管理”

  • delete <slug>：软删除（owner/mod/admin），--yes 跳过确认
  • undelete <slug>：恢复隐藏技能
  • hide/unhide：分别是 delete/undelete 的别名
  • transfer：所有权转让工作流（request/list/accept/reject/cancel），并列出对应 API

它像一个对秩序负责的城管：能撤下、能恢复，也能把店铺交接给新主人。

Public REST API + CLI：两条腿一起走

ClawHub 的姿态很明确：
它既给“人”准备了网页/目录，也给“工具”准备了 API 与 CLI。

你可以用 API 做客户端、做自动化；也可以用 CLI 把流程串成脚本。比如：

  • 用 API 搜索：GET /api/v1/search?q=...
  • 用 CLI 搜索：clawhub search "..."

这两条路通向同一个港口，只是你选择坐船还是走桥。

本地开发：ClawHub 是“两个可部署体”，而你可以在本机把它们都叫醒

在贡献指南里，ClawHub 把本地开发写成一套明确的仪式：

1）准备工具

  • Bun（Convex CLI 通过 bunx 运行）
  • Node.js v18/20/22/24（并说明 v25+ 暂不支持）

2）安装与配置

1
2
bun install
cp .env.local.example .env.local

并给出本地 Convex 的环境变量示例（放在 .env.local）：

1
2
3
4
VITE_CONVEX_URL=http://127.0.0.1:3210
VITE_CONVEX_SITE_URL=http://127.0.0.1:3210
SITE_URL=http://localhost:3000
CONVEX_DEPLOYMENT=anonymous:anonymous-clawhub

3）启动后端（Convex）

1
bunx convex dev --typecheck=disable

然后在另一个终端设置后端环境变量（Convex 有自己的 env store）：

1
2
3
bunx convex env set AUTH_GITHUB_ID <your-client-id>
bunx convex env set AUTH_GITHUB_SECRET <your-client-secret>
bunx convex env set SITE_URL http://localhost:3000

并生成 JWT keys（Convex Auth）：

1
bunx @convex-dev/auth

4）启动前端

1
bun run dev -- --port 3000

5）给 UI 喂点数据（seed）

1
2
3
bunx convex run --no-push devSeed:seedNixSkills
bunx convex run --no-push devSeedExtra:seedExtraSkillsInternal
bunx convex run --no-push statsMaintenance:updateGlobalStatsInternal

如果想重置再来：

1
bunx convex run --no-push devSeed:seedNixSkills '{"reset": true}'

这套流程读起来像是 ClawHub 在说：“我不怕你来改我，我还会带你一步步把我跑起来。”

CLI 也能对接你的本地实例

贡献指南还给了一个很具体的例子：让 CLI 指向你的本地 registry 与 site：

1
CLAWHUB_REGISTRY=http://127.0.0.1:3210 CLAWHUB_SITE=http://localhost:3000 clawhub search "padel"

像是它在对 CLI 说：“别只盯着线上那个大港口，你也可以在本地搭一个小码头，照样跑完整套流程。”

ClawHub 的一颗“产品脑”：它把自己要做什么写成了 spec

在 docs/spec.md 里，ClawHub 把目标写得很像一份工程宣言（我按要点整理叙述）：

  • 用一个简洁快速的 SPA 浏览与发布 agent skills
  • skills 存储在 Convex（文件 + metadata + versions + stats）
  • GitHub OAuth 登录
  • GitHub App 备份 skills 到 clawdbot/skills
  • 基于向量的搜索（skill 文本 + metadata）
  • 版本管理、tags（latest + 用户 tags）、changelog、rollback
  • Public read；上传需要 auth
  • Moderation：徽章、评论删除、审计记录

它还列了非目标（v1）：不做付费、私有 skills、二进制资产；GitHub App 同步暂时只做备份。

如果它是个人，它会很像一个项目经理：目标、边界、阶段性不做什么，都写得清清楚楚。

最后：ClawHub 想成为“技能世界的目录”，而不是又一个孤立仓库

ClawHub 的定位很纯粹：它是 OpenClaw 的公共技能注册表与目录。
它的存在感不是靠“炫技”，而是靠“把技能这件事做成基础设施”。

当你需要一个技能时，它会帮你找到它；当你写出一个技能时，它会帮你把它发布出去；当技能变多、世界变嘈杂时，它又会用版本、标签、搜索、限流与审核把秩序稳住。

它像一个认真守夜的人：不抢舞台，但一定把灯点亮。