1. OpenClaw技能开发概述OpenClaw作为新一代智能体开发平台其技能系统采用模块化设计理念。每个技能本质上是一个独立的功能单元通过标准化的目录结构和Markdown文件进行定义。这种设计既保证了功能的独立性又实现了系统的可扩展性。技能开发的核心在于SKILL.md文件它采用YAML frontmatter定义元数据正文部分则包含具体的操作指令。这种混合格式既方便机器解析又保持了人类可读性。在实际项目中我经常建议开发者将相关技能按功能域分类存放比如建立/skills/network、/skills/io等子目录这样既便于管理又不会影响技能的实际调用。2. Hello World技能实现详解2.1 技能目录结构创建规范的目录结构是技能开发的第一步。建议在用户主目录下的.openclaw/workspace/skills/路径中创建技能目录mkdir -p ~/.openclaw/workspace/skills/hello-world这里有几个关键细节需要注意目录名建议使用小写字母和连字符与后续SKILL.md中的name字段保持一致即使将技能放在子目录中如/skills/demo/hello-world调用时仍使用/hello-world而非完整路径工作区目录结构会在OpenClaw启动时自动加载无需额外配置2.2 SKILL.md文件编写完整的SKILL.md示例--- name: hello-world description: Prints a greeting message. user-invocable: true --- # Greeting Skill When user requests a greeting: 1. Use exec tool to run: bash echo Hello from OpenClaw!关键字段说明name: 必须使用小写字母、数字和连字符且需与目录名一致description: 会显示在斜杠命令列表中建议控制在160字符内user-invocable: 设为true才能通过/hello-world直接调用实际开发中发现description字段的质量直接影响技能被调用的准确率。建议用动词开头明确功能如Send greeting message比Greeting skill更明确。2.3 技能加载验证编写完成后可通过以下命令验证技能是否成功加载openclaw skills list | grep hello-world如果修改了已有技能需要重启网关使变更生效openclaw gateway restart常见问题排查技能未显示检查目录是否在skills/下SKILL.md文件名是否正确权限问题确保OpenClaw进程对技能目录有读取权限格式错误使用yamllint等工具验证YAML语法3. 技能调用与测试3.1 基础调用方式有三种主要调用方式显式调用推荐openclaw agent --message /skill hello-world自然语言触发openclaw agent --message say hello聊天界面直接输入/hello-world3.2 执行过程分析当技能被调用时OpenClaw会解析SKILL.md中的frontmatter获取元数据将Markdown正文转换为操作指令根据exec工具声明执行对应命令返回标准输出结果执行流程示意图[用户请求] - [技能匹配] - [指令解析] - [工具执行] - [结果返回]3.3 调试技巧开发过程中建议添加--verbose参数查看详细日志openclaw agent --message hello --verbose使用exec工具时先本地测试命令# 测试SKILL.md中的命令 echo Hello from OpenClaw!对于复杂技能分阶段验证先测试基础命令执行再添加条件逻辑最后整合完整功能4. 高级技能配置4.1 环境变量管理通过openclaw.json配置技能专属环境变量{ skills: { entries: { hello-world: { enabled: true, apiKey: { source: env, provider: default, id: GREETING_API_KEY } } } } }这种配置方式可以实现不同技能的环境隔离避免敏感信息硬编码方便不同环境切换配置4.2 条件门控设置通过metadata控制技能加载条件--- name: advanced-greeting metadata: { openclaw: { requires: { bins: [festival], env: [GREETING_LANG] }, os: [linux] } } ---支持的条件类型二进制依赖requires.bins环境变量requires.env操作系统os配置文件requires.config4.3 技能工作坊流程对于团队协作场景建议使用Skill Workshop# 创建新技能提案 openclaw skills workshop propose-create \ --name hello-world \ --description Greeting skill \ --proposal ./PROPOSAL.md # 审核提案 openclaw skills workshop inspect ID # 应用通过审核的提案 openclaw skills workshop apply ID工作坊模式特别适合需要代码审查的场景多人协作开发需要保留修改历史的项目5. 生产环境最佳实践5.1 安全规范使用exec工具时必须验证输入bash # 安全示例 - 使用固定命令 echo Hello $USER # 危险示例 - 直接执行用户输入 echo $USER_INPUT敏感操作添加确认步骤Before running this command, always ask for confirmation: Are you sure you want to execute this command?限制技能权限{ skills: { hello-world: { allowExec: [echo] } } }5.2 性能优化减少技能加载时间避免在frontmatter中添加不必要的大段metadata将大型资源文件放在assets/子目录提高响应速度# 使用缓存示例 bash [ -f /tmp/greeting ] || echo Hello /tmp/greeting cat /tmp/greeting批量处理优化 对于高频调用的技能建议使用内置工具而非exec减少子进程创建合并连续操作5.3 版本管理与发布通过ClawHub管理技能版本# 安装ClawHub CLI npm install -g clawhub # 登录并发布技能 clawhub login clawhub skill publish ./hello-world --version 1.0.0版本控制建议遵循语义化版本规范重大变更升级主版本号保持向后兼容性为每个版本添加变更说明6. 典型问题解决方案6.1 技能加载失败排查常见错误及解决方法错误现象可能原因解决方案技能未显示目录位置错误确认在~/.openclaw/workspace/skills/下权限拒绝文件权限不足chmod r SKILL.md解析失败YAML语法错误使用yamllint验证格式依赖缺失requires配置不满足检查bins/env配置6.2 执行异常处理命令不存在# 添加存在性检查 bash command -v festival /dev/null echo Hello || echo Greeting参数错误Always validate input parameters: bash [[ $1 ~ ^[a-Z]$ ]] echo Hello $1 || echo Invalid name超时处理{ skills: { hello-world: { timeout: 5 } } }6.3 跨平台适配操作系统判断bash case $(uname -s) in Linux*) echo Hello Linux ;; Darwin*) echo Hello Mac ;; *) echo Hello ;; esac路径处理Use {baseDir} for skill-relative paths: bash cat {baseDir}/config/greeting.txt换行符转换bash # 统一换行符 sed -i s/\r$// {baseDir}/scripts/run.sh在开发自定义技能时我发现最有效的调试方式是使用--message参数进行快速测试同时结合journalctl -u openclaw查看系统日志。对于复杂技能建议先制作最小可行版本再逐步添加功能。
