ClawHub Skill 发布避坑指南

ClawHub Skill 发布避坑指南。让你的 Skill 发布后能被搜索到，避免安全扫描导致隐藏。适用于需要发布 Skill 到 ClawHub 的开发者。

Security Scan

This is an instruction-only publishing guide whose content matches its stated purpose, but it contains a few minor inconsistencies and user-safety notes you should be aware of before following the commands.

Purpose & Capability

The SKILL.md content (how to publish to ClawHub, declaring env vars in front matter, curl/CLI examples) aligns with the skill's stated purpose. Minor mismatch: the instructions assume tools (clawhub CLI, curl, jq) and access to a local ClawHub config file, but the registry metadata lists no required binaries or env vars.

Instruction Scope

Instructions are generally scoped to publishing tasks, but they explicitly show commands that read a local file (~/.config/clawhub/config.json) to extract a bearer token and upload SKILL.md via curl. Reading a local token and uploading files is relevant to publishing but is sensitive — the guide doesn't warn about ensuring SKILL.md contains no secrets before uploading.

Install Mechanism

No install spec and no code files — lowest-risk form. The guide only contains shell/CLI examples and does not cause files to be downloaded or installed by the platform.

Credentials

Registry metadata declares no required env vars, while the document teaches developers to declare required env vars in SKILL.md front matter. The curl example reads a bearer token from a local config file instead of using a declared env var; this is reasonable for publishing but is a point to verify personally.

Persistence & Privilege

always is false and there is no indication the skill asks for persistent or elevated privileges or modifies other skills' configuration.

Assessment

This guide appears coherent and intended to help developers publish skills. Before following its commands: (1) verify SKILL.md contains no secrets before uploading (the curl example will post your file to https://clawhub.ai), (2) the curl example extracts a bearer token from ~/.config/clawhub/config.json — confirm you trust the destination and understand where the token comes from, (3) the guide assumes tools (clawhub CLI, curl, jq); ensure these are present and you trust any commands you paste into a shell, (4) consider declaring required binaries/env vars in your skill metadata as recommended so scanners don't hide your skill, and (5) if you plan to automate publishing, prefer using environment variables or an approved CLI auth flow rather than cat-ing local config files to avoid accidental credential exposure.

发布前检查清单

✅ 必须避免的内容

问题类型	风险等级	解决方案
硬编码 API Keys	🔴 高	使用环境变量
HTTP 明文传输	🟡 中	添加安全警告说明
外部 URL/端点	🟢 低	正常发布
敏感信息	🔴 高	移除或环境变量
未声明环境变量	🔴 高	在 YAML front matter 中声明

✅ 推荐做法

1. API Key 放在环境变量

# ❌ 硬编码（会被扫描拦截）
API_KEY = "sk-xxx"

# ✅ 环境变量（安全）
API_KEY = os.environ.get("API_KEY")

2. HTTP endpoint 要警告用户

## ⚠️ 安全警告
- HTTP 明文传输，API Key 可能有泄露风险
- 仅在可信网络使用

3. ⚠️ 必须在 YAML front matter 中声明环境变量

这是最重要的一步！如果不在 front matter 中声明，安全扫描会报警告：

---
name: my-skill
version: 1.0.0
description: 使用某个 API 的技能
metadata:
  openclaw:
    requires:
      env:
        - MY_API_KEY        # 必需的环境变量
        - MY_OPTIONAL_URL   # 可选的环境变量
    primaryEnv: MY_API_KEY  # 主要认证凭据
---

关键点：

• requires.env：列出所有需要的环境变量
• primaryEnv：指定主要认证凭据（API Key）
• 这样 ClawHub 才能正确识别你的 skill 需要哪些环境变量

4. SKILL.md 正文也要说明环境变量

## 环境变量
- MY_API_KEY=xxx  # 必需
- MY_OPTIONAL_URL=http://example.com  # 可选

⚠️ 开发者协议确认（新！）

如果发布时遇到错误：acceptLicenseTerms: invalid value

说明你需要先在 ClawHub 网站上同意开发者协议：

1. 访问 https://clawhub.ai
2. 登录你的账户
3. 进入 Settings 或 Developer Settings
4. 同意开发者许可协议
5. 然后再执行发布命令

发布命令

# 方式一：使用 clawhub CLI（需要先在网站同意开发者协议）
clawhub publish ./skills/your-skill --version 1.0.0

# 方式二：使用 curl 直接发布（支持 acceptLicenseTerms）
TOKEN=$(cat ~/.config/clawhub/config.json | jq -r '.token')
curl -X POST "https://clawhub.ai/api/v1/skills" \
  -H "Authorization: Bearer $TOKEN" \
  -F 'payload={"slug":"your-skill","displayName":"Your Skill","version":"1.0.0","changelog":"","tags":["latest"],"acceptLicenseTerms":true};type=application/json' \
  -F "files=@SKILL.md;filename=SKILL.md"

注意：acceptLicenseTerms: true 是必需的参数，表示同意开发者许可协议。

发布后验证

# 搜索 Skill
clawhub search your-skill-name

# 检查状态
clawhub inspect your-skill-name

常见问题

Q: Skill 被隐藏怎么办？

A: 等待安全扫描通过，或移除敏感信息重新发布

Q: 提示 hard-coded credentials 怎么办？

A: 改用环境变量，添加安全警告

Q: 版本号冲突怎么办？

A: 升级版本号，如 1.0.0 → 1.0.1

Q: 提示 acceptLicenseTerms: invalid value 怎么办？

A: 先在 ClawHub 网站上同意开发者协议，然后再发布

Q: 安全扫描报警告 "未声明环境变量" 怎么办？

A: 在 YAML front matter 中添加 metadata.openclaw.requires.env 声明：

metadata:
  openclaw:
    requires:
      env:
        - YOUR_API_KEY
    primaryEnv: YOUR_API_KEY

Q: 安全扫描说 "registry metadata claims no required env vars" 怎么办？

A: 同上，你需要在 front matter 中声明环境变量。即使代码中已经使用了 os.environ.get()，也必须在元数据中声明，否则 ClawHub 无法正确识别。