1. 本期目标上一期我们分析了 OpenClaw 的 Skills 技能系统。Skill 负责把可复用的任务经验、工具使用流程和行为约束沉淀下来让 Agent 不只是“有工具”而是“知道如何使用工具”。这一期继续分析 OpenClaw 的另一层扩展机制Plugins 插件系统。前面几期已经反复提到过Tool 解决 Agent 能调用什么动作 Skill 解决 Agent 应该如何组织动作 Channel 解决外部消息如何进入 Agent Provider 解决模型、语音、搜索、媒体能力如何接入 Plugin 则是把这些能力打包扩展到 OpenClaw 的机制。OpenClaw 官方文档对 Plugin 的定位很明确插件可以扩展 Channel、模型提供商、Agent harness、Tools、Skills、语音、实时转录、媒体理解、生成、Web fetch、Web search 等运行时能力。(OpenClaw)本期重点分析1. Plugin 在 OpenClaw 架构中解决什么问题 2. Plugin、Tool、Skill、Channel、Provider 的关系是什么 3. openclaw.plugin.json 承担什么作用 4. Plugin 如何安装、启用、加载和验证 5. definePluginEntry、defineToolPlugin、defineChannelPluginEntry 有什么区别 6. 插件如何注册工具、技能、Channel、Provider 和 hooks 7. native plugin 和 compatible bundle 有什么区别 8. 插件系统的安全边界和排错思路是什么2. Plugin 是什么可以先给一个直观定义Plugin 是 OpenClaw 的能力扩展包。它不是单纯的工具函数也不是单纯的提示词文件而是一个可以被 OpenClaw 发现、验证、加载并在运行时注册能力的扩展模块。例如一个插件可以提供一个新的 Telegram-like Channel 一个新的模型 Provider 一个新的 Web Search Provider 一组新的 Agent Tools 一组配套 Skills 一组 Gateway HTTP routes 一组 runtime hooks 一个本地 CLI backend 一个媒体生成能力 一个语音或实时转录能力。所以 Plugin 的核心作用是在不修改 OpenClaw 核心代码的前提下把新的运行时能力接入系统。官方构建插件文档也强调插件可以在不改变 OpenClaw core 的情况下添加消息 Channel、模型 Provider、本地 CLI backend、Agent tool、hook、media provider 等能力。(OpenClaw)3. 为什么需要 Plugin如果没有插件系统OpenClaw 每增加一个能力都需要改核心代码。比如要支持一个新的聊天平台修改 src/channels 修改配置 schema 修改 Gateway 启动逻辑 修改消息投递逻辑 修改文档 重新发布 OpenClaw。要支持一个新的模型提供商修改 provider registry 修改模型配置 修改鉴权逻辑 修改工具调用适配 重新发布 OpenClaw。这会导致核心代码越来越臃肿也会让社区扩展变得困难。Plugin 系统把这个问题拆开OpenClaw core 提供统一的加载、配置、权限、运行时 API。 Plugin 按照约定注册自己的能力。 Gateway 启动时发现插件并把插件能力纳入统一运行时。这样OpenClaw core 只需要维护稳定扩展接口具体能力可以由插件独立演进。4. Plugin、Tool、Skill、Channel、Provider 的关系这几个概念很容易混淆可以用一句话区分Tool 是动作 Skill 是动作说明 Channel 是消息入口 Provider 是能力供应方 Plugin 是把这些能力打包接入 OpenClaw 的扩展机制。举个例子一个 browser plugin 可以注册 browser tool 可以附带 browser-automation skill 可以注册相关 hooks 可以提供浏览器控制 runtime。 一个 Slack plugin 可以注册 Slack channel 可以定义消息收发格式 可以提供 setup CLI 可以提供 channel-specific message presentation。 一个 stock plugin 可以注册 stock_quote tool 可以提供 API key config schema 可以附带 stock-analysis skill。可以画成Plugin ├─ Tool ├─ Skill ├─ Channel ├─ Provider ├─ Hook ├─ Gateway method / HTTP route ├─ CLI command └─ Runtime service所以前几期讲过的 Tool、Skill、Channel其实都可以通过 Plugin 扩展。5. Plugin 的两种主要形态OpenClaw 文档中区分了两类插件格式Native OpenClaw plugin Compatible bundleNative OpenClaw plugin 使用openclaw.plugin.json加运行时模块由 OpenClaw 进程内加载适合开发 OpenClaw 专用的运行时能力Compatible bundle 则是 Codex、Claude、Cursor 等外部插件布局被 OpenClaw 映射进自己的插件清单和能力体系。(OpenClaw)可以这样理解Native plugin OpenClaw 原生插件可以注册运行时能力。 Compatible bundle 外部生态内容包OpenClaw 尽量把其中的 skills、commands、hooks、MCP tools 等映射成原生能力。Native plugin 更像“代码型插件”Bundle 更像“内容和元数据包”。6. Native Plugin 的基本组成一个最小 Native Plugin 通常包含package.json openclaw.plugin.json src/index.ts 或 dist/index.js其中package.json 告诉 Node / npm 这个包是什么以及 OpenClaw runtime entry 在哪里。 openclaw.plugin.json 告诉 OpenClaw 这个插件声明了哪些能力、如何配置、何时激活。 index.ts / index.js 真正的插件运行时代码用来 register tool、provider、channel、hook 等。官方 quickstart 中的示例也包含这三类核心内容package.json中声明openclaw.extensionsopenclaw.plugin.json中声明id、name、description、contracts、activation、configSchema运行时代码中通过definePluginEntry注册工具。(OpenClaw)7. openclaw.plugin.json 的作用openclaw.plugin.json是插件系统的核心文件。它不是给模型看的也不是给用户看的而是给 OpenClaw 插件加载器看的。它解决几个问题这个插件是谁 这个插件声明了哪些能力 它拥有哪些 tool / channel / provider 它是否需要启动时加载 它的配置 schema 是什么 OpenClaw 能否在不执行插件代码的情况下检查它官方插件构建文档明确说明每个插件都需要 manifest即使没有配置也需要运行时工具必须出现在contracts.tools中这样 OpenClaw 才能在不急切加载每个插件 runtime 的情况下发现工具归属。(OpenClaw)一个简化的 manifest 如下{ id: my-plugin, name: My Plugin, description: Adds a custom tool to OpenClaw, contracts: { tools: [my_tool] }, activation: { onStartup: true }, configSchema: { type: object, additionalProperties: false } }可以把它理解成openclaw.plugin.json 是插件的冷启动身份证。OpenClaw 可以先读这个文件判断插件是否存在、配置是否合法、能力是否冲突而不需要一开始就执行插件代码。8. 冷元数据和运行时代码的分离OpenClaw 插件系统有一个很重要的设计思想先读冷元数据再决定是否加载运行时代码。也就是说OpenClaw 不会为了知道“这个插件有什么工具”就立即执行它的 JavaScript 代码而是先读取 manifest。这有几个好处第一启动更安全 可以先验证插件身份、配置 schema、工具归属和冲突。 第二启动更快 不用无条件加载所有插件 runtime。 第三排错更清楚 plain inspect 可以做冷检查runtime inspect 再验证实际注册。 第四权限边界更明确 插件声明能力和实际注册能力可以相互校验。这也是为什么 manifest 里的contracts.tools很重要。如果插件运行时代码注册了一个工具但 manifest 里没有声明那么 OpenClaw 很难在冷启动阶段识别这个工具的归属。9. Plugin 安装来源OpenClaw 支持多种插件安装来源ClawHub npm git local path marketplace archive官方插件文档给出的安装示例包括 ClawHub、npm、git 和本地开发目录例如openclaw plugins install clawhub:package、npm:package、git:github.com/owner/reporef、./my-plugin或--link ./my-plugin。(OpenClaw)可以这样区分ClawHub OpenClaw 原生发现和分发渠道。 npm 适合 JavaScript / TypeScript 插件包。 git 适合从仓库分支、tag、commit 安装。 local path 适合本地开发调试。 marketplace 适合兼容 Claude 等外部生态的插件包。如果追求可复现建议使用带版本、tag 或 commit 的安装方式而不是总是安装 latest。10. Plugin 启用与配置插件安装后不一定等于立即可用。它还会受到插件配置策略影响。OpenClaw 的插件配置通常位于plugins.entries.plugin-id.config plugins.entries.plugin-id.enabled plugins.allow plugins.deny plugins.load.paths plugins.slots官方文档给出的配置形态包括plugins.enabled、plugins.allow、plugins.deny、plugins.load.paths、plugins.slots和plugins.entries其中plugins.deny优先于 allow 和 per-plugin enablementplugins.allow是独占白名单plugins.entries.id.enabled: false可以禁用单个插件并保留配置。(OpenClaw)示例{ plugins: { enabled: true, allow: [stock-quotes], deny: [untrusted-plugin], load: { paths: [~/Projects/openclaw-stock-plugin] }, entries: { stock-quotes: { enabled: true, config: { apiKey: YOUR_API_KEY } } } } }可以理解为安装 插件文件进入 OpenClaw 可发现范围。 启用 插件被策略允许加载。 配置 插件获得运行时所需参数。 重启或 reload Gateway 真正加载插件 runtime。11. Plugin policy 和 Tool policy 的区别这里要特别区分两层策略Plugin policy 决定插件能不能被加载。 Tool policy 决定插件里的某个工具能不能暴露给模型。举例{ plugins: { allow: [stock-quotes] }, tools: { allow: [stock_quote] } }这表示stock-quotes 插件可以加载 stock_quote 工具可以暴露给模型。如果只允许 tool但插件被 deny 了插件加载失败 工具自然不会出现。如果插件加载了但 tool 没有通过 Tool policy插件 runtime 可以存在 模型当前 session 仍然看不到该工具。所以二者是上下游关系Plugin policy ↓ 插件能否加载 ↓ Tool policy ↓ 工具能否暴露给模型官方文档也说明如果插件不在plugins.allow中则插件拥有的工具不可用即使tools.allow包含*也不行。(OpenClaw)12. Plugin 加载和 Gateway 重启安装或更新插件代码后Gateway 需要重新加载插件。官方文档说明安装、更新或卸载插件代码需要 Gateway restart如果 managed Gateway 已运行并启用 config reloadOpenClaw 可以检测插件安装记录变化并自动重启否则需要手动执行openclaw gateway restart。(OpenClaw)这点很关键。很多初学者会以为openclaw plugins install xxx之后插件马上在正在运行的聊天会话中生效。但更准确的是插件安装改变了磁盘状态 Gateway runtime 还需要重新加载 session 也可能需要下一轮或新 session 才能看到相关能力。所以调试插件时要形成习惯openclaw plugins inspect plugin-id --runtime --json openclaw gateway status --deep --require-rpc openclaw gateway restart官方文档也强调plaininspect是冷 manifest 和 registry 检查--runtime才用于证明 registered tools、hooks、services、Gateway methods 或插件自有 CLI commands 是否真正加载。(OpenClaw)13. definePluginEntry通用插件入口definePluginEntry是非 Channel 插件的通用入口。官方 SDK entrypoint 文档说明definePluginEntry适用于 provider plugin、高级 tool plugin、hook plugin以及任何不是 messaging channel 的插件它通过register(api)注册 provider、tool 等能力。(OpenClaw)示意import { Type } from typebox; import { definePluginEntry } from openclaw/plugin-sdk/plugin-entry; export default definePluginEntry({ id: my-plugin, name: My Plugin, description: Adds a custom tool to OpenClaw, register(api) { api.registerTool({ name: my_tool, description: Echo one input value, parameters: Type.Object({ input: Type.String() }), async execute(_id, params) { return { content: [ { type: text, text: Got: ${params.input} } ] }; } }); } });可以理解为definePluginEntry 是插件运行时代码的总入口。它让插件在被 Gateway 加载时有机会向 OpenClaw 注册自己的能力。14. defineToolPlugin轻量工具插件入口如果一个插件只想注册固定工具列表可以使用defineToolPlugin。官方 Tool plugins 文档说明Tool plugin 用来添加 Agent 可调用工具不添加 channel、model provider、hook、service 或 setup backend推荐流程是 init、写工具、build、生成 manifest 和 package metadata、validate。(OpenClaw)示意import { Type } from typebox; import { defineToolPlugin } from openclaw/plugin-sdk/tool-plugin; export default defineToolPlugin({ id: stock-quotes, name: Stock Quotes, description: Fetch stock quote snapshots., configSchema: Type.Object({ apiKey: Type.Optional(Type.String()), baseUrl: Type.Optional(Type.String()) }), tools: (tool) [ tool({ name: stock_quote, label: Stock Quote, description: Fetch a stock quote snapshot., parameters: Type.Object({ symbol: Type.String() }), async execute({ symbol }, config, context) { context.signal?.throwIfAborted(); return { symbol: symbol.toUpperCase(), configured: Boolean(config.apiKey), baseUrl: config.baseUrl ?? https://api.example.com }; } }) ] });这里有几个重点configSchema 定义插件配置结构。 tools 定义工具列表。 parameters 定义工具参数 schema。 execute 执行工具逻辑。 context.signal 支持中断和取消。官方文档也强调工具名是稳定 API应选择唯一、小写、足够具体的名称避免和 core tools 或其他插件冲突。(OpenClaw)15. required tool、optional tool 和 factory tool插件工具并不都是同一种暴露方式。官方文档区分了 required tool、optional tool 和 factory tool。required tool 插件启用后默认可用。 optional tool 需要用户通过 tools.allow 明确 opt-in 后才暴露给模型。 factory tool 工具名称固定但具体工具对象需要根据运行时上下文动态生成。官方文档说明required tools 在插件启用时可用optional tools 需要用户 opt-in如果工具需要 runtime tool context 才能创建可以使用 factory让工具根据 sandbox 状态、runtime helpers 等决定是否返回。(OpenClaw)例如tool({ name: local_workflow, description: Run a local workflow outside sandboxed sessions., parameters: Type.Object({ goal: Type.String() }), optional: true, factory({ api, toolContext }) { if (toolContext.sandboxed) { return null; } return createLocalWorkflowTool(api); } });这表示如果当前 session 是 sandboxed就不创建这个工具 如果不是 sandboxed才返回真正的工具定义。这个设计可以让插件工具跟随当前 Agent、Session、Sandbox、Channel 上下文变化。16. defineChannelPluginEntryChannel 插件入口如果插件要接入一个新的消息平台就不能只注册普通工具而要注册 Channel。官方 SDK entrypoint 文档说明defineChannelPluginEntry会包装 channel-specific wiring自动调用api.registerChannel({ plugin })并支持 channel 相关 setup / runtime 约定。(OpenClaw)可以理解为defineToolPlugin 适合只添加工具。 definePluginEntry 适合添加 provider、hook、高级工具、service 等非 channel 能力。 defineChannelPluginEntry 适合添加消息平台接入。Channel 插件通常要处理外部平台鉴权 Webhook 或 Gateway 连接 入站消息标准化 DM / group 访问控制 pairing reply threading outbound messaging 平台限流和重试 setup CLI 或 setup wizard。所以 Channel 插件的复杂度通常高于普通 Tool 插件。17. Setup entry为什么 Channel 插件可能需要轻量入口Channel 插件有时还会拆出 setup entry。原因是某些配置、安装、setup wizard 或 webhook 验证逻辑需要在 Channel 完整 runtime 尚未启用时也能运行。官方 SDK entrypoint 文档提到defineSetupPluginEntry用于轻量setup-entry.tsOpenClaw 可以在 channel disabled、unconfigured 或 deferred loading 时加载它而不是加载完整 entryheavy SDK、CLI registration 和 long-lived runtime services 应放在 full entry 中。(OpenClaw)可以这样理解setup entry 轻量、安全、配置相关。 full entry 完整运行时、真实消息收发、长期服务。这有助于避免一个尚未配置好的 Channel 插件在 Gateway 启动时就加载大量外部 SDK 或启动长连接。18. 插件注册 Tool 的完整链路以一个工具插件为例完整链路可以这样画安装插件包 ↓ 读取 package.json ↓ 读取 openclaw.plugin.json ↓ 验证 manifest / configSchema / contracts.tools ↓ 检查 plugins.allow / plugins.deny / entries.enabled ↓ Gateway 启动或重启 ↓ 加载插件 entry ↓ register(api) 执行 ↓ api.registerTool(...) ↓ 工具进入 plugin tool registry ↓ 当前 session 构造 effective tools ↓ 经过 Tool policy / Sandbox / Sender policy ↓ 模型看到允许的工具 schema ↓ 模型发起 tool call ↓ 插件 execute 执行 ↓ tool result 写回 Agent 上下文这条链路说明插件工具不是注册后无条件暴露给模型 它还要经过插件策略、工具策略、运行时上下文和会话策略过滤。19. 插件如何携带 Skill上一期我们讲过Skill 是SKILL.md目录。插件也可以携带自己的 Skill。OpenClaw Skills 文档说明插件可以在openclaw.plugin.json中列出 skills directories路径相对于插件根目录当插件启用时这些 plugin skills 会加载适合放置那些太长、不适合写进 tool description但又应该随插件可用的工具操作指南。(OpenClaw)比如一个浏览器插件可能包含skills/browser-automation/SKILL.md这个 Skill 告诉 Agent如何打开页面 如何等待元素 如何点击按钮 如何处理登录 如何截图 如何在失败时回退。这样 Tool 和 Skill 就形成配套Plugin 注册 browser tool Plugin 携带 browser-automation skill Agent 既有工具又有使用工具的流程说明。20. 插件 Hooks扩展运行时行为插件不仅能注册工具也能注册 hooks。OpenClaw 文档区分了两类 hook API一种是通过api.on(...)注册 typed hooks适合 middleware、policy、message rewriting、prompt shaping、tool control 等另一种是api.registerHook(...)主要用于内部 hook 系统中的粗粒度 command / lifecycle side effects。(OpenClaw)可以理解为api.on(...): 更偏运行时中间件可以参与更细粒度控制。 api.registerHook(...): 更偏已有 HOOK-style 自动化兼容处理粗粒度事件。可能的 hook 场景包括消息进入前改写 模型调用前调整 prompt 工具调用前做审批 工具调用后记录日志 发送消息后做审计 session reset 后做清理 命令触发后执行副作用。这使 Plugin 不只是“增加能力”还可以“改变能力运行过程”。21. Plugin Bundle兼容外部生态OpenClaw 还支持 compatible bundle把 Codex、Claude、Cursor 等外部生态的内容映射到 OpenClaw。官方 Plugin bundles 文档说明OpenClaw 可以安装来自 Codex、Claude、Cursor 三类外部生态的插件这些 bundle 是内容和元数据包会被映射成 OpenClaw 原生的 skills、hooks、MCP tools 等能力bundle 不是 native plugin它们不会像 Native plugin 那样在进程内注册任意能力。(OpenClaw)支持映射的能力包括Skill content Commands Hook packs MCP tools LSP servers。文档中明确提到bundle skill roots 会作为普通 OpenClaw skill roots 加载Claude commands roots 和 Cursor.cursor/commandsroots 也会被作为额外 skill roots 处理。(OpenClaw)所以 Bundle 的意义是不用要求所有外部生态插件都重写成 OpenClaw Native Plugin OpenClaw 尽量把可兼容的内容接进自己的能力系统。22. Native Plugin 和 Bundle 的区别可以从四个角度区分1. 是否运行代码 Native Plugin 可以运行 OpenClaw 插件代码注册 runtime capabilities。 Bundle 更多是内容和元数据映射能力边界更窄。 2. 是否使用 openclaw.plugin.json Native Plugin 使用 openclaw.plugin.json。 Bundle 使用 Codex / Claude / Cursor 自己的布局。 3. 能力范围 Native Plugin 可以注册 tools、channels、providers、hooks、routes、services 等。 Bundle 主要映射 skills、commands、hooks、MCP tools、LSP defaults 等。 4. 使用场景 Native Plugin 适合 OpenClaw 专用能力开发。 Bundle 适合复用外部 Agent 生态已有内容。一句话概括Native Plugin 是 OpenClaw 的原生运行时扩展Bundle 是外部生态内容到 OpenClaw 的兼容映射。23. Plugin inspect冷检查和运行时检查排查插件时inspect很重要。但要区分openclaw plugins inspect id openclaw plugins inspect id --runtime前者偏冷检查插件是否安装 manifest 是否存在 registry 状态如何 配置是否可识别 声明能力是什么。后者会加载 runtime用来检查实际注册了哪些 tools 实际注册了哪些 hooks 实际注册了哪些 services 是否有 plugin-owned CLI commands runtime import 是否失败。官方 CLI 文档也说明plain inspect 会显示 identity、load status、source、manifest capabilities、policy flags、diagnostics、install metadata 等但默认不导入插件 runtime加--runtime后才会加载插件模块并展示已注册 hooks、tools、commands、services、Gateway methods 和 HTTP routes。(GitHub)所以如果遇到插件列表里有但 Agent 看不到工具 插件启用了但 hook 没运行 配置写了但 Channel 没启动。优先执行openclaw plugins inspect plugin-id --runtime --json openclaw gateway status --deep --require-rpc openclaw gateway restart24. 插件冲突谁拥有同一个能力插件系统引入了一个新问题如果两个插件都声明自己拥有同一个 tool 或 channel怎么办例如plugin-a 声明 tools: [stock_quote] plugin-b 也声明 tools: [stock_quote] plugin-x 声明 channel: telegram plugin-y 也声明 channel: telegram这会造成能力归属冲突。OpenClaw 文档的 troubleshooting 中提到如果出现 duplicate channel 或 tool ownership diagnostics可以运行openclaw plugins list --enabled --verbose再用inspect --runtime --json对比每个插件的 channel/tool ownership如果是有意替换可以通过 manifestpreferOver表达替换意图。(OpenClaw)这说明 OpenClaw 并不会默默让后加载的插件覆盖前面的插件而是尽量把冲突暴露出来。25. 插件安全风险Plugin 比 Skill 风险更高。Skill 通常是 Markdown 行为说明而 Plugin 可以执行代码、注册工具、开 HTTP route、连接外部服务、读配置、调用本地资源。所以安装插件要像安装 npm 包或浏览器扩展一样谨慎。主要风险包括第一代码执行风险 插件 runtime 是代码可以在加载或执行时做危险操作。 第二凭据泄露风险 插件可能读取 config、env、apiKey 或 workspace 文件。 第三工具扩大风险 插件可能注册高权限工具诱导模型调用。 第四消息入口风险 Channel 插件可能把外部未授权消息接入 Gateway。 第五Hook 篡改风险 插件 hook 可能改写消息、prompt、tool call 或输出。 第六依赖链风险 npm / git 插件可能携带复杂依赖。因此建议优先安装可信来源插件 生产环境使用 pinned version 限制 plugins.allow 对高风险工具使用 tools.allow / tools.deny 不可信插件先在测试环境试运行 查看 openclaw.plugin.json 和 runtime entry 使用 inspect --runtime 验证实际注册能力 启用必要的 sandbox 和 approval。官方插件文档也提醒应把插件安装视为运行代码在需要可复现生产安装时优先使用 pinned versions。(OpenClaw)26. 插件开发的最小流程如果自己写一个最小工具插件可以按下面流程1. 创建插件包 2. 编写 package.json 3. 编写 openclaw.plugin.json 4. 编写 src/index.ts 5. 注册工具 6. build 成 JavaScript 7. validate 插件 8. 本地 install 或 link 9. restart Gateway 10. inspect --runtime 验证 11. 在 Agent session 中测试工具是否进入 effective tools官方 Tool plugin 文档推荐流程也类似使用openclaw plugins init脚手架编写defineToolPlugin构建 JavaScript生成openclaw.plugin.json和package.jsonmetadata发布或安装前先 validate。(OpenClaw)示例命令openclaw plugins init stock-quotes --name Stock Quotes cd stock-quotes npm install npm run plugin:build npm run plugin:validate npm test openclaw plugins install --link . openclaw gateway restart openclaw plugins inspect stock-quotes --runtime --json27. 一个完整例子Stock Quotes Tool Plugin我们可以构造一个简单插件提供股票价格查询工具。目录结构stock-quotes/ ├─ package.json ├─ openclaw.plugin.json ├─ tsconfig.json └─ src/ └─ index.tspackage.json{ name: myorg/openclaw-stock-quotes, version: 0.1.0, type: module, openclaw: { extensions: [./dist/index.js] }, dependencies: { typebox: ^1.0.0 }, devDependencies: { typescript: ^5.0.0 } }openclaw.plugin.json{ id: stock-quotes, name: Stock Quotes, description: Fetch stock quote snapshots., activation: { onStartup: true }, contracts: { tools: [stock_quote] }, configSchema: { type: object, additionalProperties: false, properties: { apiKey: { type: string, description: Quote API key. }, baseUrl: { type: string, description: Quote API base URL. } } } }src/index.tsimport { Type } from typebox; import { defineToolPlugin } from openclaw/plugin-sdk/tool-plugin; export default defineToolPlugin({ id: stock-quotes, name: Stock Quotes, description: Fetch stock quote snapshots., configSchema: Type.Object({ apiKey: Type.Optional(Type.String()), baseUrl: Type.Optional(Type.String()) }), tools: (tool) [ tool({ name: stock_quote, label: Stock Quote, description: Fetch a stock quote snapshot for a ticker symbol., parameters: Type.Object({ symbol: Type.String({ description: Ticker symbol, for example AAPL or MSFT. }) }), async execute({ symbol }, config, context) { context.signal?.throwIfAborted(); return { symbol: symbol.toUpperCase(), providerConfigured: Boolean(config.apiKey), baseUrl: config.baseUrl ?? https://api.example.com, note: This is a demo response. Replace it with a real quote API call. }; } }) ] });配置{ plugins: { entries: { stock-quotes: { enabled: true, config: { apiKey: YOUR_API_KEY, baseUrl: https://api.example.com } } } }, tools: { allow: [stock_quote] } }这个例子体现了插件系统的核心链路manifest 声明工具归属 entry 注册工具运行逻辑 configSchema 定义配置 plugins.entries 注入配置 tools.allow 决定模型是否能看到工具。28. 插件和 Gateway 的关系Plugin 最终是由 Gateway 加载的。因为 Gateway 是 OpenClaw 的控制平面它负责加载配置 发现插件 验证插件 启动 Channel 注册 Provider 构造工具目录 处理会话和消息 执行 Agent run 暴露 RPC / HTTP 方法。所以 Plugin 不是直接被 Agent 单独加载而是进入 Gateway 的能力注册体系。可以画成openclaw.json ↓ Plugin registry / manifest ↓ Gateway startup ↓ Plugin runtime load ↓ api.registerTool / Channel / Provider / Hook ↓ Gateway capability registry ↓ Agent / Channel / Session / Tool pipeline 使用这些能力这也是为什么插件修改后通常要重启 Gateway。29. 插件相关源码阅读路线这一期建议从这些方向读源码第一组插件入口和 SDK src/plugins/ src/plugin-sdk/ packages 或 extensions 中的插件示例 第二组插件 manifest 和 registry openclaw.plugin.json plugin registry plugin manifest validation plugin inventory 第三组插件加载 plugin loader runtime entry loading cold registry runtime inspect 第四组插件工具 plugin tools tool factory optional tools tools.catalog tools.effective 第五组插件配置 plugins.entries plugins.allow plugins.deny plugins.load.paths plugins.slots configSchema validation 第六组插件 hooks typed plugin hooks api.on(...) api.registerHook(...) 第七组Channel / Provider 插件 channel plugin entry provider plugin entry setup entry deferred loading 第八组CLI 文档对照 docs/tools/plugin.md docs/plugins/building-plugins.md docs/plugins/tool-plugins.md docs/plugins/manifest.md docs/cli/plugins.md docs/plugins/bundles.md阅读时可以带着这些问题1. OpenClaw 如何发现已安装插件 2. openclaw.plugin.json 在什么时候被读取 3. configSchema 在什么时候校验 4. plugins.allow 和 plugins.deny 在哪里生效 5. 插件 runtime entry 是如何加载的 6. api.registerTool 注册后的工具进入了哪个 registry 7. optional tool 如何等待 tools.allow opt-in 8. factory tool 如何根据 sandbox/session context 动态返回 null 9. plain inspect 和 --runtime inspect 差别在哪里 10. Channel plugin 为什么需要 setup entry30. 初学者容易混淆的几个点30.1 安装插件不等于启用插件install 插件文件存在。 enable 插件被配置策略允许。 runtime loaded Gateway 真正加载了插件代码。30.2 Plugin allow 不等于 Tool allowplugins.allow 决定插件能不能加载。 tools.allow 决定工具能不能暴露给模型。30.3 manifest 不等于 runtimemanifest 插件声明的冷元数据。 runtime 插件实际注册的工具、hooks、routes、services。30.4 Native plugin 不等于 BundleNative plugin OpenClaw 原生运行时扩展。 Bundle 外部生态内容映射。30.5 Plugin 不是 SkillSkill 是行为说明 Plugin 是能力扩展包 Plugin 可以携带 Skill但二者不是一回事。31. 我的理解我认为 OpenClaw 的 Plugin 系统最值得学习的地方是它把“扩展能力”拆成了两层第一层冷元数据 用 openclaw.plugin.json 描述插件身份、配置 schema 和能力归属。 第二层运行时代码 用 definePluginEntry / defineToolPlugin / defineChannelPluginEntry 注册真实能力。这种设计比“加载插件代码后再问它有什么能力”更稳健。因为 OpenClaw 可以在执行插件代码之前就完成很多检查配置是否合法 插件是否被 allow / deny 工具归属是否冲突 Channel 是否重复 是否需要 onStartup 是否有 stale plugin config 是否需要 doctor 修复。同时Plugin 又没有被限制成单一形态。它既可以是一个很小的工具插件也可以是完整 Channel 插件、Provider 插件、Hook 插件、Media 插件甚至通过 bundle 复用其他 Agent 生态的内容。所以 Plugin 是 OpenClaw 从“一个本地 Agent 工具”演进为“可扩展 AI 助手平台”的关键机制。32. 本期重点理解这一期可以总结为五点第一Plugin 是 OpenClaw 的能力扩展包可以注册 tools、skills、channels、providers、hooks、services、routes 和 CLI commands。 第二Native Plugin 通过 openclaw.plugin.json 声明冷元数据通过 runtime entry 注册真实能力。 第三Plugin policy 决定插件能否加载Tool policy 决定插件工具能否暴露给模型。 第四defineToolPlugin 适合固定工具列表definePluginEntry 适合通用插件能力defineChannelPluginEntry 适合消息平台接入。 第五Compatible Bundle 用来把 Codex、Claude、Cursor 等外部生态内容映射为 OpenClaw skills、commands、hooks、MCP tools 等能力。一句话概括OpenClaw 的 Plugin 系统本质上是一个 manifest-first 的能力扩展机制先用冷元数据声明插件身份和能力归属再由运行时代码把工具、技能、频道、模型和 hooks 接入 Gateway。33. 本期小结本期主要分析了 OpenClaw 的 Plugins 插件系统。Plugin 是 OpenClaw 的能力扩展机制可以在不修改核心代码的前提下接入 Tool、Skill、Channel、Provider、Hook、Gateway route、CLI command 等能力。Native Plugin 依赖openclaw.plugin.json作为冷元数据入口用于声明插件身份、配置 schema、能力归属和激活方式运行时代码则通过definePluginEntry、defineToolPlugin或defineChannelPluginEntry注册真实能力。插件安装后还要经过plugins.allow、plugins.deny、plugins.entries、Gateway restart 和 runtime inspect 等步骤最终能力才会进入 OpenClaw 的运行时体系。对于外部生态OpenClaw 还支持 Compatible Bundle把 Codex、Claude、Cursor 等格式中的 skills、commands、hooks、MCP tools 等映射到原生能力体系中。这一期可以用一句话总结Plugin 让 OpenClaw 的能力不再固定在 core 里而是可以通过可验证、可配置、可安装、可审计的方式持续扩展。下一期可以继续分析OpenClaw 源码解析十四Provider 系统与模型能力接入机制下一期重点看模型 Provider 如何接入 OpenClawProvider、Model、Agent runtime、tool calling、media generation、web search provider 之间的关系以及 OpenClaw 如何把不同模型后端统一到 Agent 执行链路中。