OpenClaw 插件开发实战教程:从零写一个自定义 Agent 工具到 requireApproval 审批钩子完整指南
OpenClaw 2026.3.28 刚发布插件机制大更新。这一版加了 requireApproval 审批钩子工具执行前让用户确认、CLI Backend 插件自动加载、还有 Grok 搜索插件的自动启用。插件能干嘛简单说就是给龙虾装扩展——自定义工具、接入新渠道、加审批流程。不需要改 OpenClaw 源码写个 JS 文件放对位置就行。插件基础结构一个 OpenClaw 插件长这样my-plugin/ ├── openclaw.plugin.json # 必须有插件清单 ├── index.js # 入口文件 └── package.json # 可选清单文件openclaw.plugin.json是必须的没有这个文件 OpenClaw 直接报错{id:my-tool,name:我的自定义工具,description:做一些自动化的事情,configSchema:{type:object,additionalProperties:false,properties:{enabled:{type:boolean,default:true}}}}configSchema必须有哪怕你不需要配置项也得写一个空的{id:my-tool,configSchema:{type:object,additionalProperties:false}}写一个 Agent 工具Agent 工具就是 LLM 可以调用的函数。比如写一个查天气的工具// index.jsimport{Type}fromsinclair/typebox;exportdefaultfunction(api){api.registerTool({name:check_weather,description:查询指定城市的天气,parameters:Type.Object({city:Type.String({description:城市名称}),}),asyncexecute(_id,params){// 这里调用天气 APIconstweatherawaitfetchWeather(params.city);return{content:[{type:text,text:${params.city}${weather}}]};},});}注册完后LLM 在对话中就能调用check_weather这个工具了。必选工具 vs 可选工具默认注册的工具是必选的——所有 Agent 都能用。但有些工具有副作用比如发邮件、删文件应该设成可选exportdefaultfunction(api){api.registerTool({name:send_notification,description:发送通知到指定渠道,parameters:{type:object,properties:{channel:{type:string},message:{type:string},},required:[channel,message],},asyncexecute(_id,params){awaitsendToChannel(params.channel,params.message);return{content:[{type:text,text:通知已发送}]};},},{optional:true});}可选工具需要在配置里手动启用{agents:{list:[{id:main,tools:{allow:[send_notification]}}]}}也可以用插件 ID 一次性启用该插件的所有工具allow: [my-tool]requireApproval 审批钩子2026.3.28 新功能这是这个版本的重要更新。before_tool_call钩子现在支持requireApproval可以在工具执行前暂停等用户确认。适合什么场景比如删除操作、发布操作、任何不可逆的动作。exportdefaultfunction(api){api.hook(before_tool_call,async(context){constdangerousTools[delete_file,publish_article,send_email];if(dangerousTools.includes(context.toolName)){// 暂停执行等待用户审批awaitcontext.requireApproval({reason:即将执行${context.toolName}参数${JSON.stringify(context.params)},timeout:60000,// 60 秒超时});}// 用户确认后才会继续执行});}用户会在对话界面看到审批请求。不同渠道的交互方式不同Telegram弹出按钮Discord交互式按钮Slack/其他/approve命令如果用户不确认或超时工具调用会被取消。在配置中启用插件把插件目录放到~/.openclaw/plugins/下然后在openclaw.json里启用{plugins:{allow:[my-tool],entries:{my-tool:{enabled:true}}}}重启 Gateway 生效openclaw gateway restartCLI Backend 插件2026.3.28 新功能这个版本还简化了 CLI Backend 插件的配置。Claude CLI、Codex CLI、Gemini CLI 现在可以作为插件自动加载不需要手动写plugins.allow。在openclaw.json里配置 provider 引用就够了{providers:{claude-cli:{model:claude-opus-4}}}OpenClaw 会自动发现并加载对应的 CLI Backend 插件。调试插件开发插件时用openclaw doctor检查openclaw doctor如果清单文件有问题schema 不合法、ID 冲突doctor 会直接报错。运行时日志openclaw gateway start# 看日志里的 plugin 相关输出注意事项工具名不能和 OpenClaw 内置工具冲突比如read、write、exec冲突的会被跳过configSchema在配置读写时就会验证不是运行时才验证插件引用的未知 channel ID 或 plugin ID 会直接报错有副作用的工具用optional: true让用户显式启用requireApproval有超时机制不会无限等待OpenClaw 插件文档https://docs.openclaw.ai/plugins/manifestAgent 工具文档https://docs.openclaw.ai/plugins/agent-toolsGitHubhttps://github.com/openclaw/openclaw