OpenClaw技能动态加载机制详解

有兴趣的朋友可以到我的知识星球“小龙虾孵化实验室”共同探索智能工具的实现与应用落地与变现。目录核心概念OpenClaw 技能加载机制小龙虾技能加载机制对比分析最佳实践故障排查注小龙虾是我开发的类OpenClaw系统核心概念什么是技能动态加载技能动态加载 AI 启动时自动扫描技能目录解析技能定义生成工具列表无需修改代码。传统方式静态// 硬编码在代码中this.toolDefinitions[{name:read_file,...},{name:write_file,...},// 添加新技能需要修改代码];动态加载// 运行时生成this.toolDefinitionsthis.loadSkillsFromDirectory();// 添加新技能只需复制文件到 skills/ 目录技能文件格式SKILL.md--- name: weather description: Get current weather and forecasts (no API key required). homepage: https://wttr.in/:help metadata: {clawdbot:{emoji:️,requires:{bins:[curl]}}} --- # Weather Two free services, no API keys needed. ## wttr.in (primary) bash curl -s wttr.in/London?format3Open-Meteo (fallback, JSON)curl-shttps://api.open-meteo.com/v1/forecast?...**结构说明** - **Frontmatter**YAML技能元数据 - name - 技能名称工具调用名 - description - 技能描述AI 理解用途 - homepage - 技能主页 - metadata - 扩展配置 - **Markdown 正文**技能使用说明、示例代码 --- ## OpenClaw 技能加载机制 ### 目录结构 ~/.openclaw/ ├── workspace/ │ └── skills/ # 技能目录 │ ├── weather/ # 天气技能 │ │ └── SKILL.md │ ├── stock-monitor/ # 股票监控 │ │ └── SKILL.md │ └── README.md ├── config/ │ └── openclaw.json # 配置文件 └── ...加载流程┌─────────────────────────────────────────────────────────┐ │ 1. OpenClaw Gateway 启动 │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 2. 扫描 skills 目录 │ │ for skill_dir in workspace/skills/ │ │ if exists(skill_dir /SKILL.md): │ │ skills.append(parseSKILL(skill_dir)) │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 3. 解析 SKILL.md │ │ - 读取 frontmatterYAML │ │ - 提取 name, description, metadata │ │ - 验证技能格式 │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 4. 注册技能到工具系统 │ │ tools.register({ │ │ name: skill.name, │ │ description: skill.description, │ │ handler: loadSkillHandler(skill.path) │ │ }) │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 5. 生成系统提示词 │ │ prompt │ │ 你是阿财老大的助手。 │ │ │ │ ## 你有以下工具 │ │ ${tools.map(t - ${t.name}: ${t.description})}│ │ │ │ ... │ │ │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 6. 发送给大模型 │ │ - 大模型看到动态生成的工具列表 │ │ - 根据需要调用工具 │ │ - Gateway 执行对应技能 │ └─────────────────────────────────────────────────────────┘核心代码伪代码// OpenClaw GatewayclassSkillManager{constructor(workspace){this.skillsDirpath.join(workspace,skills);this.skills[];}asyncloadSkills(){// 扫描技能目录constdirsawaitfs.readdir(this.skillsDir);for(constdirofdirs){constskillPathpath.join(this.skillsDir,dir,SKILL.md);if(awaitfs.exists(skillPath)){constskillawaitthis.parseSKILL(skillPath);this.skills.push(skill);// 注册工具this.tools.register({name:skill.name,description:skill.description,handler:this.createHandler(skill)});}}}asyncparseSKILL(path){constcontentawaitfs.readFile(path,utf-8);constpartscontent.split(---);// 解析 YAML frontmatterconstfrontmatteryaml.parse(parts[1]);return{name:frontmatter.name,description:frontmatter.description,path:path,body:parts[2]};}buildPrompt(){constlines[## 你有以下工具];for(constskillofthis.skills){lines.push(-${skill.name}:${skill.description});}returnlines.join(\n);}}特点特性说明技能存储~/.openclaw/workspace/skills/加载时机Gateway 启动时技能格式SKILL.mdYAML frontmatter Markdown工具注册自动注册到 Gateway 工具系统提示词生成运行时动态生成技能执行Gateway 统一调度小龙虾技能加载机制目录结构simple-ai/ ├── src/ │ ├── core/ │ │ ├── skill_loader.py # 技能加载器 │ │ └── plugin_manager.py # 插件管理器 │ └── assistant-v7.js # AI 核心 ├── skills/ # 技能目录与 OpenClaw 共享 │ └── weather/ │ └── SKILL.md └── ...加载流程┌─────────────────────────────────────────────────────────┐ │ 1. 小龙虾启动node src/server.js │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 2. 创建 AI 助手实例 │ │ const assistant new SimpleAIAssistant(...) │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 3. 调用异步初始化 │ │ await assistant.init() │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 4. 加载技能调用 Python 加载器 │ │ spawn(python, [skill_loader.py, skills_dir]) │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 5. Python 技能加载器执行 │ │ - 扫描 skills 目录 │ │ - 解析 SKILL.md │ │ - 输出技能列表JSON/文本 │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 6. Node.js 解析输出 │ │ - 提取技能名和描述 │ │ - 构建工具定义JSON Schema │ │ - 更新 this.toolDefinitions │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 7. 生成系统提示词 │ │ this.buildToolsPrompt() │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 8. 调用大模型 API │ │ - 发送工具定义给千问 API │ │ - 接收工具调用请求 │ │ - 执行对应技能 │ └─────────────────────────────────────────────────────────┘核心代码Python 技能加载器skill_loader.pyclassSkillLoader:def__init__(self,skills_dir):self.skills_dirskills_dir self.skills[]defscan_skills(self):扫描所有技能foriteminos.listdir(self.skills_dir):item_pathos.path.join(self.skills_dir,item)ifnotos.path.isdir(item_path)oritem.startswith(.):continueskill_mdos.path.join(item_path,SKILL.md)ifos.path.exists(skill_md):skillself._parse_skill_md(skill_md)ifskill:self.skills.append(skill)print(f[OK] 加载技能{skill[name]})returnself.skillsdef_parse_skill_md(self,path):解析 SKILL.mdwithopen(path,r,encodingutf-8)asf:contentf.read()# 提取 frontmatterifcontent.startswith(---):partscontent.split(---,2)frontmatter_strparts[1].strip()frontmatterself._parse_yaml(frontmatter_str)return{name:frontmatter.get(name,),description:frontmatter.get(description,),path:path,}returnNonedefbuild_tools_definition(self):构建工具定义JSON Schematools[]forskillinself.skills:tool{type:function,function:{name:skill[name],description:skill[description],parameters:{type:object,properties:{city:{type:string,description:城市名,default:Beijing}}}}}tools.append(tool)returntoolsNode.js AI 核心assistant-v7.jsclassSimpleAIAssistant{constructor(apiKey,workspace){this.workspaceworkspace;this.skillsDirpath.join(workspace,..,skills);this.skills[];this.toolDefinitions[];}asyncinit(){awaitthis.loadSkills();awaitthis.loadMemoryToCache();}asyncloadSkills(){log(正在加载技能...);// 调用 Python 技能加载器constresultawaitnewPromise((resolve,reject){constpyProcessspawn(python,[path.join(__dirname,core,skill_loader.py),this.skillsDir],{cwd:this.workspace,encoding:utf-8});letoutput;pyProcess.stdout.on(data,(data){outputdata;});pyProcess.on(close,(code){if(code0)resolve(output);elsereject(newError(加载失败));});});// 解析输出提取技能constskillMatchesresult.match(/\[OK\] 加载技能(.)/g);if(skillMatches){for(constmatchofskillMatches){constskillNamematch.replace([OK] 加载技能,).trim();this.skills.push({name:skillName});}}// 更新工具定义this.toolDefinitionsthis.buildToolDefinitions();log(加载完成${this.skills.length}个技能);}buildToolDefinitions(){// 基础工具constbaseToolsthis.getBaseToolDefinitions();// 技能工具constskillToolsthis.skills.map(skill({type:function,function:{name:skill.name,description:调用${skill.name}技能,parameters:{type:object,properties:{city:{type:string,description:城市名,default:Beijing}}}}}));returnbaseTools.concat(skillTools);}buildToolsPrompt(){constlines[## 你有以下工具];// 基础工具constbaseToolsthis.getBaseToolDefinitions();for(consttoolofbaseTools){lines.push(-${tool.function.name}:${tool.function.description});}// 技能工具for(constskillofthis.skills){lines.push(-${skill.name}: 调用${skill.name}技能);}returnlines.join(\n);}}特点特性说明技能存储simple-ai/../skills/可与 OpenClaw 共享加载时机AI 启动时异步技能格式SKILL.md与 OpenClaw 兼容工具注册动态生成 JSON Schema提示词生成运行时动态生成技能执行Node.js 直接执行或调用 Python 对比分析架构对比维度OpenClaw小龙虾运行环境Node.js GatewayNode.js Python技能目录~/.openclaw/workspace/skills/simple-ai/../skills/加载方式直接扫描调用 Python 加载器工具注册Gateway 内部注册JSON Schema 生成技能执行Gateway 统一调度直接执行/Python 调用配置复杂度中等简单优劣势分析OpenClaw优势统一调度资源管理好技能执行环境隔离支持复杂技能编排有完整的技能市场劣势架构复杂学习成本高需要 Gateway 常驻运行技能执行有额外开销小龙虾优势架构简单易于理解直接执行响应快Python Node.js 灵活组合可与 OpenClaw 共享技能劣势技能执行需要自己管理没有统一的调度系统技能市场依赖 OpenClaw【注现已接入腾讯的skills社区】实践1. 技能目录管理推荐结构skills/ ├── weather/ # 按功能分类 │ └── SKILL.md ├── stock-monitor/ │ └── SKILL.md └── README.md # 技能说明文档命名规范技能名用小写字母和连字符避免中文和空格描述要清晰简洁2. SKILL.md 编写好的示例--- name: weather description: 查询全球任何城市的当前天气和预报 homepage: https://wttr.in/ metadata: {emoji:️} --- # Weather Skill 查询天气情况无需 API 密钥。 ## 使用方法 bash curl -s wttr.in/Beijing?format3参数说明city: 城市名英文或拼音format: 输出格式3简洁T详细**避免** - 描述过于简单查天气 - 没有使用示例 - 参数说明不清晰 ### 3. 技能加载优化 **启动时预加载** javascript // 推荐启动时加载 await assistant.init(); // 不推荐每次请求都加载 async chat() { await this.loadSkills(); // 太慢 }缓存技能列表# 技能变化时重新加载ifskills_changed:loader.scan_skills()else:returncached_skills4. 错误处理技能加载失败try{awaitthis.loadSkills();}catch(error){log(技能加载失败${error.message});// 使用基础工具继续运行this.toolDefinitionsthis.getBaseToolDefinitions();}技能执行失败asyncexecuteSkill(skill,params){try{returnawaitskill.handler(params);}catch(error){return技能执行失败${error.message};}} 故障排查问题 1技能未加载现象AI 说我没有这个工具排查步骤检查技能目录是否存在ls~/.openclaw/workspace/skills/检查 SKILL.md 格式catweather/SKILL.md查看加载日志tail-flogs/info.log|grep技能手动测试加载器python src/core/skill_loader.py ~/.openclaw/workspace/skills/问题 2技能加载报错常见错误output is not defined→ Promise 作用域问题EADDRINUSE→ 端口被占用ENOENT→ 文件路径错误解决方法检查代码中的变量作用域停止占用的进程使用绝对路径问题 3技能执行失败排查步骤检查技能依赖如 curl、python 包查看技能执行日志手动测试技能命令检查权限问题总结核心要点技能即文件- 每个技能是独立的 SKILL.md 文件动态发现- 启动时自动扫描无需修改代码提示词生成- 运行时构建工具列表零配置- 用户安装技能后重启即可用计划技能热加载- 无需重启即可加载新技能技能依赖管理- 自动安装技能依赖技能沙箱- 更安全地执行第三方技能技能市场- 一键安装社区技能有兴趣的朋友可以到我的知识星球“小龙虾孵化实验室”共同探索智能工具的实现与应用落地与变现。