必须重写插件以适配openclaw v2026.5.4新sdk体系，使用createskill工厂函数、四阶段生命周期钩子（ondiscover/onload/onexecute/onunload），并配置openclaw.plugin.json及权限声明。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你需要让自定义插件在OpenClaw v2026.5.4上正常运行，但旧版基于openclaw/extension-api开发的插件全部失效，控制台报错register is not a function，且npm install安装后插件不被识别——这是因为v2026.5.4已彻底废弃旧API，强制启用新SDK体系，所有插件必须重写并适配中间件生命周期钩子。
确认当前环境与SDK版本
打开终端，执行：openclaw --version，确保输出为v2026.5.4或更高；若低于此版本，请先升级：openclaw update --force。
检查Node.js版本：node -v必须≥22.12.0，npm -v必须≥10.9.0；否则插件编译会因ESM模块解析失败而中断。
运行openclaw plugin sdk info，确认返回中currentSdk字段值为@openclaw/plugin-sdk@2026.5.4——【这是唯一兼容v2026.5.4的SDK版本，其他任何版本均无法通过加载校验】。
重写插件入口：从export default到createSkill
旧插件使用module.exports = { register };，v2026.5.4要求改用SDK导出的createSkill工厂函数。
新建skill.ts（或skill.js），顶部引入：import { createSkill } from '@openclaw/plugin-sdk';。
替换原register(api)逻辑为：export default createSkill({ id: 'my-formatter', name: '代码格式化助手', version: '1.0.0' });——注意id必须全局唯一，且仅允许小写字母、数字、短横线。
旧版中直接调用api.registerTool的位置，现在必须包裹在onLoad钩子里：onLoad: (ctx) => { ctx.registerTool(...); }；否则插件启动时工具不会注册，命令不可见。
适配中间件生命周期：四阶段钩子不可省略
v2026.5.4将插件加载拆分为四个严格顺序的中间件阶段，每个阶段对应一个可选钩子函数，缺失任一阶段声明会导致插件被静默跳过。
第一步：声明onDiscover——用于返回插件元数据，必须同步返回{ id, name, description, icon }对象；若返回Promise或异步操作，插件会被判定为“发现失败”并终止加载。
第二步：实现onLoad——插件被正式载入内存后的初始化入口，此处注册工具、监听事件、建立数据库连接；【所有副作用操作（如fs.readFile、fetch）必须在此阶段完成，onDiscover中禁止IO操作】。
第三步：定义onExecute——用户触发插件时的核心执行逻辑，接收input参数并返回Promise<any></any>；该函数内可调用ctx.runtime.exec执行系统命令，但不能直接process.exit()，否则会杀死整个Gateway进程。
第四步：补充onUnload——插件卸载前的清理工作，例如关闭HTTP服务器、释放文件句柄；若未定义，OpenClaw会在热重载时残留资源，连续三次重载后触发EMFILE错误。
迁移配置文件：openclaw.plugin.json强制校验
删除旧版package.json中的openclaw字段，新建openclaw.plugin.json（必须同名，不可改为.yaml或.ts）。
方法一：基础结构（必填项）：
填写{"id":"my-formatter","name":"代码格式化助手","version":"1.0.0","main":"dist/skill.js"}——main路径必须指向编译后产物，且相对插件根目录；若指向src/skill.ts，加载时直接报ERR_MODULE_NOT_FOUND。
方法二：带能力声明（推荐）：
追加"capabilities": ["tool", "http"]，明确告知OpenClaw该插件需注册工具并暴露HTTP路由；若实际注册了HTTP路由但未声明http能力，ctx.http.registerRoute调用会静默失败。
方法三：安全上下文声明：
添加"permissions": ["fs:read", "network:outbound"]，否则插件在v2026.5.4默认沙箱下无法读取本地文件或发起网络请求——【不声明即无权，无例外】。
