人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载OpenClaw 将扩展目录视为一个与第三方插件完全一致的边界所有插件只能通过openclaw/plugin-sdk/*与类型化子路径与核心交互绝不允许直接深入src/**内部实现。本文以仓库根目录 CLAUDE.md 定义的 Extensions Boundary 契约为骨架结合 Plugin SDK 源码、边界守卫测试与内置扩展的真实配置系统讲解公共契约清单、五条边界铁律、SDK 与 Runtime 两层架构以及如何安全地扩展这条边界。读完你将掌握 OpenClaw 插件开发中最关键的依赖约束与演进规范写出与内置插件同规格、可持续升级的插件。什么是 Extensions BoundaryOpenClaw 仓库中的 extensions/ 目录存放随项目分发的内置插件bundled plugins。根目录 CLAUDE.md 开篇即点明核心设计原则This directory contains bundled plugins. Treat it as the same boundary that third-party plugins see.也就是说内置插件与第三方插件共享同一条边界它们面对的是完全相同的 SDK 表面、相同的导入限制、相同的元数据要求。这一设计消除了内置插件可以走捷径、外部插件必须守规矩的双重标准——任何内置插件如果越界导入核心内部模块就意味着第三方插件同样可能这样做边界因此失去意义。从源码结构看这一原则与 docs/refactor/plugin-sdk.md 中记录的 SDK 重构计划一脉相承该计划的目标是每一个消息连接器都是一个插件内置或外部使用同一套稳定 API没有任何插件直接从src/**导入所有依赖都经由 SDK 或 Runtime。这正是边界文档存在的底层动因——历史上连接器曾混用直接核心导入、dist-only 桥接和自定义辅助函数三种模式导致升级脆弱也堵死了干净的第三方插件表面。公共契约清单插件开发者的第一份阅读清单边界契约由两部分构成文档与定义文件。CLAUDE.md 列出了完整的 Public Contracts。文档部分CLAUDE.md 中列举的文档路径以docs/plugins/为前缀如building-plugins.md、architecture.md、sdk-overview.md、sdk-entrypoints.md、sdk-runtime.md、sdk-channel-plugins.md、sdk-provider-plugins.md。需要说明的是在当前仓库快照的 docs/plugins/ 目录下可以确认存在的文档包括 manifest.md插件清单规范、agent-tools.md、community.md、voice-call.md、zalouser.md而 SDK 整体架构与插件工具的权威说明实际落地于 docs/refactor/plugin-sdk.mdPlugin SDK Runtime 重构方案与 docs/tools/plugin.md插件系统完整指南中文版见 docs/zh-CN/refactor/plugin-sdk.md 与 docs/zh-CN/tools/plugin.md。以 docs/plugins/manifest.md 为例它明确要求每个插件必须在插件根目录提供openclaw.plugin.jsonOpenClaw 依靠该清单在不执行插件代码的前提下完成配置校验清单缺失或非法会被当作插件错误并阻塞配置校验。定义文件部分契约的权威定义集中在 Plugin SDK 源码中这是所有插件的编译期事实来源文件作用src/plugin-sdk/plugin-entry.ts通用插件入口辅助definePluginEntry的类型与实现src/plugin-sdk/core.ts核心 SDK 面通道插件入口、配置 schema 构建、会话路由、工具函数等src/plugin-sdk/provider-entry.ts单 Provider 插件入口辅助defineSingleProviderPluginEntrysrc/plugin-sdk/channel-contract.ts纯通道契约类型ChannelAgentTool、ChannelThreadingContext、ChannelStatusIssue 等scripts/lib/plugin-sdk-entrypoints.json官方导出子路径清单共 238 个package.json包导出声明exports映射plugin-sdk-entrypoints.json是理解边界的关键它一次性列出了全部 238 个被公开的子路径涵盖index、core、runtime、setup、channel-setup、provider-entry、zod、testing等。package.json的exports字段必须与这份清单严格一致——这也是仓库中subpaths.test.ts、package-contract-guardrails.test.ts等测试所守护的对象。扩展生产代码实际可用的导入面就是这两份文件交叉验证后的结果。边界五条铁律CLAUDE.md 的 Boundary Rules 是全文最硬核的部分每条都对应着可以验证的源码或测试约束。规则一只从openclaw/plugin-sdk/*与自有 barrel 导入扩展生产代码应导入自openclaw/plugin-sdk/*及其自身的局部 barrel例如./api.ts与./runtime-api.ts。以真实内置扩展 extensions/acpx/runtime-api.ts 为例其全部导入都遵循这一模式export type { AcpRuntimeErrorCode } from openclaw/plugin-sdk/acp-runtime; // 其余导入同样来自 openclaw/plugin-sdk/core、openclaw/plugin-sdk/windows-spawn、 // openclaw/plugin-sdk/provider-env-vars 等子路径而 extensions/acpx/src/config.ts 中buildPluginConfigSchema来自openclaw/plugin-sdk/corez来自openclaw/plugin-sdk/zod——即使是最基础的配置 schema 构建也必须经过 SDK而不是直接 import 核心的 schema 工具。规则二禁止导入核心内部实现src/**、src/channels/**、src/plugin-sdk-internal/**以及另一个扩展的src/**都属于禁区。从 SDK 代码结构看src/plugin-sdk/目录中的文件如 core.ts本身就是对src/**内部模块的封装层——core.ts大量使用export { ... } from ../infra/...、from ../config/...这类再导出目的就是把内部实现收敛到稳定的 SDK 表面之后让扩展永远不需要也不应该看到这些实现细节。规则三相对导入不得逃逸当前扩展包根目录扩展内部使用./xxx、../xxx只能停留在自己包内不允许出现跳出扩展根目录的相对路径。这条规则由专门的机械检查脚本 scripts/check-extension-plugin-sdk-boundary.mjs 在 CI 中强制验证——对应的测试 extension-plugin-sdk-boundary.test.ts 对三类违规库存src-outside-plugin-sdk、plugin-sdk-internal、relative-outside-package逐一断言必须为空任何越界导入都会让检查失败。规则四元数据必须准确且不依赖执行openclaw.plugin.json与 package.json 中的openclaw块必须如实反映插件能力保证发现与 setup 在不执行插件代码的情况下即可工作。内置扩展 extensions/amazon-bedrock/openclaw.plugin.json 展示了标准清单{ id: amazon-bedrock, enabledByDefault: true, providers: [amazon-bedrock], configSchema: { type: object, additionalProperties: false, properties: {} } }其 package.json 中的openclaw块则声明入口{ name: openclaw/amazon-bedrock-provider, type: module, openclaw: { extensions: [./index.ts] } }结合 docs/plugins/manifest.md 的字段说明id与configSchema为必填kind如memory、context-engine、channels、providers、skills、name、description、uiHints、version为可选即使插件不接受任何配置也必须提供 schema空 schema 合法如{ type: object, additionalProperties: false }schema 在配置读写时校验而非运行时校验。规则五私有文件需要提升才能对外src/**、onboard.ts等本地辅助文件默认视为私有除非你有意通过api.ts必要时配合src/plugin-sdk/id.tsfacade将其提升为公共能力。反过来如果核心代码或核心测试需要某个内置插件的辅助函数也应当先从该插件的api.ts导出而不是让核心深度导入扩展内部实现。这条双向约束保证了导入方向永远是从核心流向扩展的 SDK 表面而不是反向渗透。两层架构编译期 SDK 与执行期 Runtime边界文档背后是 docs/refactor/plugin-sdk.md 规划的两层架构理解它才能理解为什么导入规则如此严格。第一层Plugin SDK编译期稳定、可发布。它只包含类型、辅助函数与配置工具没有运行时状态、没有副作用。典型内容包括ChannelPlugin等类型、buildChannelConfigSchema/setAccountEnabledInConfigSection等配置辅助、配对辅助、工具参数辅助等。这一层的消费方式是类型导入与纯函数调用。第二层Plugin Runtime执行期注入式。一切触及核心运行时行为的操作都经由OpenClawPluginApi.runtime注入插件因此永远不需要 importsrc/**。Runtime 面覆盖通道文本分块、回复分发、路由解析、配对、媒体抓取、群组策略、去抖、命令授权、日志与状态目录等能力并以channel.text、channel.reply、channel.routing、logging、state等命名空间组织。这一分层在 src/plugin-sdk/core.ts 中得到了直接体现defineChannelPluginEntry在注册通道能力的同时通过setRuntime?.(api.runtime)注入 Runtime并且只有api.registrationMode full时才执行registerFull——setup 模式与完整运行模式共享同一入口但执行不同注册深度。这正是Runtime 是访问核心行为的唯一途径这一原则的可运行实现。插件入口辅助函数三种标准化写法Plugin SDK 为不同插件形态提供了三个规范入口全部以id、name、description、configSchema、register为共同骨架plugin-entry.ts 中definePluginEntry的选项定义通用插件definePluginEntry({ id, name, description, kind?, configSchema?, register })用于 provider、tool、command、service、memory、context-engine 插件configSchema既可以是具体 schema也可以是返回 schema 的工厂函数resolvePluginConfigSchema统一处理默认值为emptyPluginConfigSchema。通道插件defineChannelPluginEntry({ id, name, description, plugin, configSchema?, setRuntime?, registerFull? })core.ts它包装definePluginEntry、自动调用api.registerChannel注册通道能力并可选注入 Runtime 与全量注册逻辑。单 Provider 插件defineSingleProviderPluginEntryprovider-entry.ts集中处理 API Key 认证方法、环境变量解析resolveEnvVars会去重合并envVars与各 auth 方法的envVar、Provider catalog 构建与 setup 向导wizard的默认配置。此外core.ts 还提供defineSetupPluginEntry给带独立setup-entry.ts的通道插件只需导出{ plugin }即可保持形状显式。扩展边界的正确姿势新增 seam 而非伸手够核心CLAUDE.md 的 Expanding The Boundary 一节给出了边界演进的三条准则这是插件生态可持续的关键需要新接口时添加类型化 Plugin SDK 子路径或增量导出而不是直接触及核心。换句话说新能力必须修路而非抄近道。新的插件面必须向后兼容并带版本管理——因为第三方插件正是消费这个表面任何破坏性变更都会波及生态。有意扩展契约时文档、导出子路径清单、package exports、API/契约检查必须在同一次变更中一并更新防止文档与实现漂移。这一准则的机器执行可以看两个真实测试 src/plugin-sdk/plugin-entry-guardrails.test.ts 遍历所有内置扩展的index.ts断言其中不得出现import { definePluginEntry } from openclaw/plugin-sdk/core——连核心 SDK 中最基础的入口辅助都禁止被扩展入口模块直接引用因为入口模块应当使用更专门的辅助如通道、Provider 专用入口src/plugin-sdk/package-contract-guardrails.test.ts 与subpaths.test.ts则守护 SDK 子路径清单与包导出的同步性。这些测试就是变更必须同步更新契约的自动化落地。写给插件开发者边界合规速查清单结合 CLAUDE.md、docs/plugins/manifest.md 与上述源码证据开发或审查一个 OpenClaw 插件时可对照以下清单导入面生产代码只从openclaw/plugin-sdk/*子路径须在 scripts/lib/plugin-sdk-entrypoints.json 清单内与自有api.ts/runtime-api.ts导入绝不出现src/**、src/channels/**、src/plugin-sdk-internal/**或其他扩展的src/**。相对路径所有相对导入都停留在扩展包根目录内不向上逃逸。元数据插件根目录必须有openclaw.plugin.jsonidconfigSchema必填package.json 的openclaw.extensions声明入口模块且清单在不执行插件代码的前提下即可完成发现与配置校验。私有边界src/**、onboard.ts等默认私有确需对外时通过api.ts显式提升必要时增加src/plugin-sdk/id.tsfacade。演进方式新能力以新增类型化子路径或增量导出方式提供保持向后兼容并同步更新文档、子路径清单、package exports 与契约测试。运行时能力凡涉及核心行为回复分发、路由、配对、媒体、群组策略等一律经由OpenClawPluginApi.runtime注入而非导入核心模块。遵守这条边界你的插件就能与 extensions/ 下的内置插件处于完全对等的地位享受同样的类型安全、同样的测试守卫也能在核心升级时保持稳定——这正是 OpenClaw 插件体系一个稳定 API、所有连接器皆插件架构目标的落地保证。赞分享人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载相关推荐OpenClaw 插件边界Extensions Boundary权威指南Plugin SDK 契约、边界规则与扩展机制OpenClaw 插件边界Extensions Boundary权威指南Plugin SDK 契约、边界规则与扩展机制 本文围绕仓库根目录 AGENTS.人工智能大模型LLM 网关AI Agent即时通讯OpenClaw 扩展边界规范extensions 目录下捆绑插件的公共契约与导入边界OpenClaw 扩展边界规范extensions 目录下捆绑插件的公共契约与导入边界 本文基于 OpenClaw 仓库中 extensions/CLAUDEAI 应用AI Agent交互助手后端即时通讯网关OpenClaw 扩展边界规范内置插件如何通过 Plugin SDK 与清单契约与核心解耦OpenClaw 扩展边界规范内置插件如何通过 Plugin SDK 与清单契约与核心解耦 本文基于 OpenClaw 仓库中的扩展边界规范文档 extensAI 应用AI Agent交互助手后端即时通讯网关上一篇读懂 CLIP 模型卡tiny-universe 中 TinyIMGRAG 的图文检索基石下一篇openEuler secScanner架构解析深入理解安全扫描工具的实现原理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考