1. 为什么要在 OpenClaw 里折腾本地插件OpenClaw 这个工具最近在圈子里讨论度很高很多人拿它来做本地化的智能助手、自动化流程编排或者把它当成一个可扩展的 Agent 运行框架。它本身自带了一套插件机制官方市场里能直接装的东西不少但真正用起来你会发现本地插件才是把 OpenClaw 变成自己的工具的关键一步。原因很简单官方插件解决的是通用需求而你的工作流里那些奇奇怪怪的私有逻辑——比如读取本地某个特定格式的日志、调用内网的一个接口、把结果写进某个自建数据库——这些官方不可能替你做只能靠本地插件。我最初接触 OpenClaw 的时候也是从装个官方插件试试开始的跑通之后觉得挺顺直到我想让它去处理一批本地 CSV 文件并做特定清洗才发现官方插件根本覆盖不到。那时候我才认真去研究openclaw plugins install这条命令背后的机制以及本地插件到底该怎么组织目录、怎么写清单文件、怎么让 Gateway 正确加载。踩了几轮坑之后我把整个流程梳理清楚了这篇文章就是把这套经验完整地摊开讲。需要先明确一点本地插件和远程插件在 OpenClaw 里的加载路径是不一样的。远程插件走的是市场拉取、校验、安装的流程而本地插件更像是你告诉 OpenClaw 去某个目录里找东西。这个差异决定了你在配置alsoAllow、Gateway 路由、以及权限声明时的写法完全不同。很多人第一次装本地插件失败根本原因就是拿远程插件的思路去套本地插件结果清单文件里的字段对不上Gateway 直接报doesnt look like an anthropic model: expected a gateway model route这类看起来毫不相关的错误。这篇文章适合三类人一是刚把 OpenClaw 跑起来、想扩展功能但不知道从哪下手的新手二是装过官方插件、但本地插件一直加载失败的中级用户三是想把 OpenClaw 集成进自己现有系统、需要深度定制插件行为的开发者。我会从环境确认讲到插件目录结构、清单文件写法、Gateway 配置、alsoAllow白名单机制再到实际排查加载失败的完整链路尽量让每一步都能直接抄作业。2. 装本地插件之前先把运行环境确认清楚2.1 OpenClaw 的安装方式决定了插件目录的位置OpenClaw 在不同系统上的安装方式差异挺大而插件目录的位置又跟安装方式强相关。如果你是在 Windows 上通过 Node.js 环境跑的那插件目录通常在用户目录下的.openclaw/plugins如果你是在 Ubuntu 上用包管理器或者源码方式部署的目录可能落在/opt/openclaw/plugins或者你自定义的工作目录里。这个路径搞错了后面所有配置都是白费。我建议你先做一件事找到 OpenClaw 的主配置文件通常在~/.openclaw/config.json或者安装目录下的config/config.json。打开它看里面有没有pluginsDir这个字段。如果有那本地插件就往那个路径放如果没有默认就是安装目录同级的plugins文件夹。这一步看起来简单但我见过太多人把插件扔错地方然后对着 Gateway 日志里那句plugin not found发呆半天。在 Windows 环境下如果你是用 WSL 跑的 OpenClaw那要注意一个坑Windows 侧的路径和 WSL 侧的路径是两套体系。你在 PowerShell 里看到的C:\Users\xxx\.openclaw在 WSL 里对应的是/mnt/c/Users/xxx/.openclaw。如果你在 WSL 里跑 OpenClaw但插件放在 Windows 侧目录那 OpenClaw 是读不到的除非你显式配置了跨文件系统的路径映射。我个人的做法是统一在 WSL 的 home 目录下建一个openclaw-workspace插件、配置、日志全放里面避免路径混乱。2.2 Node.js 版本与依赖检查OpenClaw 本身是 Node.js 生态的工具本地插件如果涉及原生模块或者特定版本的依赖Node 版本不对就会直接报错。我实测下来Node 18 LTS 和 Node 20 LTS 是比较稳的两个版本Node 16 在部分插件上会出现ERR_REQUIRE_ESM的问题而 Node 21 以上有些原生模块还没跟上。检查方式很简单在终端里跑node -v npm -v如果版本低于 18建议去 Node.js 官网下载 LTS 版本重装。这里有个细节如果你之前装过多个 Node 版本用nvm或者fnm管理的话要确认当前 shell 用的是哪个版本。我有一次就是系统里 Node 18 和 Node 20 并存终端默认走了 18但 OpenClaw 的启动脚本里写死了 20 的路径结果插件加载时依赖解析出错报了一个跟版本完全无关的bad gateway error eof查了半天才发现是版本不一致。另外本地插件如果依赖了某些 npm 包你需要在插件目录里单独跑一次npm install。不要指望 OpenClaw 主程序会帮你装插件的依赖它是不会的。插件目录下的node_modules必须自己维护好。2.3 Gateway 服务是否正常运行OpenClaw 的插件加载是通过 Gateway 来协调的Gateway 没跑起来插件装得再对也没用。检查 Gateway 状态的方式取决于你的部署方式如果是前台运行终端里应该能看到 Gateway 的启动日志类似Gateway listening on port xxxx。如果是后台服务用systemctl status openclaw-gatewayLinux或者查进程列表确认。Windows 下如果是用 companion 方式跑的检查托盘图标或者对应服务状态。我遇到过一次 Gateway 看似在跑、但插件就是不加载的情况后来发现是 Gateway 的配置文件里plugins字段被注释掉了。Gateway 的配置和 OpenClaw 主配置是两份文件很多人只改了主配置忘了 Gateway 那份结果插件目录扫描根本没启用。这个坑后面在讲 Gateway 配置时会详细展开。3. 本地插件的目录结构与清单文件怎么写3.1 一个最小可用的本地插件长什么样本地插件本质上就是一个文件夹里面至少包含两个东西一个清单文件通常是plugin.json或manifest.json一个入口文件通常是index.js。OpenClaw 扫描插件目录时就是靠清单文件来识别这个插件叫什么、能做什么、入口在哪。一个最小可用的目录结构大概是这样plugins/ my-local-plugin/ plugin.json index.js package.jsonplugin.json是 OpenClaw 识别插件的核心里面要声明插件的名称、版本、入口、以及它需要的能力capabilities。index.js是实际逻辑OpenClaw 加载后会调用这里导出的函数。package.json不是必须的但如果你的插件依赖了 npm 包就需要它来管理依赖。我建议新手先从官方文档里的示例插件抄一份清单文件改改名字和入口路径跑通之后再往里加逻辑。不要一上来就写复杂插件因为本地插件加载失败时错误信息往往很模糊插件越复杂越难定位问题。3.2 清单文件里的关键字段逐个拆解清单文件里几个字段是必须的缺一个都可能导致加载失败字段作用常见错误name插件唯一标识用了大写或空格导致 Gateway 识别失败version版本号格式不对比如写成v1.0而不是1.0.0main入口文件路径路径写错或者用了绝对路径capabilities声明插件能力没声明却调用了对应 API运行时报权限错误engines兼容的 OpenClaw 版本版本范围写太窄导致插件被跳过name这个字段特别容易踩坑。OpenClaw 内部对插件名做了规范化处理只允许小写字母、数字和连字符。如果你写成MyPlugin或者my_pluginGateway 在加载时可能直接跳过日志里只留一句invalid plugin name。我建议统一用my-local-plugin这种全小写加连字符的格式省心。capabilities字段是很多人忽略的。OpenClaw 的插件系统有一套权限模型插件要调用某些 API比如读写文件、发起网络请求、访问 Gateway 路由必须在清单里显式声明。没声明就调用轻则功能不生效重则整个插件被 Gateway 禁用。这个机制跟移动端 App 的权限声明是一个思路目的是让用户知道插件要干什么。3.3 入口文件的导出约定入口文件index.js需要按照 OpenClaw 的约定导出特定的函数或对象。不同版本的 OpenClaw 对导出格式要求略有差异但大体上是导出一个包含activate和deactivate两个方法的对象或者导出一个默认函数。// index.js 示例 module.exports { activate(context) { // 插件被加载时调用 context.logger.info(my-local-plugin activated); // 注册命令、监听事件等 }, deactivate() { // 插件被卸载时调用 // 清理资源 } };context对象是 OpenClaw 注入的里面包含了日志器、配置读取、命令注册等能力。不要试图在模块顶层直接访问 context因为那时候插件还没被激活context 还不存在。我见过有人在文件顶部就写context.logger.info(...)结果插件加载直接报context is undefined。另外如果你的插件是 ESM 模块用了import/export要在package.json里声明type: module否则 Node 会按 CommonJS 解析报语法错误。这个细节在 Node 18 和 20 上表现一致但如果你混用了两种模块系统问题会很难查。4. Gateway 配置与 alsoAllow 白名单机制4.1 Gateway 是怎么发现本地插件的Gateway 启动时会扫描配置里指定的插件目录读取每个子目录的清单文件然后决定加载哪些。扫描是递归的还是只扫一层取决于 Gateway 的配置。默认情况下只扫一层也就是说你的插件必须直接放在plugins/下面不能嵌套在plugins/group/my-plugin/这种结构里除非你显式开启了递归扫描。Gateway 的配置文件里通常有这几个跟插件相关的字段pluginsDir插件目录路径plugins要加载的插件列表可以是*表示全部加载也可以是具体插件名数组alsoAllow白名单用于放行那些默认被拦截的插件alsoAllow这个字段是重点。OpenClaw 出于安全考虑对本地插件有一套默认的拦截策略没有在官方市场注册过的插件默认是不被加载的除非你在alsoAllow里显式放行。这个设计是为了防止用户不小心加载了来路不明的插件。所以很多人装完本地插件发现没生效第一反应是插件写错了其实只是没加白名单。4.2 alsoAllow 的正确写法与常见误区alsoAllow的值是一个数组里面填插件名。写法上要注意{ plugins: { alsoAllow: [my-local-plugin, another-plugin] } }几个常见误区第一插件名要跟清单文件里的name字段完全一致包括大小写和连字符。写成my_local_plugin或者MyLocalPlugin都不会生效。第二alsoAllow和plugins字段是两回事。plugins决定加载哪些alsoAllow决定放行哪些。如果你plugins里写了*但alsoAllow是空的那些未注册的本地插件依然不会被加载。两个字段要配合使用。第三修改配置后要重启 Gateway热重载对alsoAllow不一定生效。我实测下来部分版本的 OpenClaw 在修改alsoAllow后需要完全重启 Gateway 进程而不是 reload。如果你改了配置没反应先重启再说。4.3 Gateway 路由与插件的关系OpenClaw 的 Gateway 不只是个加载器它还负责把请求路由到对应的插件。当你在 OpenClaw 里触发某个命令时Gateway 会根据命令注册信息找到对应的插件然后把请求转发过去。如果插件的路由没注册成功你会看到expected a gateway model route这类错误。这个错误的本质是Gateway 收到了一个请求但在它的路由表里找不到对应的处理者。可能的原因有几个插件没加载成功、插件的capabilities没声明路由能力、或者插件的路由注册代码有 bug。排查时先确认插件是否在 Gateway 的已加载列表里再看路由注册的日志。我建议在插件激活时打一条日志把注册的路由信息也打出来这样出问题时一眼就能看出是没注册还是注册错了。5. 从零跑通一个本地插件的完整实操5.1 创建插件目录与清单文件假设你的 OpenClaw 插件目录是~/.openclaw/plugins我们要创建一个叫hello-local的插件。第一步建目录mkdir -p ~/.openclaw/plugins/hello-local cd ~/.openclaw/plugins/hello-local然后创建plugin.json{ name: hello-local, version: 1.0.0, main: index.js, capabilities: [commands], engines: { openclaw: 1.0.0 } }这里capabilities声明了commands表示这个插件要注册命令。engines声明了兼容的 OpenClaw 版本范围写宽一点比较保险。5.2 编写入口逻辑并注册一个命令index.js里我们注册一个简单的命令输出一句话module.exports { activate(context) { context.logger.info(hello-local plugin activating); context.commands.register(hello, async (args) { return hello from local plugin; }); context.logger.info(hello-local plugin activated); }, deactivate() { // 清理 } };注意context.commands.register这个 API 的签名可能因 OpenClaw 版本而异有的版本是register(name, handler)有的是register({ name, handler })。以你本地 OpenClaw 的文档为准我这里是按常见写法给的。5.3 配置 Gateway 放行并重启编辑 Gateway 配置文件加上{ plugins: { pluginsDir: ~/.openclaw/plugins, plugins: [*], alsoAllow: [hello-local] } }然后重启 Gateway。重启后看日志应该能看到hello-local plugin activated这行。如果没看到往下看排查章节。5.4 验证插件是否真正生效在 OpenClaw 里执行hello命令如果返回hello from local plugin说明整条链路通了。如果报错先看 Gateway 日志里有没有插件的加载记录再看命令注册有没有成功。我建议在这个阶段多打日志插件激活、命令注册、命令执行这三个节点各打一条这样出问题时能快速定位是哪个环节断了。6. 加载失败时的完整排查链路6.1 第一步确认插件目录被扫描到Gateway 日志里通常会有一行scanning plugins dir: xxx。如果没有这行说明pluginsDir配置没生效或者 Gateway 根本没读到这份配置。检查配置文件的路径是否正确以及 Gateway 启动时用的是哪份配置。6.2 第二步确认清单文件被解析如果目录扫描到了但插件没出现在加载列表里大概率是清单文件有问题。常见问题包括JSON 格式错误多逗号、少引号、name字段不合规、main指向的文件不存在。用node -e require(./plugin.json)快速验证 JSON 是否合法比肉眼检查靠谱。6.3 第三步确认 alsoAllow 放行插件被解析了但没加载检查alsoAllow里有没有这个插件名。这一步最容易被忽略因为日志里可能只写plugin skipped不会明确告诉你是因为白名单。6.4 第四步确认入口文件无运行时错误插件开始加载但激活失败看日志里的堆栈。常见错误有context is undefined在顶层访问 context、Cannot find module依赖没装、SyntaxError模块系统不匹配。依赖问题就在插件目录里跑npm install模块系统问题就检查package.json里的type字段。6.5 第五步确认 Gateway 路由注册成功插件激活了但命令不生效看路由注册的日志。如果注册时报route already exists说明命令名跟其他插件冲突了换个名字。如果注册成功但调用时报expected a gateway model route检查 Gateway 的路由表是否刷新必要时重启。这套排查链路我走过好几遍大部分问题集中在前三步也就是目录、清单、白名单。把这三步确认清楚后面基本不会有大问题。7. 几个实测下来值得记住的经验第一个经验本地插件的开发最好在独立目录里做跑通后再复制到插件目录。因为插件目录里的东西 Gateway 会实时扫描你改一半保存了Gateway 可能就加载了一个半成品日志里一堆错误反而干扰排查。第二个经验插件名一旦确定就不要改。改了名字alsoAllow要跟着改已经注册的命令可能也会失效历史日志里的记录也对不上。我一般会在插件开发初期就把名字定死后面只改逻辑不改名。第三个经验Gateway 的日志级别调成 debug能看到插件扫描、解析、加载的完整过程。默认的 info 级别会漏掉很多细节排查时很吃亏。调级别的方式在 Gateway 配置里通常是logLevel: debug。第四个经验如果插件涉及网络请求注意 Gateway 的超时配置。本地插件调用外部接口时如果接口响应慢Gateway 可能先超时了报一个bad gateway error eof看起来像网络问题其实是超时设置太短。把 Gateway 的requestTimeout调大一点问题就消失了。第五个经验插件目录不要放在会被系统清理的临时目录里。我有一次把插件放在/tmp下测试跑得好好的结果系统重启后/tmp被清了插件全没了Gateway 启动时报一堆plugin not found。后来统一放到用户目录下再没出过这个问题。8. 把本地插件接入现有工作流的思路本地插件跑通之后真正的价值在于把它接入你现有的工作流。比如你有一个每天要处理的日志文件可以写一个插件注册一个process-log命令内部读取文件、做清洗、把结果写到指定位置。然后在 OpenClaw 里配置一个定时任务每天自动触发这个命令。这里有个设计上的取舍插件里做多少OpenClaw 里做多少。我的建议是插件只做原子操作比如读文件、调接口、写数据而流程编排、条件判断、错误重试这些放在 OpenClaw 的流程配置里。这样插件更容易复用也更容易测试。如果你把所有逻辑都塞进插件插件会变得很重改一点就要重新加载调试成本高。另外插件之间的通信尽量通过 OpenClaw 提供的事件机制而不是直接互相调用。直接调用会让插件产生隐式依赖一个插件改了接口另一个就挂了。用事件机制的话插件之间是松耦合的各自独立演进。如果你要把 OpenClaw 集成进已有的系统比如让它去对接某个内部平台那本地插件就是那个适配层。适配层里处理协议转换、认证、数据格式映射OpenClaw 侧只关心业务逻辑。这种分层方式我在几个项目里用过维护起来比把所有东西揉在一起清爽得多。最后说一个我自己的习惯每个本地插件都配一个 README写清楚它做什么、依赖什么、怎么配置、怎么测试。插件多了之后没有文档根本记不住哪个是哪个。这个习惯看起来多余但等你半年后回头看自己写的插件会感谢当时的自己。