插件系统
OpenClaw 插件是 TypeScript 模块，用于扩展核心功能，包括命令、工具和 RPC 方法。插件在 Gateway 进程内运行，通过 jiti 加载。
命令
管理 Gateway 插件/扩展（进程内加载）：
openclaw plugins list— 列出所有已安装的插件openclaw plugins info <id>— 显示插件详细信息openclaw plugins install <npm-spec>— 安装插件（仅支持 npm 包）openclaw plugins enable <id>— 启用插件openclaw plugins disable <id>— 禁用插件openclaw plugins uninstall <id>— 卸载插件openclaw plugins doctor— 诊断插件问题openclaw plugins update— 更新已安装的插件
说明：
- 捆绑插件随 OpenClaw 发布，但默认处于禁用状态。
- 所有插件必须附带
openclaw.plugin.json文件及内联 JSON Schema。 - npm 规范仅限注册表；Git/URL/文件规范会被拒绝。
- 使用
--link可避免复制本地目录。 uninstall会移除插件记录。对于活跃的内存插件，内存槽位会重置。- 更新仅适用于从 npm 安装的插件。
配置
插件在 plugins.entries 中配置，并通过 openclaw.plugin.json 中定义的 JSON Schema 进行验证。独占类别（槽位）如 memory 使用 plugins.slots。
json5
{
plugins: {
entries: {
"my-plugin": {
enabled: true,
config: {
// 插件特定配置
},
},
},
slots: {
memory: "my-memory-plugin",
},
},
}说明：
- 配置更改需要 Gateway 重启。
- 插件配置在读写时通过 JSON Schema 验证，而非运行时。
- 如果插件配置存在但插件被禁用，配置会保留并在 Doctor + 日志中显示警告。
插件清单
每个插件必须在插件根目录下附带一个 openclaw.plugin.json 文件。OpenClaw 使用此清单在不执行插件代码的情况下验证配置。缺失或无效的清单会被视为插件错误并阻止配置验证。
必需字段
json
{
"id": "voice-call",
"configSchema": {
"type": "object",
"additionalProperties": false,
"properties": {}
}
}必需的键：
id（string）：规范插件 ID。configSchema（object）：插件配置的 JSON Schema（内联）。
可选的键：
kind（string）：插件类型（例如："memory"）。channels（array）：此插件注册的频道 ID（例如：["matrix"]）。providers（array）：此插件注册的提供商 ID。skills（array）：要加载的技能目录（相对于插件根目录）。name（string）：插件的显示名称。description（string）：插件简短摘要。uiHints（object）：用于 UI 渲染的配置字段标签/占位符/敏感标志。version（string）：插件版本（信息性）。
JSON Schema 要求
- 每个插件都必须附带 JSON Schema，即使它不接受任何配置。
- 空 Schema 是可接受的（例如
{ "type": "object", "additionalProperties": false }）。 - Schema 在配置读写时验证，而非运行时。
验证行为
- 未知的
channels.**键是错误，除非频道 ID 由插件清单声明。 plugins.entries.*、plugins.allow、plugins.deny和plugins.slots.**必须引用可发现的插件 ID。未知 ID 是错误。- 如果插件已安装但清单或 Schema 损坏或缺失，验证失败且 Doctor 会报告插件错误。
- 清单对所有插件都是必需的，包括本地文件系统加载。
开发
项目结构
插件必须包含 openclaw.plugin.json。
API
插件导出一个函数或带有 register(api) 方法的对象。
能力
插件可以注册：
- HTTP 路由
- Gateway RPC 方法
- CLI 命令
- 代理工具（JSON Schema 函数，暴露给 LLM）
- 后台服务
代理工具
OpenClaw 插件可以注册代理工具（JSON Schema 函数），暴露给 LLM。工具可以是必需的或可选的。
生命周期钩子
支持的生命周期钩子包括 before_prompt_build 和 before_model_resolve 等。
频道
插件可以定义新的消息频道，包含元数据和出站适配器。
安全
插件是受信任的代码。请仅安装你信任的插件。
- 安装使用
npm install --ignore-scripts。 - 路径遍历和全局可写目录会被阻止。
- 优先使用固定版本。
- 将插件安装视为运行代码。
- 如果你的插件依赖原生模块，请记录构建步骤和任何包管理器允许列表要求（例如 pnpm
allow-build-scripts+pnpm rebuild）。
槽位系统
独占类别使用 plugins.slots。这确保同一时间只有一个插件占据特定的功能槽位（如内存）。
json5
{
plugins: {
slots: {
memory: "my-memory-plugin",
},
},
}