本页介绍 OpenClaw 插件系统的完整用法。插件为 OpenClaw 扩展新能力：频道、模型 Provider、工具、技能、语音、视频生成等。安装方式：openclaw plugins install <package> 从 ClawHub 或 npm 安装，openclaw plugins install ./path 从本地安装，openclaw plugins install <pkg> --marketplace <source> 从 marketplace 安装。安装后重启 Gateway 生效。

插件

插件为 OpenClaw 扩展了新能力：频道、模型 Provider、工具、技能（skills）、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取和网页搜索等。部分插件是核心插件（随 OpenClaw 内置），其他是外部插件（由社区发布到 npm）。

快速开始

第一步：查看已加载的插件

openclaw plugins list

第二步：安装插件

# 从 npm/ClawHub 安装
openclaw plugins install @openclaw/voice-call

# 从本地目录或压缩包安装
openclaw plugins install ./my-plugin
openclaw plugins install ./my-plugin.tgz

第三步：重启 Gateway

openclaw gateway restart

然后在配置文件的 plugins.entries.<id>.config 下进行配置。

如果你更喜欢在聊天中控制，启用 commands.plugins: true 并使用：

/plugin install clawhub:@openclaw/voice-call
/plugin show voice-call
/plugin enable voice-call

安装路径使用的解析器与 CLI 相同：本地路径/压缩包、显式 clawhub:<pkg>，或裸包名（先查 ClawHub，再回退到 npm）。

如果配置无效，安装通常会安全失败并指向 openclaw doctor --fix。唯一的恢复例外是针对选择加入 openclaw.install.allowInvalidConfigRecovery 的插件的窄路径捆绑插件重装。

插件类型

OpenClaw 识别两种插件格式：

格式	工作方式	示例
Native（原生）	openclaw.plugin.json + 运行时模块；在进程内执行	官方插件、社区 npm 包
Bundle（包）	Codex/Claude/Cursor 兼容布局；映射到 OpenClaw 功能	.codex-plugin/、.claude-plugin/、.cursor-plugin/

两种类型都会显示在 openclaw plugins list 中。Bundle 详情参见 Plugin Bundles。

如果你想编写原生插件，从 Building Plugins 和 Plugin SDK Overview 开始。

官方插件

可安装（npm）

插件	包名	文档
Matrix	@openclaw/matrix	Matrix
Microsoft Teams	@openclaw/msteams	Microsoft Teams
Nostr	@openclaw/nostr	Nostr
Voice Call	@openclaw/voice-call	Voice Call
Zalo	@openclaw/zalo	Zalo
Zalo Personal	@openclaw/zalouser	Zalo Personal

核心插件（随 OpenClaw 内置）

模型 Provider（默认启用）

anthropic、byteplus、cloudflare-ai-gateway、github-copilot、google、 huggingface、kilocode、kimi-coding、minimax、mistral、qwen、 moonshot、nvidia、openai、opencode、opencode-go、openrouter、 qianfan、synthetic、together、venice、 vercel-ai-gateway、volcengine、xiaomi、zai

记忆插件

• memory-core — 内置记忆搜索（通过 plugins.slots.memory 默认启用）
• memory-lancedb — 按需安装的长期记忆，支持自动回忆/捕获（设置 plugins.slots.memory = "memory-lancedb"）

语音 Provider（默认启用）

elevenlabs、microsoft

其他

• browser — 内置浏览器插件，提供浏览器工具、openclaw browser CLI、browser.request Gateway 方法、浏览器运行时和默认浏览器控制服务（默认启用；替换前请先禁用）
• copilot-proxy — VS Code Copilot Proxy 桥接（默认禁用）

第三方插件请参见 Community Plugins。

配置

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-extension"] },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}

字段	说明
enabled	总开关（默认：true）
allow	插件白名单（可选）
deny	插件黑名单（可选；黑名单优先）
load.paths	额外的插件文件/目录
slots	独占插槽选择器（如 memory、contextEngine）
entries.<id>	单插件开关 + 配置

配置变更需要重启 Gateway。如果 Gateway 在启用配置监视 + 进程内重启的情况下运行（默认 openclaw gateway 路径），通常会在配置写入后自动重启。

插件状态：disabled、missing、invalid 的区别

• Disabled（禁用）：插件存在，但启用规则将其关闭。配置保留。
• Missing（缺失）：配置引用了一个发现过程中未找到的插件 ID。
• Invalid（无效）：插件存在，但配置不符合声明的 schema。

发现与优先级

OpenClaw 按以下顺序扫描插件（第一个匹配为准）：

1. 配置路径：plugins.load.paths — 显式文件或目录路径。
2. 工作区扩展：<workspace>/.openclaw/<plugin-root>/*.ts 和 <workspace>/.openclaw/<plugin-root>/*/index.ts。
3. 全局扩展：~/.openclaw/<plugin-root>/*.ts 和 ~/.openclaw/<plugin-root>/*/index.ts。
4. 内置插件：随 OpenClaw 内置。许多默认启用（模型 Provider、语音）。其他需要显式启用。

启用规则

• plugins.enabled: false 禁用所有插件
• plugins.deny 始终优先于 allow
• plugins.entries.<id>.enabled: false 禁用该插件
• 工作区来源的插件默认禁用（必须显式启用）
• 内置插件遵循内置默认启用集，除非被覆盖
• 独占插槽可强制启用该插槽对应的插件

插件插槽（独占分类）

某些分类是独占的（同一时间只能有一个处于活动状态）：

{
  plugins: {
    slots: {
      memory: "memory-core", // 或 "none" 禁用
      contextEngine: "legacy", // 或插件 ID
    },
  },
}

插槽	控制内容	默认值
memory	活动记忆插件	memory-core
contextEngine	活动上下文引擎	legacy（内置）

CLI 参考

openclaw plugins list                    # 紧凑清单
openclaw plugins list --enabled          # 仅已加载插件
openclaw plugins list --verbose          # 每插件详情行
openclaw plugins list --json             # 机器可读清单
openclaw plugins inspect <id>            # 详细信息
openclaw plugins inspect <id> --json     # 机器可读
openclaw plugins inspect --all           # 全局表格
openclaw plugins info <id>               # inspect 别名
openclaw plugins doctor                  # 诊断

openclaw plugins install <package>               # 安装（先 ClawHub，再 npm）
openclaw plugins install clawhub:<pkg>           # 仅从 ClawHub 安装
openclaw plugins install <spec> --force          # 覆盖已有安装
openclaw plugins install <path>                  # 从本地路径安装
openclaw plugins install -l <path>               # 链接（不复制，用于开发）
openclaw plugins install <plugin> --marketplace <source>
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <spec> --pin            # 记录精确解析的 npm spec
openclaw plugins install <spec> --dangerously-force-unsafe-install

openclaw plugins update <id>             # 更新单个插件
openclaw plugins update <id> --dangerously-force-unsafe-install
openclaw plugins update --all            # 更新所有插件
openclaw plugins uninstall <id>          # 移除配置/安装记录
openclaw plugins uninstall <id> --keep-files
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json

openclaw plugins enable <id>
openclaw plugins disable <id>

内置插件随 OpenClaw 一起提供。许多默认启用（如内置模型 Provider、语音 Provider、浏览器插件）。其他内置插件仍需 openclaw plugins enable <id>。

标志说明：

• --force：覆盖已有的已安装插件或 hook 包。不支持与 --link 同用。
• --pin：仅支持 npm，不支持 --marketplace（marketplace 安装持久化 marketplace 来源元数据）。
• --dangerously-force-unsafe-install：针对内置危险代码扫描误报的紧急覆盖，允许跳过 critical 发现继续安装/更新，但仍不能绕过 before_install 策略阻止或扫描失败阻止。
• --marketplace：从 marketplace 来源安装。来源可以是 Claude 已知 marketplace 名称、本地 marketplace 根目录或 marketplace.json 路径、GitHub 简写（owner/repo）、GitHub 仓库 URL 或 git URL。

兼容 Bundle 插件参与相同的 list/inspect/enable/disable 流程。当前运行时支持包括 bundle 技能、Claude command-skills、Claude settings.json 默认值、Cursor command-skills 和兼容 Codex hook 目录。

完整 CLI 参考参见 openclaw plugins CLI reference。

插件 API 概览

原生插件导出一个暴露 register(api) 的入口对象。旧版插件可能仍使用 activate(api) 作为遗留别名，但新插件应使用 register：

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
    api.registerChannel({
      /* ... */
    });
  },
});

OpenClaw 在插件激活时加载入口对象并调用 register(api)。加载器仍回退到旧版插件的 activate(api)，但内置插件和新外部插件应将 register 视为公共契约。

常用注册方法：

方法	注册内容
registerProvider	模型 Provider（LLM）
registerChannel	聊天频道
registerTool	Agent 工具
registerHook / on(...)	生命周期钩子
registerSpeechProvider	文本转语音 / STT
registerRealtimeTranscriptionProvider	流式 STT
registerRealtimeVoiceProvider	双工实时语音
registerMediaUnderstandingProvider	图像/音频分析
registerImageGenerationProvider	图像生成
registerMusicGenerationProvider	音乐生成
registerVideoGenerationProvider	视频生成
registerWebFetchProvider	网页抓取/爬取 Provider
registerWebSearchProvider	网络搜索
registerHttpRoute	HTTP 端点
registerCommand / registerCli	CLI 命令
registerContextEngine	上下文引擎
registerService	后台服务

类型化生命周期钩子的守护行为：

• before_tool_call：{ block: true } 是终止性的；优先级更低的处理器会被跳过。
• before_tool_call：{ block: false } 是空操作，不会清除之前的 block。
• before_install：{ block: true } 是终止性的；优先级更低的处理器会被跳过。
• before_install：{ block: false } 是空操作，不会清除之前的 block。
• message_sending：{ cancel: true } 是终止性的；优先级更低的处理器会被跳过。
• message_sending：{ cancel: false } 是空操作，不会清除之前的 cancel。

完整类型化钩子行为参见 SDK Overview。

相关链接

• Building Plugins — 创建你自己的插件
• Plugin Bundles — Codex/Claude/Cursor Bundle 兼容性
• Plugin Manifest — manifest schema
• Registering Tools — 在插件中添加 Agent 工具
• Plugin Internals — 能力模型和加载流水线
• Community Plugins — 第三方插件列表

养龙虾小贴士：给你的龙虾装上语音通话插件（@openclaw/voice-call），它就能直接接打电话了。--dangerously-force-unsafe-install 这个长标志是破玻璃紧急选项，日常不要轻易使用——先用 openclaw doctor 诊断一下再说。

常见问题

Q: 插件安装后为什么没有生效？

A: 插件安装后必须重启 Gateway。如果 Gateway 使用默认的配置监视 + 进程内重启，写入配置后通常会自动重启；但手动安装插件后需要确认重启。可以运行 openclaw gateway restart 或 openclaw plugins status 检查状态。

Q: --pin 和 --force 有什么区别？

A: --pin 只支持 npm 安装，用于记录精确解析的 npm spec（如 @pkg@1.2.3），方便后续精确复现相同版本。--force 用于覆盖已有的已安装插件，不管版本是否一样——适合本地开发时反复覆盖安装。两者不冲突但 --pin 不支持 --marketplace 来源。

Q: 内置插件（如 browser）和可安装插件有什么区别？

A: 内置插件随 OpenClaw 一起提供，许多默认启用（如 browser、anthropic provider）。可安装插件需要 openclaw plugins install <pkg> 单独安装。内置插件可以被禁用（plugins.entries.browser.enabled: false），但不能被卸载；可安装插件可以通过 openclaw plugins uninstall <id> 完全移除。