ClawHub

ClawHub 是 Clawdbot 的公共技能注册表：用于发布、版本化和搜索基于文本的智能体技能（包含 SKILL.md 及其支持文件）。它专为快速浏览和 CLI 友好的 API 设计，同时提供内容审核钩子和向量搜索功能。此外，它现在还公开了一个原生的 OpenClaw 包目录，用于管理代码插件和捆绑插件。

onlycrabs.ai 是 SOUL.md 注册表：以与发布技能相同的方式发布和分享系统背景故事。

ClawHub · onlycrabs.ai · 愿景 · 文档 · 贡献指南 · Discord

你可以用它做什么

• 浏览技能并渲染其 SKILL.md。
• 发布新版本的技能，附带变更日志和标签（包括 latest）。
• 在不破坏旧链接或安装的情况下重命名你拥有的技能。
• 将重复的自有技能合并为一个规范的别名。
• 浏览灵魂并渲染其 SOUL.md。
• 发布新版本的灵魂，并附带变更日志和标签。
• 使用嵌入向量（向量索引）进行搜索，而非依赖脆弱的关键字。
• 收藏和评论；管理员或版主可以对技能进行精选和批准。
• 浏览 OpenClaw 包，并查看其家族、信任度和能力元数据。
• 通过 /packages API 和 CLI 流程发布原生代码插件和捆绑插件。

onlycrabs.ai（SOUL.md 注册表）

• 入口是基于主机的：onlycrabs.ai。
• 在 onlycrabs.ai 主机上，首页和导航默认显示灵魂。
• 在 ClawHub 上，灵魂位于 /souls 路径下。
• 灵魂包目前仅接受 SOUL.md 文件（不支持其他文件）。

工作原理（高层次）

• Web 应用：TanStack Start（React、Vite/Nitro）。
• 后端：Convex（数据库、文件存储和 HTTP 操作）+ Convex Auth（GitHub OAuth）。
• 搜索：使用 OpenAI 嵌入模型（text-embedding-3-small）结合 Convex 向量搜索。
• API 架构和路由：packages/schema（clawhub-schema）。

CLI

常用 CLI 流程：

• 认证：clawhub login、clawhub whoami
• 发现：clawhub search ...、clawhub explore
• 浏览统一目录（技能 + 插件）：clawhub package explore、clawhub package inspect <name>
• 管理本地安装：clawhub install <slug>、clawhub uninstall <slug>、clawhub list、clawhub update --all
• 不安装直接检查：clawhub inspect <slug>
• 发布/同步技能：clawhub skill publish <path>、clawhub sync
• 发布插件：clawhub package publish <source>
• 规范化自有技能：clawhub skill rename <slug> <new-slug>、clawhub skill merge <source> <target>

文档：docs/quickstart.md、docs/cli.md。

删除权限

• clawhub uninstall <slug> 仅会移除你本机上的本地安装。
• 已上传到注册表的技能采用软删除/恢复机制（clawhub delete <slug> / clawhub undelete <slug> 或等效的 API 操作）。
• 软删除/恢复操作允许技能所有者、版主和管理员执行。
• 硬删除仅限管理员操作（通过管理工具或封禁流程）。
• 所有者重命名时，旧的别名 slug 会保留为重定向别名。
• 所有者合并时，源条目将被隐藏，旧的 slug 会被重定向到规范的目标。

遥测

ClawHub 会在你登录状态下运行 clawhub sync 时，收集最少的 安装遥测数据（用于计算安装次数）。 可通过以下方式禁用：

export CLAWHUB_DISABLE_TELEMETRY=1

详情请参阅 docs/telemetry.md。

仓库结构

• src/ — TanStack Start 应用（路由、组件、样式）。
• convex/ — 架构、查询/变更/动作以及 HTTP API 路由。
• packages/schema/ — CLI 和应用共享的 API 类型及路由。
• docs/ — 项目文档（架构、CLI、认证、部署等）。
• docs/spec.md — 产品与实现规格说明（适合初次阅读）。

本地开发

先决条件：Bun（Convex 通过 bunx 运行，无需全局安装）。

bun install
cp .env.local.example .env.local
# 编辑 .env.local — 请参考 CONTRIBUTING.md 获取本地 Convex 配置值

# 终端 A：本地 Convex 后端
bunx convex dev

# 终端 B：Web 应用（端口 3000）
bun run dev

# 种植示例数据
bunx convex run --no-push devSeed:seedNixSkills

完整设置说明（环境变量、GitHub OAuth、JWT 密钥、数据库种子等），请参阅 CONTRIBUTING.md。

环境变量

• VITE_CONVEX_URL：Convex 部署 URL（https://<deployment>.convex.cloud）。
• VITE_CONVEX_SITE_URL：Convex 站点 URL（https://<deployment>.convex.site）。
• VITE_SOULHUB_SITE_URL：onlycrabs.ai 站点 URL（https://onlycrabs.ai）。
• VITE_SOULHUB_HOST：onlycrabs.ai 主机匹配（onlycrabs.ai）。
• VITE_SITE_MODE：SSR 构建的可选覆盖模式（skills 或 souls）。
• CONVEX_SITE_URL：与 VITE_CONVEX_SITE_URL 相同（认证和 Cookie）。
• SITE_URL：应用 URL（本地：http://localhost:3000）。
• AUTH_GITHUB_ID / AUTH_GITHUB_SECRET：GitHub OAuth 应用程序。
• JWT_PRIVATE_KEY / JWKS：Convex Auth 密钥。
• OPENAI_API_KEY：用于搜索和索引的嵌入模型 API 密钥。

Nix 插件（nixmode 技能）

ClawHub 可以在 SKILL 的 frontmatter 中存储一个 nix-clawdbot 插件指针，以便注册表知道要安装哪个 Nix 软件包束。Nix 插件与常规技能包不同：它将技能包、CLI 二进制文件及其配置标志/要求打包在一起。

将以下内容添加到 SKILL.md：

---
name: peekaboo
description: 使用 Peekaboo CLI 捕获并自动化 macOS UI。
metadata:
  {
    "clawdbot":
      {
        "nix":
          {
            "plugin": "github:clawdbot/nix-steipete-tools?dir=tools/peekaboo",
            "systems": ["aarch64-darwin"],
          },
      },
  }
---

通过 nix-clawdbot 安装：

programs.clawdbot.plugins = [
  { source = "github:clawdbot/nix-steipete-tools?dir=tools/peekaboo"; }
];

你还可以声明配置要求以及示例片段：

---
name: padel
description: 通过 Playtomic 查看帕德尔球场可用情况并管理预订。
metadata:
  {
    "clawdbot":
      {
        "config":
          {
            "requiredEnv": ["PADEL_AUTH_FILE"],
            "stateDirs": [".config/padel"],
            "example": "config = { env = { PADEL_AUTH_FILE = \"/run/agenix/padel-auth\"; }; };",
          },
      },
  }
---

为了显示 CLI 帮助信息（建议用于 Nix 插件），请包含 cli --help 的输出：

---
name: padel
description: 通过 Playtomic 查看帕德尔球场可用情况并管理预订。
metadata: { "clawdbot": { "cliHelp": "padel --help\\n用法: padel [命令]\\n" } }
---

推荐使用 metadata.clawdbot，但也接受 metadata.clawdis 和 metadata.openclaw 作为别名。

技能元数据

技能会在 SKILL.md 的 frontmatter 中声明其运行时要求（环境变量、二进制文件、安装规范）。ClawHub 的安全分析会将这些声明与技能的实际行为进行比对。

完整参考：docs/skill-format.md

快速示例：

---
name: my-skill
description: 使用 API 做某件事。
metadata:
  openclaw:
    requires:
      env:
        - MY_API_KEY
      bins:
        - curl
    primaryEnv: MY_API_KEY
---

脚本

bun run dev
bun run build
bun run test
bun run coverage
bun run lint

ClawHub 快速上手指南

ClawHub 是 Clawdbot 的公共技能注册中心，支持发布、版本管理和搜索基于文本的 Agent 技能（SKILL.md）及代码插件。它提供 Web 浏览界面和友好的 CLI 工具，并集成了向量搜索功能。

环境准备

系统要求

• 操作系统：Linux / macOS / Windows (WSL)
• 网络：需能访问 GitHub 和 Convex 云服务

前置依赖

本项目使用 Bun 作为运行时和包管理器（Convex 通过 bunx 运行，无需全局安装）。

1. 安装 Bun：

   curl -fsSL https://bun.sh/install | bash
   

   注：国内用户若下载缓慢，可尝试使用镜像源或手动下载安装包。

2. 确保已拥有 GitHub 账号（用于登录认证）。

安装步骤

1. 克隆项目

git clone https://github.com/openclaw/clawhub.git
cd clawhub

2. 安装依赖

bun install

3. 配置环境变量

复制示例配置文件并根据需要修改（本地开发通常只需确认 Convex 相关配置）：

cp .env.local.example .env.local

提示：具体的本地 Convex 值和 GitHub OAuth 配置请参考项目根目录的 CONTRIBUTING.md。

4. 启动开发环境

你需要开启两个终端窗口分别运行后端和前端。

终端 A：启动本地 Convex 后端

bunx convex dev

终端 B：启动 Web 应用（默认端口 3000）

bun run dev

5. 种子数据（可选）

如需加载示例技能数据以便测试：

bunx convex run --no-push devSeed:seedNixSkills

启动完成后，访问 http://localhost:3000 即可看到 ClawHub 界面。

基本使用

ClawHub 的核心功能主要通过 CLI 工具进行交互。在使用前，请确保你已通过 clawhub login 登录。

1. 认证登录

使用 GitHub 账号登录：

clawhub login

查看当前登录用户信息：

clawhub whoami

2. 浏览与搜索技能

探索可用的技能库：

clawhub explore

通过向量嵌入（语义）搜索技能，而非简单的关键词匹配：

clawhub search <query>

查看特定技能的详细信息（无需安装）：

clawhub inspect <slug>

3. 安装与管理技能

安装指定技能到本地：

clawhub install <slug>

列出已安装的本地技能：

clawhub list

更新所有已安装的技能：

clawhub update --all

卸载本地技能（仅移除本地文件，不影响注册表）：

clawhub uninstall <slug>

4. 发布技能

将本地的技能目录发布到注册中心（包含版本变更日志和标签）：

clawhub skill publish <path>

同步本地状态：

clawhub sync

5. 高级管理（所有者权限）

重命名技能（旧链接会自动重定向）：

clawhub skill rename <slug> <new-slug>

合并重复的技能：

clawhub skill merge <source> <target>

关闭遥测（可选）

ClawHub 默认收集最小化的安装统计数据。如需禁用，可在运行命令前设置环境变量：

export CLAWHUB_DISABLE_TELEMETRY=1