第7章OpenClaw 与 ClawHub 技能商店 7-2 OpenClaw Skills 使用

CHAPTER07/SECTION2OpenClawSkills使用第7章·OpenClaw与ClawHub技能商店AgentSkills多平台应用实战·授课课件目标受众：有基础的开发人员｜课时：20分钟7-2SKILLSUSAGECONTENTS/目录本节学习路径01Skill调用原理与架构触发匹配、上下文注入、执行反馈全流程02调用方式对比对话调用、API调用、工作流编排三种模式03实战：多Skill协同爬虫→数据分析→报告生成完整流水线04常见问题与排查调用失败、数据传递丢失、权限问题定位05数据传递与串联编排Skill间上下文共享、参数映射、状态保持06远程调用与API网关跨节点Skill调用、鉴权、限流与熔断07课后实操任务搭建三Skill协同流水线并完成验收08本节总结核心要点回顾与下节预告Skill调用原理：从意图匹配到执行反馈OpenClawAgent接收用户请求后，经七步流水线完成Skill调用与结果反馈STEP1用户输入STEP2意图匹配STEP3Skill加载STEP4上下文注入STEP5执行引擎STEP6结果解析STEP7行动反馈匹配层：意图与Skill路由基于Skill元数据（name、description、parameters）进行语义匹配，支持模糊匹配与精确触发，多Skill命中时按置信度排序。执行层：沙箱与权限隔离Skill在独立沙箱中执行，通过能力白名单控制文件系统、网络、进程访问，超时与资源限制防止恶意或失控执行。反馈层：结果驱动后续行动结果解析后可触发链式调用：自动调用下一个Skill、追问用户参数、或直接返回最终答案，实现Agent自主决策。关键设计：整个调用流程对用户透明，Agent自动完成匹配与编排；开发者只需关注Skill自身的输入输出契约，无需关心调度细节。Skill的description质量直接决定匹配准确率，是Skill开发中最容易被忽视的关键环节。三种Skill调用方式对比对话调用、API调用、工作流编排各有适用场景，按业务复杂度选择对比维度对话界面调用API直接调用工作流编排调用触发方式自然语言意图匹配HTTP/gRPC显式调用DAG节点按依赖触发适用场景探索性查询、助手交互系统集成、自动化脚本多步骤复杂业务流水线参数传递LLM提取，可能需追问结构化JSON，精确可控节点间变量映射传递状态保持对话上下文自动维护无状态，需外部存储工作流上下文全局共享错误处理Agent自动重试/降级调用方自行处理异常内置重试、补偿、分支开发复杂度低，写好description即可中，需定义接口与鉴权高，需设计DAG与编排典型用例智能客服、个人助手CI/CD钩子、定时任务数据管道、报表生成选型建议：单一能力用对话调用，系统集成交API调用，三步以上且有依赖关系的任务必须用工作流编排。实战案例：三Skill协同完成竞品分析爬虫Skill→数据分析Skill→报告生成Skill，数据在Skill间自动传递与转换TRIGGER用户请求SKILL01/CRAWLER爬虫Skill抓取竞品官网、定价页、产品文档，输出原始HTMLHTMLSKILL02/ANALYZER数据分析Skill解析数据、清洗去重、统计对比，输出结构化JSONJSONSKILL03/REPORTER报告生成Skill渲染模板、插入图表、生成PDF/Markdown报告OUTPUT分析报告输入输出契约爬虫Skill输入：urls:string[]输出：raw_html:Map<url,html>超时：30s｜重试：3次依赖：requests+BeautifulSoup数据分析Skill输入：raw_html（上游输出）输出：analysis_result:JSON含：定价对比、功能矩阵、评分依赖：pandas+scikit-learn报告生成Skill输入：analysis_result（上游输出）输出：report.pdf+report.md含：封面、对比表、图表、结论依赖：jinja2+matplotlib+weasyprint核心要点：上游Skill的output字段名必须与下游Skill的input字段名一致，这是Skill间自动数据传递的契约基础。上手演示：对话界面调用Skill四步完成一次Skill调用：输入请求→自动匹配→执行反馈→获取结果OpenClaw·对话界面帮我抓取竞品A和B的定价页并生成对比报告Skill调用中...爬虫Skill(1/3)Skill调用中...数据分析Skill(2/3)完成报告生成Skill(3/3)✓Agent回复已完成竞品定价对比分析。共抓取2个目标站点，提取15项定价维度，生成报告含对比表与趋势图。报告已保存：competitor_report.pdf操作步骤1输入自然语言请求在对话框描述目标，无需指定Skill名称，Agent会自动理解意图。2Agent自动匹配与编排基于Skilldescription语义匹配，自动编排多Skill执行顺序。3实时查看执行过程界面展示每个Skill的调用状态、输入输出、耗时，便于调试。4获取最终输出Agent汇总所有Skill结果，生成自然语言回复并附产物链接。Skill间数据传递与串联编排三种数据传递机制+四种编排模式，构建复杂业务流水线的核心能力一、数据传递机制上下文自动注入上游Skill的output自动写入工作流上下文，下游Skill按字段名自动读取。优点：零配置，约定优于配置要求：字段名与类型必须对齐显式参数映射通过mapping配置指定源字段到目标字段的转换关系，支持重命名、类型转换、表达式计算。场景：字段名不一致、需数据转换语法：target:${source.field}全局变量存储跨Skill、跨轮次的持久化存储，用于保存用户偏好、中间状态、大对象引用。生命周期：会话级/工作流级注意：敏感数据需加密存储二、串联编排模式PATTERN01顺序执行A→B→C，最基础模式适用于有严格依赖的流水线PATTERN02条件分支if/else按结果选择路径适用于分类处理、异常降级PATTERN03并行执行A∥B同时执行后汇总适用于无依赖的批量任务PATTERN04循环迭代for/while重复调用Skill适用于批量处理、重试编排建议：优先用顺序执行，需要判断加条件分支，无依赖任务用并行提速，循环必须设置最大迭代次数防止死循环。远程调用与API网关集成跨节点Skill调用架构：鉴权、限流、熔断、可观测性四大网关能力CLIENT本地Agent发起Skill调用请求HTTPSAPIGATEWAYAPI网关层鉴权·限流·路由熔断·日志·监控gRPCSKILLSERVICEA爬虫Skill服务SKILLSERVICEB数据分析Skill服务SKILLSERVICEC报告生成Skill服务MORESERVICES弹性扩展集群...网关四大核心能力鉴权与安全·APIKey简单鉴权·OAuth2/JWT令牌·mTLS双向认证·IP白名单+签名校验限流与熔断·令牌桶速率限制·并发数控制·熔断降级（错误率阈值）·超时控制+重试策略路由与负载均衡·按路径/版本路由·灰度发布（流量切分）·加权轮询/一致性哈希·健康检查+自动摘除可观测性·全链路追踪（TraceID）·调用指标（QPS/延迟）·结构化日志采集·告警规则配置生产环境必须：所有远程Skill调用经过API网关，禁止直连后端服务；熔断阈值建议错误率>50%触发，超时不超过30秒。常见问题排查Six类高频故障的现象、根因与解决方案，按出现频率排序#问题现象根因分析解决方案1Skill匹配失败description过于抽象，缺少触发关键词；与其他Skill语义重叠导致路由错误优化description，增加具体场景词和输入输出示例；使用显式@skill_name强制调用2数据传递丢失上游output与下游input字段名不一致；类型不匹配（stringvsobject）；嵌套字段路径错误检查SKILL.md的parameters契约；使用显式mapping配置字段映射；开启上下文调试日志3调用超时Skill本身执行慢（爬虫、大文件处理）；远程服务网络延迟；默认超时30s不足在Skill配置中调大timeout；长任务改为异步执行+轮询；检查远程服务健康状态4权限拒绝403APIKey未配置或已过期；OAuth令牌失效；远程Skill服务未授予调用方权限检查环境变量中的密钥配置；刷新OAuth令牌；在API网关配置调用方的访问策略5循环死循环循环编排未设置终止条件；max_iterations未配置；Skill输出始终触发下一轮调用必须设置max_iterations（建议≤10）；增加结果收敛判断；监控循环调用次数并告警6结果格式错误Skill输出不符合JSONSchema；字段缺失或类型错误；LLM生成的结构化数据不稳定在Skill出口增加JSONSchema校验；失败时自动重试或降级；使用functioncalling约束输出格式排查口诀：先看日志定层级（匹配/传递/执行/输出），再查契约对字段，最后看配置和权限。80%的问题出在输入输出契约不对齐。本节总结五大核心要点回顾+能力进阶路径，从Skill消费者到生态贡献者核心要点回顾01调用对用户透明，Agent自动匹配编排用户只需描述目标，Skill的选择、排序、串联由Agent完成02输入输出契约是多Skill协同的基石字段名、类型、结构必须对齐，80%的协同问题源于契约不一致03循环必须设上限，远程调用必须过网关两条生产红线：max_iterations防死循环，API网关统一安全管控04四种编排模式按需组合，优先顺序执行四种编排模式按需组合，简单任务用顺序，复杂任务组合使用05排查先定层级：匹配→传递→执行→输出通过日志定位故障层级，再针对性排查契约、配置、权限，效率最高能力进阶路径LEVEL1Skill消费者会调用、会排查、能组合现有Skill完成任务↓LEVEL2Skill编排者能设计复杂工作流、优化契约、搭建企业级Skill体系↓LEVEL3Skill生态贡献者开发高质量Skill、发布到ClawHub、推动社区生态繁荣下节预告：7-3ClawHub技能商店使用→从消费者到贡献者课后实操任务搭建三Skill协同流水线，完成从文件扫描到报告生成的完整自动化任务任务名称文件批量处理流水线：扫描→转换→报告任务步骤（建议用时90分钟）1环境准备与契约设计（15分钟）安装OpenClaw，定义三个Skill的input/outputJSONSchema2实现三个Skill核心逻辑（30分钟）文件扫描、格式转换、报告生成，每个Skill独立可运行3配置工作流编排与数据传递（20分钟）顺序执行编排，配置上游output到下游input的字段映射4端到端测试与问题排查（25分钟）准备测试文件，运行完整流水线，定位并修复数据传递问题评判标准（满分100分）验收项分值通过标准三个Skill独立可运行25全部通过输入输出契约定义清晰15Schema完整工作流自动串联执行