Scaffold
用 openclaw plugins init 先搭好小盒子。
Plugins 导读
Tool Plugin 是给代理挂一件小工具，不是重做一整套插件系统
这页讲最轻量的插件形态：只注册 agent-callable tools，不新增 channel、provider、hook 或服务。读它时抓住三步就够了：用 defineToolPlugin 写工具，生成 openclaw.plugin.json 和 package metadata，再用验证命令确认入口、参数和 metadata 没有错位。
先讲这一页到底在解决什么
Tool Plugin 是给代理挂一件小工具，不是重做一整套插件系统
这页讲最轻量的插件形态：只注册 agent-callable tools，不新增 channel、provider、hook 或服务。读它时抓住三步就够了：用 defineToolPlugin 写工具，生成 openclaw.plugin.json 和 package metadata，再用验证命令确认入口、参数和 metadata 没有错位。
第一站
先确认：你要做的是“工具”，不是一整座游乐场
官方把 tool plugin 单独拿出来，是为了让简单工具不用背上太重的插件框架。
它适合什么
适合固定的一组工具，比如查一个系统状态、读一个特殊资源、调用一个小服务。
它不适合什么
如果你还要注册 provider、channel、hook、setup backend，应该去看更完整的 Building plugins。
defineToolPlugin它像一张工具登记表：工具叫什么、吃什么参数、做完后交回什么结果，都写在这里。
为什么要生成 metadata
OpenClaw 需要先看说明书，才能在不加载运行时代码的情况下知道有哪些工具可用。
第二站
Quickstart 像装一盒彩笔：先摆好，再贴标签，再试画
Write
用 defineToolPlugin 写出工具和参数形状。
Build
把 TypeScript 做成可安装的 JavaScript。
Generate
运行 openclaw plugins build，让 manifest 和 package metadata 对齐。
第三站
工具真正上班时，重点看三件事
参数
参数像任务单的格子。格子画清楚，代理才不容易把错误东西塞进去。
返回值
返回值像工具交回来的回执。文字、结构化数据、错误信息，都要让调用方看得懂。
可选工具
有副作用、会碰外部系统、或者需要额外本地程序的工具，适合先设成 optional，再由用户允许。
工厂工具
factory tools 像“按配置现做一把工具”。配置不同，做出来的工具也可以不同。
第四站
最常见的坑，都是“盒子标签”和“盒子里面”没对上
plugin entry not found通常是 ./dist/index.js 没构建出来，或者 manifest 指错了入口。
metadata stale
工具改了，但生成出来的 openclaw.plugin.json 还停在旧版本，需要重新 build。
extensions 漏入口
package.json 里的 openclaw.extensions 必须包含真正的运行时入口。
最后检查
CI 里跑验证，就像出门前拉一下书包拉链：小动作，能挡住很多安装后才爆的错。