skillhub/docs/openclaw-integration.md

OpenClaw 集成指南

本文档说明如何配置 ClawHub CLI 连接到 SkillHub 私有注册中心，实现技能的搜索、查看和安装。发布技能请使用第一方 SkillHub CLI。

不仅适用于 Openclaw，通过指定安装目录，可适用于其他的 CLI Coding Agent (Claude Code、OpenCode、Qcoder等) 或者 Agent 助手（Nanobot、CoPaw等）。

概述

SkillHub 提供 ClawHub 兼容 API，覆盖常用的只读发现和安装流程。通过简单配置，您可以：

• 🔍 搜索组织内的私有技能
• 📥 下载和安装技能包
• ⭐ 收藏技能

当前兼容边界：

• 已验证的 ClawHub CLI 0.23.3 使用 /api/v1/whoami，与 SkillHub 兼容层一致。
• ClawHub CLI 的发布协议依赖 SkillHub 未实现的上传票据接口，因此 clawhub publish 和 clawhub sync 不属于支持范围。
• ClawHub CLI 0.23.3 不会可靠地优先使用登录时保存的私有 Registry；站点发现或默认地址可能覆盖预期目标。每个终端会话都应设置 CLAWHUB_REGISTRY，或在命令中显式传入 --registry。
• canonical slug 使用 -- 分隔 namespace 与 skill。SkillHub 会拒绝新建包含连续 -- 的 namespace 或 skill slug，以保证新坐标可无歧义解析；历史或外部导入的异常坐标应先重命名，再使用 ClawHub CLI。

快速开始

1. 配置 Registry 地址

为当前终端会话设置 SkillHub 注册中心地址：

# 不依赖 login 配置的 Registry 解析顺序
export CLAWHUB_REGISTRY=https://skillhub.your-company.com

2. 登录认证（可选）

对于全局命名空间（@global）的公开技能（PUBLIC），无需登录即可下载。对于以下情况需要认证：

• 团队命名空间的技能（无论可见性）
• NAMESPACE_ONLY 或 PRIVATE 技能
• 收藏等需要登录的操作

# 使用 API Token 登录
npx clawhub login --token YOUR_API_TOKEN
# 如果使用 npm i -g clawhub 安装过 clawhub，文档中所有的 npx clawhub 命令都可以直接使用 clawhub 命令来执行

# 查看当前登录用户
npx clawhub whoami

# 退出当前用户登录
npx clawhub logout

# 查看帮助
npx clawhub --help

获取 API Token

1. 登录 SkillHub Web UI
2. 进入 个人设置 → API Tokens
3. 点击 创建新 Token
4. 设置 Token 名称和权限范围
5. 复制生成的 Token

3. 搜索/浏览/查看技能

# 搜索，显示所有相关技能
npx clawhub search <skill-name>
# 搜索，结果显示前 5 个结果
npx clawhub search <skill-name> --limit 5  
# 显示 skill 详情
npx clawhub inspect <skill-name>
# 浏览最新技能
npx clawhub explore
npx clawhub explore --limit 20    # 前20个

# 示例
npx clawhub search find-skills
npx clawhub search find-skills --limit 5 
npx clawhub inspect find-skills

# 使用帮助
npx clawhub search --help
npx clawhub inspect --help

4. 安装/更新/卸载技能

# 安装
npx clawhub install <skill-name>
npx clawhub install <skill-name> --version <version number>   # 指定版本
npx clawhub install <skill-name> --force                      # 覆盖已有
npx clawhub --dir <install-path> install <skill-name>         # 指定目录

# 更新
npx clawhub update <skill-name>
npx clawhub update --all

# 卸载
npx clawhub uninstall <skill-name>

# 查看已安装 skills
npx clawhub list

# Claude Code 安装 Skill 示例
npx clawhub --dir ~/.claude/skills install find-skills
CLAWHUB_WORKDIR=~/.claude/skills npx clawhub install find-skills

# 使用帮助
npx clawhub install --help
npx clawhub update --help
npx clawhub uninstall --help
npx clawhub list --help

5. 使用 SkillHub CLI 发布技能

ClawHub CLI 0.23.3 的发布协议与 SkillHub 不兼容。请使用第一方 SkillHub CLI：

export SKILLHUB_REGISTRY=https://skillhub.your-company.com
export SKILLHUB_TOKEN=YOUR_API_TOKEN
npx @astron-team/skillhub@latest publish ./my-skill --namespace global
npx @astron-team/skillhub@latest publish ./my-skill --namespace my-space

说明：

• 发布需要具有 skill:publish scope 的 API Token，以及目标 namespace 对应权限。
• clawhub login 与 SkillHub CLI 不共享凭据；请为第一方 CLI 单独设置 SKILLHUB_TOKEN。
• 第一方 CLI 使用独立 namespace 参数，但仍遵循服务端 slug 校验规则。

API 端点说明

SkillHub 兼容层提供以下端点：

端点	方法	说明	认证要求
/api/v1/whoami	GET	获取当前用户信息	必需
/api/v1/search	GET	搜索技能	可选
/api/v1/resolve	GET	解析技能版本	可选
/api/v1/download/{slug}	GET	下载技能（重定向）	可选*
/api/v1/download	GET	下载技能（查询参数）	可选*
/api/v1/skills/{slug}	GET	获取技能详情	可选
/api/v1/stars/{slug}	POST	收藏技能	必需
/api/v1/stars/{slug}	DELETE	取消收藏	必需
/api/v1/publish	POST	旧版兼容发布端点；ClawHub CLI 0.23.3 不使用	必需

说明：

• 兼容层对外继续使用 “latest” 语义，但这里严格指向“最新已发布版本”
• 兼容层内部实现应从统一 lifecycle projection 的 publishedVersion 映射，而不是自行推导“当前版本”

* 下载端点认证要求：

• 全局命名空间（@global）的 PUBLIC 技能：无需认证
• 团队命名空间的所有技能：需要认证
• NAMESPACE_ONLY 和 PRIVATE 技能：需要认证

技能可见性说明

SkillHub 支持三种技能可见性级别，下载权限规则如下：

PUBLIC（公开）

• ✅ 任何人都可以搜索和查看
• ✅ 全局命名空间（@global）：无需登录即可下载
• 🔒 团队命名空间：需要登录认证才能下载
• 📍 适用于组织内通用的、可公开分享的技能

NAMESPACE_ONLY（命名空间内可见）

• ✅ 命名空间成员可以搜索和查看
• 🔒 需要登录且是命名空间成员才能下载
• 📍 适用于团队内部技能

PRIVATE（私有）

• ✅ 仅所有者可以查看
• 🔒 需要登录且是所有者才能下载
• 📍 适用于个人开发中的技能

重要说明：

• 全局命名空间（@global）的 PUBLIC 技能支持匿名下载，便于组织内广泛分发
• 团队命名空间的所有技能（包括 PUBLIC）都需要认证，确保团队边界安全

Canonical Slug 映射规则

SkillHub 内部使用 @{namespace}/{skill} 格式，但兼容层会自动转换为 ClawHub 风格的 canonical slug：

SkillHub 内部坐标	Canonical Slug	说明
@global/my-skill	my-skill	全局命名空间技能
@my-team/my-skill	my-team--my-skill	团队命名空间技能

OpenClaw CLI 使用 canonical slug 格式，SkillHub 会自动处理转换。

canonical 格式没有转义规则，因此 SkillHub 会拒绝新建包含连续 -- 的 namespace 或 skill slug。若历史或外部导入数据绕过了该校验，应先重命名坐标；第一方 SkillHub CLI 虽使用独立 --namespace 参数，也不能绕过服务端 slug 校验。

配置示例

ClawHub CLI 环境变量配置

ClawHub CLI 通过环境变量配置：

# Registry 配置
export CLAWHUB_REGISTRY=https://skillhub.your-company.com

# 如需认证，先登录一次
clawhub login --token sk_your_api_token_here

环境变量配置

# Registry 配置
export CLAWHUB_REGISTRY=https://skillhub.your-company.com

# 可选：登录后再执行需要认证的命令
clawhub login --token sk_your_api_token_here

常见问题

Q: 如何切换回公共 ClawHub？

# 取消设置自定义 Registry
unset CLAWHUB_REGISTRY

# ClawHub CLI 将使用默认的公共注册中心

Q: 下载技能时提示 403 Forbidden？

可能原因：

1. 技能属于团队命名空间，需要登录
2. 技能是 NAMESPACE_ONLY 或 PRIVATE，需要登录
3. 您不是该命名空间的成员
4. API Token 已过期

解决方法：

# 设置新的 Token 并重新登录
clawhub login --token YOUR_NEW_TOKEN

# 测试连接
curl https://skillhub.your-company.com/api/v1/whoami \
  -H "Authorization: Bearer YOUR_NEW_TOKEN"

提示：全局命名空间（@global）的 PUBLIC 技能可以匿名下载，无需认证。

Q: 如何查看我有权访问的所有技能？

# 搜索所有技能（会根据权限过滤）
npx clawhub search ""

Q: 使用 ClawHub CLI 发布为什么失败？

ClawHub CLI 0.23.3 使用的上传票据协议不在 SkillHub 兼容范围内。该错误不代表 API Token 已撤销；请改用第一方 SkillHub CLI。

如果第一方 CLI 提示权限不足：

• 发布者必须是目标命名空间成员；SUPER_ADMIN 例外
• 普通成员可提交发布，是否直接发布或进入审核由可见性和审核规则决定
• 联系命名空间管理员加入目标空间

Q: 支持哪些 OpenClaw 版本？

SkillHub 兼容层设计兼容使用 ClawHub CLI 的工具。ClawHub CLI 通过 npm 分发：

# 安装 ClawHub CLI
npm install -g clawhub

# 或使用 npx 直接运行
npx clawhub install my-skill

如遇到兼容性问题，请提交 Issue。

API 响应格式

搜索响应示例

{
  "results": [
    {
      "slug": "my-team--email-sender",
      "name": "Email Sender",
      "description": "Send emails via SMTP",
      "author": {
        "handle": "user123",
        "displayName": "John Doe"
      },
      "version": "1.2.0",
      "downloadCount": 150,
      "starCount": 25,
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-03-10T14:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

版本解析响应示例

{
  "slug": "my-skill",
  "version": "1.2.0",
  "downloadUrl": "/api/v1/skills/global/my-skill/versions/1.2.0/download"
}

发布响应示例

{
  "id": "12345",
  "version": {
    "id": "67890"
  }
}

安全建议

1. 使用 HTTPS：生产环境务必使用 HTTPS 连接
2. Token 管理：
   • 定期轮换 API Token
   • 不要在代码中硬编码 Token
   • 使用环境变量或密钥管理工具
3. 权限最小化：为 Token 分配最小必需权限
4. 审计日志：定期检查 SkillHub 审计日志

故障排查

启用调试日志

# 查看详细请求日志
DEBUG=clawhub:* npx clawhub search my-skill

# 或使用 verbose 模式
npx clawhub --verbose install my-skill

测试连接

# 测试 Registry 连接
curl https://skillhub.your-company.com/api/v1/whoami \
  -H "Authorization: Bearer YOUR_TOKEN"

# 测试搜索
curl "https://skillhub.your-company.com/api/v1/search?q=test"

进一步阅读

• SkillHub API 设计文档
• 技能协议规范
• 认证与授权
• 部署指南

支持

如有问题或建议：

• 📖 查看完整文档：https://zread.ai/iflytek/skillhub
• 💬 GitHub Discussions：https://github.com/iflytek/skillhub/discussions
• 🐛 提交 Issue：https://github.com/iflytek/skillhub/issues