1. 项目概述为什么我们需要一份SKILL.md如果你正在接触OpenClaw或者已经尝试过部署和运行它你可能会发现一个现象系统自带的技能Skill用起来很顺手但当你想要定制一个属于自己的、能解决特定业务问题的技能时往往会感到无从下手。官方文档可能告诉你“创建一个skill目录编写__init__.py和skill.py”但这中间的空白地带——如何构思、如何设计、如何调试、如何让技能真正“智能”起来——才是真正的挑战所在。这正是我决定动手写一份《SKILL.md》的初衷。它不是一个简单的API参考而是一份从零开始的、手把手的技能开发实战指南。这份文档的核心价值在于填补“知道要做什么”和“知道具体怎么做”之间的鸿沟。OpenClaw作为一个开源的AI智能体框架其魅力在于高度的可定制性你可以让它成为你的专属客服、数据分析助手、自动化流程引擎。但这份自由也带来了复杂性你需要理解其事件驱动架构、掌握技能与核心服务如LLM、记忆、工具调用的交互方式并学会处理各种边界情况。网络上关于OpenClaw的热搜词如“openclaw安装教程”、“docker部署openclaw”、“openclaw接入飞书”大多集中在部署和基础使用层面。而“openclaw skill”、“openclaw如何配置大模型”则开始触及核心。但更深入的问题比如“如何让技能记住上下文”、“如何处理技能执行中的异常”、“如何设计一个需要多轮对话的复杂技能”却少有系统性的解答。这份《SKILL.md》就是要解决这些问题它将技能开发拆解为清晰、可执行的步骤并融入大量我在实际项目中踩坑后总结的经验目标是让你不仅能复现更能理解其设计哲学从而创造出真正有价值的AI智能体。2. 技能开发的核心思路与架构设计在动手写代码之前我们必须先理解OpenClaw技能是如何工作的。这就像盖房子先有蓝图才能一砖一瓦地搭建。OpenClaw的技能体系建立在事件总线和插件化架构之上一个技能本质上是一个监听特定事件、执行逻辑、并可能触发新事件的独立模块。2.1 事件驱动技能运转的基石OpenClaw内部的所有通信都通过事件Event进行。用户的一条消息、一个定时任务、一个外部API的回调都会被封装成事件。你的技能需要声明它关心哪些类型的事件。例如一个“天气查询”技能可能只关心包含“天气”关键词的文本消息事件而一个“会议纪要”技能可能需要监听语音转文本后的事件。这种设计带来了巨大的灵活性。技能之间是解耦的它们只通过事件交互互不知晓对方的存在。这让你可以轻松地增、删、改技能而不会影响系统其他部分。在构思你的技能时第一个要问自己的问题就是“我的技能应该由什么事件触发” 这个问题的答案将直接决定你技能类中supported_events属性的定义。2.2 技能的生命周期从注册到执行一个技能从被系统加载到处理完一个请求大致经历以下几个阶段注册OpenClaw启动时会在指定的技能目录中扫描所有符合规范的Python包并实例化其中的技能类。此时技能的__init__方法会被调用这是你初始化数据库连接、加载配置文件、注册自定义工具的最佳时机。事件匹配当一个事件被发布到总线时OpenClaw会检查所有已注册技能的supported_events和event_filter方法判断该技能是否应该处理此事件。预处理如果匹配成功会调用技能的pre_process方法。这里可以进行一些轻量的检查比如权限验证、参数初步提取。如果返回False处理流程会就此终止。核心处理接着调用process方法。这里是技能逻辑的核心你在这里与LLM对话、调用工具、处理业务数据。这个方法应该返回一个SkillOutput对象其中包含了要返回给用户的响应内容。后处理最后调用post_process方法。你可以在这里进行日志记录、数据持久化、或触发新的后续事件例如处理完一个订单后自动触发一个发货通知事件。理解这个生命周期至关重要它告诉你在哪个阶段应该做什么事。把资源初始化放在__init__把核心业务放在process把清理和回调放在post_process能让你的代码清晰且健壮。2.3 与核心服务的交互LLM、记忆与工具一个强大的技能 rarely works alone。它需要借助OpenClaw的核心服务LLM服务这是技能“智能”的来源。你通过self.llm来调用配置好的大模型。关键不在于直接问“今天天气如何”而在于设计合适的系统提示词System Prompt和对话历史引导LLM理解上下文并以结构化方式如JSON输出方便你后续解析。记忆服务self.memory让技能拥有“记忆”。你可以存储和检索与当前会话或用户相关的信息。对于多轮对话技能这是实现上下文连贯性的关键。例如一个旅行规划技能需要记住用户之前提到的目的地和预算。工具调用OpenClaw允许技能暴露自定义工具函数给LLM。当LLM认为需要执行某个具体操作如查询数据库、调用外部API时它可以“思考”并决定调用你提供的工具。这是实现复杂、确定性操作的核心手段。在设计技能时你需要像导演一样思考LLM是那位富有创造力但需要引导的演员记忆是剧本的上下文工具是舞台上可用的实体道具。你的代码技能逻辑就是导演的指令协调这三者共同完成一场表演。3. 从零开始创建你的第一个技能理论说得再多不如动手实践。让我们创建一个最简单的“回声”技能它会把用户说的话原样返回但在此基础上我们会逐步添加复杂度演示一个完整技能的诞生过程。3.1 环境准备与项目结构假设你的OpenClaw已经部署在/opt/openclaw目录无论是源码部署还是Docker部署技能开发方式类似。技能通常存放在skills/目录下每个技能是一个独立的Python包。首先创建技能目录结构cd /opt/openclaw/skills mkdir -p echo_skill/echo_skill cd echo_skill一个最简化的技能包结构如下echo_skill/ ├── pyproject.toml # 包声明和依赖管理可选但推荐 ├── README.md # 技能说明文档 ├── echo_skill/ # Python包目录 │ ├── __init__.py # 必须存在用于标识这是一个包 │ └── skill.py # 技能主逻辑文件 └── tests/ # 单元测试目录可选pyproject.toml文件可以很简单[project] name openclaw-skill-echo version 0.1.0 description A simple echo skill for OpenClaw3.2 编写技能骨架代码现在打开echo_skill/skill.py开始编写核心代码。我们从最基本的骨架开始import logging from typing import List, Optional from openclaw.models.events import BaseEvent, TextMessageEvent from openclaw.skills.base import BaseSkill, SkillOutput logger logging.getLogger(__name__) class EchoSkill(BaseSkill): 一个简单的回声技能用于演示技能开发基础。 # 1. 技能元信息 name echo_skill description 将用户发送的文本信息原样返回。 version 0.1.0 # 2. 声明支持的事件类型 supported_events [TextMessageEvent] def __init__(self, **kwargs): super().__init__(**kwargs) # 在这里初始化你的资源例如数据库连接、API客户端等。 # 对于简单的回声技能可能什么都不需要。 logger.info(f技能 {self.name} 初始化完成。) def event_filter(self, event: BaseEvent) - bool: 更细粒度的事件过滤器。 这里我们只处理纯文本消息并且忽略可能来自系统或其他技能的消息。 if not isinstance(event, TextMessageEvent): return False # 示例忽略以斜杠开头的命令消息可能由其他技能处理 if event.text.startswith(/): return False # 也可以检查消息来源比如只处理来自特定用户或群组的事件 # if event.sender_id not in self.allowed_users: # return False return True async def pre_process(self, event: TextMessageEvent) - bool: 预处理。这里可以做一些轻量检查如果返回False则跳过process。 # 检查消息是否为空 if not event.text or event.text.strip() : logger.warning(收到空消息跳过处理。) return False logger.debug(f开始预处理消息: {event.text[:50]}...) return True async def process(self, event: TextMessageEvent) - Optional[SkillOutput]: 核心处理逻辑。 user_message event.text logger.info(f处理回声请求: {user_message}) # 最简单的逻辑原样返回 response_text f你说了: {user_message} # 构建返回对象 output SkillOutput( contentresponse_text, eventevent # 通常需要关联原始事件 ) return output async def post_process(self, event: TextMessageEvent, output: SkillOutput): 后处理。用于日志、清理或触发链式事件。 logger.info(f技能执行完毕。输入: {event.text}, 输出: {output.content}) # 例如可以将本次交互存入长期记忆 # await self.memory.add_conversation(event.session_id, event.text, output.content) pass这个技能已经可以工作了将它放到skills/目录下重启OpenClaw服务它就会自动加载。当你发送一条文本消息非命令时就会收到回声回复。3.3 为技能添加配置项硬编码的参数不利于维护。OpenClaw技能支持通过配置文件进行参数化。首先在技能根目录创建config.yaml或config.json# echo_skill/config.yaml echo: prefix: 回声: # 在回复前添加的前缀 enabled: true # 是否启用该技能 ignore_keywords: # 包含这些关键词的消息将不被回声 - 密码 - token然后修改skill.py的__init__和process方法来读取配置class EchoSkill(BaseSkill): # ... 元信息部分不变 ... def __init__(self, **kwargs): super().__init__(**kwargs) # 加载技能专属配置 self.config self.load_config(config.yaml) self.prefix self.config.get(echo, {}).get(prefix, 回声: ) self.ignore_keywords self.config.get(echo, {}).get(ignore_keywords, []) logger.info(f技能配置加载: prefix{self.prefix}) async def event_filter(self, event: BaseEvent) - bool: # ... 原有逻辑 ... # 增加配置检查 if not self.config.get(echo, {}).get(enabled, True): return False return True async def process(self, event: TextMessageEvent) - Optional[SkillOutput]: user_message event.text # 检查是否包含忽略关键词 for keyword in self.ignore_keywords: if keyword in user_message: logger.warning(f消息包含忽略关键词 {keyword}不予回声。) return None # 返回None表示不产生输出 response_text f{self.prefix}{user_message} # ... 其余不变 ...注意load_config方法是BaseSkill提供的辅助方法它会自动在技能目录下寻找配置文件。确保你的配置文件格式正确并且技能对文件有读取权限。4. 进阶技能开发集成LLM与工具调用一个只会回声的技能显然不够“智能”。接下来我们升级它创建一个“智能问答”技能它不仅能回复还能调用外部工具例如查询天气和利用LLM进行总结。4.1 设计系统提示词System Prompt与LLM交互的核心是设计一个好的系统提示词。它定义了LLM的角色、能力和行为规范。我们创建一个prompts/system.md文件# prompts/system.md 你是一个乐于助人的AI助手集成在OpenClaw系统中。你的名字叫“小智”。 ## 能力 1. 你可以进行友好的日常对话。 2. 当用户询问天气时你可以调用get_weather工具来获取实时天气信息并组织成友好的语言回复用户。 3. 当用户要求总结一段文本时你可以进行简洁的概括。 ## 行为规范 - 回复应简洁、准确、友好。 - 如果用户的问题超出你的能力范围请礼貌地告知。 - 调用工具时请严格按照工具要求的JSON格式提供参数。 - 所有回复请使用中文。在技能中加载并使用这个提示词class SmartQASkill(BaseSkill): # ... 元信息 ... def __init__(self, **kwargs): super().__init__(**kwargs) # 加载系统提示词 with open(os.path.join(os.path.dirname(__file__), prompts, system.md), r, encodingutf-8) as f: self.system_prompt f.read() # 初始化对话历史存储结构 self.conversation_history {} # 键可以是session_id async def process(self, event: TextMessageEvent) - Optional[SkillOutput]: session_id event.session_id user_input event.text # 1. 获取或初始化当前会话的历史 if session_id not in self.conversation_history: self.conversation_history[session_id] [] history self.conversation_history[session_id] # 2. 构建发送给LLM的消息列表 messages [ {role: system, content: self.system_prompt}, *history, # 注入历史对话 {role: user, content: user_input} ] # 3. 调用LLM并允许其使用工具 try: # 注意这里假设LLM服务支持工具调用格式如OpenAI的function calling response await self.llm.chat_completion( messagesmessages, tools[self.get_weather_tool_schema()], # 提供工具定义 tool_choiceauto # 让LLM自行决定是否调用工具 ) except Exception as e: logger.error(f调用LLM失败: {e}) return SkillOutput(content抱歉我暂时无法处理你的请求。, eventevent) # 4. 处理LLM的响应 llm_message response.choices[0].message final_response if llm_message.tool_calls: # LLM决定调用工具 for tool_call in llm_message.tool_calls: if tool_call.function.name get_weather: # 解析参数并执行工具 args json.loads(tool_call.function.arguments) city args.get(city) weather_info await self._get_weather_impl(city) # 实际调用天气API # 将工具执行结果作为新的消息追加让LLM生成面向用户的回复 messages.append(llm_message) # 添加LLM的请求 messages.append({ role: tool, tool_call_id: tool_call.id, content: weather_info }) # 再次调用LLM让它根据工具结果生成最终回复 second_response await self.llm.chat_completion(messagesmessages) final_response second_response.choices[0].message.content else: # LLM直接生成了回复 final_response llm_message.content # 5. 更新对话历史注意控制长度避免无限增长 history.append({role: user, content: user_input}) history.append({role: assistant, content: final_response}) # 可选只保留最近N轮对话 if len(history) 10: history history[-10:] self.conversation_history[session_id] history return SkillOutput(contentfinal_response, eventevent) def get_weather_tool_schema(self): 定义get_weather工具的JSON Schema用于告知LLM如何使用此工具。 return { type: function, function: { name: get_weather, description: 获取指定城市的实时天气信息。, parameters: { type: object, properties: { city: { type: string, description: 城市名称例如北京、上海 } }, required: [city] } } } async def _get_weather_impl(self, city: str) - str: 实际执行天气查询的工具函数。 # 这里应该调用真实的天气API例如和风天气、OpenWeatherMap等。 # 为演示我们返回模拟数据。 logger.info(f查询天气: {city}) # 模拟API调用延迟 await asyncio.sleep(0.5) return json.dumps({city: city, weather: 晴, temperature: 22°C, humidity: 65%})这个技能已经具备了基本的智能它能理解上下文通过conversation_history能在需要时调用外部工具并能根据工具结果生成人性化的回复。这是构建复杂技能的基础模式。4.2 利用记忆服务实现持久化上下文上面的例子使用内存字典存储历史这在服务重启后会丢失且无法在多实例间共享。OpenClaw提供了self.memory服务它可能基于数据库如PostgreSQL、Redis可以实现持久化和共享。改造上面的历史管理部分async def process(self, event: TextMessageEvent) - Optional[SkillOutput]: session_id event.session_id user_input event.text # 1. 从记忆服务中获取历史 # 假设memory服务有get_conversation_history方法 history await self.memory.get_conversation_history(session_id, limit5) # 获取最近5轮 # history 格式可能是 [{role:user, content:...}, {role:assistant, content:...}, ...] # 2. 构建消息列表 (同上) messages [{role: system, content: self.system_prompt}] if history: messages.extend(history) messages.append({role: user, content: user_input}) # ... (调用LLM和处理工具响应的部分不变) ... # 5. 将本轮对话存入记忆服务 new_history_entry [ {role: user, content: user_input}, {role: assistant, content: final_response} ] await self.memory.add_to_conversation_history(session_id, new_history_entry) return SkillOutput(contentfinal_response, eventevent)实操心得使用记忆服务时要特别注意会话session的标识。event.session_id通常能唯一标识一次对话上下文例如一个私聊窗口或一个群聊。确保你的技能使用一致的session_id进行存储和检索。另外记忆服务的具体API可能因OpenClaw版本或配置的存储后端而异开发时需要查阅对应版本的文档或源码。5. 技能调试、测试与性能优化开发完成只是第一步让技能稳定、高效地运行同样重要。5.1 单元测试与集成测试为技能编写测试是保证质量的最佳实践。使用pytest框架在tests/目录下创建测试文件。单元测试示例 (tests/test_skill.py):import pytest from unittest.mock import AsyncMock, MagicMock, patch from echo_skill.skill import EchoSkill from openclaw.models.events import TextMessageEvent pytest.fixture def mock_skill(): 创建一个模拟了基础服务的技能实例。 skill EchoSkill() skill.llm AsyncMock() skill.memory AsyncMock() skill.logger MagicMock() return skill pytest.mark.asyncio async def test_event_filter_accepts_text(mock_skill): event TextMessageEvent(texthello, session_idtest_session) result await mock_skill.event_filter(event) assert result is True pytest.mark.asyncio async def test_event_filter_rejects_command(mock_skill): event TextMessageEvent(text/help, session_idtest_session) result await mock_skill.event_filter(event) assert result is False pytest.mark.asyncio async def test_process_echo(mock_skill): event TextMessageEvent(text测试消息, session_idtest_session) output await mock_skill.process(event) assert output is not None assert 测试消息 in output.content集成测试可以编写一个简单的脚本模拟OpenClaw环境来调用技能检查端到端的流程。这有助于发现配置、依赖等问题。5.2 日志与监控完善的日志是调试的利器。在技能中合理使用logger对象记录关键步骤、输入输出和错误。logger logging.getLogger(__name__) class MySkill(BaseSkill): async def process(self, event): logger.debug(f开始处理事件: {event.id}) # 详细流程 logger.info(f用户输入: {event.text}) # 关键信息 try: # ... 业务逻辑 ... logger.info(业务逻辑执行成功。) except SomeSpecificError as e: logger.error(f处理业务时发生特定错误: {e}, exc_infoTrue) # 记录异常堆栈 return None except Exception as e: logger.exception(f处理过程发生未知异常: {e}) # 自动记录完整堆栈 return None建议为技能配置独立的日志级别可以在OpenClaw的主配置文件或技能配置中指定例如将日志级别设为DEBUG以便在开发时看到更详细的信息。5.3 性能考量与最佳实践异步编程OpenClaw基于异步IOasyncio。确保你的技能中所有可能阻塞的I/O操作网络请求、数据库查询、文件读写都使用异步库如aiohttp,asyncpg,aiofiles或放在线程池中执行避免阻塞整个事件循环。资源管理在__init__中初始化的资源如HTTP客户端、数据库连接池考虑在技能的shutdown方法如果基类提供或使用上下文管理器进行妥善关闭防止资源泄漏。错误处理与重试对于调用外部API等可能失败的操作实现重试机制和断路器模式。这能极大提升技能的鲁棒性。限制与超时为LLM调用、工具调用设置合理的超时时间。对于用户输入可以进行长度限制或复杂度检查防止恶意或意外输入导致服务过载。缓存对于频繁查询且变化不频繁的数据如城市信息、静态配置使用内存缓存如lru_cache或Redis缓存减少不必要的计算和外部调用。6. 实战构建一个电商客服技能让我们综合运用以上知识设计一个更贴近实际场景的技能一个简单的电商客服技能。它能处理订单查询、退货申请并能将复杂问题转接给人工。6.1 需求分析与设计触发事件文本消息事件。核心功能意图识别判断用户是想查询订单、申请退货还是其他。订单查询调用内部订单系统API根据订单号返回状态。退货引导提供标准退货流程链接并收集必要信息订单号、问题描述创建工单。人工转接当识别到复杂问题或用户明确要求时结束自动对话并通知人工客服系统。所需服务LLM用于意图识别和信息提取、记忆记录用户状态、自定义工具调用订单API、创建工单。6.2 系统提示词设计# prompts/customer_service.md 你是一个电商平台的AI客服助手。你的主要职责是高效、准确地处理用户的常见问题并在必要时引导至人工服务。 ## 你的能力 1. **订单查询**当用户提供订单号时你可以调用query_order_status工具获取最新状态并用清晰、友好的语言告知用户。 2. **退货申请**当用户表达退货意愿时你需要 a. 请用户提供订单号。 b. 询问退货原因简短描述即可。 c. 调用create_return_ticket工具为用户创建退货工单并告知工单号和后续流程。 3. **人工转接**遇到以下情况你应主动建议转接人工客服 - 用户明确说“转人工”、“找真人客服”。 - 问题涉及复杂的纠纷、赔偿等。 - 你无法理解用户意图或连续两次未能解决用户问题。 此时调用transfer_to_human工具并礼貌告知用户稍后会有专员联系。 ## 回复风格 - 专业、友善、耐心。 - 一次尽量只解决一个问题或只询问一个信息。 - 使用中文适当使用表情符号如增加亲和力但不要过度。6.3 关键代码实现这里展示核心的process方法和工具调用部分class EcommerceServiceSkill(BaseSkill): # ... 元信息、__init__等 ... async def process(self, event: TextMessageEvent) - Optional[SkillOutput]: session_id event.session_id user_input event.text # 从记忆获取当前会话状态例如是否正在处理退货流程 state await self.memory.get(session_id, conversation_state, defaultidle) context await self.memory.get(session_id, context, default{}) messages [ {role: system, content: self.system_prompt}, {role: system, content: f当前对话状态: {state}. 上下文: {context}}, # 注入状态 *await self.memory.get_conversation_history(session_id, limit3), {role: user, content: user_input} ] tools [ self._get_tool_schema(query_order_status), self._get_tool_schema(create_return_ticket), self._get_tool_schema(transfer_to_human) ] response await self.llm.chat_completion(messagesmessages, toolstools, tool_choiceauto) llm_message response.choices[0].message final_response new_state state new_context context.copy() if llm_message.tool_calls: for tool_call in llm_message.tool_calls: func_name tool_call.function.name args json.loads(tool_call.function.arguments) if func_name query_order_status: order_id args[order_id] # 调用内部API status await self._call_order_api(order_id) tool_result json.dumps({order_id: order_id, status: status}) # 更新上下文记录查询过的订单 new_context[last_queried_order] order_id elif func_name create_return_ticket: order_id args[order_id] reason args.get(reason, ) # 调用工单系统API ticket_id await self._create_ticket(order_id, reason, session_id) tool_result json.dumps({ticket_id: ticket_id, message: 工单已创建}) # 重置状态 new_state idle new_context.pop(pending_return_order, None) elif func_name transfer_to_human: # 通知人工客服系统 await self._notify_human_agent(session_id, user_input) tool_result json.dumps({transferred: True}) final_response 您的问题已转接给人工客服请稍候。 # 可以设置状态为“已转接”避免后续继续自动回复 new_state transferred break # 转人工后不再需要LLM生成回复 # 将工具执行结果追加到消息历史让LLM生成最终回复 messages.append(llm_message) messages.append({ role: tool, tool_call_id: tool_call.id, content: tool_result }) if new_state ! transferred: # 需要LLM根据工具结果生成回复 second_response await self.llm.chat_completion(messagesmessages) final_response second_response.choices[0].message.content else: # LLM直接回复可能需要更新状态例如识别到用户开始提供退货信息 final_response llm_message.content # 可以在这里添加简单的规则更新状态机 if 退货 in user_input and state idle: new_state awaiting_return_order_id new_context[intent] return # 保存更新后的状态和上下文到记忆 await self.memory.set(session_id, conversation_state, new_state) await self.memory.set(session_id, context, new_context) # 保存对话历史 await self._save_conversation_round(session_id, user_input, final_response) return SkillOutput(contentfinal_response, eventevent) if final_response else None6.4 状态管理与多轮对话这个技能演示了简单的状态管理conversation_state。对于更复杂的流程如多步骤表单填写可以设计更精细的状态机State Machine或者直接利用LLM的强大理解能力在系统提示词中明确告知当前步骤和已收集的信息让LLM来主导流程。后者更灵活但可能对提示词工程要求更高。7. 部署、配置与问题排查技能开发完成后如何让它成为OpenClaw服务的一部分7.1 技能部署方式本地开发模式直接将技能目录放到OpenClaw的skills/目录下。修改OpenClaw的主配置文件如config/skills.yaml确保你的技能在启用列表中。重启OpenClaw服务即可。Docker部署如果你使用Docker运行OpenClaw需要将技能目录挂载到容器内的技能路径。例如在docker-compose.yml中services: openclaw: image: openclaw/openclaw:latest volumes: - ./my_skills:/app/skills # 将本地的my_skills目录挂载到容器的技能目录 - ./config:/app/config # 挂载配置文件 # ... 其他配置然后在容器内的/app/config/skills.yaml中配置启用你的技能。打包分发对于成熟的技能可以打包成Python包wheel上传到私有或公共的PyPI仓库。这样其他人可以通过pip install your-skill-package安装并在OpenClaw配置中通过包名来启用。这要求你的技能pyproject.toml配置正确且skill.py位于包的根目录或通过入口点entry-point声明。7.2 常见配置问题技能未加载检查OpenClaw日志看是否有加载错误。常见原因包括技能目录结构不正确缺少__init__.py、技能类未继承BaseSkill、pyproject.toml格式错误、或Python依赖未安装。LLM调用失败检查OpenClaw的LLM配置如API Key、Base URL是否正确。在技能代码中捕获LLM异常并记录详细日志。记忆服务不可用如果使用了self.memory但未配置记忆后端如Redis相关调用会失败。确保OpenClaw的memory部分配置正确或者你的技能在不依赖记忆的情况下有降级方案。事件不触发检查技能的supported_events和event_filter逻辑。确保你发送的事件类型匹配并且过滤条件没有错误地排除掉目标事件。可以通过在event_filter方法开始处打印日志来调试。7.3 调试技巧实录启用Debug日志在OpenClaw的日志配置中将你的技能对应的logger级别设为DEBUG。这能让你看到技能内部更详细的执行流程。使用模拟事件测试可以编写一个测试脚本直接实例化你的技能类并手动创建和发送事件对象观察其处理流程和输出而不需要启动完整的OpenClaw服务。检查工具调用格式LLM工具调用失败很多时候是因为工具的模式Schema定义与LLM期望的格式不匹配或者工具返回的结果格式不符合LLM预期。仔细对比OpenAI等平台的Function Calling文档确保模式定义准确。会话隔离问题如果发现不同用户的对话历史混在一起检查session_id的生成逻辑。确保来自不同用户或不同聊天窗口的事件拥有不同的session_id。开发OpenClaw技能是一个将创意、工程思维和对AI能力的理解相结合的过程。从最简单的回声开始逐步集成LLM、工具和记忆你就能构建出功能强大且实用的智能体。最关键的是保持迭代从真实交互中学习不断优化提示词、工具设计和错误处理。这份《SKILL.md》希望为你提供了一个坚实的起点和持续的参考剩下的就交给你的想象力和代码了。如果在实践中遇到具体问题不妨回头看看技能的生命周期和与核心服务的交互方式大部分难题都能从中找到解决思路。 OpenClaw技能开发实战指南：从事件驱动到LLM集成的完整流程
1. 项目概述为什么我们需要一份SKILL.md如果你正在接触OpenClaw或者已经尝试过部署和运行它你可能会发现一个现象系统自带的技能Skill用起来很顺手但当你想要定制一个属于自己的、能解决特定业务问题的技能时往往会感到无从下手。官方文档可能告诉你“创建一个skill目录编写__init__.py和skill.py”但这中间的空白地带——如何构思、如何设计、如何调试、如何让技能真正“智能”起来——才是真正的挑战所在。这正是我决定动手写一份《SKILL.md》的初衷。它不是一个简单的API参考而是一份从零开始的、手把手的技能开发实战指南。这份文档的核心价值在于填补“知道要做什么”和“知道具体怎么做”之间的鸿沟。OpenClaw作为一个开源的AI智能体框架其魅力在于高度的可定制性你可以让它成为你的专属客服、数据分析助手、自动化流程引擎。但这份自由也带来了复杂性你需要理解其事件驱动架构、掌握技能与核心服务如LLM、记忆、工具调用的交互方式并学会处理各种边界情况。网络上关于OpenClaw的热搜词如“openclaw安装教程”、“docker部署openclaw”、“openclaw接入飞书”大多集中在部署和基础使用层面。而“openclaw skill”、“openclaw如何配置大模型”则开始触及核心。但更深入的问题比如“如何让技能记住上下文”、“如何处理技能执行中的异常”、“如何设计一个需要多轮对话的复杂技能”却少有系统性的解答。这份《SKILL.md》就是要解决这些问题它将技能开发拆解为清晰、可执行的步骤并融入大量我在实际项目中踩坑后总结的经验目标是让你不仅能复现更能理解其设计哲学从而创造出真正有价值的AI智能体。2. 技能开发的核心思路与架构设计在动手写代码之前我们必须先理解OpenClaw技能是如何工作的。这就像盖房子先有蓝图才能一砖一瓦地搭建。OpenClaw的技能体系建立在事件总线和插件化架构之上一个技能本质上是一个监听特定事件、执行逻辑、并可能触发新事件的独立模块。2.1 事件驱动技能运转的基石OpenClaw内部的所有通信都通过事件Event进行。用户的一条消息、一个定时任务、一个外部API的回调都会被封装成事件。你的技能需要声明它关心哪些类型的事件。例如一个“天气查询”技能可能只关心包含“天气”关键词的文本消息事件而一个“会议纪要”技能可能需要监听语音转文本后的事件。这种设计带来了巨大的灵活性。技能之间是解耦的它们只通过事件交互互不知晓对方的存在。这让你可以轻松地增、删、改技能而不会影响系统其他部分。在构思你的技能时第一个要问自己的问题就是“我的技能应该由什么事件触发” 这个问题的答案将直接决定你技能类中supported_events属性的定义。2.2 技能的生命周期从注册到执行一个技能从被系统加载到处理完一个请求大致经历以下几个阶段注册OpenClaw启动时会在指定的技能目录中扫描所有符合规范的Python包并实例化其中的技能类。此时技能的__init__方法会被调用这是你初始化数据库连接、加载配置文件、注册自定义工具的最佳时机。事件匹配当一个事件被发布到总线时OpenClaw会检查所有已注册技能的supported_events和event_filter方法判断该技能是否应该处理此事件。预处理如果匹配成功会调用技能的pre_process方法。这里可以进行一些轻量的检查比如权限验证、参数初步提取。如果返回False处理流程会就此终止。核心处理接着调用process方法。这里是技能逻辑的核心你在这里与LLM对话、调用工具、处理业务数据。这个方法应该返回一个SkillOutput对象其中包含了要返回给用户的响应内容。后处理最后调用post_process方法。你可以在这里进行日志记录、数据持久化、或触发新的后续事件例如处理完一个订单后自动触发一个发货通知事件。理解这个生命周期至关重要它告诉你在哪个阶段应该做什么事。把资源初始化放在__init__把核心业务放在process把清理和回调放在post_process能让你的代码清晰且健壮。2.3 与核心服务的交互LLM、记忆与工具一个强大的技能 rarely works alone。它需要借助OpenClaw的核心服务LLM服务这是技能“智能”的来源。你通过self.llm来调用配置好的大模型。关键不在于直接问“今天天气如何”而在于设计合适的系统提示词System Prompt和对话历史引导LLM理解上下文并以结构化方式如JSON输出方便你后续解析。记忆服务self.memory让技能拥有“记忆”。你可以存储和检索与当前会话或用户相关的信息。对于多轮对话技能这是实现上下文连贯性的关键。例如一个旅行规划技能需要记住用户之前提到的目的地和预算。工具调用OpenClaw允许技能暴露自定义工具函数给LLM。当LLM认为需要执行某个具体操作如查询数据库、调用外部API时它可以“思考”并决定调用你提供的工具。这是实现复杂、确定性操作的核心手段。在设计技能时你需要像导演一样思考LLM是那位富有创造力但需要引导的演员记忆是剧本的上下文工具是舞台上可用的实体道具。你的代码技能逻辑就是导演的指令协调这三者共同完成一场表演。3. 从零开始创建你的第一个技能理论说得再多不如动手实践。让我们创建一个最简单的“回声”技能它会把用户说的话原样返回但在此基础上我们会逐步添加复杂度演示一个完整技能的诞生过程。3.1 环境准备与项目结构假设你的OpenClaw已经部署在/opt/openclaw目录无论是源码部署还是Docker部署技能开发方式类似。技能通常存放在skills/目录下每个技能是一个独立的Python包。首先创建技能目录结构cd /opt/openclaw/skills mkdir -p echo_skill/echo_skill cd echo_skill一个最简化的技能包结构如下echo_skill/ ├── pyproject.toml # 包声明和依赖管理可选但推荐 ├── README.md # 技能说明文档 ├── echo_skill/ # Python包目录 │ ├── __init__.py # 必须存在用于标识这是一个包 │ └── skill.py # 技能主逻辑文件 └── tests/ # 单元测试目录可选pyproject.toml文件可以很简单[project] name openclaw-skill-echo version 0.1.0 description A simple echo skill for OpenClaw3.2 编写技能骨架代码现在打开echo_skill/skill.py开始编写核心代码。我们从最基本的骨架开始import logging from typing import List, Optional from openclaw.models.events import BaseEvent, TextMessageEvent from openclaw.skills.base import BaseSkill, SkillOutput logger logging.getLogger(__name__) class EchoSkill(BaseSkill): 一个简单的回声技能用于演示技能开发基础。 # 1. 技能元信息 name echo_skill description 将用户发送的文本信息原样返回。 version 0.1.0 # 2. 声明支持的事件类型 supported_events [TextMessageEvent] def __init__(self, **kwargs): super().__init__(**kwargs) # 在这里初始化你的资源例如数据库连接、API客户端等。 # 对于简单的回声技能可能什么都不需要。 logger.info(f技能 {self.name} 初始化完成。) def event_filter(self, event: BaseEvent) - bool: 更细粒度的事件过滤器。 这里我们只处理纯文本消息并且忽略可能来自系统或其他技能的消息。 if not isinstance(event, TextMessageEvent): return False # 示例忽略以斜杠开头的命令消息可能由其他技能处理 if event.text.startswith(/): return False # 也可以检查消息来源比如只处理来自特定用户或群组的事件 # if event.sender_id not in self.allowed_users: # return False return True async def pre_process(self, event: TextMessageEvent) - bool: 预处理。这里可以做一些轻量检查如果返回False则跳过process。 # 检查消息是否为空 if not event.text or event.text.strip() : logger.warning(收到空消息跳过处理。) return False logger.debug(f开始预处理消息: {event.text[:50]}...) return True async def process(self, event: TextMessageEvent) - Optional[SkillOutput]: 核心处理逻辑。 user_message event.text logger.info(f处理回声请求: {user_message}) # 最简单的逻辑原样返回 response_text f你说了: {user_message} # 构建返回对象 output SkillOutput( contentresponse_text, eventevent # 通常需要关联原始事件 ) return output async def post_process(self, event: TextMessageEvent, output: SkillOutput): 后处理。用于日志、清理或触发链式事件。 logger.info(f技能执行完毕。输入: {event.text}, 输出: {output.content}) # 例如可以将本次交互存入长期记忆 # await self.memory.add_conversation(event.session_id, event.text, output.content) pass这个技能已经可以工作了将它放到skills/目录下重启OpenClaw服务它就会自动加载。当你发送一条文本消息非命令时就会收到回声回复。3.3 为技能添加配置项硬编码的参数不利于维护。OpenClaw技能支持通过配置文件进行参数化。首先在技能根目录创建config.yaml或config.json# echo_skill/config.yaml echo: prefix: 回声: # 在回复前添加的前缀 enabled: true # 是否启用该技能 ignore_keywords: # 包含这些关键词的消息将不被回声 - 密码 - token然后修改skill.py的__init__和process方法来读取配置class EchoSkill(BaseSkill): # ... 元信息部分不变 ... def __init__(self, **kwargs): super().__init__(**kwargs) # 加载技能专属配置 self.config self.load_config(config.yaml) self.prefix self.config.get(echo, {}).get(prefix, 回声: ) self.ignore_keywords self.config.get(echo, {}).get(ignore_keywords, []) logger.info(f技能配置加载: prefix{self.prefix}) async def event_filter(self, event: BaseEvent) - bool: # ... 原有逻辑 ... # 增加配置检查 if not self.config.get(echo, {}).get(enabled, True): return False return True async def process(self, event: TextMessageEvent) - Optional[SkillOutput]: user_message event.text # 检查是否包含忽略关键词 for keyword in self.ignore_keywords: if keyword in user_message: logger.warning(f消息包含忽略关键词 {keyword}不予回声。) return None # 返回None表示不产生输出 response_text f{self.prefix}{user_message} # ... 其余不变 ...注意load_config方法是BaseSkill提供的辅助方法它会自动在技能目录下寻找配置文件。确保你的配置文件格式正确并且技能对文件有读取权限。4. 进阶技能开发集成LLM与工具调用一个只会回声的技能显然不够“智能”。接下来我们升级它创建一个“智能问答”技能它不仅能回复还能调用外部工具例如查询天气和利用LLM进行总结。4.1 设计系统提示词System Prompt与LLM交互的核心是设计一个好的系统提示词。它定义了LLM的角色、能力和行为规范。我们创建一个prompts/system.md文件# prompts/system.md 你是一个乐于助人的AI助手集成在OpenClaw系统中。你的名字叫“小智”。 ## 能力 1. 你可以进行友好的日常对话。 2. 当用户询问天气时你可以调用get_weather工具来获取实时天气信息并组织成友好的语言回复用户。 3. 当用户要求总结一段文本时你可以进行简洁的概括。 ## 行为规范 - 回复应简洁、准确、友好。 - 如果用户的问题超出你的能力范围请礼貌地告知。 - 调用工具时请严格按照工具要求的JSON格式提供参数。 - 所有回复请使用中文。在技能中加载并使用这个提示词class SmartQASkill(BaseSkill): # ... 元信息 ... def __init__(self, **kwargs): super().__init__(**kwargs) # 加载系统提示词 with open(os.path.join(os.path.dirname(__file__), prompts, system.md), r, encodingutf-8) as f: self.system_prompt f.read() # 初始化对话历史存储结构 self.conversation_history {} # 键可以是session_id async def process(self, event: TextMessageEvent) - Optional[SkillOutput]: session_id event.session_id user_input event.text # 1. 获取或初始化当前会话的历史 if session_id not in self.conversation_history: self.conversation_history[session_id] [] history self.conversation_history[session_id] # 2. 构建发送给LLM的消息列表 messages [ {role: system, content: self.system_prompt}, *history, # 注入历史对话 {role: user, content: user_input} ] # 3. 调用LLM并允许其使用工具 try: # 注意这里假设LLM服务支持工具调用格式如OpenAI的function calling response await self.llm.chat_completion( messagesmessages, tools[self.get_weather_tool_schema()], # 提供工具定义 tool_choiceauto # 让LLM自行决定是否调用工具 ) except Exception as e: logger.error(f调用LLM失败: {e}) return SkillOutput(content抱歉我暂时无法处理你的请求。, eventevent) # 4. 处理LLM的响应 llm_message response.choices[0].message final_response if llm_message.tool_calls: # LLM决定调用工具 for tool_call in llm_message.tool_calls: if tool_call.function.name get_weather: # 解析参数并执行工具 args json.loads(tool_call.function.arguments) city args.get(city) weather_info await self._get_weather_impl(city) # 实际调用天气API # 将工具执行结果作为新的消息追加让LLM生成面向用户的回复 messages.append(llm_message) # 添加LLM的请求 messages.append({ role: tool, tool_call_id: tool_call.id, content: weather_info }) # 再次调用LLM让它根据工具结果生成最终回复 second_response await self.llm.chat_completion(messagesmessages) final_response second_response.choices[0].message.content else: # LLM直接生成了回复 final_response llm_message.content # 5. 更新对话历史注意控制长度避免无限增长 history.append({role: user, content: user_input}) history.append({role: assistant, content: final_response}) # 可选只保留最近N轮对话 if len(history) 10: history history[-10:] self.conversation_history[session_id] history return SkillOutput(contentfinal_response, eventevent) def get_weather_tool_schema(self): 定义get_weather工具的JSON Schema用于告知LLM如何使用此工具。 return { type: function, function: { name: get_weather, description: 获取指定城市的实时天气信息。, parameters: { type: object, properties: { city: { type: string, description: 城市名称例如北京、上海 } }, required: [city] } } } async def _get_weather_impl(self, city: str) - str: 实际执行天气查询的工具函数。 # 这里应该调用真实的天气API例如和风天气、OpenWeatherMap等。 # 为演示我们返回模拟数据。 logger.info(f查询天气: {city}) # 模拟API调用延迟 await asyncio.sleep(0.5) return json.dumps({city: city, weather: 晴, temperature: 22°C, humidity: 65%})这个技能已经具备了基本的智能它能理解上下文通过conversation_history能在需要时调用外部工具并能根据工具结果生成人性化的回复。这是构建复杂技能的基础模式。4.2 利用记忆服务实现持久化上下文上面的例子使用内存字典存储历史这在服务重启后会丢失且无法在多实例间共享。OpenClaw提供了self.memory服务它可能基于数据库如PostgreSQL、Redis可以实现持久化和共享。改造上面的历史管理部分async def process(self, event: TextMessageEvent) - Optional[SkillOutput]: session_id event.session_id user_input event.text # 1. 从记忆服务中获取历史 # 假设memory服务有get_conversation_history方法 history await self.memory.get_conversation_history(session_id, limit5) # 获取最近5轮 # history 格式可能是 [{role:user, content:...}, {role:assistant, content:...}, ...] # 2. 构建消息列表 (同上) messages [{role: system, content: self.system_prompt}] if history: messages.extend(history) messages.append({role: user, content: user_input}) # ... (调用LLM和处理工具响应的部分不变) ... # 5. 将本轮对话存入记忆服务 new_history_entry [ {role: user, content: user_input}, {role: assistant, content: final_response} ] await self.memory.add_to_conversation_history(session_id, new_history_entry) return SkillOutput(contentfinal_response, eventevent)实操心得使用记忆服务时要特别注意会话session的标识。event.session_id通常能唯一标识一次对话上下文例如一个私聊窗口或一个群聊。确保你的技能使用一致的session_id进行存储和检索。另外记忆服务的具体API可能因OpenClaw版本或配置的存储后端而异开发时需要查阅对应版本的文档或源码。5. 技能调试、测试与性能优化开发完成只是第一步让技能稳定、高效地运行同样重要。5.1 单元测试与集成测试为技能编写测试是保证质量的最佳实践。使用pytest框架在tests/目录下创建测试文件。单元测试示例 (tests/test_skill.py):import pytest from unittest.mock import AsyncMock, MagicMock, patch from echo_skill.skill import EchoSkill from openclaw.models.events import TextMessageEvent pytest.fixture def mock_skill(): 创建一个模拟了基础服务的技能实例。 skill EchoSkill() skill.llm AsyncMock() skill.memory AsyncMock() skill.logger MagicMock() return skill pytest.mark.asyncio async def test_event_filter_accepts_text(mock_skill): event TextMessageEvent(texthello, session_idtest_session) result await mock_skill.event_filter(event) assert result is True pytest.mark.asyncio async def test_event_filter_rejects_command(mock_skill): event TextMessageEvent(text/help, session_idtest_session) result await mock_skill.event_filter(event) assert result is False pytest.mark.asyncio async def test_process_echo(mock_skill): event TextMessageEvent(text测试消息, session_idtest_session) output await mock_skill.process(event) assert output is not None assert 测试消息 in output.content集成测试可以编写一个简单的脚本模拟OpenClaw环境来调用技能检查端到端的流程。这有助于发现配置、依赖等问题。5.2 日志与监控完善的日志是调试的利器。在技能中合理使用logger对象记录关键步骤、输入输出和错误。logger logging.getLogger(__name__) class MySkill(BaseSkill): async def process(self, event): logger.debug(f开始处理事件: {event.id}) # 详细流程 logger.info(f用户输入: {event.text}) # 关键信息 try: # ... 业务逻辑 ... logger.info(业务逻辑执行成功。) except SomeSpecificError as e: logger.error(f处理业务时发生特定错误: {e}, exc_infoTrue) # 记录异常堆栈 return None except Exception as e: logger.exception(f处理过程发生未知异常: {e}) # 自动记录完整堆栈 return None建议为技能配置独立的日志级别可以在OpenClaw的主配置文件或技能配置中指定例如将日志级别设为DEBUG以便在开发时看到更详细的信息。5.3 性能考量与最佳实践异步编程OpenClaw基于异步IOasyncio。确保你的技能中所有可能阻塞的I/O操作网络请求、数据库查询、文件读写都使用异步库如aiohttp,asyncpg,aiofiles或放在线程池中执行避免阻塞整个事件循环。资源管理在__init__中初始化的资源如HTTP客户端、数据库连接池考虑在技能的shutdown方法如果基类提供或使用上下文管理器进行妥善关闭防止资源泄漏。错误处理与重试对于调用外部API等可能失败的操作实现重试机制和断路器模式。这能极大提升技能的鲁棒性。限制与超时为LLM调用、工具调用设置合理的超时时间。对于用户输入可以进行长度限制或复杂度检查防止恶意或意外输入导致服务过载。缓存对于频繁查询且变化不频繁的数据如城市信息、静态配置使用内存缓存如lru_cache或Redis缓存减少不必要的计算和外部调用。6. 实战构建一个电商客服技能让我们综合运用以上知识设计一个更贴近实际场景的技能一个简单的电商客服技能。它能处理订单查询、退货申请并能将复杂问题转接给人工。6.1 需求分析与设计触发事件文本消息事件。核心功能意图识别判断用户是想查询订单、申请退货还是其他。订单查询调用内部订单系统API根据订单号返回状态。退货引导提供标准退货流程链接并收集必要信息订单号、问题描述创建工单。人工转接当识别到复杂问题或用户明确要求时结束自动对话并通知人工客服系统。所需服务LLM用于意图识别和信息提取、记忆记录用户状态、自定义工具调用订单API、创建工单。6.2 系统提示词设计# prompts/customer_service.md 你是一个电商平台的AI客服助手。你的主要职责是高效、准确地处理用户的常见问题并在必要时引导至人工服务。 ## 你的能力 1. **订单查询**当用户提供订单号时你可以调用query_order_status工具获取最新状态并用清晰、友好的语言告知用户。 2. **退货申请**当用户表达退货意愿时你需要 a. 请用户提供订单号。 b. 询问退货原因简短描述即可。 c. 调用create_return_ticket工具为用户创建退货工单并告知工单号和后续流程。 3. **人工转接**遇到以下情况你应主动建议转接人工客服 - 用户明确说“转人工”、“找真人客服”。 - 问题涉及复杂的纠纷、赔偿等。 - 你无法理解用户意图或连续两次未能解决用户问题。 此时调用transfer_to_human工具并礼貌告知用户稍后会有专员联系。 ## 回复风格 - 专业、友善、耐心。 - 一次尽量只解决一个问题或只询问一个信息。 - 使用中文适当使用表情符号如增加亲和力但不要过度。6.3 关键代码实现这里展示核心的process方法和工具调用部分class EcommerceServiceSkill(BaseSkill): # ... 元信息、__init__等 ... async def process(self, event: TextMessageEvent) - Optional[SkillOutput]: session_id event.session_id user_input event.text # 从记忆获取当前会话状态例如是否正在处理退货流程 state await self.memory.get(session_id, conversation_state, defaultidle) context await self.memory.get(session_id, context, default{}) messages [ {role: system, content: self.system_prompt}, {role: system, content: f当前对话状态: {state}. 上下文: {context}}, # 注入状态 *await self.memory.get_conversation_history(session_id, limit3), {role: user, content: user_input} ] tools [ self._get_tool_schema(query_order_status), self._get_tool_schema(create_return_ticket), self._get_tool_schema(transfer_to_human) ] response await self.llm.chat_completion(messagesmessages, toolstools, tool_choiceauto) llm_message response.choices[0].message final_response new_state state new_context context.copy() if llm_message.tool_calls: for tool_call in llm_message.tool_calls: func_name tool_call.function.name args json.loads(tool_call.function.arguments) if func_name query_order_status: order_id args[order_id] # 调用内部API status await self._call_order_api(order_id) tool_result json.dumps({order_id: order_id, status: status}) # 更新上下文记录查询过的订单 new_context[last_queried_order] order_id elif func_name create_return_ticket: order_id args[order_id] reason args.get(reason, ) # 调用工单系统API ticket_id await self._create_ticket(order_id, reason, session_id) tool_result json.dumps({ticket_id: ticket_id, message: 工单已创建}) # 重置状态 new_state idle new_context.pop(pending_return_order, None) elif func_name transfer_to_human: # 通知人工客服系统 await self._notify_human_agent(session_id, user_input) tool_result json.dumps({transferred: True}) final_response 您的问题已转接给人工客服请稍候。 # 可以设置状态为“已转接”避免后续继续自动回复 new_state transferred break # 转人工后不再需要LLM生成回复 # 将工具执行结果追加到消息历史让LLM生成最终回复 messages.append(llm_message) messages.append({ role: tool, tool_call_id: tool_call.id, content: tool_result }) if new_state ! transferred: # 需要LLM根据工具结果生成回复 second_response await self.llm.chat_completion(messagesmessages) final_response second_response.choices[0].message.content else: # LLM直接回复可能需要更新状态例如识别到用户开始提供退货信息 final_response llm_message.content # 可以在这里添加简单的规则更新状态机 if 退货 in user_input and state idle: new_state awaiting_return_order_id new_context[intent] return # 保存更新后的状态和上下文到记忆 await self.memory.set(session_id, conversation_state, new_state) await self.memory.set(session_id, context, new_context) # 保存对话历史 await self._save_conversation_round(session_id, user_input, final_response) return SkillOutput(contentfinal_response, eventevent) if final_response else None6.4 状态管理与多轮对话这个技能演示了简单的状态管理conversation_state。对于更复杂的流程如多步骤表单填写可以设计更精细的状态机State Machine或者直接利用LLM的强大理解能力在系统提示词中明确告知当前步骤和已收集的信息让LLM来主导流程。后者更灵活但可能对提示词工程要求更高。7. 部署、配置与问题排查技能开发完成后如何让它成为OpenClaw服务的一部分7.1 技能部署方式本地开发模式直接将技能目录放到OpenClaw的skills/目录下。修改OpenClaw的主配置文件如config/skills.yaml确保你的技能在启用列表中。重启OpenClaw服务即可。Docker部署如果你使用Docker运行OpenClaw需要将技能目录挂载到容器内的技能路径。例如在docker-compose.yml中services: openclaw: image: openclaw/openclaw:latest volumes: - ./my_skills:/app/skills # 将本地的my_skills目录挂载到容器的技能目录 - ./config:/app/config # 挂载配置文件 # ... 其他配置然后在容器内的/app/config/skills.yaml中配置启用你的技能。打包分发对于成熟的技能可以打包成Python包wheel上传到私有或公共的PyPI仓库。这样其他人可以通过pip install your-skill-package安装并在OpenClaw配置中通过包名来启用。这要求你的技能pyproject.toml配置正确且skill.py位于包的根目录或通过入口点entry-point声明。7.2 常见配置问题技能未加载检查OpenClaw日志看是否有加载错误。常见原因包括技能目录结构不正确缺少__init__.py、技能类未继承BaseSkill、pyproject.toml格式错误、或Python依赖未安装。LLM调用失败检查OpenClaw的LLM配置如API Key、Base URL是否正确。在技能代码中捕获LLM异常并记录详细日志。记忆服务不可用如果使用了self.memory但未配置记忆后端如Redis相关调用会失败。确保OpenClaw的memory部分配置正确或者你的技能在不依赖记忆的情况下有降级方案。事件不触发检查技能的supported_events和event_filter逻辑。确保你发送的事件类型匹配并且过滤条件没有错误地排除掉目标事件。可以通过在event_filter方法开始处打印日志来调试。7.3 调试技巧实录启用Debug日志在OpenClaw的日志配置中将你的技能对应的logger级别设为DEBUG。这能让你看到技能内部更详细的执行流程。使用模拟事件测试可以编写一个测试脚本直接实例化你的技能类并手动创建和发送事件对象观察其处理流程和输出而不需要启动完整的OpenClaw服务。检查工具调用格式LLM工具调用失败很多时候是因为工具的模式Schema定义与LLM期望的格式不匹配或者工具返回的结果格式不符合LLM预期。仔细对比OpenAI等平台的Function Calling文档确保模式定义准确。会话隔离问题如果发现不同用户的对话历史混在一起检查session_id的生成逻辑。确保来自不同用户或不同聊天窗口的事件拥有不同的session_id。开发OpenClaw技能是一个将创意、工程思维和对AI能力的理解相结合的过程。从最简单的回声开始逐步集成LLM、工具和记忆你就能构建出功能强大且实用的智能体。最关键的是保持迭代从真实交互中学习不断优化提示词、工具设计和错误处理。这份《SKILL.md》希望为你提供了一个坚实的起点和持续的参考剩下的就交给你的想象力和代码了。如果在实践中遇到具体问题不妨回头看看技能的生命周期和与核心服务的交互方式大部分难题都能从中找到解决思路。