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？步骤如下：

第一步，在插件目录或独立的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，能拦截请求却无处获取知识。三者协同，才能使知识结构化地加载并被AI智能运用。

具体实现步骤：

第一步，在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确实不在其中，从根源上确保隔离。

理解这三层扩展体系各自的职责与协作关系，是高效、安全地为OpenClaw赋能的关键。希望这份指南能帮助你跨越从简单使用到深度定制的门槛。