创建插件

本页介绍编写命令：plugins init、plugins build、plugins validate 和 plugins pack，以及它们生成的工具（tool）、功能（feature）和提供商（provider）脚手架。

编写¶

openclaw plugins init stock-quotes --name "Stock Quotes"
cd stock-quotes
npm run plugin:build
npm run plugin:validate

plugins init 默认创建一个最小化的 TypeScript 工具插件。第一个参数是插件 id；--name 设置显示名称。OpenClaw 使用该 id 作为默认输出目录和包命名。工具脚手架使用 defineToolPlugin，并生成 package.json 脚本 plugin:build 和 plugin:validate，这两个脚本会先构建，再调用 openclaw plugins build/validate。

plugins build 会导入构建后的入口，读取其静态工具元数据，写入 openclaw.plugin.json，并保持 package.json 中的 openclaw.extensions 同步。plugins validate 检查生成的清单、包元数据和当前入口导出是否仍然一致。传入 --json 可获取机器可读的验证结果。完整的编写工作流请参阅工具插件。

脚手架会写入 TypeScript 源码，但从构建后的 ./dist/index.js 入口生成元数据，因此该工作流也适用于已发布的 CLI。当入口不是默认的包入口时，使用 --entry <path>。在 CI 中使用 plugins build --check，可在生成的元数据过时时失败，且不会重写任何文件。

工具和提供商脚手架将 src/index.ts 及其导入的模块编译到 dist，同时将独立的测试文件排除在包之外。功能脚手架还会在 TypeScript 检查中包含其单独的浏览器入口。所有脚手架都将 TypeScript 版本锁定为 7.0.2，并将 rootDir 设置为 src，从而将编译后的入口保留在 dist/index.js。

功能脚手架与产物¶

使用 --type feature 创建类型化的后端操作、agent 工具、原生页面和 Composer 替代组件。在生成的项目中运行 npm install、npm run build 和 npm run validate。其浏览器源码在 package.json.openclaw.controlUi 中声明；plugins build 会写入不可变的打包资源及其清单声明。

插件 API 属于实验性功能。要加载脚手架的原生浏览器 UI，请启用设置 → 实验室 → 自定义插件 UI，然后重启 Gateway 并重新加载浏览器。请参阅启用自定义插件 UI。

plugins pack 会验证构建后的项目，打包其后端依赖，并写入一个归档，其中包含编译后的代码和 UI，且不含安装脚本或运行时包依赖。--json 会返回其绝对路径、SHA-256 摘要以及确切的 plugin_activate_artifact 请求。输出文件必须不存在。默认文件名为项目根目录下的 <plugin-id>.tgz；对于带作用域的 id，/ 会替换为 __（例如 @author__tools.tgz）。使用 --out 可选择其他路径。打包过程遵循包的运行时入口选择（包括 runtimeExtensions），并单独打包声明的 setup 入口。源码/运行时入口路径会被重写，指向归档中包含的编译文件。有关激活审批、重新加载、视图生命周期和恢复，请参阅功能插件。

提供商脚手架¶

openclaw plugins init acme-models --name "Acme Models" --type provider
cd acme-models
npm install
npm run build
npm test
npm run validate

提供商脚手架会创建一个通用的、兼容 OpenAI 的模型提供商插件，其中包含 API 密钥认证管道、一个运行 clawhub package validate 的 npm run validate 脚本、ClawHub 包元数据，以及一个手动触发的 GitHub Actions 工作流，用于将来通过 GitHub OIDC 进行可信发布。提供商脚手架不会生成技能（skills），也不使用 openclaw plugins build/validate；这些命令用于工具脚手架的生成元数据路径。

发布前，请将占位的 API 基础 URL、模型目录、文档路由、凭据文本和 README 内容替换为真实的提供商信息。首次发布到 ClawHub 以及进行可信发布者设置时，请使用生成的 README。