OpenClaw 插件（Plugins）系统开发与配置指南

适用版本：OpenClaw v2026.3.8+
核心理念：插件是扩展 OpenClaw 能力的安全、模块化方式，用于添加命令、工具、渠道、模型认证、HTTP 接口等。

一、快速入门

1. 什么是插件？

插件是一个小型代码模块，用于在不修改 OpenClaw 核心代码的前提下，动态扩展其功能。典型用途包括：

添加新的聊天渠道（如 Microsoft Teams）
集成自定义 AI 模型认证流程
提供语音通话、文件处理等新工具
暴露 Webhook 或 RPC 接口

2. 基础操作

# 查看已加载插件
openclaw plugins list

# 安装官方插件（例如语音通话）
openclaw plugins install @openclaw/voice-call

# 启用插件（部分插件默认启用）
openclaw plugins enable voice-call

# 重启 Gateway 使配置生效

⚠️ 安装规则：

仅支持 npm 包名 + 精确版本或 dist-tag（如 @beta）

不支持 Git URL、本地路径（除 openclaw plugins install ./dir 外）、语义化版本范围（如 ^1.0.0）

@latest 或无版本号默认使用稳定版；若解析到预发布版，需显式指定 @beta 等标签

二、架构设计

OpenClaw 插件系统采用 “声明式发现 + 运行时注册” 的两阶段模型：

这种分离确保了：

配置错误可在启动前被检测
控制台可安全展示插件元数据
插件行为与核心解耦，便于维护

三、插件加载与优先级

OpenClaw 按以下顺序扫描插件（高优先级在前）：

配置路径：plugins.load.paths（显式指定的文件或目录）
工作区扩展：<workspace>/.openclaw/extensions/
全局扩展：~/.openclaw/extensions/
内置插件：随 OpenClaw 发布的 extensions/ 目录

📌 覆盖规则：同 ID 插件，高优先级路径覆盖低优先级。
例如：工作区中的 voice-call 会覆盖内置版本，便于本地开发调试。

安全检查

非内置插件需通过以下安全审查，否则被拒绝加载：

插件入口不得通过符号链接逃逸出插件根目录
插件目录不得为全局可写（world-writable）
POSIX 系统下，目录所有者必须是当前用户或 root

四、核心配置项（`openclaw.json`）

{
  "plugins": {
    "enabled": true,
    "allow": ["voice-call"],
    "deny": ["untrusted-plugin"],
    "load": {
      "paths": ["~/Projects/my-plugin"]
    },
    "slots": {
      "memory": "memory-lancedb",
      "contextEngine": "lossless-claw"
    },
    "entries": {
      "voice-call": {
        "enabled": true,
        "config": { "provider": "twilio" }
      }
    }
  }
}

字段说明

🔁 注意：修改插件配置后必须重启 Gateway 才能生效。

五、插件能力注册

插件通过 register(api) 函数向核心注册能力。常见注册项包括：

1. Agent 工具（Tools）

api.registerTool({
  name: "voice_call",
  description: "Initiate a voice call",
  handler: async (args) => { /* ... */ }
});

2. HTTP 路由

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin", // 或 "gateway"
  handler: async (_req, res) => {
    res.end("OK");
    return true;
  }
});

3. CLI 命令

api.registerCli(({ program }) => {
  program.command("mystatus").action(() => console.log("OK"));
}, { commands: ["mystatus"] });

4. 自动回复命令（无需 LLM）

api.registerCommand({
  name: "mystatus",
  handler: () => ({ text: "Plugin is running!" })
});

5. 渠道（Channels）

用于实现 WhatsApp、Teams 等新消息平台集成（详见下文）。

6. 模型提供者（Providers）

实现 OAuth、API Key 等认证流程，支持 openclaw onboard 集成。

7. 上下文引擎（Context Engine）

替换默认的对话上下文组装逻辑，适用于高级会话管理。

六、关键概念详解

1. 独占插槽（Slots）

某些功能类别仅允许一个插件激活：

memory：长期记忆实现（如 memory-core、memory-lancedb）
contextEngine：上下文编排引擎

配置示例：

{
  "plugins": {
    "slots": {
      "memory": "memory-lancedb",
      "contextEngine": "none"  // 禁用
    }
  }
}

2. 渠道插件（Channel Plugins）

用于添加新的消息平台（如 Microsoft Teams、Zalo）。

配置位于 channels.<id>，而非 plugins.entries
必须实现 resolveAccount、sendText 等基础适配器
支持多账号、状态检查、安全策略等高级特性

💡 提示：Microsoft Teams 自 2026.1.15 起仅通过插件提供，需手动安装 @openclaw/msteams。

3. 模型提供者插件（Provider Plugins）

用于集成自定义 LLM 服务，支持：

交互式 OAuth / API Key 录入
非交互式（CI/CD）配置
模型自动发现（如本地 Ollama 服务）
模型选择后的后置操作（如下载模型）

4. 技能（Skills）与插件

插件可附带技能（放在 skills/ 目录），通过 plugins.entries.<id>.enabled 控制是否加载。

七、开发最佳实践

1. 安全原则

插件 = 受信任代码：运行于 Gateway 同一进程，可访问全部内存与网络
生产环境务必使用 allow 白名单
避免安装来源不明的插件

2. 开发调试

使用 openclaw plugins install -l ./my-plugin 软链接开发
工作区插件默认禁用，需显式启用，防止意外加载

3. 分发规范

官方插件命名：@openclaw/<name>
package.json 必须包含 openclaw.extensions 字段
使用 openclaw/plugin-sdk 子路径导入（如 openclaw/plugin-sdk/telegram）

4. 测试

内置插件：使用 Vitest 编写单元测试
独立插件：自行配置 CI，验证 openclaw.extensions 指向正确入口

八、高级功能

1. 生命周期钩子

// 在 prompt 构建前注入上下文
api.on("before_prompt_build", (event) => ({
  prependSystemContext: "Follow company style guide."
}));

2. 运行时辅助

TTS：api.runtime.tts.textToSpeechTelephony()
STT：api.runtime.stt.transcribeAudioFile()

3. 控制台 UI 优化

在 openclaw.plugin.json 中提供 uiHints，提升配置表单体验：

{
  "configSchema": { "properties": { "apiKey": { "type": "string" } } },
  "uiHints": { "apiKey": { "label": "API Key", "sensitive": true } }
}

九、故障排查

十、总结

OpenClaw 插件系统为开发者提供了强大而安全的扩展机制。通过遵循本文指南，您可以：

安全地集成第三方功能
构建企业级定制能力
参与社区插件生态建设

记住：插件虽强，安全第一。始终将插件视为受信任代码，并通过 allow 列表、私有仓库、代码审计等方式保障生产环境安全。

适用版本：OpenClaw v2026.3.8+ 核心理念：插件是扩展 OpenClaw 能力的安全、模块化方式，用于添加命令、工具、渠道、模型认证、HTTP 接口等。

一、快速入门

1. 什么是插件？

插件是一个小型代码模块，用于在不修改 OpenClaw 核心代码的前提下，动态扩展其功能。典型用途包括：

添加新的聊天渠道（如 Microsoft Teams）
集成自定义 AI 模型认证流程
提供语音通话、文件处理等新工具
暴露 Webhook 或 RPC 接口

2. 基础操作

# 查看已加载插件 openclaw plugins list # 安装官方插件（例如语音通话） openclaw plugins install @openclaw/voice-call # 启用插件（部分插件默认启用） openclaw plugins enable voice-call # 重启 Gateway 使配置生效

⚠️ 安装规则：

仅支持 npm 包名 + 精确版本或 dist-tag（如 @beta）
不支持 Git URL、本地路径（除 openclaw plugins install ./dir 外）、语义化版本范围（如 ^1.0.0）
@latest 或无版本号默认使用稳定版；若解析到预发布版，需显式指定 @beta 等标签

二、架构设计

OpenClaw 插件系统采用 “声明式发现 + 运行时注册” 的两阶段模型：

阶段	目标	是否执行插件代码
发现与验证	读取 openclaw.plugin.json，校验配置合法性，生成 UI 提示	❌ 否
运行时加载	调用 register(api)，注册工具、渠道、HTTP 路由等行为	✅ 是

这种分离确保了：

配置错误可在启动前被检测
控制台可安全展示插件元数据
插件行为与核心解耦，便于维护

三、插件加载与优先级

OpenClaw 按以下顺序扫描插件（高优先级在前）：

配置路径：plugins.load.paths（显式指定的文件或目录）
工作区扩展：<workspace>/.openclaw/extensions/
全局扩展：~/.openclaw/extensions/
内置插件：随 OpenClaw 发布的 extensions/ 目录

📌 覆盖规则：同 ID 插件，高优先级路径覆盖低优先级。例如：工作区中的 voice-call 会覆盖内置版本，便于本地开发调试。

安全检查

非内置插件需通过以下安全审查，否则被拒绝加载：

插件入口不得通过符号链接逃逸出插件根目录
插件目录不得为全局可写（world-writable）
POSIX 系统下，目录所有者必须是当前用户或 root

四、核心配置项（openclaw.json）

{"plugins":{"enabled":true,"allow":["voice-call"],"deny":["untrusted-plugin"],"load":{"paths":["~/Projects/my-plugin"]},"slots":{"memory":"memory-lancedb","contextEngine":"lossless-claw"},"entries":{"voice-call":{"enabled":true,"config":{"provider":"twilio"}}}}}

字段说明

字段	作用
enabled	全局开关（默认 true）
allow / deny	ID 白名单/黑名单（deny 优先级更高）
load.paths	额外插件加载路径
slots	独占插槽选择（如内存引擎、上下文引擎）
entries.<id>	单个插件的启用状态与专属配置

🔁 注意：修改插件配置后必须重启 Gateway 才能生效。

五、插件能力注册

插件通过 register(api) 函数向核心注册能力。常见注册项包括：

1. Agent 工具（Tools）

api.registerTool({name:"voice_call",description:"Initiate a voice call",handler:async(args)=>{/* ... */}});

2. HTTP 路由

api.registerHttpRoute({path:"/acme/webhook",auth:"plugin",// 或 "gateway"handler:async(_req, res)=>{ res.end("OK");returntrue;}});

3. CLI 命令

api.registerCli(({ program })=>{ program.command("mystatus").action(()=> console.log("OK"));},{commands:["mystatus"]});

4. 自动回复命令（无需 LLM）

api.registerCommand({name:"mystatus",handler:()=>({text:"Plugin is running!"})});

5. 渠道（Channels）

用于实现 WhatsApp、Teams 等新消息平台集成（详见下文）。

6. 模型提供者（Providers）

实现 OAuth、API Key 等认证流程，支持 openclaw onboard 集成。

7. 上下文引擎（Context Engine）

替换默认的对话上下文组装逻辑，适用于高级会话管理。

六、关键概念详解

1. 独占插槽（Slots）

某些功能类别仅允许一个插件激活：

memory：长期记忆实现（如 memory-core、memory-lancedb）
contextEngine：上下文编排引擎

配置示例：

{"plugins":{"slots":{"memory":"memory-lancedb","contextEngine":"none"// 禁用}}}

2. 渠道插件（Channel Plugins）

用于添加新的消息平台（如 Microsoft Teams、Zalo）。

配置位于 channels.<id>，而非 plugins.entries
必须实现 resolveAccount、sendText 等基础适配器
支持多账号、状态检查、安全策略等高级特性

💡 提示：Microsoft Teams 自 2026.1.15 起仅通过插件提供，需手动安装 @openclaw/msteams。

3. 模型提供者插件（Provider Plugins）

用于集成自定义 LLM 服务，支持：

交互式 OAuth / API Key 录入
非交互式（CI/CD）配置
模型自动发现（如本地 Ollama 服务）
模型选择后的后置操作（如下载模型）

4. 技能（Skills）与插件

插件可附带技能（放在 skills/ 目录），通过 plugins.entries.<id>.enabled 控制是否加载。

七、开发最佳实践

1. 安全原则

插件 = 受信任代码：运行于 Gateway 同一进程，可访问全部内存与网络
生产环境务必使用 allow 白名单
避免安装来源不明的插件

2. 开发调试

使用 openclaw plugins install -l ./my-plugin 软链接开发
工作区插件默认禁用，需显式启用，防止意外加载

3. 分发规范

官方插件命名：@openclaw/<name>
package.json 必须包含 openclaw.extensions 字段
使用 openclaw/plugin-sdk 子路径导入（如 openclaw/plugin-sdk/telegram）

4. 测试

内置插件：使用 Vitest 编写单元测试
独立插件：自行配置 CI，验证 openclaw.extensions 指向正确入口

八、高级功能

1. 生命周期钩子

// 在 prompt 构建前注入上下文 api.on("before_prompt_build",(event)=>({prependSystemContext:"Follow company style guide."}));

2. 运行时辅助

TTS：api.runtime.tts.textToSpeechTelephony()
STT：api.runtime.stt.transcribeAudioFile()

3. 控制台 UI 优化

在 openclaw.plugin.json 中提供 uiHints，提升配置表单体验：

{"configSchema":{"properties":{"apiKey":{"type":"string"}}},"uiHints":{"apiKey":{"label":"API Key","sensitive":true}}}

九、故障排查

问题	诊断方法
插件未加载	检查 openclaw plugins list；确认路径权限与安全策略
配置无效	查看启动日志；确保 configSchema 匹配
命令冲突	插件命令不能覆盖 help、reset 等保留字
HTTP 403	确认路由 auth 策略（"gateway" 需令牌，"plugin" 自行验证）

十、总结

OpenClaw 插件系统为开发者提供了强大而安全的扩展机制。通过遵循本文指南，您可以：

安全地集成第三方功能
构建企业级定制能力
参与社区插件生态建设

记住：插件虽强，安全第一。始终将插件视为受信任代码，并通过 allow 列表、私有仓库、代码审计等方式保障生产环境安全。

posted @ 2026-03-15 16:21 JackYang 阅读(30) 评论(0) 收藏举报

刷新页面返回顶部