ClawHub 技能发布流程

本文档总结了从 0 到发布一个 ClawHub 技能的完整流程和经验。

📋 前置要求

• - Node.js >= 18
• INLINECODE0 CLI (npm install -g clawhub)
• Git
• GitHub CLI (gh)
• ClawHub 账号（已登录）
• GitHub 账号（用于 push 和 GitHub Release）

🧰 环境检查与补装

先检查命令是否存在：

CODEBLOCK0

如果缺命令：

CODEBLOCK1

验证：

CODEBLOCK2

🔐 GitHub 鉴权与 Git 初始化

如果用户还没登录 GitHub，先做这个：

CODEBLOCK3

如果用户本机 Git 还没初始化身份，先配置：

CODEBLOCK4

如果仓库还没绑远程：

CODEBLOCK5

发布前最少确认这 4 件事：

CODEBLOCK6

✅ 发布顺序（必须按此顺序，不能错）

发布前，先检查 references/clawhub-review-checklist.md，确认元数据、README、脚本行为、凭证声明和示例参数已经一致。

1. 1. 确定版本号 — 同步修改 SKILL.md 和 package.json 的 version 字段
2. 更新 CHANGELOG.md — 在顶部追加新版本记录
3. 先过一遍 checklist — 特别检查 requires.bins / requires.env / primaryEnv / 本地文件行为说明
4. push + GitHub Release — git add -A && git commit && git push，然后 INLINECODE10
5. 发布到 ClawHub — INLINECODE11
6. 如需立即让当前 agent 使用最新技能定义，再手动同步到 agent 工作空间 — INLINECODE12

硬规则： 以后凡是发布 OpenClaw 技能，每次 ClawHub 发布都必须同步创建对应的 GitHub Release。不允许只发技能不发 release。

新增硬规则： 发布前必须过一遍 references/clawhub-review-checklist.md。尤其是带脚本、凭证、工作区文件读写的技能，不检查就发，极容易被 ClawHub 审核打回。

敏感操作提示： 同步到 ~/.openclaw/workspace/skills 属于对 agent 工作区的写操作，只应在受信任环境中显式执行，不应在公共或不受信任场景下默认执行。

🚀 完整流程

1. 准备技能文件夹

CODEBLOCK7

2. 创建必需文件

SKILL.md（必需）

CODEBLOCK8

⚠️ 关键：元数据必须准确声明

ClawHub 安全分析会检查声明与实际代码是否一致：

• - requires.env - 代码中引用的所有环境变量
• INLINECODE16 - 代码中调用的所有 CLI 工具
• INLINECODE17 - 主要凭证变量名

package.json

CODEBLOCK9

README.md

CODEBLOCK10bash
clawhub install my-skill
CODEBLOCK11

CHANGELOG.md

CODEBLOCK12

3. 推送到 GitHub

CODEBLOCK13

4. 发布到 ClawHub

CODEBLOCK14

5. 验证发布

CODEBLOCK15

⚠️ 常见问题与解决方案

问题 1: fetch failed 错误

症状：
CODEBLOCK16

原因： 网络问题、服务端暂时不可达或本机登录状态异常

解决：
CODEBLOCK17

问题 2: SKILL.md required 错误

症状：
CODEBLOCK18

原因：

• - 文件不存在
• 文件名大小写错误（必须是 SKILL.md 或 skill.md）
• 当前目录错误

解决：
CODEBLOCK19

问题 3: 发布超时（Timeout）

症状：
CODEBLOCK20

原因： 服务器响应慢或网络问题

解决：
CODEBLOCK21

问题 4: 元数据不一致（审核失败）

症状： 审核反馈 "metadata mismatch"

原因： SKILL.md frontmatter 声明与实际代码不符

解决： 确保 frontmatter 准确声明：

CODEBLOCK22

问题 5: ClawHub 登录失败

症状：
CODEBLOCK23

解决：
CODEBLOCK24

问题 6: gh release create 或 git push 失败

常见原因：

• - 没安装 INLINECODE24
• GitHub CLI 未登录
• Git 没配置 user.name / INLINECODE26
• 仓库没配置 INLINECODE27
• 当前账号对仓库无 push 权限

排查顺序：
CODEBLOCK25

解决：
CODEBLOCK26

问题 7: SKILL.md required / acceptLicenseTerms: invalid value

症状 1：
CODEBLOCK27

先判断：

• - 如果目录里真的没有 SKILL.md，那就是路径或文件问题
• 如果目录里明明有 SKILL.md，但后续又报 acceptLicenseTerms: invalid value，那真正的问题通常不是技能文件缺失，而是 ClawHub CLI 与服务端 publish payload 兼容有坑

症状 2：
CODEBLOCK28

结论：

• - 这类问题不要盲重试 INLINECODE33
• 先确认：

  pwd
  ls -la
  sed -n '1,20p' SKILL.md
  clawhub whoami
  

• - 如果 SKILL.md 存在、登录正常，基本可判定为 CLI publish payload bug，而不是技能目录缺文件

兜底方案（实测可用）：

1. 1. 正常完成 git push 和 INLINECODE36
2. 从本机 ClawHub 配置里读取 token：

1. 3. 手工向 https://clawhub.ai/api/v1/skills 发 multipart/form-data 请求：

1. 4. 发布成功后，用 clawhub inspect <slug> 验证最新版本

规则更新：

• - 以后遇到 acceptLicenseTerms: invalid value，默认按 CLI bug 排查，不再把时间浪费在反复重试上
• GitHub Release 成功 + ClawHub CLI 失败，不代表技能不能发布；优先切到手工 API 发布兜底

问题 8: ClawHub 审核提示 metadata mismatch

典型反馈：

• - 功能本身是对的
• 但 registry metadata 没声明实际依赖的二进制或环境变量

高频遗漏项：

• - INLINECODE50
• INLINECODE51
• INLINECODE52
• INLINECODE53 里的 requiresBinaries / requiredEnv / INLINECODE56

处理顺序：

1. 1. 对照代码、脚本、README、SKILL.md，列出真实依赖
2. 同步修复：

1. 3. 升一个 patch 版本
2. 重新走：git push → gh release create → INLINECODE61

硬规则：

• - 只要 skill 里用了 CLI、环境变量、本地沙箱目录，就必须把声明写全；不写全，审核很容易打回

📝 版本更新流程

CODEBLOCK30

🔐 安全注意事项

1. 1. 凭证安全

1. 2. 脚本审查

1. 3. 元数据准确性

📚 参考资源

• - 技能格式规范：https://github.com/openclaw/clawhub/blob/main/docs/skill-format.md
• 安全规范：https://github.com/openclaw/clawhub/blob/main/docs/security.md
• ClawHub 技能市场：https://clawhub.ai/skills

💡 最佳实践

1. 1. 小步迭代 - 每次发布只做一个主要改动
2. 详细 Changelog - 清晰记录每个版本的变更
3. 测试先行 - 在发布前充分测试技能功能
4. 文档完善 - 好的文档减少用户问题
5. 语义化版本 - 遵循 semver (major.minor.patch)