插件

插件可为 OpenClaw 扩展新能力：渠道、模型提供商、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是核心插件（随 OpenClaw 一起提供），其他则是外部插件（由社区发布到 npm）。

快速开始

查看已加载内容

openclaw plugins list

安装插件

# 从 npm
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 可识别两种插件格式：

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

两者都会显示在 openclaw plugins list 中。有关 bundle 详情，请参见插件 Bundles。如果你正在编写原生插件，请从构建插件和插件 SDK 概览开始。

官方插件

可安装（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 一起提供）

模型提供商（默认启用）

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 插件

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

语音提供商（默认启用）

elevenlabs, microsoft

其他

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

想找第三方插件？请参见社区插件。

配置

{
  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 路径），则通常会在配置写入完成后稍等片刻自动执行该重启。

插件状态：已禁用 vs 缺失 vs 无效

已禁用：插件存在，但启用规则将其关闭。配置会被保留。
缺失：配置引用了一个设备发现未找到的插件 id。
无效：插件存在，但其配置不符合声明的 schema。

设备发现与优先级

OpenClaw 按以下顺序扫描插件（先匹配者优先）：

配置路径

plugins.load.paths — 显式文件或目录路径。

工作区扩展

\<workspace\>/.openclaw/<plugin-root>/*.ts 和 \<workspace\>/.openclaw/<plugin-root>/*/index.ts。

全局扩展

~/.openclaw/<plugin-root>/*.ts 和 ~/.openclaw/<plugin-root>/*/index.ts。

内置插件

随 OpenClaw 一起提供。许多默认启用（模型提供商、语音等）。其他则需要显式启用。

启用规则

plugins.enabled: false 会禁用所有插件
plugins.deny 总是优先于 allow
plugins.entries.\<id\>.enabled: false 会禁用该插件
来源于工作区的插件默认禁用（必须显式启用）
内置插件遵循内建的默认启用集合，除非被覆盖
独占槽位可强制启用该槽位中选定的插件

插件槽位（独占类别）

有些类别是独占的（同一时间只能激活一个）：

{
  plugins: {
    slots: {
      memory: "memory-core", // 或 "none" 以禁用
      contextEngine: "legacy", // 或某个插件 id
    },
  },
}

槽位	控制内容	默认值
`memory`	活动 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 一起提供。许多默认启用（例如内置模型提供商、内置语音提供商和内置 browser 插件）。其他内置插件仍然需要 openclaw plugins enable <id>。 --force 会就地覆盖现有已安装插件或 hook pack。它不支持与 --link 一起使用，因为 --link 会复用源路径，而不是复制到受管理的安装目标。 --pin 仅适用于 npm。它不支持与 --marketplace 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。 --dangerously-force-unsafe-install 是针对内置危险代码扫描器误报的紧急覆盖开关。它允许插件安装和插件更新在遇到内置 critical 发现后继续进行，但仍不会绕过插件 before_install 策略阻止或扫描失败阻止。这个 CLI 标志仅适用于插件安装 / 更新流程。由 Gateway 网关驱动的 skill 依赖安装则使用对应的 dangerouslyForceUnsafeInstall 请求覆盖，而 openclaw skills install 仍然是独立的 ClawHub skill 下载 / 安装流程。兼容 bundles 会参与相同的插件列表 / 检查 / 启用 / 禁用流程。当前运行时支持包括 bundle Skills、Claude command-skills、Claude settings.json 默认值、Claude .lsp.json 和清单声明的 lspServers 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。 openclaw plugins inspect <id> 还会报告检测到的 bundle 能力，以及由 bundle 支持或不支持的 MCP 和 LSP server 条目。 Marketplace 来源可以是来自 ~/.claude/plugins/known_marketplaces.json 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 marketplace.json 路径、形如 owner/repo 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplaces，插件条目必须保留在克隆的 marketplace 仓库内，并且只能使用相对路径来源。完整详情请参见 openclaw plugins CLI 参考。

插件 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`	模型提供商（LLM）
`registerChannel`	聊天渠道
`registerTool`	智能体工具
`registerHook` / `on(...)`	生命周期 hooks
`registerSpeechProvider`	文本转语音 / STT
`registerRealtimeTranscriptionProvider`	流式 STT
`registerRealtimeVoiceProvider`	双工实时语音
`registerMediaUnderstandingProvider`	图像 / 音频分析
`registerImageGenerationProvider`	图像生成
`registerMusicGenerationProvider`	音乐生成
`registerVideoGenerationProvider`	视频生成
`registerWebFetchProvider`	网页抓取 / scrape 提供商
`registerWebSearchProvider`	Web 搜索
`registerHttpRoute`	HTTP 端点
`registerCommand` / `registerCli`	CLI 命令
`registerContextEngine`	上下文引擎
`registerService`	后台服务

类型化生命周期 hooks 的 hook 守卫行为：

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。

完整的类型化 hook 行为，请参见 SDK 概览。

概览

内置工具

浏览器

代理协作

技能

扩展

自动化与任务

媒体与设备

插件

插件

快速开始

插件类型

官方插件

可安装（npm）

核心（随 OpenClaw 一起提供）

配置

设备发现与优先级

启用规则

插件槽位（独占类别）

CLI 参考

插件 API 概览

相关内容

概览

内置工具

浏览器

代理协作

技能

扩展

自动化与任务

媒体与设备

​插件

​快速开始

​插件类型

​官方插件

​可安装（npm）

​核心（随 OpenClaw 一起提供）

​配置

​设备发现与优先级

​启用规则

​插件槽位（独占类别）

​CLI 参考

​插件 API 概览

​相关内容

插件

快速开始

插件类型

官方插件

可安装（npm）

核心（随 OpenClaw 一起提供）

配置

设备发现与优先级

启用规则

插件槽位（独占类别）

CLI 参考

插件 API 概览

相关内容