openclaw插件必须满足五项核心要求才能被gateway识别：一、元数据需严格遵循openclaw.plugin.json规范；二、运行时须导出符合openclawplugin接口的类或对象；三、目录结构须满足posix权限与路径安全约束；四、构建产物须为es2020+ commonjs模块且禁用动态特性；五、configschema须符合json schema v7并确保类型与默认值一致。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试为OpenClaw开发插件，但插件无法被Gateway识别或注册失败，则可能是由于未遵循其强制性的接口标准与结构规范。以下是确保插件合法加载与运行所必需满足的核心要求：
一、插件元数据接口标准
OpenClaw在加载任何插件前，首先读取openclaw.plugin.json（不可替换为package.json或其他名称），该文件是插件的唯一元数据凭证，必须严格符合JSON Schema校验规则。缺失、字段类型错误或权限声明越界均会导致发现阶段直接拒绝加载。
1、必须包含id字段，值为全小写ASCII字符加连字符组成的唯一标识符，禁止使用下划线、大写字母或空格。
2、main字段必须指向插件根目录下的相对路径入口文件，路径须以"./"开头且不得包含../逃逸序列。
3、permissions数组若存在，仅允许填写OpenClaw白名单中的能力标识，例如"file.read"、"http.request"，不允许自定义权限字符串。
二、插件运行时API契约规范
插件在运行时必须导出一个符合OpenClawPlugin接口的类或对象，该接口定义了生命周期钩子与能力注册方法。Gateway通过调用register(api)函数完成能力绑定，此调用必须在模块顶层同步执行，不可包裹于异步回调或条件分支中。
1、register函数接收单个api参数，该参数为只读对象，禁止对其属性赋值或添加新键。
2、注册HTTP路由时，路径前缀必须为/plugins/{pluginId}/，不得注册根路径"/"或跨插件路径如"/api/"。
3、注册斜杠命令（Slash Command）时，command字段值须全小写且长度不超过32字符，禁止包含冒号、斜杠或控制字符。
三、目录结构与文件系统安全约束
OpenClaw采用声明式发现机制，对插件所在目录实施严格的POSIX权限与路径拓扑校验。违反任一约束将触发安全拦截，插件被标记为“untrusted”并静默跳过加载。
1、插件根目录所有者必须为当前运行OpenClaw进程的用户，若属主为root则仅当进程以root身份启动时才允许加载。
2、目录权限掩码不得包含全局可写位（即octal 002），chmod 755为最低合规要求，777将导致立即拒绝。
3、所有源文件路径必须位于插件根目录内，禁止通过symbolic link指向外部路径，否则触发逃逸检测并终止加载。
四、类型系统与构建产物兼容性要求
尽管OpenClaw支持JavaScript与TypeScript源码，但最终交付给Gateway执行的必须是ES2020+语法、无动态import()、无Top-Level Await的CommonJS模块。构建工具链需确保输出符合运行时环境限制。
1、入口文件（main指定路径）必须导出默认值（export default），命名导出（export const x = ...）不被识别为有效插件主体。
2、若使用TypeScript，tsconfig.json中module必须设为commonjs，target不得低于ES2020，lib中禁止包含"dom"，仅允许"es2020", "node"。
3、打包产物中不得包含eval()、Function constructor或vm模块调用，Webpack的eval-source-map模式将导致校验失败。
五、配置驱动能力注册规范
插件行为可通过configSchema声明运行时可配置项，该Schema用于生成UI表单及启动前参数校验。其结构直接影响插件在管理界面中的可用性与健壮性。
1、configSchema必须为合法JSON Schema v7对象，不支持$ref远程引用或循环引用。
2、每个属性的default值类型必须与type声明完全一致，字符串default不可设为null，布尔default不可设为0。
3、若声明required数组，则对应字段在插件启用前必须提供有效值，空字符串对string类型不视为有效，需显式设置为null或删除该字段。
