OpenClaw 自定义技能开发教程

openclaw openclaw官方 2026-04-09 2

OpenClaw 是一个开源的语音助手平台，允许开发者创建自定义技能来扩展其功能，本教程将指导您完成自定义技能的开发流程。

OpenClaw 自定义技能开发教程-第1张图片-OpenClaw开源下载|官方OpenClaw下载

环境准备

安装 OpenClaw

# 克隆 OpenClaw 仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw
# 安装依赖
pip install -r requirements.txt

技能开发工具包

# 安装技能开发工具
pip install openclaw-sdk

技能结构

一个基本的技能包含以下结构：

my_skill/
├── __init__.py
├── manifest.json      # 技能配置文件
├── handlers.py        # 请求处理程序
├── intents/           # 意图定义
├── dialogs/           # 对话流程
└── utils/             # 工具函数

创建你的第一个技能

步骤1：创建技能目录

import os
from openclaw.skill_builder import SkillBuilder
# 创建技能基础结构
sb = SkillBuilder("my_first_skill")
sb.create_structure()

步骤2：配置技能清单 (manifest.json)

{
  "skillName": "MyFirstSkill",
  "version": "1.0.0",
  "author": "YourName",
  "description": "我的第一个OpenClaw技能",
  "invocationName": "我的技能",
  "category": "UTILITY",
  "intents": [
    {
      "name": "GreetIntent",
      "samples": [
        "你好",
        "打个招呼",
        "说hello"
      ]
    }
  ]
}

步骤3：实现意图处理程序

# handlers.py
from openclaw import skill
@skill.request_handler("LaunchRequest")
def launch_handler(event, context):
    """处理启动请求"""
    return skill.respond(
        "欢迎使用我的技能！你可以说：你好",
        should_end_session=False
    )
@skill.intent_handler("GreetIntent")
def greet_handler(event, context):
    """处理问候意图"""
    import datetime
    current_hour = datetime.datetime.now().hour
    if 5 <= current_hour < 12:
        greeting = "早上好！"
    elif 12 <= current_hour < 18:
        greeting = "下午好！"
    else:
        greeting = "晚上好！"
    return skill.respond(
        f"{greeting}很高兴为你服务！",
        should_end_session=False
    )

步骤4：添加对话管理

# dialogs/greet_dialog.py
from openclaw.dialog import Dialog
class GreetDialog(Dialog):
    def __init__(self):
        super().__init__("GreetDialog")
    def start(self, session):
        session["step"] = "ask_name"
        return "请问你叫什么名字？"
    def handle_response(self, session, user_input):
        if session.get("step") == "ask_name":
            session["user_name"] = user_input
            session["step"] = "greet"
            return f"你好{user_input}！有什么可以帮你的吗？"
        return None

步骤5：注册技能

# __init__.py
from openclaw import skill
from .handlers import *
from .dialogs.greet_dialog import GreetDialog
def initialize():
    # 注册对话框
    skill.register_dialog("greet", GreetDialog())
    # 注册技能
    return skill.SkillBuilder("my_first_skill").build()

高级功能

使用槽位 (Slots)

@skill.intent_handler("WeatherIntent")
def weather_handler(event, context):
    """天气查询技能"""
    city = event.get_slot_value("city")
    if not city:
        return skill.respond(
            "请问你想查询哪个城市的天气？",
            should_end_session=False
        )
    # 调用天气API
    weather_info = get_weather(city)
    return skill.respond(
        f"{city}的天气是：{weather_info}",
        should_end_session=True
    )

持久化存储

from openclaw.persistence import PersistenceAdapter
@skill.session_started_handler
def session_started(event, context):
    """会话开始"""
    user_id = event.context.user.user_id
    session_attributes = PersistenceAdapter.load_attributes(user_id)
    return session_attributes
@skill.session_ended_handler
def session_ended(event, context):
    """会话结束"""
    user_id = event.context.user.user_id
    PersistenceAdapter.save_attributes(user_id, event.session.attributes)

多轮对话

class OrderPizzaDialog(Dialog):
    def __init__(self):
        super().__init__("OrderPizza")
        self.steps = ["size", "toppings", "confirm"]
    def handle(self, session, intent):
        current_step = session.get("current_step", 0)
        if current_step == 0:
            return "请问你想要什么尺寸的披萨？"
        elif current_step == 1:
            session["size"] = intent.slots["size"].value
            return "想要什么配料？"
        elif current_step == 2:
            session["toppings"] = intent.slots["toppings"].value
            return f"确认：{session['size']}披萨，配料{session['toppings']}，对吗？"

测试技能

单元测试

# tests/test_my_skill.py
import unittest
from openclaw.testing import SkillTest
class TestMySkill(unittest.TestCase):
    def setUp(self):
        self.skill_test = SkillTest("my_first_skill")
    def test_greet_intent(self):
        response = self.skill_test.intent("GreetIntent")
        self.assertIn("你好", response.text)
    def test_launch(self):
        response = self.skill_test.launch()
        self.assertIn("欢迎", response.text)

模拟测试

# 启动测试服务器
openclaw test --skill my_first_skill
# 在浏览器中测试
# 访问 http://localhost:3000

部署技能

打包技能

# 创建技能包
openclaw package --skill my_first_skill --output my_skill.zip

部署到 OpenClaw

# 部署到本地 OpenClaw 实例
openclaw deploy --skill-package my_skill.zip
# 或者部署到远程服务器
openclaw deploy --skill-package my_skill.zip \
                --endpoint https://your-openclaw-server.com

调试技巧

日志记录

import logging
logger = logging.getLogger(__name__)
@skill.intent_handler("MyIntent")
def handler(event, context):
    logger.info(f"收到请求: {event.request}")
    logger.debug(f"会话属性: {event.session.attributes}")
    # 处理逻辑
    return response

使用调试器

# 启用调试模式
export OPENCLAW_DEBUG=1
# 运行技能时附加调试器
python -m pdb -m openclaw.run --skill my_first_skill

最佳实践

错误处理：始终包含适当的错误处理
用户引导：提供清晰的引导提示
会话管理：合理管理会话状态
性能优化：减少网络请求，使用缓存
多语言支持：考虑支持多种语言

参考资料

故障排除

常见问题：

技能无法加载：检查 manifest.json 格式
意图无法匹配：确认示例语句足够多样
会话状态丢失：检查持久化配置
API调用失败：验证网络连接和权限

通过本教程,你应该已经掌握了 OpenClaw 自定义技能开发的基础知识，开始创建你的第一个技能吧！

标签： OpenClaw 自定义技能开发

本文地址： https://www.lx-openclaw.com.cn/post/998.html