深入理解Plugin-Hook-Skill：OpenClaw三层扩展体系架构详解
OpenClaw三层扩展体系中，Skill定义“做什么”，Hook控制“怎么介入”，Plugin承载“新能力注册”；三者职责分明、协同工作，缺一不可。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您正在使用OpenClaw并希望为其添加定制化能力，但发现仅靠修改提示词或调用简单函数无法满足需求，则很可能是未正确理解其三层扩展体系的职责边界与协作关系。以下是深入解析Plugin、Hook、Skill三者定位与交互逻辑的操作指南：
一、Skill：策略层说明书，定义“做什么”与“何时做”
Skill是纯声明式策略单元，不包含可执行代码，仅通过SKILL.md文档和配置规则向Agent传达行为规范。它被注入系统提示词，在模型推理前生效，用于约束输出风格、指定工具优先级或限定任务执行条件，属于最轻量、最安全的扩展方式。
1、在OpenClaw项目根目录下创建skills/your-skill/子目录。
2、在该目录中新建SKILL.md文件，明确写出能力名称、触发条件、执行步骤及失败回退逻辑。
3、在SKILL.md头部添加YAML元数据块，声明required_tools、priority、enabled等字段。
4、将该目录路径写入config.skills.enabled列表，重启Agent使策略生效。
5、验证时发送符合触发条件的Query，观察Agent是否按SKILL.md中定义的流程响应。
二、Hook：运行时拦截点，控制“怎么介入”与“何时干预”
Hook嵌入Agent生命周期管线，在特定事件节点（如before_prompt_build、after_tool_call）自动执行自定义逻辑，不新增功能但可修改上下文、重写prompt、注入元数据或阻断非法调用。它是连接策略层与系统层的关键桥梁，具备强时效性与高可控性。
1、在插件目录或hooks/独立目录中新建hook.ts文件。
2、导出符合Hook接口的函数对象，例如export const before_prompt_build = (context) => { ... }。
3、确保该文件被Plugin的register方法显式注册，或通过openclaw.hooks字段在plugin.json中声明。
4、在函数体内访问context.prompt、context.query、context.tools等只读/可写属性进行干预。
5、重启Gateway后触发任意对话，检查日志中是否输出Hook执行标记。
三、Plugin：系统级容器，承载“新能力注册”与“全生命周期接管”
Plugin是唯一能注册Tool、HTTP路由、CLI命令、后台服务及模型Provider的扩展单元，通过openclaw.plugin.json清单与index.ts入口实现物理分发与逻辑隔离。它在启动时被PluginRegistry扫描激活，可替换默认组件、挂载钩子、持久化状态，是实现RAG增强、云端记忆、多Agent协同的基础载体。
1、初始化npm包，设置package.json中的openclaw.extensions字段指向入口文件。
2、编写openclaw.plugin.json，声明id、name、configSchema及依赖声明。
AiMusic.so
Aimusic.so是一款全新的在线免费AI音乐生成器
下载
3、在index.ts中导出id与register函数，register内调用agent.toolRegistry.register()或agent.hookRegistry.register()。
4、将插件目录复制至~/.openclaw/plugins/或通过openclaw plugin install --local安装。
5、执行openclaw plugin activate your-plugin-id，确认activatePlugin返回成功且无unregisterHooks残留。
四、三者协同验证：以自动注入企业知识库为例
该场景需Skill定义检索意图识别规则、Hook在before_model_resolve阶段触发知识查询、Plugin提供RAG Tool并管理向量数据库连接。三者缺一不可，任一层缺失将导致知识无法结构化加载或AI忽略检索动作。
1、在skills/kb-search/SKILL.md中声明：“当用户提问含‘公司政策’‘报销流程’等关键词时，必须调用kb_search_tool”。
2、在hooks/kb-inject.ts中实现before_model_resolve钩子，从Plugin暴露的API拉取最新知识片段并注入context.prompt。
3、在plugins/rds-rag/中注册kb_search_tool，并在register函数中初始化MySQL连接池与全文索引查询逻辑。
4、启动OpenClaw后，向Agent提问“差旅报销需要哪些材料？”，观察是否跳过通用回答、直接调用kb_search_tool并返回结构化结果。
5、检查~/.openclaw/logs/hook-execution.log中是否存在before_model_resolve执行记录及SQL查询耗时。
五、权限与隔离边界校验
OpenClaw强制实施能力沙箱机制：Skill仅影响提示词文本；Hook运行于受限上下文，无法直接访问文件系统或网络；Plugin虽具系统级权限，但其Tool与Hook注册受PluginRegistry内存映射表约束，未激活插件的组件不会进入全局Catalog。此设计保障了扩展安全性与运行稳定性。
1、临时禁用某Plugin，执行openclaw plugin deactivate plugin-id。
2、观察Agent是否仍能调用该Plugin注册的Tool，预期结果为调用失败并抛出ToolNotFoundError。
3、在Skill中引用一个已被卸载Plugin提供的Tool名称，验证Agent是否拒绝生成调用指令。
4、启用Hook后，在其before_prompt_build中尝试fs.writeFileSync()，确认Node.js报错“Permission denied”。
5、检查src/plugins/registry.ts中loadPluginManifestRegistry()返回的插件ID映射表，确认已卸载插件ID不在其中。