OpenClaw 插件开发:Plugin、Hook、Skill 三层扩展怎么分工

AI 推荐

适合读者：准备把 OpenClaw 从使用阶段推进到扩展阶段的开发者。

预计阅读：6 分钟

你将看到：

•Skill、Hook、Plugin 是三层不同粒度的扩展方式，不该混写。

•Plugin 负责注册工具、方法、服务和路由，Hook 负责挂接生命周期。

•最小插件骨架先跑通，再谈更复杂的能力注入。

真正开始自己扩 OpenClaw 时，很多人碰到的第一个坑，不是不会写代码，而是：

我到底该写 Skill，还是写 Hook，还是直接上 Plugin？

这是 OpenClaw 最容易混的三个扩展面。因为它们看起来都在“扩能力”，但真正负责的层完全不同。

这一篇的目标不是让你一上来做复杂插件，而是先帮你把判断顺序理清：

什么时候只需要 Skill，什么时候插 Hook 就够了，什么时候必须把能力真正注册进 Gateway。

一、先定本篇起点和完成标志

你的起点状态

1. 你已经理解 Skill 和 Hook 大致分别做什么

2. 你开始希望把某个能力真正接入 OpenClaw 运行时

3. 你不想一上来就写大而重的系统级扩展

本篇完成标志

到最后，你至少应该做到：

1. 能判断一个需求该落到 Skill、Hook 还是 Plugin

2. 知道一个最小 Plugin 至少包含什么

3. 能先注册出一个真的可调用的 tool，而不是只写一个插件空壳

二、先给结论：Skill、Hook、Plugin 分别解决什么问题

1. Skill

适合：

• 告诉 Agent 什么时候该做某类事

• 给出能力边界、使用条件、操作步骤

• 组织现有工具和工作流

它更像“能力说明书 + 调用策略”。

2. Hook

适合：

• 在 Agent 生命周期某个节点插入逻辑

• 修改 prompt 构建过程

• 做运行前后的小型控制和策略调整

它更像“运行时拦截点”。

3. Plugin

适合：

• 注册真正的新能力

• 暴露 Gateway RPC

• 注册 HTTP route

• 注册 agent tool

• 注册 CLI command

• 注册 background service

• 给系统提供新的 channel 或 provider

它更像“把代码真正装进 Gateway 里”。

所以最简单的判断是：

• 只是教 Agent 怎么做事，用 Skill

• 只是修改运行时流程，用 Hook

• 需要把新功能注册进系统，用 Plugin

三、第一版 Plugin 不要做大，先注册一个最小 tool

如果你是第一次写 Plugin，最容易成功的路径不是先做 channel，也不是先接一堆服务，而是先注册一个 agent tool。

这是因为它能最快帮你验证三件事：

1. 插件有没有被系统发现

2. 代码有没有正确加载

3. Agent 能不能真的调用你注册的能力

换句话说，第一版 Plugin 的目标不是“做出完整产品”，而是：

先注册出一个真的能被 Agent 调到的 tool。

四、Plugin 的最小形态不是一个 TS 文件，而是 Manifest + Module

官方 Plugin Manifest 文档给的规则非常明确：

每个插件都必须带一个：

openclaw.plugin.json

而且至少要有两个关键字段：

• id

• configSchema

一个最小 manifest 长这样：

{

  “id”: “voice-call”,

  “configSchema”: {

    “type”: “object”,

    “additionalProperties”: false,

    “properties”: {}

  }

}

这里最关键的一点不是 JSON 长什么样，而是官方设计意图：

OpenClaw 会先通过 manifest 做发现与配置校验，而不是先执行你的插件代码。

这意味着 Plugin 不是“先跑起来再说”，而是先成为一个可验证、可发现的系统单元。

五、一个最小插件骨架，应该先从 Tool 开始

官方 Plugin Agent Tools 文档给的最小例子是：

import { Type } from “@sinclair/typebox”;

export default function (api) {

  api.registerTool({

    name: “my_tool”,

    description: “Do a thing”,

    parameters: Type.Object({

      input: Type.String(),

    }),

    async execute(_id, params) {

      return { content: [{ type: “text”, text: params.input }] };

    },

  });

}

这个最小例子背后的关键点有三个：

1. Tool 是 JSON-schema function，不是随便一个 JS 函数

2. 参数结构要显式声明

3. 返回结果也要符合 Agent 工具结果格式

所以第一次写 Plugin，最好的目标不是“做大”，而是“先把注册链路打通”。

六、Plugin 真正能注册什么

官方 Plugins 文档列得很完整，一个插件可以注册：

• Gateway RPC methods

• Gateway HTTP routes

• Agent tools

• CLI commands

• Background services

• Context engines

• Optional config validation

• Skills 目录

• Auto-reply commands

这串列表本身已经说明了 Plugin 的定位：

它不是某个点状功能，而是系统级扩展容器。

所以当你需要的能力开始越过“提示词组织”，进入“系统表面注册”，就应该考虑 Plugin 了。

七、如果工具有副作用，优先做 optional tool

官方文档专门强调了 optional tool：

api.registerTool(toolDef, { optional: true });

而且明确说明：

optional tools 不会自动启用，用户必须显式加到 allowlist。

这条规则非常适合下面这些能力：

• 会改外部系统状态

• 依赖额外二进制或凭据

• 容易误触发

同时，它也和 OpenClaw 的 tool policy 完整接起来了：

• tools.allow

• agents.list[].tools.allow

• group:plugins

• 插件 id 级别启用

所以对插件作者来说，一个很成熟的习惯是：

默认把有副作用的工具做成 optional。

八、Plugin 不只是 Tool，还能真正接入运行时生命周期

如果你只把 Plugin 理解成“提供几个工具”，那还是太窄了。

官方 Plugins 文档里，api.on(...) 明确提供了生命周期 hook 能力，例如：

api.on(

  “before_prompt_build”,

  (event, ctx) => {

    return {

      prependSystemContext: “Follow company style guide.”,

    };

  },

  { priority: 10 },

);

而且文档还把几个关键 hook 区分得很清楚：

• before_model_resolve

• before_prompt_build

• before_agent_start（legacy compatibility）

这说明一件事：

Hook 是运行时切点，Plugin 是承载这些切点的代码扩展容器之一。

九、真正系统级的 Plugin，还会碰到 RPC、CLI、HTTP Route 和 Service

这是 Skill 和单纯 Hook 都替代不了的地方。

官方文档给了非常直接的例子：

1. Gateway RPC method

api.registerGatewayMethod(“myplugin.status”, ({ respond }) => {

  respond(true, { ok: true });

});

2. CLI command

api.registerCli(

  ({ program }) => {

    program.command(“mycmd”).action(() => {

      console.log(“Hello”);

    });

  },

  { commands: [“mycmd”] },

);

3. HTTP route

官方也明确建议用：

api.registerHttpRoute(…)

而且 route 必须显式声明 auth 是 gateway 还是 plugin。

4. Background service

api.registerService({

  id: “my-service”,

  start: () => api.logger.info(“ready”),

  stop: () => api.logger.info(“bye”),

});

当你开始需要这些能力时，说明你已经不在“怎么组织提示词”的层，而是在扩 OpenClaw 的系统表面。

十、给扩展阶段的最小判断标准

如果你现在还在犹豫到底该用哪一层，可以用这组判断：

1. 只是想告诉 Agent 何时做事，用 Skill

2. 只是想在运行某个节点插一段逻辑，用 Hook

3. 需要新增 tool / route / RPC / CLI / service，用 Plugin

只要按这个顺序判断，绝大多数扩展都不会走偏。

十一、这一篇之后，你该建立什么认知

到这里，你应该把 Plugin 理解成：

它不是“大号 Skill”，也不是“随便放点代码的目录”，而是 OpenClaw 的系统级扩展容器。

把这三层分清以后，你写的每一行扩展代码，才是在给系统加能力，而不是给提示词继续堆复杂度。

下一篇，我们收束到最终落地问题：如何把 OpenClaw 安全、稳定、长期地跑起来。

参考链接

• Plugins：
https://docs.openclaw.ai/tools/plugin

• Skills：
https://docs.openclaw.ai/tools/skills

• Agent Loop：
https://docs.openclaw.ai/concepts/agent-loop

---

这一篇属于 OpenClaw 系列的「深入」阶段。

上一篇：OpenClaw 自动化：Cron、Webhooks、Gmail Hooks 怎么把 Gateway 变成事件中枢

下一篇：OpenClaw 生产化：权限、安全、沙箱与长期运行治理