OpenClaw 扩展点全景
OpenClaw 采用 Plugin-First 架构——核心只做调度，所有能力都通过插件注入。共有 13 类扩展点。
扩展点总览
┌─────────────────────────────────────────────────────────┐
│ 用户可扩展的层级 │
├──────────┬──────────┬──────────┬──────────┬─────────────┤
│ Channel │ Provider │ Skill │ Tool │ Hook │
│ 消息渠道 │ 模型提供 │ 技能教学 │ 函数调用 │ 事件钩子 │
├──────────┴──────────┴──────────┴──────────┴─────────────┤
│ Plugin SDK 层 │
│ definePluginEntry() → api.registerXxx() │
├──────────┬──────────┬──────────┬──────────┬─────────────┤
│ Webhook │ Cron │ Service │ Node │ Context │
│ HTTP入口 │ 定时任务 │ 后台服务 │ 设备节点 │ Engine │
├──────────┴──────────┴──────────┴──────────┴─────────────┤
│ CLI Command │ Config Schema │ 兼容层(Codex/Cursor/Claude)│
└─────────────────────────────────────────────────────────┘
1. Plugin — 一等公民扩展框架
所有扩展都通过 Plugin 注册。 一个 Plugin 可同时注册多种能力。
文件结构
my-plugin/
├── package.json # name, version, "openclaw" 字段
├── openclaw.plugin.json # 清单：id, name, description, configSchema, skills
└── index.ts # 入口：definePluginEntry()
入口模板
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
export default definePluginEntry({
id: "my-plugin",
name: "My Plugin",
register(api) {
api.registerProvider(...); // LLM 提供商
api.registerChannel(...); // 消息渠道
api.registerTool(...); // Agent 工具
api.registerHook(...); // 事件钩子
api.registerHttpRoute(...); // Webhook 路由
api.registerService(...); // 后台服务
api.registerCommand(...); // CLI 命令
api.registerSpeechProvider(...);
api.registerMediaUnderstandingProvider(...);
api.registerImageGenerationProvider(...);
api.registerWebSearchProvider(...);
api.registerContextEngine(...);
},
});
发现与加载顺序（高→低）
| 优先级 | 来源 | 路径 |
|---|
| 1 | 配置指定 | plugins.load.paths |
| 2 | Workspace | <workspace>/.openclaw/extensions/ |
| 3 | 全局 | ~/.openclaw/extensions/ |
| 4 | 内置 | 随 OpenClaw 发行 |
安装方式
openclaw plugins install @myorg/my-plugin # npm 包
openclaw plugins install ./my-plugin # 本地目录
openclaw plugins install ./my-plugin.tgz # 压缩包
openclaw plugins install -l ./my-plugin # 开发模式（软链接）
关键源码
| 文件 | 职责 |
|---|
src/plugin-sdk/plugin-entry.ts | 入口定义 |
src/plugins/types.ts | OpenClawPluginApi 类型 |
src/plugins/loader.ts | 发现与加载 |
docs/plugins/building-plugins.md | 完整指南 |
docs/plugins/manifest.md | 清单 Schema |
2. Channel — 接入消息平台
让 Agent 通过新的消息平台与用户交互。
注册方式
api.registerChannel({
id: "my-channel",
label: "My Channel",
plugin: ChannelPlugin, // 实现收发消息
setRuntime: (runtime) => { ... }
});
快捷构建器（聊天类渠道）
import { createChatChannelPlugin } from "openclaw/plugin-sdk/core";
// 自动处理 DM 安全、配对、线程、打字状态
SDK 子路径
| 路径 | 功能 |
|---|
plugin-sdk/core | Channel 入口构建器 |
plugin-sdk/channel-setup | 配置向导 |
plugin-sdk/channel-pairing | DM 配对 |
plugin-sdk/channel-reply-pipeline | 回复管道 |
plugin-sdk/channel-policy | 安全策略 |
已有渠道参考
extensions/discord/ · extensions/slack/ · extensions/telegram/ · extensions/matrix/ · extensions/imessage/ · extensions/whatsapp/
3. Skill — 教 Agent 新技能
Skill 是 Markdown 文件，教 Agent 何时、如何使用某个工具。无需写代码。
文件格式
---
name: my_skill
description: 一句话描述
metadata:
{
"openclaw": {
"requires": {
"bins": ["tool-name"], # 依赖的二进制
"env": ["API_KEY"], # 依赖的环境变量
"config": ["x.enabled"] # 依赖的配置项
}
}
}
user-invocable: true
command-dispatch: tool
command-tool: my_tool_name
---
这里写给 Agent 的指令，告诉它何时以及如何使用这个工具。
存放位置（高→低）
| 优先级 | 路径 |
|---|
| 1 | <workspace>/skills/ |
| 2 | ~/.openclaw/skills/ |
| 3 | Plugin 的 openclaw.plugin.json 中声明 |
| 4 | 内置 skills/ |
门控机制
Skill 只在依赖满足时才会加载（二进制存在、环境变量设置、配置启用）。
关键源码
src/hooks/frontmatter.ts（解析）· src/hooks/loader.ts（发现与加载）
注册方式
import { Type } from "@sinclair/typebox";
api.registerTool({
name: "my_tool",
description: "工具描述",
parameters: Type.Object({
input: Type.String(),
count: Type.Optional(Type.Number())
}),
async execute(id, params) {
return { content: [{ type: "text", text: "结果" }] };
}
}, { optional: true }); // optional 需用户在 tools.allow 中启用
关键源码
src/agents/tools/ — 内置工具实现
5. Provider — 接入 LLM / Embedding / TTS
| 注册方法 | 能力 |
|---|
registerProvider() | 文本推理（LLM） |
registerSpeechProvider() | TTS / STT |
registerMediaUnderstandingProvider() | 图片/音频/视频分析 |
registerImageGenerationProvider() | 图片生成 |
registerWebSearchProvider() | 网页搜索 |
Provider 生命周期钩子
prepareAuth — 准备凭证prepareExtraParams — 附加模型参数wrapStream — 自定义流处理normalizeModel — 模型 ID 标准化
认证方式
api_key · oauth(PKCE) · device_code · token · custom
SDK 子路径
plugin-sdk/provider-auth · plugin-sdk/provider-catalog · plugin-sdk/provider-stream · plugin-sdk/speech · plugin-sdk/image-generation
已有 Provider 参考
extensions/openai/ · extensions/anthropic/ · extensions/google/ · extensions/elevenlabs/ · extensions/mistral/
6. Hook — 事件钩子
在 Agent 生命周期关键节点插入自定义逻辑。
可监听事件
| 事件 | 时机 |
|---|
before_model_resolve | 模型选择前（可覆盖模型/Provider） |
before_prompt_build | 提示词生成前 |
session:start | 会话启动 |
command:new | /new 命令执行 |
文件格式
---
name: my_hook
metadata:
{ "openclaw": { "events": ["before_model_resolve"] } }
---
# Hook 说明
配套 handler.ts 实现逻辑。
关键源码
src/hooks/types.ts · src/hooks/loader.ts · src/hooks/plugin-hooks.ts
7. Webhook — HTTP 入口
让外部服务通过 HTTP 调用 Agent。
api.registerHttpRoute({
method: "POST",
path: "/webhooks/my-service",
handler: async (req, res) => {
res.writeHead(200);
res.end("OK");
}
});
安全辅助
| SDK 路径 | 功能 |
|---|
plugin-sdk/webhook-ingress | 主 API |
plugin-sdk/webhook-request-guards | 请求校验、限流 |
plugin-sdk/webhook-memory-guards | 内存安全 |
8. Cron — 定时任务
{
"cron": {
"jobs": [{
"name": "daily_digest",
"schedule": "0 9 * * *",
"target": { "channel": "discord", "groupId": "xxx" },
"prompt": "总结今日新闻"
}]
}
}
关键源码：src/cron/ · src/cron/isolated-agent/
9. Service — 后台服务
注册随 Gateway 启停的长驻进程。
api.registerService({
name: "my-service",
start: async () => { /* 初始化 */ },
stop: async () => { /* 清理 */ }
});
10. Node — 设备节点
将 iOS/Android/macOS 设备配对为”节点”，提供硬件能力。
| 命令空间 | 能力 |
|---|
canvas.* | WebView 操作、截图 |
camera.* | 拍照、录像 |
screen.record | 录屏 |
device.* | 设备状态、通知 |
system.run | 在节点设备上执行命令 |
关键源码：src/node-host/ · src/pairing/
11. Context Engine — 自定义记忆引擎
替换默认的记忆检索实现。
api.registerContextEngine({ id: "my-memory", label: "..." });
配置插槽：
{ "plugins": { "slots": { "contextEngine": "memory-lancedb" } } }
已有实现：memory-core（默认 SQLite）· extensions/memory-lancedb/（向量搜索）
12. CLI Command — 自定义命令
api.registerCommand({
name: "my-cmd",
description: "描述",
action: async (opts) => { ... }
});
13. 兼容层
OpenClaw 自动检测并加载其他工具的插件格式：
.codex-plugin/plugin.json.claude-plugin/plugin.json.cursor-plugin/plugin.json
插件配置
{
"plugins": {
"enabled": true,
"allow": ["voice-call"],
"deny": [],
"load": { "paths": ["~/my-plugin"] },
"entries": {
"my-plugin": {
"enabled": true,
"config": { "apiKey": "..." }
}
},
"slots": {
"memory": "memory-lancedb",
"contextEngine": "legacy"
}
}
}
SDK 导入规则
始终从子路径导入，不要导入根路径：
// ✅ 正确
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createChatChannelPlugin } from "openclaw/plugin-sdk/core";
// ❌ 错误
import { definePluginEntry } from "openclaw/plugin-sdk";