OpenClaw三层扩展架构深度解析：插件、钩子与技能实战指南
当你尝试为OpenClaw添加定制化能力时，如果仅调整提示词或调用简单函数，效果往往有限。这通常源于对扩展体系内部协作逻辑的理解偏差。OpenClaw并非一个扁平的工具箱，其核心是一个职责清晰的三层架构。本文将深入解析Plugin、Hook、Skill三者的核心定位与协同机制。
一、Skill：策略层说明书，定义“做什么”与“何时做”
Skill是面向AI的“行为规范说明书”。它不包含可执行代码，仅通过SKILL.md文档和配置规则向Agent传递指令。这份说明书会在模型推理前注入系统提示词。
其核心作用是约束输出风格、指定工具调用优先级，或限定特定任务的执行条件。由于不涉及代码执行，它是最轻量且最安全的扩展方式。例如，你可以通过Skill规定：“处理天气查询时，必须优先调用A工具，且回复格式需包含温度与体感描述。”
具体操作流程如下：
首先，在OpenClaw项目根目录下，创建skills/your-skill-name/子目录。
接着，在该目录内新建SKILL.md文件。文件需明确定义：技能名称、触发条件（如特定关键词）、触发后的响应步骤、以及步骤失败的备选方案。
然后，在SKILL.md文件头部添加YAML格式的元数据块。声明关键字段，如技能依赖的工具（required_tools）、执行优先级（priority）及启用状态（enabled）。
之后，将技能目录路径添加至主配置文件config.skills.enabled的列表中。保存配置并重启Agent服务，策略即生效。
最后，向Agent发送符合触发条件的查询，验证其响应是否严格遵循SKILL.md定义的流程。
二、Hook：运行时拦截点，控制“怎么介入”与“何时干预”
如果说Skill是事前规范，Hook便是事中干预。它被嵌入Agent的生命周期管线，在特定“事件节点”（如构建提示词前before_prompt_build、调用工具后after_tool_call）自动执行预设逻辑。
Hook不负责新增功能，其威力在于“修改”与“控制”。例如，它可以修改对话上下文、重写即将发送给模型的提示词、注入额外元数据，或在检测到非法操作时阻断调用流程。作为连接上层策略（Skill）与底层系统（Plugin）的关键桥梁，Hook具备极强的时效性与可控性。
挂载一个Hook的步骤如下：
第一步，在插件目录或独立的hooks/目录下，新建hook.ts文件。
第二步，在文件中导出一个符合Hook接口的函数对象，例如：export const before_prompt_build = (context) => { … }。
第三步，确保Hook被正确注册。可通过Plugin的register方法显式注册，或在插件的openclaw.plugin.json配置文件中通过openclaw.hooks字段声明。
第四步，在Hook函数体内，你可以访问context.prompt、context.query、context.tools等属性。根据属性读写权限进行干预。
第五步，重启Gateway服务，触发任意对话，检查系统日志中是否有该Hook的执行标记，以确认其生效。
三、Plugin：系统级容器，承载“新能力注册”与“全生命周期接管”
Plugin是三层体系中最重量级的一环，它是唯一能注册新工具（Tool）、添加HTTP路由、定义CLI命令、启动后台服务乃至接入新模型提供商（Provider）的扩展单元。通过openclaw.plugin.json清单文件和index.ts入口文件，它实现了扩展能力的物理分发与逻辑隔离。
系统启动时，PluginRegistry会扫描并激活所有已安装的Plugin。一个Plugin可以替换系统默认组件、挂载多个Hook、持久化自身运行状态。实现RAG增强、云端记忆库、多Agent协同等复杂功能，均需以Plugin为载体。
创建Plugin的典型路径如下：
首先，初始化一个npm包，在package.json中设置openclaw.extensions字段，指向你的插件入口文件。
接着，编写核心的openclaw.plugin.json文件，声明插件ID、名称、配置项结构（configSchema）及其依赖的其他插件。
然后，在index.ts中导出插件ID和一个register函数。在register函数内部，你可以调用agent.toolRegistry.register()注册新工具，或调用agent.hookRegistry.register()挂载钩子。
之后，将整个插件目录复制到~/.openclaw/plugins/目录下，或使用openclaw plugin install --local命令进行本地安装。
最后，执行openclaw plugin activate your-plugin-id激活插件。确认激活命令返回成功，且系统无未注册的残留钩子。
四、三者协同验证：以自动注入企业知识库为例
理论需结合实践。我们以“让OpenClaw自动检索企业内部知识库回答问题”为例，完整诠释三者的协同必要性。
设想缺少任何一层的后果：仅有Skill，AI知道要检索但无工具可用；仅有Plugin，提供了工具但AI不知何时调用；仅有Hook，能拦截请求却无法获取知识。三者协同，方能实现知识的结构化加载与智能运用。
具体实现步骤：
第一步，在skills/kb-search/SKILL.md中声明策略：“当用户提问包含‘公司政策’、‘报销流程’等关键词时，必须调用kb_search_tool”。
第二步，在hooks/kb-inject.ts中实现before_model_resolve钩子。该钩子在模型解析问题前，从Plugin暴露的API拉取最新知识片段，并将其注入context.prompt供模型参考。
第三步，在plugins/rds-rag/插件中，注册名为kb_search_tool的工具。在插件的register函数中，完成MySQL连接池初始化与全文索引查询逻辑。
第四步，启动OpenClaw，向Agent提问：“差旅报销需要哪些材料？”。观察Agent是否跳过通用回答，直接调用kb_search_tool并返回从知识库检索出的结构化结果。
第五步，检查~/.openclaw/logs/hook-execution.log日志文件，确认存在before_model_resolve钩子的执行记录及对应的SQL查询耗时，以验证整个链路通畅。
五、权限与隔离边界校验
安全性与稳定性是扩展系统的生命线。OpenClaw通过强制性的能力沙箱机制保障：Skill仅能影响提示词文本；Hook虽可在运行时介入，但其上下文受限，无法直接访问文件系统或网络；Plugin虽拥有系统级权限，但其注册的所有Tool和Hook均受PluginRegistry内存映射表约束，未激活插件的组件绝不会进入全局目录。
可通过以下操作验证这套设计：
临时禁用一个Plugin，执行openclaw plugin deactivate plugin-id。观察Agent是否仍能调用该插件注册的工具。预期结果为调用失败并抛出ToolNotFoundError。
在一个Skill中，引用已被卸载的Plugin所提供的工具名称。验证Agent是否会拒绝生成调用该工具的指令。
启用一个Hook后，在其before_prompt_build函数中尝试执行fs.writeFileSync()等文件系统操作。确认Node.js会报出“Permission denied”错误，证明Hook的沙箱限制有效。
最后，检查源码src/plugins/registry.ts文件中loadPluginManifestRegistry()函数返回的插件ID映射表，确认已卸载的插件ID确实不在其中，从根源上确保隔离。
透彻理解Plugin、Hook、Skill三层的职责与协作关系，是高效、安全地为OpenClaw赋能的核心。掌握这套架构，你将能跨越从简单使用到深度定制的关键门槛。