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 插件系统采用 “声明式发现 + 运行时注册” 的两阶段模型：

image

这种分离确保了：

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

三、插件加载与优先级

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

1. 配置路径：plugins.load.paths（显式指定的文件或目录）
2. 工作区扩展：<workspace>/.openclaw/extensions/
3. 全局扩展：~/.openclaw/extensions/
4. 内置插件：随 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" }
      }
    }
  }
}

字段说明

image

🔁 注意：修改插件配置后必须重启 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 } }
}

九、故障排查

image

十、总结

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 按以下顺序扫描插件（高优先级在前）：

1. 配置路径：plugins.load.paths（显式指定的文件或目录）
2. 工作区扩展：<workspace>/.openclaw/extensions/
3. 全局扩展：~/.openclaw/extensions/
4. 内置插件：随 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");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 插件系统为开发者提供了强大而安全的扩展机制。通过遵循本文指南，您可以：

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

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