夜雨聆风本系列所有内容均基于OpenClaw官方文档，确保准确性与权威性。
官方地址：https://docs.openclaw.ai
01
—
OpenClaw是什么？
OpenClaw 是一个自托管的 AI Agent 网关平台。它的核心职责是：将各种消息平台（WhatsApp、Telegram、Discord、iMessage、Slack 等）与 AI 编码助手连接起来，构成一个完整的 Agent 交互系统。
用一句话概括：
OpenClaw 是 AI Agent 的「神经中枢」——一端对接用户，一端对接 AI 能力，中间通过插件化的开放系统完成一切编排。
这个定位决定了它的技术架构必须是可扩展的——不同的用户需要接入不同的消息平台，不同的场景需要不同的 AI 模型，不同的工作流需要不同的工具。如果这些能力都硬编码在核心系统中，系统将不可维护。
这就是 OpenClaw 选择插件化开放架构的原因。
—
开放系统的设计原则
OpenClaw 的插件 SDK 定义了插件与核心系统之间的类型化契约（typed contract）。这组契约遵循以下几个关键设计原则：
1. 非侵入式扩展
插件是独立的功能单元。开发者无需修改 OpenClaw 核心代码，就能扩展系统的任何能力。插件可以打包发布到 npm 或 ClawHub，用户通过一条命令安装即可使用。
2. TypeScript-first 的类型安全
SDK 全部使用 TypeScript 编写，插件开发者获得完整的类型提示和编译期检查。这不是可选的——从参数定义到返回值格式，每一个接口都有严格的类型约束。
3. 模块化子路径导入
SDK 包含 100+ 个导出，但禁止从根路径导入。每个导出都归属于一个特定的子路径：
// 正确：从特定子路径导入import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";// 错误：不要从根路径导入import { definePluginEntry } from "openclaw/plugin-sdk";
这样做的目的是：每个子路径是小型、自包含的模块，保持启动速度，防止循环依赖。
4. 插件是功能的所有权边界
这是 OpenClaw 架构中一条重要的组织原则。一个公司的所有 OpenClaw 相关功能应该归入同一个插件；一个功能引入的完整能力表面应该由同一个插件拥有。通道插件消费共享的 Provider 能力，而不是重新实现。
03
—
四层架构
第 1 层：清单与发现层
系统按优先级从高到低查找插件：
配置路径：
plugins.load.paths中显式指定的路径工作区扩展：
<workspace>/.openclaw/extensions/下的.ts文件全局扩展：
~/.openclaw/extensions/下的.ts文件捆绑插件：随 OpenClaw 一起提供的内置插件
每个插件必须包含一个 openclaw.plugin.json 清单文件，声明插件 ID、配置 Schema、提供的能力等元数据。
第 2 层：启用与验证层
发现插件后，系统决定哪些插件可以运行：
plugins.enabled: false会禁用所有插件plugins.deny列表始终优先于允许列表工作区来源的插件默认禁用，需要显式启用
独占插槽（如 Context Engine）可以强制启用特定插件
第 3 层：运行时加载层
通过 jiti（运行时 TypeScript 加载器）加载插件入口模块，调用 register(api) 回调，插件在回调中向中央注册表注册其能力。
第 4 层：表面消费层
Agent 工具、消息通道、管理面板等系统组件从中央注册表读取已注册的能力，供用户和 AI 使用。
04
—
能力模型
这是理解 OpenClaw 开放系统的核心。一个插件可以通过 register(api) 回调中的 api 对象注册多种能力。这些能力分为三大类：
能力注册
工具与命令
基础设施
独占插槽
部分能力采用独占插槽机制——同一时间只有一个插件可以激活：
独占插槽通过配置文件指定：
{"plugins": {"slots": {"contextEngine": "legacy","memory": "memory-core"}}}
05
—
兼容生态：Plugin Bundles
除了原生 OpenClaw 插件，系统还支持兼容性捆绑包——来自 Claude、Codex、Cursor 生态的插件格式。系统会自动检测这些格式，将其中支持的功能映射到 OpenClaw 的原生能力：
06
—
系列导航
第 0 篇（本文） 开放系统全景第 1 篇 Plugin SDK 入门第 2 篇 工具注册第 3 篇 Provider 插件第 4 篇 Channel 插件第 5 篇 事件钩子第 6 篇 上下文引擎第 7 篇 记忆系统第 8 篇 运行时 API第 9 篇 HTTP 路由与 CLI 扩展第 10 篇 技能 Skills第 11 篇 高级实战
07
—
建议阅读路径
入门线（从零开始）：第 0 → 1 → 2 → 5 → 10 → 11
进阶线（系统掌握）：第 0 → 1 → 2 → 3 → 4 → 5 → 8 → 9 → 11
专题线（按兴趣选择）：
AI 服务集成：第 3 → 7
平台对接：第 4 → 9
Agent 增强：第 5 → 6 → 7 → 10
