企业官网建设流程全解析

• 人工智能
• AI Agent
• AI 技能
• 后端
• 前端

本篇技术指南讲解如何通过 ClawHub CLI 接入 SkillHub 自托管技能注册中心，实现组织内私有技能的搜索、查看、下载与安装，并深入剖析 SkillHub 服务端 ClawHub 兼容层的实现原理（canonical slug 映射、可见性权限、版本解析与 Bearer Token 认证）。读完本文，你将能够独立完成 OpenClaw、Claude Code、OpenCode 等 CLI Coding Agent 与 SkillHub 的对接配置，并能定位 403、版本解析失败等常见问题。

适用范围：本文所述的接入方式不仅适用于 OpenClaw，通过指定安装目录（--dir），同样适用于其他 CLI Coding Agent（Claude Code、OpenCode、Qcoder 等）或 Agent 助手（Nanobot、CoPaw 等）。发布技能请使用第一方 SkillHub CLI。

概述：SkillHub 的 ClawHub 兼容 API

SkillHub 在自有/api/v1/**Native API 之外，额外提供了一层 ClawHub 兼容 API，覆盖 ClawHub CLI 常用的只读发现与安装流程。通过简单配置，你可以：

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

从源码结构看，这层兼容能力由独立的compat包实现：入口为 ClawHubCompatController.java，业务装配在 ClawHubCompatAppService.java，slug 转换由 CanonicalSlugMapper.java 完成，另有 WellKnownController.java 提供协议发现入口，安全链配置见 ClawHubRegistrySecurityConfig.java。这与 docs/06-api-design.md §7.10「ClawHub CLI 协议兼容层」的设计要求一致：兼容层与 Native API 并存、共享同一套权限、审计、限流与领域服务。

当前兼容边界

• 已验证的 ClawHub CLI0.23.3使用/api/v1/whoami，与 SkillHub 兼容层一致。
• ClawHub CLI 的发布协议依赖 SkillHub 未实现的上传票据接口，因此clawhub publish和clawhub sync不属于支持范围。
• ClawHub CLI0.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

从实现上看，兼容层的认证复用 SkillHub 的 Bearer Token 体系：ClawHubRegistrySecurityConfig为/api/v1/search、/api/v1/download、/api/v1/skills/*等路径挂载了无状态（STATELESS）安全链，并前置ApiTokenAuthenticationFilter，即Authorization: Bearer <token>中的 Token 可来自 CLI Device Flow 或平台 API Token（详见 docs/06-api-design.md §7.10）。测试 ClawHubCompatControllerTest.java 中search_withBearerToken_shouldProjectNamespaceRolesIntoRequestContext用例验证了携带 Bearer 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

对应服务端实现中，GET /api/v1/search支持q、page（默认 0）、limit（默认 20）参数；空关键词时按newest排序，非空关键词按relevance相关度排序（见 ClawHubCompatAppService.java 的search方法）。搜索结果中的version字段取自统一生命周期投影的publishedVersion，严格对应「最新已发布版本」。

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

扩展：让其他 Agent 共享同一套技能。SkillHub 第一方 CLI 内置了多种 Agent profile，例如 openclaw.ts 将 OpenClaw 的项目级与用户级技能根目录都映射为.openclaw/skills（通过 make-profile.ts 生成）。这表示你完全可以用第一方 CLI 将技能直接安装到 OpenClaw 的.openclaw/skills目录，例如skillhub install find-skills --agent openclaw；同时，ClawHub CLI 通过--dir指定任意目录的做法，天然支持 Claude Code（~/.claude/skills）、OpenCode、Qcoder 等任意 Agent 的安装位置。技能包目录规范（SKILL.md+references/+scripts/+assets/）详见 docs/07-skill-protocol.md §8.2。

5. 使用第一方 SkillHub CLI 发布技能

ClawHub CLI0.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:publishscope 的 API Token，以及目标 namespace 对应权限。
• clawhub login与 SkillHub CLI 不共享凭据；请为第一方 CLI 单独设置SKILLHUB_TOKEN。
• 第一方 CLI 使用独立--namespace参数，但仍遵循服务端 slug 校验规则。

从实现看，兼容层也提供了POST /api/v1/publish与POST /api/v1/skills发布入口（multipart 表单），但发布结果走的是与 Native API 完全相同的SkillPublishService.publishFromEntries领域服务，且每次兼容层发布都会写入COMPAT_PUBLISH类型的审计日志（见 ClawHubCompatAppService.java 的publish/recordCompatPublishAudit）。普通用户发布后进入PENDING_REVIEW审核态，SUPER_ADMIN始终直发（PUBLISHED）。

API 端点说明

SkillHub 兼容层提供以下端点：

说明：

• 兼容层对外继续使用「latest」语义，但这里严格指向最新已发布版本。
• 兼容层内部实现应从统一 lifecycle projection 的publishedVersion映射，而不是自行推导「当前版本」——这正对应 ClawHubCompatAppService.java 中toSearchResult/toSkillListItem对item.publishedVersion()的读取方式。

* 下载端点认证要求：

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

协议发现：/.well-known/clawhub.json

ClawHub CLI 通过GET /.well-known/clawhub.json发现 API 基地址。实现上，WellKnownController.java 会返回：

{ "apiBase": "/api/v1", "capabilities": ["skill-suite-v1"] }

值得注意的是，apiBase会尊重部署子路径：当站点部署在非根路径（如/skillhub）时，返回/<prefix>/api/v1，避免 CLI 向域名根路径发起请求。

下载端点的重定向细节

/api/v1/download/{slug}与/api/v1/download?slug=...&version=...本身不直接输出 zip 流，而是返回302 Found，Location指向 Native 下载接口（如/api/v1/skills/team-ai/my-skill/download）。源码中对每个路径段做了百分号编码——因为非 ASCII slug（例如中文技能名）无法直接写入 HTTPLocation头（Tomcat 按 ISO-8859-1 编码 header，超范围字符会导致整个 header 被丢弃，进而破坏 ClawHub CLI 下载）。测试download_query_with_canonical_slug_redirects_to_namespace_skill_download验证了team-ai--my-skill会正确重定向到/api/v1/skills/team-ai/my-skill/download。

技能可见性说明

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

PUBLIC（公开）

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

NAMESPACE_ONLY（命名空间内可见）

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

PRIVATE（私有）

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

重要说明：

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

这套规则在兼容层同样生效：resolveQueryCoordinate在解析 legacy slug 时会通过compatSkillLookupService.canAccess(...)做可见性校验，无权限时抛出与「技能不存在」相同的领域异常（避免坐标枚举），见 ClawHubCompatAppService.java。

Canonical Slug 映射规则

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

OpenClaw CLI 使用 canonical slug 格式，SkillHub 会自动处理转换。转换逻辑集中在 CanonicalSlugMapper.java：

• toCanonical(namespace, slug)：namespace 为global时直接返回 slug，否则返回namespace--slug；
• fromCanonical(canonicalSlug)：按首个--拆分出 namespace 与 slug，不含--时视为全局命名空间。

canonical 格式没有转义规则，因此 SkillHub 会拒绝新建包含连续--的 namespace 或 skill slug。若历史或外部导入数据绕过了该校验，应先重命名坐标；第一方 SkillHub CLI 虽使用独立--namespace参数，也不能绕过服务端 slug 校验。发布时如果 canonical slug 包含--，服务端会将其解析为团队空间发布，否则发布到全局空间（见determineNamespace的实现）。

配置示例

ClawHub CLI 环境变量配置

ClawHub CLI 通过环境变量配置：

# Registry 配置 export CLAWHUB_REGISTRY=https://skillhub.your-company.com # 如需认证，先登录一次 clawhub login --token sk_your_api_token_here

第一方 SkillHub CLI 环境变量配置

# Registry 配置 export SKILLHUB_REGISTRY=https://skillhub.your-company.com # 可选：登录后再执行需要认证的命令 export SKILLHUB_TOKEN=sk_your_api_token_here

常见问题（FAQ）

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 CLI0.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为 canonical slug 格式（全局空间直接返回 skill slug，团队空间返回namespace--skill）；version来自已发布版本投影。测试 ClawHubCompatControllerTest.java 的search_returns_mapped_results用例断言了results[0].slug、summary、version三个字段的映射行为。

版本解析响应示例

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

版本解析接口的语义约定（来自 docs/06-api-design.md §7.9）：version与tag不可同时传；仅传version精确匹配；仅传tag查skill_tag表；仅传hash遍历已发布版本比对 fingerprint；均不传时返回最新已发布版本（latest）。

发布响应示例

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

安全建议

1. 使用 HTTPS：生产环境务必使用 HTTPS 连接。
2. Token 管理：
   • 定期轮换 API Token
   • 不要在代码中硬编码 Token
   • 使用环境变量或密钥管理工具
3. 权限最小化：为 Token 分配最小必需权限（发布场景至少需要skill:publishscope）。
4. 审计日志：定期检查 SkillHub 审计日志（兼容层的每次发布都会写入COMPAT_PUBLISH审计记录，含客户端 IP 与 User-Agent，便于追踪来源）。

故障排查

启用调试日志

# 查看详细请求日志 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"

排查清单速查

1. 确认 Registry 生效：echo $CLAWHUB_REGISTRY，确保当前会话已 export，且未被站点发现逻辑覆盖。
2. 确认认证状态：npx clawhub whoami能返回用户信息，说明 Token 有效。
3. 确认可见性：团队命名空间技能（含 PUBLIC）一律需要登录；@global的 PUBLIC 技能可匿名下载。
4. 确认坐标合法：namespace 与 slug 不含连续--；历史异常坐标先重命名再使用 ClawHub CLI。
5. 确认部署子路径：若站点部署在非根路径，/.well-known/clawhub.json会返回带前缀的apiBase，请勿手工拼错路径。

进一步阅读

• SkillHub API 设计文档（§7.10 兼容层协议契约、§7.9 resolve 语义、§7.11 限流策略）
• 技能协议规范（SKILL.md 格式、技能包目录结构与互操作边界）
• 认证与授权（Bearer Token / Device Flow / RBAC 角色体系）
• 部署指南（自托管部署与 HTTPS 前置要求）
• DeepSeek Harness 集成指南（将技能安装到 dsh 的另一种 Agent 集成路径）

• 人工智能
• AI Agent
• AI 技能
• 后端
• 前端