是ip白名单问题：若curl -i返回头含x-whitelist-required: true，则确认需白名单；否则排查dns、证书或代理。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
导入时返回 403 Forbidden 怎么确认是不是 IP 白名单问题
WorkBuddy 向私有 SkillHub 实例（如 https://internal.skillhub.corp/）发起请求时，若出口 IP 未登记，服务端会直接返回 403 Forbidden，且不透露具体原因。不能只看状态码就断定是权限问题。
验证步骤如下：
- 在 WorkBuddy 中开启开发者模式，导入时加
--debug参数，从日志中提取目标域名（如https://mirror.openclaw.dev/） - 用
curl -I https://mirror.openclaw.dev/health检查响应头，确认是否含X-Whitelist-Required: true - 若存在该 header，说明必须走白名单；否则应排查 DNS、证书或代理配置
绕过方式：改用官方通道 https://skillhub.tencent.com，它不启用 IP 白名单，所有合法客户端可直连。
技能包解压后报 “格式错误” 或 “签名无效”
这类错误多因文件扩展名与实际内容不匹配。WorkBuddy 根据扩展名决定用 JSON 还是 YAML 解析器，一旦错配，立刻失败。
常见错配场景：
- 文件名为
xxx.skill.json，但内容是 YAML（含name:、- trigger:等缩进语法） - 文件名为
xxx.skill，但内容是未压缩的目录结构（缺manifest.json或skill.yaml根文件） - 使用了 YAML 特有语法（如锚点
&common、合并），但解析器按 JSON 处理
修复建议：
- 用 VS Code 打开文件，确认首行是
{（JSON）还是name:（YAML） - 若为 YAML，用
yq e -o=json skill.yaml > skill.json转换，并重命名为.skill.json - 确保转换后根对象包含且仅含四个必需字段：
"name"、"description"、"triggers"、"steps"
导入成功但技能无法触发，关键词不生效
“已安装”不等于“可触发”。WorkBuddy 在运行时依赖 keywords 字段构建本地倒排索引，若该字段缺失、为空、含非法字符或被解析跳过，技能将完全不可见。
检查路径：
- 进入技能详情页，看「触发关键词」是否显示为有效字符串（如
会议纪要、生成摘要），而非“未配置”或空 - 手动打开本地技能目录：
%APPDATA%\Tencent\WorkBuddy\skills\{skill_id}\manifest.json（Windows）或~/Library/Application Support/WorkBuddy/skills/{skill_id}/manifest.json（macOS），确认keywords字段存在且为非空数组 - 若字段存在但未生效，可能是导入时 YAML 缩进错误导致解析中断——
keywords被忽略，只注册了 ID
临时绕过方法：在指令前加 [force] 前缀，例如 [force]会议纪要整理，强制调度该技能。
导入后运行时报 “参数解析失败” 或卡在 input schema 校验
这个错误几乎都出在 InputSchema 定义上。WorkBuddy 对其执行严格 JSON Schema 校验，任何格式或结构偏差都会中断流程。
高频雷区：
-
InputSchema含 JavaScript 风格注释（//或/* */）——JSON 不支持，必须删净 - 字段用单引号包裹（
'name': 'user_id'）——必须全用双引号："name": "user_id" -
type: "array"字段缺少"items"子定义，或"items"内没声明"type" - 使用
$ref引用definitions时，路径写错（如写成#/def/user而非#/definitions/user）
调试建议：
- 把
InputSchema粘到jsonlint.com校验语法 - 用 Postman 捕获一次失败调用的 raw body，和 schema 的
properties逐项比对字段名、嵌套层级、是否必填、类型是否一致 - 临时把
$ref替换为内联结构，快速判断是否引用解析失败
最隐蔽的问题是：schema 合法、调用参数也合法，但系统缓存了旧版 schema。此时需清除缓存目录 Cache\skills 并重启客户端。
